Load configuration from files

PyRel can auto-discover configuration files and load them automatically. This guide describes how to create a raiconfig.yaml file, how file discovery works, and how to use profiles and environment variables for flexible configuration management.

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.

What file-based configuration covers

This guide applies to the Load and validate configuration step in the PyRel workflow:

You can use file-based configuration to set up your Snowflake and RAI Native App connections, change behavior defaults, and manage multiple environments with profiles. If you want to configure PyRel without files, see Create configuration in code.

How file discovery works

If the RAI_CONFIG_FILE_PATH environment variable is set, PyRel loads that file directly and skips file discovery. If that variable is not set, PyRel looks for a raiconfig.yaml or raiconfig.yml file in the current working directory and parent directories. If it does not find one, it falls back to other file-based sources primarily as a convenience for users who already have Snowflake connections defined in Snowflake CLI config or DBT profiles.

This is the discovery order:

PyRel validates the first source it finds. If that source is invalid, it raises an error immediately and does not continue to lower-priority files.

How Snowflake config.toml file fallback works

If ~/.snowflake/config.toml exists, PyRel can use it as a fallback when no higher-priority config source 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 process explains how PyRel uses ~/.snowflake/config.toml as a fallback.

1. Check for ~/.snowflake/config.toml:

   If ~/.snowflake/config.toml does not exist, PyRel skips this fallback source.

2. Validate required fields:

   PyRel expects the file to 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.

3. Load the selected Snowflake connection into a Config object:

   PyRel validates the fallback source and creates a Config object using ConfigFromSnowflake. In that created Config object, the selected Snowflake connection is mapped to a connection named snowflake, and default_connection is set to snowflake.

   You can inspect the created Config object after instantiating a Model object to confirm that the fallback source was loaded:

   from relationalai.semantics import Model
   
   m = Model("MyModel")
   
   print(type(m.config))  # Will show ConfigFromSnowflake if a Snowflake config was loaded

   See Access configuration values for more details on inspecting the loaded config.

Note that:

• PyRel only uses this file when it cannot find a higher-priority config source, like raiconfig.yaml.
• PyRel uses default_connection_name to select which Snowflake connection entry to use.
• PyRel creates a Config object with a connection named snowflake. It also sets default_connection to snowflake.
• PyRel does not create or modify any config files on disk.

How DBT profiles.yml file fallback works

If a DBT profiles.yml exists, PyRel can use it as a fallback when no higher-priority config source 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 process explains how PyRel uses profiles.yml as a fallback.

1. Check for profiles.yml:

   If no supported profiles.yml file exists, PyRel skips this fallback source. PyRel supports these locations:

   • ./profiles.yml
   • ~/.dbt/profiles.yml

2. Validate required fields:

   PyRel expects the file to 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.

3. 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.

4. Load the selected DBT output into a Config object:

   PyRel validates the fallback source and creates a Config object using ConfigFromDBT. In that created Config object, the selected DBT output is mapped to a PyRel connection. The mapped connection name matches the DBT output provider. Currently, only snowflake outputs are supported.

   You can inspect the created Config object after instantiating a Model object to confirm that the fallback source was loaded:

   from relationalai.semantics import Model
   
   m = Model("MyModel")
   
   print(type(m.config))  # Will show ConfigFromDBT if a DBT profile was loaded

   See Access configuration values for more details on inspecting the loaded config.

Caution

If your DBT config references environment variables (for example, {{ env_var('SNOWFLAKE_PASSWORD') }}), they must be set in your shell before running Python in order for PyRel to load the config successfully.

Note that:

• PyRel only uses this file when it cannot find a higher-priority config file, like raiconfig.yaml.
• PyRel only supports type: snowflake outputs in profiles.yml.
• PyRel creates a Config object from the selected DBT profile and target.
• PyRel does not create or modify any config files on disk.

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.

1. 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.

2. 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: "{{ env_var('SNOWFLAKE_PASSWORD') }}"

3. 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)

Related resources:

• Configure Snowflake authentication
• Configure execution behavior
• Configure reasoners
• Use a Snowflake table with Model.Table()

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.

To use a config file outside the current directory tree:

1. Set RAI_CONFIG_FILE_PATH to the config file you want PyRel to use:

   export RAI_CONFIG_FILE_PATH="$HOME/shared-config/raiconfig.yaml"

2. Run PyRel normally:

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

3. 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.

Note that:

• 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 dev vs prod without duplicating every field.

To set up profiles:

1. Add name overrides to the profile section of your YAML file.

   In this example, the dev profile overrides the warehouse to dev_warehouse, and the prod profile overrides it to prod_warehouse:

   default_connection: snowflake
   connections:
     snowflake:
       type: snowflake
       authenticator: username_password
       account: "my_account"
       user: "my_user"
       warehouse: "base_warehouse"
       password: "{{ env_var('SNOWFLAKE_PASSWORD') }}"
   
   profile:
     dev:
       connections:
         snowflake:
           warehouse: "dev_warehouse"
     prod:
       connections:
         snowflake:
           warehouse: "prod_warehouse"

   In this example:

   • dev and prod are just example profile names. You can choose any names that make sense for your project.
   • The profile overrides only the warehouse field, so other values like account and user are shared between profiles.

   Note that:

   • Everything supported in the base config is also supported in profiles. You can override any field, including default_connection.

2. 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.

3. 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:

1. 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') }}"

2. 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="..."

3. 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.

:::