datahike.pg.sql.ctx — org.replikativ/pg-datahike 0.1.8

Translation context for the SQL → Datalog translator.

The ctx is an immutable map of per-translation atoms that every translate-* fn threads through. Atoms capture the side-effecting state (fresh-var counter, collected where clauses, entity-var bindings, prepared-statement placeholders, …) while the outer map stays shareable with nested sub-translations.

Fn inventory:

• resolve-column / resolve-inherited-attr — map a JSqlParser Column reference to a Datahike attribute keyword, following the table-alias map and PostgreSQL INHERITS semantics.
• make-ctx — build a fresh context.
• fresh-var!, entity-var!, add-clause!, col-var! — primitives the translators call to allocate logic variables, assign entity bindings, append where clauses, and lazily produce get-else-backed column bindings.
• materialize-arg! — bind a composite expression to a fresh var.
• null-guard-clauses / make-columns-optional! — SQL 3-valued-logic helpers.
• collect-vars — recursively gather ?v-style symbols out of a translated form.

Fns originally marked ^:private in sql.clj are promoted to public here so the extracted translate-* namespaces can reach them without re-exporting through the top-level sql ns.

add-clause! clj

(add-clause! ctx clause)

Append a Datalog clause to the context's where-clauses.

col-var! clj

(col-var! ctx attr)

Get or create the logic variable for an attribute.

For ordinary columns, binds the var via get-else so rows without the column still flow through (bound to the :__null__ sentinel). This models SQL NULL semantics — a missing attribute is NULL, not a reason to drop the row — and the var is recorded in :nullable-vars so comparison predicates can wrap it in null-guards (three-valued logic).

Exception: when the entity is a LEFT JOIN right-side var (already registered in :left-join-evars), emit a plain data pattern instead. The LEFT JOIN or-join construction (run later in translate-select) identifies those patterns and relocates them into the matched branch, synthesising :__null__ via ground in the unmatched branch. A get-else with the LEFT JOIN sentinel entity-id would otherwise throw. These vars are still added to :nullable-vars so null-guards apply.

Handles three forms of attr: [:db-id alias-key] → return entity var for the alias [:aliased alias-key kw] → aliased column (self-joins) :ns/col → regular column

collect-vars clj

(collect-vars form)

Collect all logic variables (symbols starting with ?) from a form.

entity-var! clj

(entity-var! ctx alias-key)

Get or create the entity variable for a table alias.

extract-table-info clj

(extract-table-info table)

Extract table name and alias from a FROM clause Table.

fresh-var! clj

(fresh-var! ctx)

Generate a fresh logic variable ?v1, ?v2, etc.

make-columns-optional! clj

(make-columns-optional! ctx vars)

Convert plain data patterns for the given variable symbols to get-else. Used by COALESCE, NULLIF, CASE — functions that handle NULLs explicitly. Skips patterns whose entity var is a LEFT JOIN right-side entity var, because those patterns will be moved inside the or-join where NULL synthesis is handled by the matched/unmatched branches.

make-ctx clj

(make-ctx schema table-aliases default-table & [{:keys [db parse-sql hints]}])

Create a fresh translation context. The options map may carry:

• :db — live Datahike db snapshot (for schema inherits lookup, virtual catalog resolution, subquery execution)
• :parse-sql — recursion hook: a fn of [sql schema db] that re-enters the parser to translate inner SQL strings (IN / EXISTS subqueries). Passed by datahike.pg.sql/parse-sql at top-level ctx construction so expression translators can recurse without a cyclic namespace load. Callers that don't need subquery support can omit it.
• :hints — {attr-ident → hint-map} from datahike.pg.schema/schema-hints. Drives the :col-overrides lookup used by resolve-column so WHERE <renamed-col> and JOIN … ON … resolve hint- mapped columns to their real attribute keywords.

materialize-arg! clj

(materialize-arg! ctx arg)

If arg is a compound form (seq), bind it to a fresh var via a function-binding clause and return the var. Otherwise return arg.

null-guard-clauses clj

(null-guard-clauses ctx vars)

Return a vector of predicate clauses that assert none of the supplied vars is the :__null__ sentinel. Used to make comparison predicates null-safe per SQL's three-valued logic: col op V when col IS NULL yields UNKNOWN, and WHERE treats UNKNOWN as FALSE (row filtered).

Only vars that were emitted via col-var! (and therefore recorded in :nullable-vars) need guarding — other vars cannot be :__null__.

resolve-column clj

(resolve-column col table-aliases default-table)

(resolve-column col table-aliases default-table col-overrides)

Resolve a column reference to a Datahike attribute keyword. Uses table-aliases map {alias → table-name} and schema-tables for lookup. Handles table inheritance: if a column doesn't exist in the child table's namespace but does exist in an inherited parent's namespace, resolves to the parent namespace (PostgreSQL INHERITS semantics).

Optional 4th arg col-overrides is {table-name → {hinted-col-name → attr-ident}} from make-ctx; when a column name appears there, the override wins over the default (keyword table-name col-name) construction. Makes :datahike.pg/column renames resolve on the read side too.

Returns either: [:db-id alias-key] — for db_id references [:aliased alias-key kw] — for aliased column references (self-joins) :ns/col — for regular column references

resolve-inherited-attr clj

(resolve-inherited-attr attr schema db)

For INHERITS support: check if an attribute exists in the table's schema. If not, walk up the inheritance chain to find it in a parent. Returns the resolved keyword (possibly in parent namespace) or the original.