Load configuration from files

PyRel configuration files let you reuse Snowflake connections across projects and switch between development and test settings without changing your model code. This guide shows how to create those files, keep secrets out of them, and check which settings PyRel loads.

Prerequisites: You have access to a Snowflake account with the RelationalAI Native App installed. If you are unsure, contact your Snowflake administrator. The examples inspect configuration without connecting to Snowflake; deployment also requires the privileges described in Deploy a model.

You have a working PyRel installation. See Install and run PyRel for instructions.

How file discovery works

PyRel can combine shared settings from your home directory with project-specific settings. Setting RAI_CONFIG_FILE_PATH skips both locations and loads only the file you specify. The diagram shows these two paths to the resolved configuration:

Both global and project files can be named raiconfig.yaml or raiconfig.yml. Within a project, PyRel searches the current working directory and its parents; nearer files override matching values in ancestor files. Settings you do not override are inherited.

Run rai config explain to check the resolved settings and which files supplied them. If loading fails, check those files for invalid syntax or missing required fields.

Create a `raiconfig.yaml` file

Create a configuration file that PyRel can auto-discover and use by default. PyRel searches upward from your current working directory to find the file.

Create a config file in your project:

Create raiconfig.yaml (or raiconfig.yml) in your project directory. PyRel searches the current working directory and parent directories to find it.
Start from a minimal connection configuration:

Start with a single Snowflake connection. Replace the account, user, and warehouse placeholders with values from your Snowflake administrator. This example uses browser authentication; see Configure Snowflake authentication for alternatives. Set default_connection explicitly for clarity. If you omit default_connection and define exactly one connection, PyRel auto-selects that connection. For example:
```
default_connection: snowflake
connections:
  snowflake:
    type: snowflake
    authenticator: externalbrowser
    account: "my_account"
    user: "my_user"
    warehouse: "my_warehouse"
```
Load the config and verify it:
```
from relationalai.semantics import Model

m = Model("MyModel")
print(m.config.default_connection)
```
The printed value should be snowflake. This confirms the selected connection name, not authentication or deployment permissions. If it differs, run rai config explain and check for profile or environment overrides.

This example supplies a connection, not a complete deployment configuration. For the model entry point and deployment settings, see Configure a model and Configure deployment.

Put shared settings in ~/.rai/raiconfig.yaml or ~/.rai/raiconfig.yml. Here, ~ means your home directory; create the .rai directory if it does not exist. These settings are available across projects unless you pin a file with RAI_CONFIG_FILE_PATH or load deprecated RAI TOML configuration.

For example, place this connection in your global YAML file, replacing the account, user, and warehouse placeholders:

default_connection: snowflake
connections:
  snowflake:
    type: snowflake
    authenticator: externalbrowser
    account: "my_account"
    user: "my_user"
    warehouse: "shared_warehouse"

In a project’s raiconfig.yaml, override just the warehouse:

connections:
  snowflake:
    warehouse: "project_warehouse"

The project inherits the global connection’s other fields. Run Python from that project to inspect the merged setting:

from relationalai.semantics import Model

m = Model("MyModel")
print(m.config.connections["snowflake"].warehouse)

The printed value should be project_warehouse. This verifies the project override, not a connection to Snowflake. If the value differs, check for RAI_CONFIG_FILE_PATH, active profiles, and nearer project files with rai config explain. Keep secrets out of both global and project YAML; see Use environment variables for secrets and overrides.

Use a config file outside the current directory tree

Use the RAI_CONFIG_FILE_PATH environment variable when your raiconfig.yaml is outside the current working directory tree or when you want a shell or notebook environment to point to a shared config file. When this variable is set, PyRel loads that file directly and does not continue with discovery. It does not merge ancestor files, global YAML, Snowflake configuration, or DBT profiles into the pinned file. Include the connection settings it needs in that file.

To use a config file outside the current directory tree:

Set RAI_CONFIG_FILE_PATH to the config file you want PyRel to use:
Terminal window
```
export RAI_CONFIG_FILE_PATH="$HOME/shared-config/raiconfig.yaml"
```
Run PyRel normally:
```
from relationalai.semantics import Model

m = Model("MyModel")
print(m.config.default_connection)
```
The printed name should match the default connection in your pinned file after any profile or environment overrides. This inspects configuration without opening a Snowflake session.
Fix any config errors:

PyRel validates the file at RAI_CONFIG_FILE_PATH and raises an error immediately if the path is wrong or the file cannot be loaded. No fallback or discovery occurs when this variable is set, so you must fix the path or file for PyRel to load any config.

Use this override when you want a shell or notebook environment to point to a shared config file without changing directories.
Unset RAI_CONFIG_FILE_PATH to return to normal auto-discovery.

Use profiles to manage multiple configurations

Profiles are named overrides on top of your base YAML config. Use them when you want one file that supports development and testing without duplicating every field.

To set up profiles:

Add named overrides to the profile section of your YAML file.

In this example, the dev and test profiles choose different warehouses and deployment schemas. Replace the connection and schema placeholders with values for your environment:
```
default_connection: snowflake
active_profile: dev
connections:
  snowflake:
    type: snowflake
    authenticator: externalbrowser
    account: "my_account"
    user: "my_user"
    warehouse: "base_warehouse"

profile:
  dev:
    connections:
      snowflake:
        warehouse: "dev_warehouse"
    deployment:
      public_schema: "MY_DATABASE.MODEL_DEV"
      identity:
        internal_schema: "MY_DATABASE.MODEL_DEV_META"
  test:
    connections:
      snowflake:
        warehouse: "test_warehouse"
    deployment:
      public_schema: "MY_DATABASE.MODEL_TEST"
      identity:
        internal_schema: "MY_DATABASE.MODEL_TEST_META"
```
In this example:
- dev and test are just example profile names. You can choose any names that make sense for your project.
- Each profile sets its own warehouse, public schema, and internal schema. Connection values such as account and user remain shared.
- Selecting a warehouse alone does not isolate a deployment’s outputs. The distinct deployment.public_schema values select different target schemas. For the remaining deployment settings and privileges, see Configure deployment.
Note that:
- Everything supported in the base config is also supported in profiles. You can override any field, including default_connection.
Choose the active profile using one of these methods:
- Set active_profile: <profile_name> in your raiconfig.yaml for the file’s default.
- Set RAI_PROFILE=<profile_name> in your shell to override the YAML selection. RAI_ACTIVE_PROFILE is also supported, but RAI_PROFILE takes precedence if both are set.
- For a single CLI invocation, use the root --profile option, for example rai --profile dev config explain. It overrides RAI_PROFILE for that invocation.
- When loading files from Python, pass active_profile="<profile_name>" to create_config() to override the file and environment selections.
Load the config and verify the profile:
```
from relationalai.semantics import Model

m = Model("MyModel")

print(m.config.active_profile)
print(m.config.connections["snowflake"].warehouse)
print(m.config.deployment.public_schema)
```
With the example’s dev profile and no overrides, the printed values should be dev, dev_warehouse, and MY_DATABASE.MODEL_DEV. These values confirm profile selection, not deployment readiness. If they differ, check the profile selectors above and run rai config explain.

Use environment variables for secrets and overrides

Environment variable references let you keep secrets and environment-specific values out of your config file. Use them when you want to commit raiconfig.yaml to version control without storing passwords or tokens. Keep secrets out of files and load them from environment variables at runtime:

Reference environment variables in your YAML using {{ env_var('NAME') }}:

connections:
  snowflake:
    type: snowflake
    authenticator: username_password
    account: "{{ env_var('SNOWFLAKE_ACCOUNT') }}"
    user: "{{ env_var('SNOWFLAKE_USER') }}"
    warehouse: "{{ env_var('SNOWFLAKE_WAREHOUSE') }}"
    password: "{{ env_var('SNOWFLAKE_PASSWORD') }}"

Make the environment variables available before running Python or the CLI:

Set the non-secret connection values in your shell:
Terminal window
```
export SNOWFLAKE_ACCOUNT="my_account"
export SNOWFLAKE_USER="my_user"
export SNOWFLAKE_WAREHOUSE="my_warehouse"
```
Supply SNOWFLAKE_PASSWORD through your organization’s secret-management workflow. Do not put its value in a committed file or print it to verify that it loaded. If you use a notebook, ensure its Python process receives these variables too.
Load the config and inspect a non-secret setting:
```
from relationalai.semantics import Model

m = Model("MyModel")

print(m.config.connections["snowflake"].warehouse)
```
The printed value should match SNOWFLAKE_WAREHOUSE. This confirms that the value was loaded, not that authentication or deployment will succeed. If a variable is missing, set it in the environment of the process that loads the configuration, then reload the config. For authentication errors when connecting, see Configure Snowflake authentication.

Reuse existing Snowflake or DBT connection files

If you already maintain Snowflake connection settings for Snowflake or DBT, PyRel can reuse them during file discovery. These sources supply connection settings, not model entry points or deployment settings. Project and global YAML override matching values from both sources; Snowflake settings override DBT settings. Setting RAI_CONFIG_FILE_PATH skips these sources.

Snowflake config.toml

PyRel reads ~/.snowflake/config.toml and selects the connection named by default_connection_name. The file must include a connections section, and each connection must include account and warehouse. A user is also required unless you use OAuth client credentials. For example:

default_connection_name = "my_sf"

[connections.my_sf]
account = "my_account"
user = "my_user"
authenticator = "externalbrowser"
warehouse = "my_warehouse"

PyRel maps the selected entry to a connection named snowflake and contributes default_connection: snowflake. Higher-priority YAML settings can override these values. See Configure Snowflake authentication for other authentication methods.

DBT profiles.yml

PyRel uses ./profiles.yml if it exists, otherwise ~/.dbt/profiles.yml. It does not merge the two files. The selected profile must include an outputs section; only type: snowflake outputs are supported. For example:

my_profile:
  target: dev
  outputs:
    dev:
      type: snowflake
      account: "my_account"
      user: "my_user"
      authenticator: externalbrowser
      warehouse: "my_warehouse"

Set DBT_PROFILE to select a profile; otherwise, PyRel uses the first profile in the file. Set DBT_TARGET to select an output; otherwise, PyRel uses the profile’s target, tries dev, then falls back to the first output. The selected output contributes a connection named snowflake and default_connection: snowflake, subject to higher-priority overrides.

If the file references environment variables, make them available to the Python or CLI process before loading configuration. Missing variables can prevent loading.

PyRel does not create or modify these files. Run rai config explain to inspect the resolved settings and their source files without opening a session. Malformed files can stop loading, while an optional source that cannot be converted can contribute no settings. If an expected connection is missing, check the source’s required fields or define the connection in YAML.