useful-notes/scratches/query-engine-glossary.md

Query Engine Glossary

This is a short glossary for the query-engine and IR discussion.

Terms

• IR: Intermediate representation. A simpler form that sits between elaboration and execution.
• lowering: The step that converts elaborated Geolog code into the IR.
• table: A relational object in the IR. It describes stored data with columns and sometimes a primary key.
• law: A logical rule or constraint in the IR. It says what relationships must hold about the data.
• law checking: Testing whether the current data satisfies a law.
• query engine: The execution component that consumes the IR and answers queries. In a broader design it may also do law checking, chase steps, and fixpoint work.
• backend: A concrete execution target, such as an in-memory database, Postgres, or a Rust-native storage/query layer.
• backend-neutral: Not tied to one storage or execution technology. The IR should ideally be backend-neutral.
• RelTable: A table representing a relation or predicate.
• FunTable: A table representing something function-like, where input columns determine an output.
• foreignKeys: Generated laws saying that if one row exists, dependent rows must also exist.
• total: Generated laws saying that if the inputs to a function exist, an output row must exist too.
• runtime IR: A second execution-oriented representation above the lowered theory IR. It would hold changing state needed during execution.
• runtime state: Mutable or evolving execution data, such as current facts, branch identity, witness allocation, equality classes, or provenance.
• fixpoint: The point where running the rules produces no new facts or changes.
• chase: The general reasoning process that repeatedly checks laws and adds whatever is needed to satisfy them.
• witness: A fresh element introduced to satisfy an existential conclusion.
• branch: One possible world or execution path created by a disjunctive rule.
• equality merging: Collapsing two terms or elements when the theory says they must be equal.
• provenance: Information about where a fact came from or which rules produced it.
• planning: Choosing how to execute a query or check a law efficiently.
• adapter: A layer that maps shared IR execution concepts onto one specific backend.

Short mental model

• the front end parses, elaborates, and lowers
• the IR is the contract
• the query engine consumes that contract
• the backend is where execution actually lands