Modern abstraction over SQL

Errors

Parse, name, type, and dialect errors before SQL is emitted.

BtrQL checks source before emitting SQL. Errors point at the construct that failed and stop generation for that file or statement.

Parse errors

Parse errors mean the source shape is incomplete or malformed. Common cases:

  • users.: a pipeline step name is missing after the dot.
  • orders.innerJoin(users): a join needs a source and an on predicate.
  • view broken users.select(id): object definitions need = before the relation body.
  • table users [id: INTEGER, name]: every declared column needs a type.
  • import shared { exported as local }: import aliases use exported -> local.

Fix the local syntax first; later name and type checks depend on the parsed shape.

Name and type errors

Name and type errors mean the source parses, but a referenced object, column, callable, argument, or row shape does not match the available metadata.

Typical fixes:

  • qualify a relation when multiple relation instances make an extension-column reference ambiguous
  • alias one imported extension member with import module { name -> local_name } when modules export the same applicable name
  • correct a column name before it is used in select, where, group, joins, or returning
  • break a reported extension-column dependency cycle; the diagnostic prints the complete cycle
  • move a sequential alias reference after the expression that declares it
  • give every final select or addColumn output a unique name
  • resolve join output collisions with explicit projection aliases
  • align extension receiver, table-kind arguments, scalar-kind arguments, and optional result annotations with the derived types
  • keep non-grouped columns out of grouped projections unless they are grouped or aggregated
  • update cached schema metadata when the database shape changes

Removed recipe syntax

The PostgreSQL and ClickHouse C# prototypes reject column recipe and addColumn[Type] with targeted migration errors. Move each reusable scalar expression into an extension member such as column tax: DECIMAL = amount * tax_rate, then request it with orders.addColumn(tax). A written column type is optional, but if present it must equal the normalized inferred scalar type.

Dialect capability errors

Dialect errors mean the BtrQL source is valid, but the selected SQL target cannot emit that construct. Use the Feature Matrix to check support, then choose one of three options:

  • rewrite the source using a supported construct
  • switch the target dialect
  • keep that statement in dialect-native SQL until BtrQL supports the shape you need