Load configuration from files

PyRel can auto-discover configuration files and load the highest-priority source it finds. If it finds a config file but the file is invalid, it raises an error immediately.

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

Create a `raiconfig.yaml` file

Create a project config file that PyRel can auto-discover and use by default. Use this when you want a shareable, repo-friendly default for most projects. 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 working config:

Start with a single Snowflake connection. 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: username_password
    account: "my_account"
    user: "my_user"
    warehouse: "my_warehouse"
    password: ${SNOWFLAKE_PASSWORD}

Load the config and verify it:

from relationalai.semantics import Model

m = Model("MyModel")
session = m.config.get_session()

# Verify that the default connection has the expected value:
print(m.config.default_connection)

Use profiles to manage multiple configurations

Profiles are named overlays on top of your base YAML config. Use them when you want one file that supports dev vs prod without duplicating every field. Use profile overlays to override only the fields that change across environments:

Add profile overlays to your YAML file:

default_connection: snowflake
connections:
  snowflake:
    type: snowflake
    authenticator: username_password
    account: "my_account"
    user: "my_user"
    warehouse: "base_warehouse"
    password: ${SNOWFLAKE_PASSWORD}

profile:
  dev:
    connections:
      snowflake:
        warehouse: "dev_warehouse"
  prod:
    connections:
      snowflake:
        warehouse: "prod_warehouse"

Choose the active profile using one of these methods:
1. Set active_profile: <profile_name> in your raiconfig.yaml.
2. Set RAI_PROFILE=<profile_name> in your shell. This overrides the YAML setting, so you can use it to switch profiles without changing your file.
3. Pass active_profile="<profile_name>" when calling create_config() programmatically. This overrides both the YAML and environment variable settings.

Load the config and verify the profile:

from relationalai.semantics import Model

m = Model("MyModel")

# Verify that the active profile and overrides are applied:
print(m.config.active_profile)
print(m.config.connections["snowflake"].warehouse)

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 ${NAME}:

connections:
  snowflake:
    type: snowflake
    authenticator: username_password
    account: ${SNOWFLAKE_ACCOUNT}
    user: ${SNOWFLAKE_USER}
    warehouse: ${SNOWFLAKE_WAREHOUSE}
    password: ${SNOWFLAKE_PASSWORD}

Set the environment variables before running Python:

export SNOWFLAKE_ACCOUNT="my_account"
export SNOWFLAKE_USER="my_user"
export SNOWFLAKE_WAREHOUSE="my_warehouse"
export SNOWFLAKE_PASSWORD="..."

Load the config and verify secrets:

from relationalai.semantics import Model

m = Model("MyModel")

# Verify that session creation works with environment variables:
session = m.config.get_session()

If a referenced environment variable is missing, treat the resulting failure as a setup error. Set the missing environment variable and try again.

Use a Snowflake `config.toml` file

If you already have ~/.snowflake/config.toml, PyRel can use it as a fallback when no raiconfig.yaml is found. This reduces setup friction for first-time users who already have Snowflake CLI tools configured, but it’s not a replacement for raiconfig.yaml.

The following steps outline how PyRel uses an existing ~/.snowflake/config.toml as a fallback.

Find your existing ~/.snowflake/config.toml:

If you do not have ~/.snowflake/config.toml, skip this section. Create a raiconfig.yaml instead.
Look for required fields:

Your file must include default_connection_name and a connections section. Each Snowflake connection must include account, user, and warehouse. For example:
```
default_connection_name = "my_sf"

[connections.my_sf]
account = "my_account"
user = "my_user"
password = "my_password"
warehouse = "my_warehouse"
```
If any required fields are missing, PyRel raises an error when it tries to load the file.

Map the Snowflake connection to the connections PyRel config setting:

PyRel maps the selected Snowflake connection into a PyRel config with a connection named snowflake.

from relationalai.semantics import Model

m = Model("MyModel")

# Loading the session forces config auto-discovery and validation:
session = m.config.get_session()

# Verify that the default connection is `snowflake`:
print(m.config.default_connection)

# Inspect the mapped connection values:
print(m.config.connections["snowflake"].account)
print(m.config.connections["snowflake"].user)
print(m.config.connections["snowflake"].warehouse)

PyRel only uses this file when it cannot find raiconfig.yaml or raiconfig.yml.
PyRel uses default_connection_name to select which Snowflake connection entry to use.
PyRel maps the selected Snowflake connection into a PyRel config with a connection named snowflake. It also sets default_connection to snowflake.
PyRel does not create or modify any config files on disk.

Use a DBT `profiles.yml` file

If you already have a DBT profiles.yml, PyRel can use it as a fallback when no raiconfig.yaml is found. This reduces setup friction for first-time users who already have DBT configured, but it’s not a replacement for raiconfig.yaml.

The following steps outline how PyRel uses an existing profiles.yml as a fallback.

Find your existing profiles.yml file:

If you do not have profiles.yml, skip this section. Create a raiconfig.yaml instead. PyRel supports these locations:
- ./profiles.yml
- ~/.dbt/profiles.yml

Look for required fields:

Your file must include a profile with an outputs section. Each output must have a supported type. For example:

my_profile:
  target: dev
  outputs:
    dev:
      type: snowflake
      account: "my_account"
      user: "my_user"
      password: "{{ env_var('SNOWFLAKE_PASSWORD') }}"
      warehouse: "my_warehouse"

If any required fields are missing, PyRel raises an error when it tries to load the file.

Select the profile and target output:

PyRel chooses the DBT profile and target using environment variables when they are set:
- Set DBT_PROFILE to select a profile.
- Set DBT_TARGET to select an output target.
If DBT_TARGET is not set, PyRel uses the profile’s target. If the profile has no target, PyRel tries dev, then falls back to the first output.

If DBT_PROFILE is not set, PyRel uses the first profile in the file.

Map the DBT output to the connections PyRel config setting:

PyRel maps the selected DBT output into a PyRel config. The mapped connection name matches the DBT output provider (currently only snowflake is supported).

Load the config and inspect the mapped connection:

from relationalai.semantics import Model

m = Model("MyModel")

# Loading the session forces config auto-discovery and validation:
session = m.config.get_session()

# Verify that the default connection matches the DBT provider:
provider = m.config.default_connection
print(provider)

# Inspect the mapped connection:
conn = m.config.connections[provider]
print(conn)

PyRel only uses this file when it cannot find a higher-priority config file.
PyRel supports type: snowflake outputs in profiles.yml.
PyRel does not create or modify any config files on disk.