Enum Model Contracts

An enum can describe the allowed domain of a model column as well as provide individual SQL literals.

These are separate uses:

• @enum("fulfillment_method").DELIVERY inserts one validated value into SQL.
• type fulfillment_method declares that a model column uses the complete enum domain.

Declare an enum-typed column

Use the enum name as the column type:

MODEL (
  description "Example model",
  contract enforced,
  columns (
    fulfillment_method (type fulfillment_method),
  ),
);

SQLBuild does not send fulfillment_method to the warehouse as a physical type and does not create a warehouse-native enum. It translates the enum into portable column metadata:

Enum values	Physical column type	Generated validation
Strings such as DELIVERY and PICKUP	VARCHAR	accepted_values for the enum strings
Integers such as 1 and 3	INTEGER	accepted_values for the enum integers

Contract behavior

With contract enforced, SQLBuild runs the generated accepted_values audit with the model’s other audits. Its severity and timing follow the model’s ordinary audit and materialization settings.

With contract none, SQLBuild still resolves the enum to its portable scalar column type but does not generate the domain audit.

Literals checked at compile time

With contract enforced, sqb compile also checks every constant string literal that fills an enum-typed column of a string enum, so a missing member fails before the build rather than in the audit afterwards. A literal counts when it is the column’s whole expression, when it fills the column in any UNION or UNION ALL branch, or when the column passes it through unfiltered from a CTE or derived table:

MODEL (
  description "Orders from every channel",
  contract enforced,
  columns (
    fulfillment_method (type fulfillment_method),
  ),
);

SELECT order_id, 'DELIVERY' AS fulfillment_method FROM __ref("stg_web_orders")
UNION ALL
SELECT order_id, 'COURIER' FROM __ref("stg_partner_orders")

error[K013]: value 'COURIER' in column 'fulfillment_method' of model 'orders' is not a member of enum fulfillment_method

The error points at the literal in the model file. Computed values, such as a CASE expression or a function call, are not checked at compile time, and neither is a column read from a CTE or derived table through a filter, join or row limit that could remove the literal’s rows; the generated accepted_values audit still checks them when the model builds.

SQL Server compares strings ignoring case and trailing spaces under its default collation, so the compile-time check is skipped on the SQL Server adapter and the audit alone checks the column.

This behavior is the same on adapters with and without native enum support. The physical warehouse column remains an ordinary string or integer column.

Changing the members of an enum-typed contract changes the model’s contract identity and generated validation.