Documentation
¶
Overview ¶
Package constructsql is the leeway constructor family of ADR-0181 §SD2: LW_PLAIN, LW_TV, LW_TV_MEMB and LW_TV_SUPPORT as the client-side nanopass expansion pass LwConstructExpand. A constructor call wraps an expression and mints the physical leeway column name for it, expanding into `<expr> AS "<physical name>"` before the statement ships — the write-direction dual of column handles (ADR-0116): a handle resolves an existing column, a constructor mints a new one.
Nothing is installed server-side. The expanded output is plain SQL any endpoint runs; an unexpanded call reaching a raw server fails loudly as an unknown function. Name composition is lwsql's spec→name seam (§SD6), so the spec tokens mean the same thing here, in `leeway ddl compose`, and in tests.
Index ¶
- Constants
- Variables
- func CheckOutputColumns(names []string) (err error)
- func ComponentExpandPass(comps ComponentSourceI, defaultDatabase string) nanopass.Pass
- func ComponentExpansionDependencies() (names []string)
- func ExpandPassWithSegments(seg lwsql.TableSegments) nanopass.Pass
- func ExpandPassWithTargetAdoption(schema TargetSchemaI, defaultDatabase string) nanopass.Pass
- func ExtractExpandPass(lanes LaneSourceI, defaultDatabase string) nanopass.Pass
- func ExtractExpandPassWithIds(lanes LaneSourceI, ids MembershipIdsI, defaultDatabase string) nanopass.Pass
- func ExtractExpansionDependencies() (names []string)
- func HasAuthoringMarker(sql string) bool
- func HasComponentMarker(sql string) bool
- func HasExtractMarker(sql string) bool
- func ShapeCheckPassWithTarget(columns passes.SchemaProviderI, defaultDatabase string) nanopass.Pass
- type ComponentSourceI
- type Function
- type LaneSourceI
- type MembershipIdsI
- type TargetSchemaI
Constants ¶
const ( NameComponent = "LW_COMPONENT" NameComponentFilter = "LW_COMPONENT_FILTER" )
The component family's SQL-visible names.
const ( NamePlain = "LW_PLAIN" NameTagged = "LW_TV" NameMembership = "LW_TV_MEMB" NameSupport = "LW_TV_SUPPORT" )
The constructor names (LW_ + UPPER_SNAKE per the repo-wide namespace rule). Matching in SQL is case- and quoting-insensitive.
const ( NameGet = "LW_GET" NameGetNull = "LW_GET_NULL" NameGetList = "LW_GET_LIST" // NameSel and NameSelAttrs are the selector half: they return index // selectors rather than values, so the caller's own arrayMap / // arrayFilter / LW_CO_GATHER does the reading. // // This is the "argwhere + gather" plan the array-idioms how-to // describes. The pack already ships the gather half (LW_CO_GATHER); the // argwhere half is what these mint, against a section and a membership // instead of a physical lane. NameSel = "LW_SEL" NameSelAttrs = "LW_SEL_ATTRS" )
The extraction names (LW_ + UPPER_SNAKE per the repo-wide namespace rule). Matching in SQL is case- and quoting-insensitive.
const ComponentPassName = "LwComponentExpand"
ComponentPassName names the expansion pass in the registry and in errors.
const ExtractPassName = "LwExtractExpand"
ExtractPassName is the registered nanopass name of the extraction pass.
const PassName = "LwConstructExpand"
PassName is the registered nanopass name of the expansion pass.
const ShapeCheckPassName = "LwShapeCheck"
ShapeCheckPassName is the registered nanopass name of the shape check.
const ShapeCheckTargetPassName = "LwShapeCheckTarget"
ShapeCheckTargetPassName is the registered nanopass name of the target-aware shape check.
const TargetPassName = "LwConstructExpandTarget"
TargetPassName is the registered nanopass name of the target-adopting constructor expansion. It runs INSTEAD of the unbound LwConstructExpand on hosts that carry a schema binding (ordered just before it; whichever runs first consumes every constructor call and the other's marker scan finds nothing).
Variables ¶
var ExpandPass = ExpandPassWithSegments(lwsql.DefaultTableSegments())
ExpandPass is LwConstructExpand over the fresh-table default segments (':'-separated, row config 0, no groups) — the standard-set registration. Idempotent by construction: expansion leaves no constructor call behind, and a nested or misplaced call is an error, never a partial rewrite.
var ShapeCheckPass = nanopass.LiftBodyPass(ShapeCheckPassName, shapeCheckImpl, nanopass.PassProperties{ Idempotent: true, Reads: nanopass.RegionBody, Writes: nanopass.RegionBody, })
ShapeCheckPass is LwShapeCheck as an opt-in pass.
Functions ¶
func CheckOutputColumns ¶
CheckOutputColumns is the name-level shape check over one output column set: parse, discover, validate, and enforce per-channel section completeness, section-segment agreement, and co-section-group wholeness.
func ComponentExpandPass ¶
func ComponentExpandPass(comps ComponentSourceI, defaultDatabase string) nanopass.Pass
ComponentExpandPass is LwComponentExpand bound to a component source.
Idempotent by construction: expansion leaves no LW_COMPONENT call behind, and an unresolvable one is an error rather than a partial rewrite.
defaultDatabase resolves an unqualified table reference in the statement's FROM against the kind's bound table, the same way the extraction pass and the selection-conditions pass take one.
func ComponentExpansionDependencies ¶
func ComponentExpansionDependencies() (names []string)
ComponentExpansionDependencies are the server-side functions an expanded LW_COMPONENT may call. LW_COMPONENT_FILTER calls none of them.
func ExpandPassWithSegments ¶
func ExpandPassWithSegments(seg lwsql.TableSegments) nanopass.Pass
ExpandPassWithSegments is LwConstructExpand with the table-level naming segments chosen — the target-adoption variant for hosts that know the statement's destination table (adopt its separator and row config via lwsql.Resolver.TableSegments, the way NameConditions does).
func ExpandPassWithTargetAdoption ¶
func ExpandPassWithTargetAdoption(schema TargetSchemaI, defaultDatabase string) nanopass.Pass
ExpandPassWithTargetAdoption is LwConstructExpand bound to a schema: a statement that is not an INSERT, or whose target the schema does not know, expands exactly as the unbound pass does; an INSERT with a resolved target mints in that target's terms.
func ExtractExpandPass ¶
func ExtractExpandPass(lanes LaneSourceI, defaultDatabase string) nanopass.Pass
ExtractExpandPass is LwExtractExpand bound to a schema. Idempotent by construction: expansion leaves no LW_GET call behind, and an unresolvable one is an error, never a partial rewrite.
defaultDatabase resolves unqualified table references, the same way the selection-conditions pass takes one.
func ExtractExpandPassWithIds ¶
func ExtractExpandPassWithIds(lanes LaneSourceI, ids MembershipIdsI, defaultDatabase string) nanopass.Pass
ExtractExpandPassWithIds is ExtractExpandPass with a membership-id lookup, so a ref channel takes a NAME instead of a registry id (ADR-0171 §SD4).
Resolution happens at expansion time, client-side, which keeps the emitted SQL carrying constants — the property ADR-0066 chose deliberately over a query-time dictGet, and the reason this is a binding rather than a join.
func ExtractExpansionDependencies ¶
func ExtractExpansionDependencies() (names []string)
ExtractExpansionDependencies are the server-side functions an expanded extraction may call (ADR-0174 §SD6). The panel marks the family against them, so "installed client-side" does not read as "works everywhere".
The fast form calls fewer of these, and which form a given call takes depends on the section it reads, so the list is what an expansion MAY need rather than what any one expansion does need.
func HasAuthoringMarker ¶
HasAuthoringMarker is the cheap pre-parse scan (ADR-0181 §SD7): standard-set registration must cost approximately nothing on the overwhelming majority of queries that carry no constructor call. False positives (the substring inside a string literal or comment) merely cost the parse the pass would otherwise always run; false negatives are impossible because every call spelling — quoted included — contains one of the two substrings.
func HasComponentMarker ¶
HasComponentMarker reports whether sql could contain a component call. Both names share the LW_COMPONENT prefix, so one check covers the family.
func HasExtractMarker ¶
HasExtractMarker is the cheap pre-parse scan (ADR-0181 §SD7). Every spelling of every family member contains "lw_get" or "lw_sel", quoted included — LW_SEL_ATTRS is caught by the LW_SEL prefix.
func ShapeCheckPassWithTarget ¶
func ShapeCheckPassWithTarget(columns passes.SchemaProviderI, defaultDatabase string) nanopass.Pass
ShapeCheckPassWithTarget (ADR-0181 §SD8 M2) is the INSERT half of the transform contract's validation, opt-in like LwShapeCheck: under a wrapper it verifies the SELECT's output column names against the destination's physical names — the vertical-subset rule applied to a concrete table — and, when a column list is present, that the list and the output correspond position by position. Names compare fold-equivalent (case and separator insensitive), so an adopted mint, a pass-through physical, and a hand-spelled variant all land on the column they mean; a true miss errors naming both sides. A statement without a wrapper falls back to the closure check LwShapeCheck performs.
Types ¶
type ComponentSourceI ¶
type ComponentSourceI interface {
Lookup(kind string) (b componentsql.Binding, ok bool)
Kinds() (kinds []string)
}
ComponentSourceI resolves a component kind to its artefacts. github.com/stergiotis/boxer/public/semistructured/leeway/marshall/clickhouse/componentsql.Registry satisfies it; the pass takes the interface so a host can scope a registry to one query without building a second global.
type Function ¶
Function is one constructor family entry, declared as data for the vocabulary panel (ADR-0174 §SD3): the spelling a query uses, the parameters in order, and one line on what it does.
func ComponentFunctions ¶
func ComponentFunctions() (fns []Function)
ComponentFunctions is the component family, for the vocabulary panel.
The two names differ in what they need installed, which is the distinction ADR-0189 §SD8 asks the panel to show: LW_COMPONENT_FILTER expands to ClickHouse built-ins and runs anywhere, while LW_COMPONENT expands to the named-tuple projection, which calls the read-back helper family.
func ExtractFunctions ¶
func ExtractFunctions() (fns []Function)
ExtractFunctions returns the extraction family, declared as data for the vocabulary panel (ADR-0174 §SD3).
Client-expanded like the constructors, but with a server-side dependency they do not have: the expansion calls the read-back helper family, so a server without it fails on the expansion rather than on the name.
type LaneSourceI ¶
type LaneSourceI interface {
ExtractLanesFor(dbName string, tableName string, section string) (lanes lwsql.ExtractLanes, ok bool)
Sections(dbName string, tableName string) (names []string)
}
LaneSourceI is what the pass needs of a schema: which sections a table carries, and what a section's lanes are. lwsql.Resolver implements it.
type MembershipIdsI ¶
MembershipIdsI resolves a membership name to the uint64 a ref lane carries (ADR-0171 §SD4). One method, spelled exactly as marshallreflect.LookupI and readback.IdLookup spell it, so any registry that satisfies those satisfies this.
Optional. Without it a ref channel still takes an id, which is what it took before §SD4 — the pass degrades to the older, wordier form rather than refusing to run.
type TargetSchemaI ¶
type TargetSchemaI interface {
LaneSourceI
TableSegments(dbName string, tableName string) (seg lwsql.TableSegments, ok bool)
Resolve(dbName string, tableName string, handle string) passes.ResolveResult
}
TargetSchemaI is what target adoption needs of a schema: the fold-tolerant section lookup extraction already uses, the handle path for plain and support columns, and the table-level naming segments for the compose fallback. *lwsql.Resolver implements all three, so a host bound for handle resolution is bound for adoption too.
Source Files