Configure a model

Model configuration controls how PyRel loads your model, how it treats properties you have not declared, and how the model deploys its outputs to Snowflake. These settings live in two sections of your configuration: model for how the model runs, and deployment for where and how it deploys to Snowflake. This guide shows how to set them, and how to inspect the values PyRel actually used.

Before you start, make sure that:

• You have access to a Snowflake account with the RelationalAI Native App installed. If you are unsure, contact your Snowflake administrator.
• You have a working PyRel installation. See Set Up Your Environment for instructions.

Choose which setting to change

Use this table to find the setting for what you want to change:

Setting	Use it when
model.implicit_properties	You want accessing an undeclared property to raise an error instead of silently creating it, for example before deploying to production.
model.path	You are deploying a model and want to point PyRel at its entry point script or directory.
deployment.schema	You want to choose the Snowflake schema and role a model deploys to.
deployment.schedules	You want to control when a deployed model’s outputs refresh after deployment.
deployment.outputs	You want to choose which Snowflake object types a deployed model’s outputs use.

Require declared properties

By default, PyRel creates a property the first time you access it, even if you never declared it. Set the model.implicit_properties configuration option to false to require every property to be declared before use, so that accessing an undeclared property raises an error.

Tip

Requiring declared properties catches misspelled property names early, which is especially useful before you deploy a production model. With the default setting, a typo silently creates a new property instead of raising an error.

raiconfig.yaml

1. Set model.implicit_properties in raiconfig.yaml

   connections:
     # ...
   
   model:
     implicit_properties: false

2. Inspect the parsed config

   Note

   This check assumes your existing raiconfig.yaml already includes a valid connection configuration. If you define more than one connection, set default_connection so Model uses the intended config. See Configure Snowflake authentication for details on connection configuration.

   from relationalai.semantics import Model
   
   m = Model("MyModel")
   
   print(m.config.model.implicit_properties)

   A printed value of False confirms that PyRel loaded the implicit_properties setting from your config.

Programmatic

Set model.implicit_properties with ModelConfig or a plain Python dict. These examples assume file discovery already provides a valid connection configuration. Use one of the following approaches:

1. Set the value with a typed config class

   from relationalai.config import ModelConfig, create_config
   from relationalai.semantics import Model
   
   cfg = create_config(model=ModelConfig(implicit_properties=False))
   m = Model("MyModel", config=cfg)
   
   print(m.config.model.implicit_properties)

2. Set the value with a dict

   from relationalai.config import create_config
   from relationalai.semantics import Model
   
   cfg = create_config(model={"implicit_properties": False})
   m = Model("MyModel", config=cfg)
   
   print(m.config.model.implicit_properties)

Related resources:

• Create configuration in code
• ModelConfig API reference

Set the model entry point

model.path points PyRel at the script or directory that defines your model, for example model.py. It has no default (None).

Deployment and related tooling use model.path to locate your model. For example, rai models deploy deploys the model at model.path when you do not pass an explicit --path option to the command.

raiconfig.yaml

1. Set model.path in raiconfig.yaml

   connections:
     # ...
   
   model:
     path: model.py

2. Inspect the parsed config

   Note

   This check assumes your existing raiconfig.yaml already includes a valid connection configuration. If you define more than one connection, set default_connection so Model uses the intended config. See Configure Snowflake authentication for details on connection configuration.

   from relationalai.semantics import Model
   
   m = Model("MyModel")
   
   print(m.config.model.path)

   A printed value of model.py confirms that PyRel loaded the path setting from your config.

Programmatic

Set model.path with ModelConfig or a plain Python dict. These examples assume file discovery already provides a valid connection configuration. Use one of the following approaches:

1. Set the value with a typed config class

   from relationalai.config import ModelConfig, create_config
   from relationalai.semantics import Model
   
   cfg = create_config(model=ModelConfig(path="model.py"))
   m = Model("MyModel", config=cfg)
   
   print(m.config.model.path)

2. Set the value with a dict

   from relationalai.config import create_config
   from relationalai.semantics import Model
   
   cfg = create_config(model={"path": "model.py"})
   m = Model("MyModel", config=cfg)
   
   print(m.config.model.path)

Related resources:

• Create configuration in code
• ModelConfig API reference

Set the deployment target

The deployment section controls where and how a model deploys its outputs to Snowflake. For most models, you only need to set deployment.schema and deployment.role:

deployment:
  schema: MY_DATABASE.MY_MODEL                # Where the model's output tables and views are created
  role: MY_DEPLOYMENT_ROLE                    # Snowflake role used to deploy and refresh the model
  # meta_schema: MY_DATABASE.MY_MODEL_META    # Where PyRel stores deployment metadata (defaults to <schema>_META)
  # auto_deploy: true                         # Deploy automatically before running queries (defaults to false)

The meta_schema and auto_deploy settings are optional.

Here is what each setting does:

• schema: The fully-qualified Snowflake schema (<DATABASE>.<SCHEMA>) that holds the model’s output tables and views. Give each model its own dedicated schema, and do not create your own tables or views in it by hand. PyRel will not overwrite objects it did not create, so if one of your objects has the same name as a model output, the deploy fails until you remove it.
• role: The Snowflake role PyRel uses to deploy and refresh the model. If you omit it, PyRel uses the connection or current session role.
• meta_schema: The schema where PyRel stores the metadata it uses to manage the deployment, such as stored procedures, the refresh plan table, and the refresh log. Keeping it separate from schema prevents PyRel’s bookkeeping from mixing with your model’s outputs. If you omit it, PyRel derives it from schema as <schema>_META, for example MY_DATABASE.MY_MODEL_META.
• auto_deploy: When true, PyRel deploys the model automatically before it runs queries against it, so you do not have to run rai models deploy yourself. It defaults to false, which means you must deploy the model explicitly from the CLI.

Related resources:

• Deploy a model
• DeploymentConfig API reference

Schedule output refreshes

A deployed model keeps its outputs up to date by refreshing them on a schedule. A schedule is a named refresh cadence: for each schedule you define, PyRel creates a Snowflake task that refreshes the outputs assigned to it. Every output must be assigned to a schedule.

Use this table to find the part of scheduling you want to configure:

What to do	When to do it
Define a schedule	Setting up any deployed model; every model needs at least one schedule.
Assign outputs to schedules	Some outputs need to refresh more or less often than others.
Skip the deploy-time refresh	An external pipeline or manual trigger drives the first refresh.
Auto-suspend test schedules	Developing a model, to keep test deployments from refreshing indefinitely.

Define a schedule

Define one or more named schedules under deployment.schedules, then set a default schedule for all outputs under deployment.outputs:

deployment:
  schema: MY_DATABASE.MY_MODEL
  role: MY_DEPLOYMENT_ROLE

  schedules:
    standard:
      interval_s: 30       # refresh outputs every 30s

  outputs:
    schedule: standard     # default schedule for all outputs

interval_s is how often the schedule’s task refreshes its outputs, in seconds. It must be 0 or at least 10. Use 0 for a schedule whose refresh you trigger manually or from an external pipeline instead of on a fixed interval.

Schedule names must start with a letter and contain only letters, numbers, and underscores.

Note

interval_s sets how often a refresh starts, not how fresh the outputs are guaranteed to be. Each refresh takes time to run, and Snowflake does not start a new run while the previous one is still going. So if a refresh takes longer than interval_s to finish, outputs update less often than the interval suggests.

Assign outputs to schedules

Every output refreshes on exactly one schedule. Set the default schedule for all outputs with deployment.outputs.schedule, then assign individual outputs to a different schedule with deployment.outputs.overrides. Each override lists the objects it applies to and the schedule they refresh on:

deployment:
  schema: MY_DATABASE.MY_MODEL
  role: MY_DEPLOYMENT_ROLE

  schedules:
    standard:
      interval_s: 300      # most outputs refresh every 5 minutes
    fast_path:
      interval_s: 30       # these outputs refresh every 30s

  outputs:
    schedule: standard     # default schedule for all outputs
    overrides:
      - objects:
          - ACCOUNT_SCORE
          - RISK_FLAG
        schedule: fast_path   # refresh these two outputs on fast_path instead

Outputs you do not name in an override use the default outputs.schedule. Assign outputs to different schedules to refresh different parts of the model at different rates.

Caution

Schedules run independently. If dependent outputs use different schedules, queries can see mixed freshness across those outputs. See Understand output consistency.

Skip the deploy-time refresh

By default, deploying a model runs each schedule’s refresh task once, right away, so the outputs are populated as soon as the deploy finishes. This initial refresh runs even for a manual schedule with interval_s: 0.

Set run_on_deploy: false on a schedule to skip that initial refresh. Use this when something other than the deploy drives the first refresh, such as an external pipeline that triggers the schedule’s task on its own timing:

  schedules:
    external_pipeline:
      interval_s: 0
      run_on_deploy: false   # do not refresh at deploy time; the pipeline triggers it

  outputs:
    schedule: external_pipeline

Note

Outputs still refresh on their interval regardless of run_on_deploy. The setting only controls the one-time refresh at deploy time.

To trigger the refresh yourself, run the schedule’s Snowflake task. PyRel creates one task per schedule, named REFRESH_<SCHEDULE> (with the schedule name in upper case) in the model’s meta schema. For the external_pipeline schedule above, deployed to MY_DATABASE.MY_MODEL, you would run:

EXECUTE TASK MY_DATABASE.MY_MODEL_META.REFRESH_EXTERNAL_PIPELINE;

Running the task requires the account-level EXECUTE TASK privilege.

Auto-suspend test schedules

During development, set suspend_after_mins to auto-suspend a model’s refresh tasks after a period, so lingering tasks from test deployments do not keep running:

deployment:
  schema: MY_DATABASE.MY_MODEL
  role: MY_DEPLOYMENT_ROLE
  suspend_after_mins: 15   # suspend refresh tasks 15 minutes after the deploy starts

  schedules:
    standard:
      interval_s: 30

  outputs:
    schedule: standard

Leave suspend_after_mins unset in production, where you want outputs to keep refreshing.

Choose how outputs are materialized

By default, PyRel creates each deployed output as a Snowflake dynamic table when it can. You can override the default for all outputs with deployment.outputs.type, or override individual outputs with deployment.outputs.overrides. The valid output types are:

• dynamic_table
• table
• view

For example, this configuration creates all outputs as tables except for ACCOUNT_SCORE, which is a dynamic table:

deployment:
  schema: MY_DATABASE.MY_MODEL
  role: MY_DEPLOYMENT_ROLE

  schedules:
    standard:
      interval_s: 30

  outputs:
    schedule: standard
    type: table                 # default output type
    overrides:
      - objects:
          - ACCOUNT_SCORE
        type: dynamic_table     # override this output

Note

PyRel may fall back to a table when an output is configured as a dynamic table but cannot be represented as one, for example when the output does not depend on other Snowflake objects.