vaelii.impl.plan — com.vaelii/vaelii 0.29.0

Conjunctive query planning: the order a conjunction's literals are solved in.

Two estimators read the count-aware trie and fetch no record: est-matches, a sound upper bound on one literal's matches, and est-rows, an expected relation summary that composes across a join. order splits the generators into blocks, orders each block on est-rows, ranks the blocks, and threads the deferred, recursive and waiting literals back in; explain reports the same decision. See docs/inference.md, "Conjunctive query planning".

*enabled* clj

Bind to false to run a conjunction's generators in written order, skipping the cost ranking. The readiness discipline stays in force: deferred, waiting and computed literals still follow their binders, and the recursive literal still runs after the other generators. VAELII_PLAN=0 installs false for the whole suite (docs/inference.md).

est-matches clj

(est-matches kb goal bound)

(est-matches kb
             goal
             bound
             {:keys [count-at count-with-arg count-with-functor context]
              :or {count-at reads/stored-count-at
                   count-with-arg reads/stored-count-with-arg-global
                   count-with-functor reads/stored-count-with-functor}})

A sound upper bound on how many stored facts goal matches with the variables in bound bound. The result may be too large and is never too small, so 1 proves the literal matches at most once. opts overrides the index reads (:count-at, :count-with-arg, :count-with-functor) and gives the :context that scopes a unary type literal's subtype fan.

est-rows clj

(est-rows kb goal)

(est-rows kb goal opts)

The expected relation goal denotes, {:rows n :vars #{…} :distinct {var n}} in longs. An estimate, wrong in either direction, where est-matches is a bound. :distinct holds the one variable the trie can count, at the first position the known prefix cannot extend past; a variable in :vars and absent from :distinct is uncounted. There is no bound argument: the planner prices bindings in the join. opts is est-matches's, plus :count-children.

explain clj

(explain kb goals context)

(explain kb goals context opts)

The plan as data: one map per literal, in execution order, with

• :goal, and :bound-before, the variables bound when it runs;
• :est-matches, the sound upper bound on its fan-out under those bindings;
• :est-rows, the expected size of its own relation;
• :est-prefix, the expected rows of the plan through it;
• :block, the index of the block it ran in, nil where no ranking ran;
• :deferred?, :recursive?, and :isolated?, a cartesian factor ranked behind another block.

The flags and :block are read off the plan that ran. The numbers are recomputed through the same estimator calls, the :est-override and the plan's memoized reads. opts is order's.

order clj

(order kb goals context)

(order kb goals context opts)

Order goals, a conjunction, for execution, and return the reordered vector.

opts: :bound variables bound when the conjunction starts (default none). A caller that substituted its bindings into the goals leaves this empty. :consequent-pred the functor of the rule whose antecedents these are; the literal with that functor is placed after the other generators, and of the generators only an :end-vars literal it binds an end of follows it. :est-override (fn [goal bound]) -> estimate or nil, consulted before the index model. An estimate of unbounded marks a literal computed from its bindings. :end-vars (fn [literal]) -> the end variables of a literal that answers in full only once one end is bound, or nil. Such a literal waits for the first generator that binds an end, or for the recursive literal when only that binds one.

A conjunction with fewer than two reorderable literals skips the ranking and reads no index.

unbounded clj

The estimate for a literal the index cannot bound. A finite number rather than Long/MAX_VALUE, because the subtype fan sums estimates and a saturating sentinel would overflow. An :est-override returning it marks a literal computed from its bindings (provers/deferred-est).