DeploymentConfig
Configure how a model is deployed: schemas, identity, schedules, and outputs.
This is the single section describing deployment behavior. It carries the
deploy-specific scalar (public_schema), the required
identity block, the named refresh schedules, and the output defaults
(reasoner / materialized / incremental / schedule) with
per-output overrides.
Examples
Section titled “Examples”deployment: public_schema: analytics identity: internal_schema: analytics_internal schedules: standard: interval_s: 60 fast_path: interval_s: 10 schedule: standard materialized: auto overrides: - objects: [recursive_closure] reasoner: logic schedule: fast_pathAttributes
Section titled “Attributes”.public_schema
Section titled “.public_schema”DeploymentConfig.public_schema: (str, optional)Install schema for the model’s published SQL views and tables. A deploy needs it, but it is not checked when the config loads, so a config may set it later.
.identity
Section titled “.identity”DeploymentConfig.identity: IdentityConfigThe settings that define the model’s identity: internal_schema,
which holds the model’s internal objects and the metadata that manages
them (procedures, plan table, refresh log), and the object name
prefix/suffix. Unlike the other settings here, this one is checked when
the config loads, so a deployment: section cannot omit it.
DeploymentConfig.role: (str, optional)Snowflake role to use when deploying the model.
DeploymentConfig.tags: dict[str, str]Existing Snowflake tags applied to every RAI-created object, public and
internal, excluding schemas. Keys are fully qualified tag names
(database.schema.tag); values are the strings assigned. The tags must
already exist and the deploy role must hold APPLY on them — RAI never
creates a tag or widens its allowed values. Each tag rides the CREATE of the
object it belongs to, so editing this map changes every object’s DDL: expect a
full redeploy after any edit, and note that a tag attached out of band does not
survive its object being replaced. RAI never removes a tag — dropping an entry
is not how you unset one; do that by hand or tear the model down. RAI’s own
ownership tag cannot be named here; use managed_tag instead.
.managed_tag
Section titled “.managed_tag”DeploymentConfig.managed_tag: (str, optional)Fully qualified name (database.schema.tag) of an existing Snowflake tag for
RAI to mark the objects it owns with, instead of creating
<meta_schema>.relationalai_managed itself. Naming one says the customer owns
the definition: RAI applies it and never creates, alters or drops it. The tag
must carry no ALLOWED_VALUES. RAI writes a model hash followed by the
configured prefix and suffix, if any, and a metadata-schema display hint.
The deploy role needs, on that tag, APPLY to set it, and USAGE on the
database and schema holding it to read it back: ownership is checked with
SYSTEM$GET_TAG, which resolves the tag by name and fails without that
visibility. APPLY alone lets a deploy mark its objects and then leaves every
ownership check unable to see the mark.
Things to know before setting it:
- Models can share a tag. Its value identifies the model by metadata database, schema, and prefix/suffix. Teardown requires both a matching value and name.
- Cloning or renaming the metadata database or schema changes that identity. This requires manual repair, as objects will have stale ownership tags.
- Reserve it for RAI. A deploy overwrites what the tag marks, and
SYSTEM$GET_TAGreports a value, not who set it, so RAI cannot tell a hand-tagged object of yours from one of its own. - Set it before the first deploy. Changing it afterwards leaves the already-tagged objects reading as unmanaged, and the next deploy refuses to overwrite them.
- Never apply it to a schema. Snowflake makes objects inherit a schema’s tags, so every object in that schema would read as RAI-owned.
.schedules
Section titled “.schedules”DeploymentConfig.schedules: dict[str, ScheduleConfig]Named refresh cadences. Each key is the schedule name (letters, digits
and underscores; must start with a letter). Outputs attach to a schedule
via schedule and per-output overrides.
.schedule
Section titled “.schedule”DeploymentConfig.schedule: (str, optional)Default schedule name (under schedules) outputs refresh on. Outputs
without a schedule override use this one; if omitted, those outputs
are not scheduled.
.reasoner
Section titled “.reasoner”DeploymentConfig.reasoner: strDefault reasoner: "auto" (default; the router decides per output),
"sql", or "logic".
.materialized
Section titled “.materialized”DeploymentConfig.materialized: bool or 'auto'Whether the data behind outputs is materialized: auto (default; the
compiler decides, today a view where one suffices and a table
otherwise), true (always materialize), or false (always compute
on read).
.incremental
Section titled “.incremental”DeploymentConfig.incremental: bool or 'auto'Whether that materialization is maintained incrementally: auto
(default; the compiler decides, today the same as false), true
(dynamic tables), or false.
incremental: true with materialized: false is a config error.
.overrides
Section titled “.overrides”DeploymentConfig.overrides: list[OutputOverride]Ordered per-output adjustments. Each entry names a group of outputs and
sets one or more of reasoner, materialized, incremental,
schedule, or policies for them.
.max_parallel_exports
Section titled “.max_parallel_exports”DeploymentConfig.max_parallel_exports: (int, optional)Maximum number of LQP exports that run in parallel during a refresh (Snowflake only). If unset, the value is taken from the active warehouse’s MAX_CONCURRENCY_LEVEL, falling back to 8.
.max_concurrent_refresh_blocks
Section titled “.max_concurrent_refresh_blocks”DeploymentConfig.max_concurrent_refresh_blocks: (int, optional)Maximum number of refresh plan blocks to dispatch concurrently within a single refresh run (Snowflake only). Blocks are still ordered by their dependencies, so fewer blocks may run concurrently when the plan has dependency barriers. Set to 0 to dispatch all ready blocks at once. If unset, the value is taken from the active warehouse’s MAX_CONCURRENCY_LEVEL, falling back to 8.
.suspend_after_mins
Section titled “.suspend_after_mins”DeploymentConfig.suspend_after_mins: (int, optional)Convenience method for development (Snowflake only). If set, the refresh procedure
auto-suspends all refresh tasks in the meta schema once this many minutes
have elapsed since the last deploy finished, so every deploy restarts the
budget. Intended to bound development costs; leave unset in production.
Once suspended, change or unset this field and redeploy to resume: a bare
ALTER TASK ... RESUME does not stick, because the next run re-evaluates
the same threshold.
.preserve_column_case
Section titled “.preserve_column_case”DeploymentConfig.preserve_column_case: boolPreserve the capitalization of public view columns when deploying to Snowflake.
For example, a model field named EntityId will deploy as column
EntityId, instead of ENTITYID. This currently applies only to
public column names, not table names. In SQL, preserved names are
case-sensitive and must be quoted exactly, such as "EntityId".
Unnamed entity fields use the declared entity capitalization, such as
"Strategy". Without preservation, reserved column names fold to
upper case before quoting, so group deploys as "GROUP".
.allow_recompute_fixpoints
Section titled “.allow_recompute_fixpoints”DeploymentConfig.allow_recompute_fixpoints: boolPermit the direct-SQL compiler to deploy recursive SCCs that require full
recomputation. Defaults to False because refresh work can grow
without a useful incremental bound.
.pat_secret
Section titled “.pat_secret”DeploymentConfig.pat_secret: (str, optional)Fully-qualified Snowflake secret name (db.schema.secret) holding the
deploying user’s Programmatic Access Token; sent to the reasoners as an
X-User-Pat header on every scheduled refresh (Snowflake only). Must
be set together with pat_eai.
.pat_eai
Section titled “.pat_eai”DeploymentConfig.pat_eai: (str, optional)Snowflake External Access Integration name required to read the PAT
secret. Must be set together with pat_secret.
.pat_user
Section titled “.pat_user”DeploymentConfig.pat_user: (str, optional)Snowflake user represented by the PAT and sent as x-user-id. Must be
set together with pat_warehouse; configured Prescriptive Problems
require both PAT field pairs.
.pat_warehouse
Section titled “.pat_warehouse”DeploymentConfig.pat_warehouse: (str, optional)Snowflake warehouse available to the PAT user and sent as
x-user-warehouse. Must be set together with pat_user.