Deploy a model

Deploy a PyRel model to a Snowflake schema, where model outputs will be accessible as regular views and tables. This guide shows how to configure the target schema and role, validate and run the deployment in the CLI, inspect and query the model outputs in Snowflake with SQL, and troubleshoot common issues.

You have a working PyRel installation and a working Snowflake connection.
You have access to a Snowflake account where the RelationalAI Native App is installed.
You know which Snowflake schema to target for this workflow and can inspect that location in Snowflake.
You already know how to create a Model and run a query.

What deploying a model does

The outputs of a PyRel model are the concepts and relationships derived from its source tables via any of the supported reasoners. By mapping every concept to a table with a column for each of its properties, and every relationship to a table with a column for each of its fields, model outputs can be fully represented using familiar Snowflake objects. This makes deployed model outputs present like any other governed data source in your organization.

To deploy, you pick a target Snowflake schema in which the tables derived by your model should live. As long as your model remains the same, the generated schema remains stable, so that others in your organization can depend on it. An additional <target name>_META schema is created as a place where PyRel can store model state and intermediate results that should not be depended on.

Deploying a model to a target schema does not move the model’s source tables. Source tables can come from any other schema and remain completely unaffected.

All Snowflake objects (tables, views, procedures, and tasks) that PyRel creates on your behalf carry a relationalai_managed = 'true' tag. PyRel throws an error if a deployment would override an existing object that doesn’t carry this tag.

A single model can be deployed to an arbitrary number of target schemas simultaneously. This is typically used to create separate development and production environments, or to support multiple tenants with isolated data sources. PyRel fits into your existing development and deployment processes.

Configure deployed model refresh schedules

Most models are dynamic. Their outputs need to be maintained in response to changes to the source tables.

One or more schedules can be configured for a deployed model. Each schedule will install a periodic Snowflake task in the meta schema that orchestrates all the reasoners required to refresh the model as the source data changes.

Simple models will often use the same schedule for all outputs. For more sophisticated deployments, it can be useful to refresh different parts of the model at different intervals, or to trigger refresh from existing data pipelines.

Create your first deployable model

In this section you will set up a new, deployment-ready PyRel model. Skip to the next section if you already have a model that you would like to deploy.

Initialize a new model

In your working directory, run:
Terminal window
```
rai models init [your-model-name]
```
This creates a folder your-model-name with a starter model and raiconfig.yaml. The generated raiconfig.yaml demonstrates a best practice: use separate dev and prod profiles in raiconfig.yaml. By switching profiles, you can keep using the same rai models deploy flow, whether you are developing against an isolated schema with test data, or releasing to a production schema widely used throughout your organization.

Configure your development connection in raiconfig.yaml

In the dev profile, fill in the connection fields for your Snowflake account and authentication method. You will also need to configure which warehouse to use for SQL execution. For example:

default_connection: sf

connections:
  sf:
    type: snowflake
    account: my_org-my_account
    warehouse: my_warehouse
    rai_app_name: relationalai         # name of the RAI app in your Snowflake account
    authenticator: externalbrowser     # SSO via browser; for PAT or JWT see README.md
    user: you@example.com

Set the target schema in raiconfig.yaml

Again for the dev profile, fill in the model section. The schema should be unique to the model. No other models or applications should modify the schema, to avoid conflicts and unexpected results.

model:
  schema: MY_DATABASE.MY_DEV_SCHEMA    # fully-qualified <DATABASE>.<SCHEMA>
  role: your_role                      # Snowflake role to use when deploying the model
  path: model.py                       # path to the model entry point script
  # auto_deploy: false                 # set to true to auto-deploy the model before queries

Load some sample data

The starter model includes a script to load a few rows of test data that you can use to validate everything is working correctly:
Terminal window
```
python load_data.py
```
If you have some source tables already, just skip this step and update model.py to use those.
Deploy from the CLI

With the data loaded, it’s time to trigger the deployment. In the model directory (the one containing your raiconfig.yaml), pick the dev profile and run:
Terminal window
```
RAI_PROFILE=dev rai models deploy
```
Inspect the deployed model

Once the deployment has succeeded, your model outputs will be visible in the target schema. Use the Snowflake UI or CLI to inspect the target schema. It should now contain several dynamic tables corresponding to the Connection and Station concepts from the starter model.

You can also query a deployed model through PyRel directly. For the starter model, run:
Terminal window
```
python queries.py
```
To see a few example queries. Note that PyRel queries return dataframes and are not themselves visible in the target schema.

The prod profile can be configured in the same way. Once you are ready to deploy to production, run RAI_PROFILE=prod rai models deploy.

Make an existing model deployable

In this section, you’ll update your existing raiconfig.yaml to make your model ready for deployment. If you want to create a new deployment-ready model from scratch, please refer to the previous section.

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

In early access, deployment is only supported for models using rules-based 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 introducing separate dev and prod profiles as a best practice. The steps below apply to any profile.

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
```

Set the target schema in raiconfig.yaml

Add a deployment section specifying the target schema and role.

deployment:
  schema: MY_DATABASE.MY_DEV_SCHEMA    # fully-qualified <DATABASE>.<SCHEMA>
  role: your_role                      # Snowflake role to use when deploying 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 is the minimal configuration required to make an existing model deployable.

Define a refresh schedule

In order for your model to be refreshed automatically, extend your deployment section to create a schedule and use it as the default for all model outputs.

deployment:
  schema: MY_DATABASE.MY_DEV_SCHEMA
  role: your_role

 schedules:
   standard:
     interval_s: 30       # outputs on this schedule refresh every 30s

 outputs:
   schedule: standard     # set the `standard` schedule as the default

Deploy from the CLI

Select the right profile and trigger the deployment.
Terminal window
```
RAI_PROFILE=dev rai models deploy
```

Deploy from the CLI

After your model is correctly configured, you can quickly trigger a deployment. Pick a profile from your model directory (the one containing the raiconfig.yaml) and run:

RAI_PROFILE=dev rai models deploy

This will perform basic validation of your configuration and Snowflake connection. Refer to the troubleshooting section below if you run into issues.

Monitor a deployment from SQL

Once a deployment succeeds in the CLI, the target schema and corresponding *_META schema will have been created if they didn’t exist yet, and an initial refresh of the model will have been kicked off. Inspect the target schema to verify.

Check the target schema
```
SHOW SCHEMAS LIKE '<YOUR_TARGET_SCHEMA>' IN DATABASE <YOUR_DATABASE>;
```
Replace <YOUR_TARGET_SCHEMA> and <YOUR_DATABASE> with the target schema you set for deployment.schema.
List installed tables and views

During deployment, the PyRel compiler decides which type of Snowflake object to use for each output. It may choose regular tables, views, or dynamic tables. This can also be configured on a per-output basis.
```
SHOW OBJECTS IN SCHEMA <YOUR_DATABASE>.<YOUR_TARGET_SCHEMA>;
```
You should see objects corresponding to each of the concepts and relationships in your model.
Query the model’s refresh log

The refresh log is a table in the meta schema, which the refresh task uses to report progress.
```
SELECT * <YOUR_TARGET_SCHEMA>_META.REFRESH_LOG;
```
You should see rows indicating that a run has been prepared and started (ENTRY_TYPE = RUN_STARTED).

The refresh log is the first place to check when a model is not refreshing as expected. You can quickly scan for refresh failures:
```
SELECT * FROM REFRESH_LOG WHERE STATE = 'FAILURE';
```

If any of these steps fails or Snowflake does not show the expected objects, continue to the troubleshooting section below.

Troubleshooting

There are several reasons that can cause a rai models deploy to fail. This section covers the most common ones and how to resolve them.

By far the most common issues are due to missing or invalid configuration of the model or your Snowflake connection. These can often be diagnosed by running:

rai doctor

Specifically for configuration issues, it can be helpful to run:

rai config explain

No objects show up in the target schema

If rai models deploy succeeded but your target schema remains empty, the most likely issue is that the schema you are looking at is not the one that the model was deployed to. Verify that deployment.schema is set correctly and that you are using the correct profile.

Snowflake raises a privilege error during model refresh

Deployment succeeded but the model refresh task fails with a privilige error. This most likely means that the deployment.role you configured does not have permission to execute Snowflake tasks. Confirm the target schema and access configuration with your Snowflake admin or RelationalAI support.

Source tables are not visible in the target schema

Only model outputs are deployed into the target schema. Source tables are completely unaffected and remain in whatever schema they are. Check your tables configuration to see which schema your source tables are coming from.

Unexpected objects show up in the target schema

The PyRel compiler can decide to use tables, views, or dynamic tables for any given output. This can also be overriden in your raiconfig.yaml. Check whether a table you are expecting to see may instead have been created as a view, and vice versa.