Configuration

RealtionalAI (RAI) models must be configured to connect to your Snowflake account in order to execute queries on the RAI Native App. This guide explains how to configure a model using a raiconfig.toml file or a Config object.

The raiconfig.toml File

By default, when using RAI with a local Python installation, RAI models look for a file called raiconfig.toml for configuration information. If you are using a cloud notebook or another environment where you cannot create a file, you can pass a Config object to the Model constructor instead.

To create a raiconfig.toml file, use the rai init command from your project’s root directory:

# Switch to your project's root directory.
$ cd /path/to/my/project

# Activate your virtual environment.
$ source .venv/bin/activate  # macOS/Linux
$ .venv\Scripts\activate      # Windows

# Create a new configuration file.
$ rai init

The rai init command interactively prompts you for the necessary configuration details and writes them to a file called raiconfig.toml in your project root, such as the sample file below:

raiconfig.toml

active_profile = "default"

[profile.default]
platform = "snowflake"
authenticator = "snowflake"
user = "my_username"
password = "my_password"
account = "my_account"
role = "PUBLIC"
warehouse = "my_warehouse"
rai_app_name = "my_app_name"

Multiple profiles, each with different configuration values, can be stored in the same configuration file. See Configuration Keys for a full list of available keys.

Profiles

Profiles allow you to store multiple sets of configuration values in a single raiconfig.toml file and specify which profile to use when creating a model. You may create and modify profiles using the rai init command or by editing your raiconfig.toml file directly.

Each profile is a TOML table with a unique name, such as dev and prod in the example below:

raiconfig.toml

active_profile = "dev"

[profile.dev]
platform = "snowflake"
authenticator = "snowflake"
account = "dev_account"
user = "user@company.com"
password = "dev_password"
role = "DEV_ROLE"
warehouse = "DEV_WAREHOUSE"
rai_app_name = "relationalai"

[profile.prod]
platform = "snowflake"
authenticator = "snowflake"
account = "prod_account"
user = "user@company.com"
password = "prod_password"
role = "PROD_ROLE"
warehouse = "PROD_WAREHOUSE"
rai_app_name = "relationalai"

There are three ways to specify which profile a model should use:

1. Edit the active_profile key in your raiconfig.toml file, or use the rai profile:switch command set the key for you:

    # Switch to the "prod" profile.
    $ rai profile:switch --name prod

2. Set the RAI_PROFILE environment variable to the name of the profile you want to use:

   # Use the "prod" profile.
   $ export RAI_PROFILE=prod

   Note

   The RAI_PROFILE environment variable takes precedence over the active_profile key in the raiconfig.toml file.

3. Pass the profile name to the Model constructor’s profile parameter in your Python code:

   import relationalai as rai
   
   # Configure a model to use the "prod" profile.
   model = rai.Model("Example", profile="prod")

   Note

   The profile parameter takes precedence over both the active_profile key and the RAI_PROFILE environment variable.

Discovery

When models are created, the relationalai package looks for a raiconfig.toml file in the following locations, in order:

1. The current working directory.
2. One of the parent directories of the current working directory.
3. The ~/.rai directory in your home directory.

The first raiconfig.toml file found is used to configure the model.

Tip

Put your raiconfig.toml file in the ~/.rai directory to share profiles across multiple projects.

Config Objects

In some cases, you may want to integrate RAI into your application without relying on a configuration file.

To do so, create a Config object with a dictionary of configuration keys and pass it directly to the Model constructor:

import relationalai as rai

cfg = rai.Config({
    "platform": "snowflake",
    "authenticator": "snowflake",
    "user": "my_username",
    "password": "my_password",
    "account": "my_account_id",
    "role": "my_role",
    "warehouse": "my_warehouse",
    "rai_app_name": "relationalai",
})

model = rai.Model("Example", config=cfg)

See Getting Started: Cloud Notebooks for a complete example of using RAI in a cloud-based environment.

Any configuration keys missing from the Config object will be filled in with values from a raiconfig.toml file if one is present. This means you can use a Config object to override specific configuration values in a raiconfig.toml profile:

# Create a Config object with custom configuration values.
cfg = rai.Config({
    "role": "my_other_role",
    "warehouse": "my_other_warehouse",
})

# Override the role and warehouse values from the active raiconfig.toml profile.
model = rai.Model("Example", config=cfg)

# Use the "prod" profile but override the role and warehouse values.
model = rai.Model("Example", profile="prod", config=cfg)

Configuration Keys

The following keys may be specified in a raiconfig.toml profile or Config object:

Option	Description
platform	The platform to connect to. (Default: "snowflake")
snowflake_connection	The name of the Snowflake connection from your Snowflake connection file to use.
authenticator	The authentication method to use to connect to the platform. Required if snowflake_connection is missing. Available methods are: "snowflake" (Default): Username and password. "username_password_mfa": Username and password with multi-factor authentication (MFA). "externalbrowser": Single sign-on (SSO). "oauth_authorization_code": Interactive OAuth flow using a Snowflake security integration (public client). Requires oauth_client_id and oauth_redirect_uri. "programmatic_access_token": Programmatic access token for headless scenarios. Requires token_file_path. "snowflake_jwt": Key-pair (JWT) authentication. Requires private_key_file and optional private_key_file_pwd.
use_direct_access	Enables Direct Access for programmatic calls (Default: false). Supported authenticator options: “oauth_authorization_code" "programmatic_access_token" "snowflake_jwt”
oauth_client_id	Client ID from the Snowflake OAuth security integration.
oauth_redirect_uri	Redirect URI configured on the Snowflake OAuth security integration.
token_file_path	Path to a file containing the programmatic access token.
private_key_file	Path to the Snowflake private key file used for JWT authentication.
private_key_file_pwd	Password for the encrypted private key file (if applicable).
user	The username to use for authentication. This is the same username you use to sign in to https://app.snowflake.com. Required when using the "snowflake" or "username_password_mfa" authentication options.
password	The password to use for authentication. This is the same password you use to sign in to https://app.snowflake.com. Required when using the "snowflake" or "username_password_mfa" authentication options.
account	The account identifier of the Snowflake account to connect to in the form <ORG_NAME>-<ACCOUNT_NAME>. See Snowflake Account Identifiers for details. Required if snowflake_connection is missing.
role	The Snowflake role used by the model. Required if snowflake_connection is missing. (Default: "PUBLIC")
warehouse	The Snowflake warehouse used by the model. Required if snowflake_connection is missing.
rai_app_name	The name of the RAI native app used by the model. (Default: "relationalai")
engine	The name of the RAI engine used by the model. If missing, your Snowflake username is used as the engine name.
engine_size	The size of the RAI engine used by the model. (Default: "HIGHMEM_X64_S")
auto_suspend_mins	The number of minutes an engine must be inactive before being suspended. (Default: 60)
query_timeout_mins	The maximum number of minutes a query can run before timing out. (Default: 1440 (24 hours))
data_freshness_mins	The maximum allowed staleness (in minutes) for Snowflake table data. If the data is older, the table’s stream is synced before the next query.
wait_for_stream_sync	Whether to wait for data streams to sync before executing queries. (Default: True)
ensure_change_tracking	Whether to automatically enable change tracking, if needed, on tables or views passed to the source parameter of the model.Type() constructor. (Default: False)
debug	Whether to generate debug logs for use with the RAI debugger. (Default: True)
debug.host	The host name used for the RAI debugger. (Default: "localhost")
debug.port	The port number used for the RAI debugger. (Default: 8080)
show_full_traces	Whether to display full error stack traces for an improved debugging experience. (Default: False)

Snowflake Account Identifiers

In order to use RAI, you must provide your Snowflake account identifier to the account key in your raiconfig.toml file or Config object in the form <ORG_NAME>-<ACCOUNT_NAME>.

To find these values:

1. Log in to https://app.snowflake.com.
2. Look at the URL in our browser’s address bar, which has the form https://app.snowflake.com/<ORG_NAME>/<ACCOUNT_NAME>.

For example, if your URL is https://app.snowflake.com/plvoura/client_solutions, then the value you should use for account in your configuration is plvoura-client_solutions.

Authentication Methods

RAI supports multiple authentication methods for connecting to Snowflake. Use the authenticator key in your raiconfig.toml file or Config object to specify which method to use with your model.

Username and Password

The simplest method is to provide your Snowflake username and password in the user and password keys, respectively:

raiconfig.toml

[profile.default]
platform = "snowflake"
authenticator = "snowflake"
user = "<SNOWFLAKE_USERNAME>"
password = "<SNOWFLAKE_PASSWORD>"
account = "<SNOWFLAKE_ACCOUNT_ID>"
role = "<SNOWFLAKE_ROLE>"
warehouse = "<SNOWFLAKE_WAREHOUSE>"
rai_app_name = "relationalai"

Config Object

import relationalai as rai

cfg = rai.Config({
    "user": "<SNOWFLAKE_USERNAME>",
    "password": "<SNOWFLAKE_PASSWORD>",
    "account": "<SNOWFLAKE_ACCOUNT_ID>",
    "role": "<SNOWFLAKE_ROLE>",
    "warehouse": "<SNOWFLAKE_WAREHOUSE>",
    "rai_app_name": "relationalai",
})

model = rai.Model("Example", config=cfg)

Note that the authenticator key is not required when using this method, as it is the default. If you do wish to specify it, use "snowflake" as the value.

Multi-Factor Authentication (MFA)

If you have multi-factor authentication (MFA) enabled on your Snowflake account, use the "username_password_mfa" authenticator method:

raiconfig.toml

[profile.default]
platform = "snowflake"
authenticator = "username_password_mfa"  # Use multi-factor authentication
user = "<SNOWFLAKE_USERNAME>"
password = "<SNOWFLAKE_PASSWORD>"
account = "<SNOWFLAKE_ACCOUNT_ID>"
role = "<SNOWFLAKE_ROLE>"
rai_app_name = "relationalai"

Config Object

import relationalai as rai

cfg = rai.Config({
    "authenticator": "username_password_mfa",
    "user": "<SNOWFLAKE_USERNAME>",
    "password": "<SNOWFLAKE_PASSWORD>",
    "account": "<SNOWFLAKE_ACCOUNT_ID>",
    "role": "<SNOWFLAKE_ROLE>",
    "rai_app_name": "relationalai",
})

model = rai.Model("Example", config=cfg)

The first time you connect to Snowflake with MFA, and periodically thereafter, you will receive push notifications from the Duo Mobile app on your phone prompting you to approve a login request. Refer to the Snowflake documentation for more information on using MFA with Snowflake.

Single Sign-On (SSO)

Browser-based single sign-on (SSO) is supported by the "externalbrowser" authenticator method:

raiconfig.toml

[profile.default]
platform = "snowflake"
authenticator = "externalbrowser"  # Use single sign-on
role = "<SNOWFLAKE_ROLE>"
account = "<SNOWFLAKE_ACCOUNT_ID>"
rai_app_name = "relationalai"

Config Object

import relationalai as rai

cfg = rai.Config({
    "authenticator": "externalbrowser",
    "role": "<SNOWFLAKE_ROLE>",
    "account": "<SNOWFLAKE_ACCOUNT_ID>",
    "rai_app_name": "relationalai",
})

model = rai.Model("Example", config=cfg)

Note that when using the "externalbrowser" authenticator method, you will be prompted to select a Snowflake account and enter your credentials in a web browser window.

Caution

Browser-based SSO is not supported when running RAI from a server or other headless environment.

Snowflake Connection Files

You can use a raiconfig.toml and a Snowflake connection file together to store your Snowflake credentials in a single location. This also allows you to use any of the authentication methods supported in Snowflake connection files.

For example, you may have a ~/.snowflake/connections.toml file that looks like this:

~/.snowflake/connections.toml

[my-snowflake-connection]
account = "my_account"
user = "my_username"
password = "my_password"
warehouse = "my_warehouse"
database = "my_database"
schema = "my_schema"
role = "PUBLIC"

To use this connection in your raiconfig.toml file, set your profile’s snowflake_connection key to the connection name:

raiconfig.toml

active_profile = "default"

[profile.default]
platform="snowflake"
snowflake_connection = "my-snowflake-connection"
rai_app_name = "my_app_name"

Note

raiconfig.toml must specify any keys not present in ~/.snowflake/connections.toml. If there are any keys in common, the values in raiconfig.toml take precedence.

Snowflake Connection Objects

If you have an existing Snowflake Connection object from the snowflake-connector-python library, you can pass it directly to the connection parameter of the Model constructor:

raiconfig.toml

raiconfig.toml

[profile.default]
platform = "snowflake"
rai_app_name = "relationalai"

my_app.py

import snowflake.connector
import relationalai as rai

# Create a Snowflake connection.
conn = snowflake.connector.connect(
    user="<SNOWFLAKE_USERNAME>",
    password="<SNOWFLAKE_PASSWORD>",
    account="<SNOWFLAKE_ACCOUNT_ID>",
    warehouse="<SNOWFLAKE_WAREHOUSE>",
    role="<SNOWFLAKE_ROLE>",
)

# Create a RAI model using the Snowflake connection.
model = rai.Model("Example", connection=conn)

Config Object

import snowflake.connector
import relationalai as rai

# Create a Snowflake connection.
conn = snowflake.connector.connect(
    user="<SNOWFLAKE_USERNAME>",
    password="<SNOWFLAKE_PASSWORD>",
    account="<SNOWFLAKE_ACCOUNT_ID>",
    warehouse="<SNOWFLAKE_WAREHOUSE>",
    role="<SNOWFLAKE_ROLE>",
)

# Create a RAI model with a raiconfig.toml file using the default configuration
# and the custom Snowflake connection created above.
model = rai.Model("Example", config=rai.Config(), connection=conn)

This lets you authenticate with Snowflake using any of the methods supported by the snowflake-connector-python library and share this connection with your RAI model.

Note

The connection parameter takes precedence over all other authentication methods.

Direct Access

Direct Access sends programmatic calls directly to the RAI Native App’s secure ingress endpoint for lower latency. Learn more about Direct Access in the RAI Native App management guide.

To use Direct Access:

1. Enable direct access: Set use_direct_access = True in your raiconfig.toml profile or the equivalent a Config object.
2. Use a supported authentication method. Direct Access supports the following authentication methods:
   1. OAuth Authorization Code (best for interactive use)

      raiconfig.toml

      [profile.default]
      platform = "snowflake"
      use_direct_access = true
      authenticator = "oauth_authorization_code"
      oauth_client_id = "<OAUTH_CLIENT_ID>"
      oauth_redirect_uri = "<OAUTH_REDIRECT_URI>"  -- e.g. "http://localhost:8001/snowflake/oauth-redirect" (defined in the security integration)

   2. Programmatic Access Token (best for headless use and CI/CD)

      raiconfig.toml

      [profile.ci]
      platform = "snowflake"
      use_direct_access = true
      authenticator = "programmatic_access_token"
      token_file_path = "/secure/path/direct_access_token"

   3. Snowflake Key-Pair (best for service accounts and CI/CD)

      raiconfig.toml

      [profile.service]
      platform = "snowflake"
      use_direct_access = true
      authenticator = "snowflake_jwt"
      private_key_file = "/secure/path/rsa_key.p8"
      # private_key_file_pwd = "<password>"  # only if the key file is encrypted