Skip to main content
A model’s declared columns describe expected output metadata. The contract policy determines whether SQLBuild treats that declaration as an open shape or a complete exact shape.

​
Validation

​
Compile time

When SQL analysis can infer the model’s output, both contract policies check declared columns against that inference:
  • A missing declared column fails.
  • A proven type mismatch fails when type enforcement or an exact contract is active.
  • A declared non-null column fails when its expression is proven nullable.
  • Additional inferred columns fail only for contract enforced.
If SQLBuild cannot infer the output shape, these static shape checks cannot run. contract none does not add a later runtime requirement. An enforced contract additionally requires a non-empty column declaration. Configuration fields that reference output columns, including unique_key, cursor, updated_at, and check_columns, are checked against an enforced declaration.

​
Runtime

For supported materialization paths, contract enforced inspects the staged relation and rejects:
  • Missing declared columns.
  • Additional undeclared columns.
  • Warehouse types that differ from declared types.
Runtime contract validation does not scan data for nulls and does not inspect warehouse nullability metadata. nullable false participates in static nullability analysis; add a not_null audit when null values must be checked at runtime. Runtime exact-schema validation currently runs for:
  • Staged full-table builds.
  • Non-microbatch incremental deltas.
  • Snapshot deltas.
Views and custom materializations rely on compile-time contract analysis. Microbatch incrementals currently apply type enforcement and audits but do not perform the framework runtime exact-schema validation step. Staged table validation happens before promotion, so a failure leaves the existing destination untouched. Direct table promotion is incompatible with contract enforced because SQLBuild cannot validate output before replacing the destination.

​
Type enforcement

Declaring a model column type enables type enforcement automatically, independently of the contract policy. Type enforcement controls static type compatibility and runtime casts on supported table and incremental paths; contracts control output shape. See Type Enforcement for the materialization matrix.

​
Reusable schemas

Contracts apply to the effective declaration, not only the reusable base:
With contract enforced, this requires exactly the resolved order columns plus ingestion_batch_id. With contract none, SQLBuild checks those columns when static inference is available and permits further output. See Schemas.

​
Enum columns

A column may use a declared enum as a portable logical domain type:
This does not require, create, or reference a warehouse-native enum type. SQLBuild resolves string-valued enums to VARCHAR and integer-valued enums to INTEGER. Under contract enforced, it also generates an accepted_values audit for the declared members. Audit severity and timing follow normal audit configuration and materialization behavior. With the default error severity, it gates staged-table promotion and pre-DML delta paths; views and custom materializations may already have changed their relation when the audit runs. Enum member references such as @enum("market_type").WIN are a separate feature that render one validated SQL literal. See Enums and Constants for the complete distinction and lowering behavior. The core default is contract none. A repository can enable SQBKR401 to require enforced contracts through Kata architecture policy. Contracts also constrain schema-change behavior. For example, snapshot_schema_change append_new_columns is incompatible with contract enforced because an unannounced appended column would violate the exact declaration.