| name | rai-deployment |
| description | Take a built RelationalAI model to production — deploy it into a Snowflake schema and version it through the op log (branch, collaborate, merge, and tear down with the `rai models` CLI), or deploy it as a Snowflake CoWork (Cortex) agent. The one path-to-prod skill across deployment targets. Use when deploying a model, managing its deployed lifecycle, or operationalizing it as a Cortex agent — not for first-time install/connect (see rai-setup), building the model (see rai-ontology, rai-pyrel), or interpreting reasoner output. |
RelationalAI Deployment (Path to Prod)
Covers the path from a built RelationalAI model to production: the rai models CLI (schema deployment + lifecycle) and Snowflake CoWork (Cortex) agents. Built on the relationalai package (PyRel).
Early access. Deploy mode and semantic model management — the rai models deploy + branch/collaborate/merge/teardown lifecycle — are early-access features (documented in the RAI docs' early-access section); the API, messages, and defaults may still change. Op-log recording (the basis for branch/pull/merge) is off by default today, expected to default on soon. Verified against relationalai 1.20.1; see Prerequisites to turn it on. (The Cortex-agent path carries its own GA/PREVIEW markers — see references/cortex-agents.md.)
Summary
What: Everything between a built model and production, by either of two paths. You've built and validated a model; this skill ships it. Schema deployment — deploy into a Snowflake schema and manage its lifecycle: track every change in the op log, fork experiments into branches, collaborate through a shared model, promote vetted changes back with merge, and tear models down safely. Cortex agent — package the model as a Snowflake CoWork agent users query in natural language.
When to use:
- Deploying a model to a Snowflake schema (
rai models deploy) and understanding what the op log records
- Branching a deployed model for isolated experiments (
rai models branch)
- Collaborating with other developers on one model (shared model,
rai models pull)
- Promoting a branch back to its parent (
rai models merge) or removing a model (rai models teardown)
- Deploying a model as a Snowflake CoWork (Cortex) agent
- Choosing a path to prod (schema deployment vs. Cortex agent)
When NOT to use:
- First-time install,
rai connect, or raiconfig.yaml auth/engine tuning — see rai-setup
- Building or evolving the model itself (concepts, rules, queries) — see
rai-ontology, rai-pyrel
- Diagnosing engine performance or failed transactions — see
rai-health
Overview: Start with Choose a path to prod to pick the deployment target. For schema deployment, read Quick Reference for the command surface, then Deploy for the foundation; the lifecycle commands build on a single idea — the op log — so read that first, then load the reference matching the task (branching, collaboration, merge/teardown). Always check Prerequisites before the lifecycle commands — they refuse cleanly if op-log recording is off. For the Cortex-agent path, go straight to references/cortex-agents.md.
Choose a path to prod
A built model reaches production by one of these paths. Pick the target, then follow the matching guidance:
- Deploy into a Snowflake schema — the model's resources and outputs live in a schema you deploy, version, and evolve with
rai models. This is the default path and the foundation for branching and collaboration. Covered below; lifecycle detail in the reference files.
- Deploy as a Snowflake CoWork (Cortex) agent — package the model as a Cortex agent users query in natural language. Use when the deliverable is a conversational agent rather than a deployed schema. → references/cortex-agents.md; reference implementation in examples/deploy.py.
The two are not exclusive: you deploy a model to a schema first, then optionally expose it as a Cortex agent.
Prerequisites
-
relationalai ≥ 1.20.1 (rai --version) — this skill targets the 1.20 rai models surface.
-
A reachable Snowflake connection (rai connect passes) with a database set on the connection — model-management resolves its metadata schema from it and falls back to the app name (which fails) when it's unset. For install/auth, see rai-setup.
-
A model to deploy — a .py model file or package, with model.path set in raiconfig.yaml (or pass --path). Its outputs need a refresh schedule (deployment.schedules + deployment.outputs.schedule) or deploy refuses with "Unscheduled Outputs".
-
For branch / pull / merge: op-log recording must be ON. It is off by default (opt-in while rolling out). Turn it on in raiconfig.yaml:
oplog:
enabled: true
backend: snowflake
Without it, branch, pull, and merge refuse with Oplog recording is disabled (config.oplog.enabled = false). deploy and teardown still work (deploy installs the model but records no history).
Quick Reference
The current model is the schema named by deployment.schema in raiconfig.yaml. Every lifecycle command targets it; switch changes it.
| Command | Purpose | Key options |
|---|
rai models init [NAME] | Scaffold a starter project | --name |
rai models deploy | Install model + record diff to op log | --path --name --force --wait |
rai models list | List models (schema, parent, type, HEAD, owner) | --limit |
rai models switch NAME | Set the current model (deployment.schema) | -y/--yes |
rai models branch NAME | Zero-copy fork into a new schema | --static |
rai models pull | Reconcile shared changes into shared_model.py | --path --force --from-parent |
rai models merge | Promote branch to parent, retire branch | --path --delete --force |
rai models teardown | Drop the current model/branch + schema + op log | --force --allow-unmerged --allow-children |
deploy --schema overrides deployment.schema for that deploy (working since 1.18; earlier releases ignored it — RAI-51584). As of 1.20, pull / merge / teardown act on the current model only (no --name); use switch to target a different one.
Deploy (the foundation)
rai models deploy does two things: it installs the model's resources and outputs into the target schema, and — when op-log recording is on — it records the diff versus the previously deployed version as operations in the schema's op log.
rai connect
rai models deploy --wait
When changes are recorded, PyRel reports the count: Recorded 3 change(s) to the snowflake oplog. An empty diff is a no-op (No oplog changes to record). If you deployed owned source changes, PyRel warns you to commit them to version control.
The op log is the model's history — an ordered record of how it changed from one deploy to the next, and the foundation for everything below: deploy appends to the current model's log, branch forks it, merge appends a branch's changes onto its parent's, and collaboration uses it to keep developers in sync. You never edit it directly.
If another developer (or session) deployed since your last pull, the deploy is refused: Remote oplog is ahead (remote seq N, local seq M). Run 'rai models pull' first. Pull, then deploy again.
See references/deploy-and-oplog.md for backends, install-only behavior when the op log is off, and shared_model.py generation.
The deployed lifecycle
Once a model is deployed and op-log recording is on, four flows manage it. Load the reference file for the task:
- Branch — fork the current model into a new schema to experiment in isolation; the parent is untouched. Live branches track the parent; static branches freeze at the fork. → references/branching.md
- Collaborate — several developers work one model. You own your source (synced through version control); PyRel reconciles everyone's shared changes through the op log into a generated
shared_model.py. → references/collaboration.md
- Merge — promote a branch's vetted changes back into its parent and retire the branch. → references/merge-and-teardown.md
- Teardown — drop a model or branch and all its data, with guards against losing unmerged work. → references/merge-and-teardown.md
Reference files
Load only the file matching the task:
| File | Load when |
|---|
| references/deploy-and-oplog.md | Deploying; understanding the op log, backends, op-log opt-in, install-only mode |
| references/branching.md | branch, switch, list; live vs. static; --from-parent; single-level limit |
| references/collaboration.md | Multi-developer work; owned vs. shared; shared_model.py; pull; build_shared |
| references/merge-and-teardown.md | merge (preconditions, --delete/--force); teardown (dry-run, guards) |
| references/cortex-agents.md | Deploying the model as a Snowflake CoWork (Cortex) agent — deployment script, DeploymentConfig, tool registry, query catalog, deploy-mode reads (serving precomputed results), grants, debugging |
Examples
Reference implementations for the Cortex-agent path (see references/cortex-agents.md for the full walkthrough):
| Pattern | Description | File |
|---|
| Cortex deployment script | Complete lifecycle CLI (preflight / deploy / update / status / chat / teardown) — primary reference | examples/deploy.py |
| Cortex debug script | Describe the deployed agent, call each sproc directly, trace a chat turn | examples/debug.py |
| Model modules | Core, computed, and query modules for the zero-arg init_tools() pattern | examples/model/ |
Common Pitfalls
| Mistake | Cause | Fix |
|---|
branch/pull/merge refuse: "Oplog recording is disabled" | Op-log recording is off by default (opt-in while rolling out) | Set oplog.enabled: true in raiconfig.yaml. deploy/teardown work without it |
deploy fails: "Database '...' does not exist or not authorized" | deploy creates the target schema but not its database | Create the database first — deploy runs CREATE SCHEMA IF NOT EXISTS <db>.<schema>. If the deploy role lacks CREATE SCHEMA, pre-create the schema (and its _META meta schema, when op-log recording is on) and grant USAGE; deploy confirms it exists and proceeds |
deploy (op-log on) fails: "Insufficient privileges to operate on application 'RELATIONALAI'" | No database on the connection — model-management falls back to the app name and tries to create its metadata schema inside the app | Set database: on the connection in raiconfig.yaml; the metadata schema resolves from it (not a grant or account-enablement issue) |
Bare rai models merge fails: "Model file path is required" | Merge diffs your source to confirm the branch is fully deployed | Pass --path <model>, or set model.path in config |
merge refuses: "branch has not observed the parent's latest changes" | Branch isn't rebased on the parent's latest | On the branch: rai models pull then rai models deploy, then merge |
merge --force doesn't get past a precondition | --force only affects --delete (drops a branch that has children) | Rebase the branch (pull + deploy) to satisfy the merge preconditions |
| "Cannot branch from '...': it is itself a branch" | Branching is single-level in early access | Branch from the base model instead |
pull/deploy refuse to overwrite shared_model.py | Fail-closed guard on a hand-edited generated file | Re-run with --force (backs up to a timestamped .bak); normally let PyRel maintain it |
teardown dropped nothing | teardown is a dry run by default | Add --force; use --allow-unmerged / --allow-children only when you intend to lose that work |
Related Skills
rai-setup — install, rai connect, and raiconfig.yaml (do this first)rai-ontology — build and evolve the model you deployrai-pyrel — PyRel syntax and data loadingrai-health — diagnose engine performance, failed transactions, and CDC health
