Skip to content

Commit 91aab3b

Browse files
EliSauderCopilot
andcommitted
docs: describe engine-supplied type combination and cache wiring
Replace named-strategy documentation with the optional generic interface, engine-owned metadata validation and runtime construction after both catalog paths. Document backward-compatible inference for engines without a combiner. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
1 parent f669ca0 commit 91aab3b

2 files changed

Lines changed: 29 additions & 18 deletions

File tree

‎docs/guides/development.md‎

Lines changed: 27 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -21,22 +21,33 @@ nullability propagation. Database-specific common-type algorithms belong to
2121
the engine: SQL Server's precedence, length and decimal rules live in
2222
`internal/engine/mssql/typepolicy`, independent of its parser.
2323

24-
`set_operations.strategy` in a dialect's `dialect.json` explicitly selects an
25-
implemented policy (currently only `"mssql"`). The remaining fields configure
26-
that SQL Server policy; they are not a universal coercion language. Seeds
27-
reject missing or unsupported strategies rather than accidentally applying
28-
SQL Server's formula to another engine. The selector is serialized in the
29-
catalog, so cache restores use the same policy as freshly seeded catalogs.
30-
Omitting `set_operations` preserves the old inference fallback.
31-
32-
To support another dialect, add its engine-owned policy and explicit
33-
dispatch/seed validation, then opt in its dialect settings and add end-to-end
34-
cases. Do not copy SQL Server's settings into other seeds. Some engines need
35-
the entire candidate list, cast context, domain information or recursive
36-
structured types; extend the policy inputs/orchestration for those semantics
37-
rather than forcing them through pairwise precedence. Set operations and
38-
`CASE`-like expressions need not share one algorithm. The current cross-engine
39-
gaps and database references are in
24+
`core.TypeCombiner` receives an operation context and the entire ordered list
25+
of candidate types, retaining nil entries for untyped values. It returns a
26+
type and an explicit `Handled` flag; declining a context preserves the old
27+
inference fallback, while an error is propagated. Engines without a combiner
28+
keep their existing behavior. `Prepare` accepts the combiner through an
29+
optional analyzer option, inherited by nested queries.
30+
31+
The compiler's existing engine assembly selects an optional combiner factory.
32+
It calls that factory after `core.NewCached` returns, on both fresh and
33+
restored catalogs, and passes the instance to analysis. No engine names,
34+
imports or strategy registry are needed in shared core analysis or seeding.
35+
Combiners must allow concurrent analysis and must not mutate candidate types.
36+
37+
`set_operations` in `dialect.json` is opaque JSON to shared seeding. Its schema
38+
and validation belong to the engine implementation; SQL Server's precedence
39+
and decimal settings are not a universal coercion language. Only the data is
40+
cached; runtime behavior is constructed afresh. Malformed configuration fails
41+
in the engine factory, and configuration without a provider is a setup error.
42+
43+
To support another dialect, implement its combiner and wire its factory at
44+
the compiler's engine assembly, without editing shared policy dispatch or
45+
validation. Add end-to-end cases rather than copying SQL Server's settings.
46+
Some engines additionally need literal/domain metadata or recursive structured
47+
types; extend the inputs for actual implementations rather than forcing those
48+
semantics through pairwise precedence. Set operations and `CASE`-like
49+
expressions need not share an algorithm. The current cross-engine gaps and
50+
database references are in
4051
[`analyze`](../howto/analyze.md#common-type-inference).
4152

4253
SQL Server's converter also performs syntax/semantic lowering before seeded

‎docs/howto/analyze.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -22,12 +22,12 @@ case.
2222
## Common-type inference
2323

2424
The shared core does not give every database the same coercion rules. SQL
25-
Server explicitly enables its type-combination policy for set operations and
25+
Server supplies its own type combiner for set operations and
2626
alternative-valued expressions such as `CASE`, `COALESCE`, `GREATEST`, `LEAST`
2727
and `CHOOSE`. `ISNULL` instead keeps its first typed argument's type; both
2828
arguments must be nullable for its result to be nullable.
2929

30-
Other dialects currently keep the existing core fallback: a set-operation
30+
Dialects without a combiner keep the existing core fallback: a set-operation
3131
column takes its type from the left branch, and an alternative-valued
3232
expression takes the first typed candidate. **This is incomplete static
3333
inference, not those databases' common-type semantics.** It does not change

0 commit comments

Comments
 (0)