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.

Table of Contents#

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(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 environments, such as Snowflake or other cloud-based Python notebooks, you may not be able to create a raiconfig.toml file. Or 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(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(config=cfg)

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

Configuration Keys#

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

OptionDescription
platformThe platform to connect to. (Default: "snowflake")
snowflake_connectionThe name of the Snowflake connection from your Snowflake connection file to use.
authenticatorThe 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).
userThe 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.
passwordThe 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.
accountThe 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.
roleThe Snowflake role used by the model. Required if snowflake_connection is missing. (Default: "PUBLIC")
warehouseThe Snowflake warehouse used by the model. Required if snowflake_connection is missing.
rai_app_nameThe name of the RAI native app used by the model. (Default: "relationalai")
engineThe name of the RAI engine used by the model. If missing, your Snowflake username is used as the engine name.
engine_sizeThe size of the RAI engine used by the model. (Default: "HIGHMEM_X64_S")
debugWhether to generate debug logs for use with the RAI debugger. (Default: True)
debug.hostThe host name used for the RAI debugger. (Default: "localhost")
debug.portThe port number used for the RAI debugger. (Default: 8080)

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:

[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"

Multi-Factor Authentication (MFA)#

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

[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"

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:

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

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.

IMPORTANT

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

[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(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.