Deploy a model

Deploy a PyRel model to Snowflake so downstream users can query its outputs as views. This guide covers the deployment-specific configuration, validation, optional change review, and CLI steps for an existing model.

Prerequisites

• You have an existing PyRel model project, a working installation, and its raiconfig.yaml file. See Install and run PyRel and Configure PyRel.
• You can connect to a Snowflake account where the RelationalAI Native App is installed, and know which schema to target and inspect. See Set up RelationalAI in Snowflake and Set the deployment target.
• Your deployment role has the privileges needed for deployment and refresh. See Set the deployment target to configure the role. If an administrator will prepare schemas or tags to avoid specific creation privileges, see Deploy with fewer privileges.

Make an existing model deployable

In this section, you’ll update your existing raiconfig.yaml so an existing model is ready for deployment. If you’re starting from scratch, see Deploy the model to a dev schema in Meet PyRel.

The steps below focus only on the deployment-specific configuration you need to add.

Note that:

Eventually, any existing PyRel model will be deployable. However, the following limitations currently apply:

• Deployment supports models that use rules-based reasoning, as well as graph reasoning, which is in Public Preview. See Deploy a model that uses graph reasoning.
• Existing PyRel queries must be strictly separated from the model definition.

Your existing raiconfig.yaml will already have one or more Snowflake connections configured, which you can keep using. If you haven’t already, consider adding separate dev and prod profiles as a best practice. The steps below apply to any profile.

1. Specify the entry path for your model

   Make sure that your model section specifies where your model can be found. This is done via the path field, which can point to a Python file or module.

   model:
     path: model.py

2. Set the target schema in raiconfig.yaml

   Add a deployment section specifying the public schema, the internal schema, and the role.

   deployment:
     public_schema: MY_DATABASE.MY_DEV_SCHEMA         # fully-qualified <DATABASE>.<SCHEMA>
     identity:
       internal_schema: MY_DATABASE.MY_DEV_SCHEMA_META  # where PyRel stores internal objects and metadata
     role: MY_DEPLOYMENT_ROLE                         # Snowflake role used to deploy and refresh the model
     # auto_deploy: false                             # set to true to auto-deploy the model before queries
     # suspend_after_mins: 60                         # auto-suspend model refresh, useful in development

   This tells PyRel where to expose the model’s output views, where to keep its internal objects and metadata, and which Snowflake role to use for deployment and refresh tasks. If you omit deployment.role, PyRel uses the connection role or current session role. Deployment uses only this role and the privileges it inherits through the Snowflake role hierarchy. Privileges from secondary roles are not available, so the deployment role must have all privileges required for deployment and refresh. See Set the deployment target for details.

3. Define a refresh schedule

   Every model output must be assigned to a schedule. Extend your deployment section to create a schedule and use it as the default for all model outputs. Schedules are explained in more detail in Schedule output refreshes.

   deployment:
     public_schema: MY_DATABASE.MY_DEV_SCHEMA
     identity:
       internal_schema: MY_DATABASE.MY_DEV_SCHEMA_META
     role: MY_DEPLOYMENT_ROLE
   
     schedules:
       standard:
         interval_s: 30     # outputs on this schedule refresh every 30s
   
     schedule: standard     # set the `standard` schedule as the default

4. Deploy from the CLI

   Select the right profile and trigger the deployment.

   RAI_PROFILE=dev rai models deploy

   For command details and options, see rai models deploy.

Configure deployment settings

Deployment behavior is configured in the deployment section of raiconfig.yaml. For the full set of options, see Configure deployment:

• Set the deployment target: public schema, internal schema, role, and auto-deploy.
• Schedule output refreshes: refresh schedules, intervals, and manual triggers.
• Choose how outputs are materialized: the materialized and incremental settings that decide how the data behind each output is stored.

Deploy from the CLI

After your model is correctly configured, you can trigger a deployment from the CLI. From the model directory that contains raiconfig.yaml, pick a profile and run:

RAI_PROFILE=dev rai models deploy

See rai models deploy for command details and options.

This validates your configuration and Snowflake connection, then deploys the model. The command waits for the initial refresh to finish by default. Use --no-wait to return as soon as deployment completes, without waiting for the refresh. In PyRel versions before 1.37.0, the command doesn’t wait by default, so add --wait to wait for the refresh. To inspect proposed changes first, review a deployment plan. Refer to Troubleshoot a deployed model if you run into issues.

Review changes before deploying

Before you deploy, you can ask PyRel for a deployment plan: a complete overview of changes that the deployment will make to Snowflake. After reviewing a plan, you can kick off a deployment for exactly this plan. PyRel executes the deployment only if it matches the plan you reviewed. If anything changed in the meantime, such as the model, its configuration, or the objects in Snowflake, PyRel refuses to deploy. Generate and review a new plan before deploying.

Reviewing a plan is optional. A plain rai models deploy doesn’t need one. Planning uses the same configuration, deployment role, and privileges as deployment, so first make your model deployable. Use the same profile and PyRel version when you plan and when you deploy.

Caution

Planning connects to Snowflake and can create or update the schemas and metadata PyRel needs, even though the plan doesn’t list them. It doesn’t install model outputs or start a refresh.

Choose your interface below.

CLI

1. Generate a plan

   Run rai models deploy with the --plan option:

   RAI_PROFILE=dev rai models deploy --plan --plan-output deployment-plan.md

   This saves the plan to deployment-plan.md as Markdown, without deploying the model. To save it as JSON for tooling instead, add --plan-format json and use a .json filename.

2. Review the proposed changes

   Open the file to see the objects the deployment would change and the SQL it would run. Check that the plan targets the environment you intend to change, then look closely at any replacements and removals, since these affect objects that others may depend on. Don’t run the SQL in the plan yourself; deploy with the reviewed plan instead. Don’t edit the file: PyRel compares it exactly with the new plan.

3. Deploy with the reviewed plan

   Once the proposed changes are acceptable, run:

   RAI_PROFILE=dev rai models deploy --reviewed-plan deployment-plan.md

   If the deployment matches the reviewed plan, PyRel deploys the model and waits for the initial refresh, just like a regular deployment. If it doesn’t match, PyRel raises an error and doesn’t deploy anything. Generate and review a new plan.

Python

Run the following from a notebook or a separate script in your model directory, not from model.py itself. The example assumes model.py defines a configured Model instance named model.

1. Generate a plan

   Import your model and generate its deployment plan:

   from model import model
   
   plan = model.plan_deployment()

   This computes the plan without deploying the model.

2. Review the proposed changes

   Print the plan to see the objects the deployment would change and the SQL it would run:

   print(plan)

   Check that the plan targets the environment you intend to change, then look closely at any replacements and removals, since these affect objects that others may depend on. Don’t run the SQL in the plan yourself; deploy with the reviewed plan instead.

   Other ways to inspect or share the plan:

   • View in a notebook: In Jupyter or another IPython-based notebook, put plan on the last line of a cell, or pass it to IPython’s display() function, to see formatted Markdown.
   • Save for review or sharing: Call plan.save("deployment-plan.md") to save a Markdown file. Don’t edit the saved file: PyRel compares it exactly with the new plan.
   • Inspect programmatically: Call plan.to_dict() for a dictionary, or plan.save("deployment-plan.json", format="json") for a JSON file with the same structure.

3. Deploy with the reviewed plan

   Once the proposed changes are acceptable, pass the plan to deploy():

   model.deploy(reviewed_plan=plan)

   If you reviewed a saved file, pass its path instead, as a string or a Path:

   model.deploy(reviewed_plan="deployment-plan.md")

   If the plan still matches the reviewed plan, PyRel deploys the model and waits for the initial refresh, just like a regular deployment. If it doesn’t match, PyRel raises an error and doesn’t deploy anything. Generate and review a new plan.

Deploy multiple models into one schema

Use deployment.identity.object_name_prefix or deployment.identity.object_name_suffix to give each model its own object names within a shared schema. You can use a prefix, a suffix, or both. The same settings apply to all objects created by PyRel, both model outputs and internal objects, except the ownership tag itself.

Start with two model projects that already have a working Snowflake connection, deployment role, and refresh schedules, as described above. In the first project’s raiconfig.yaml, set these fields in the existing deployment section:

deployment:
  public_schema: MY_DATABASE.SHARED_MODELS
  identity:
    internal_schema: MY_DATABASE.SHARED_MODELS_META
    object_name_prefix: PRJ123_

In the second project’s raiconfig.yaml, use the same schema with a different prefix:

deployment:
  public_schema: MY_DATABASE.SHARED_MODELS
  identity:
    internal_schema: MY_DATABASE.SHARED_MODELS_META
    object_name_prefix: PRJ456_

Keep each project’s existing role, schedules, and output settings. Deploy each model from its project directory with the configured profile.

If both models have an output named TRANSACTION, the shared schema contains PRJ123_TRANSACTION and PRJ456_TRANSACTION. Their status procedures are PRJ123_REFRESH_STATUS() and PRJ456_REFRESH_STATUS() in MY_DATABASE.SHARED_MODELS_META.

Prefixes and suffixes can coexist in a schema. PyRel marks objects it creates with the relationalai_managed ownership tag by default; the tag’s value identifies the model that owns each object. If a deployment would overwrite an object that does not carry that model’s ownership tag, PyRel rejects it. This protects objects that belong to other models and objects that PyRel did not create.

Caution

Do not deploy with PyRel versions earlier than 1.34.0 into an internal schema shared by multiple models. In shared schemas, these older versions can delete other models’ refresh tasks.

For defaults, naming rules, and suffix examples, see Configure object name prefixes and suffixes.

Deploy with fewer privileges

An administrator can prepare schemas or tags so that the deployment role does not need the corresponding creation privileges.

Deploy without CREATE SCHEMA

Have an administrator create the model’s public schema and its internal schema, then grant the deployment role USAGE on the database and both schemas.

Deploy without CREATE TAG

Have an administrator create the tag RELATIONALAI_MANAGED in the internal schema, then grant the deployment role APPLY on this tag. Create the tag without ALLOWED_VALUES so it accepts all string values. Do not apply the tag to the schemas.

For example, replace MY_DB, MY_MODEL_META, and DEPLOY_ROLE with your database, internal schema, and deployment role:

CREATE TAG MY_DB.MY_MODEL_META.RELATIONALAI_MANAGED;
GRANT USAGE ON DATABASE MY_DB TO ROLE DEPLOY_ROLE;
GRANT USAGE ON SCHEMA MY_DB.MY_MODEL_META TO ROLE DEPLOY_ROLE;
GRANT APPLY ON TAG MY_DB.MY_MODEL_META.RELATIONALAI_MANAGED TO ROLE DEPLOY_ROLE;

It is possible to create the tag outside the internal schema. To do so, create the tag as described, in the schema of your choice, and set deployment.managed_tag to that tag’s fully qualified name, such as GOV.TAGS.RELATIONALAI_MANAGED. Grant the deployment role USAGE on the database and schema that contain the tag, and APPLY on the tag itself. Configure deployment.managed_tag before the first deployment.