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
  • Profiles
  • Discovery
• Config Objects
• Configuration Keys
• Snowflake Account Identifiers
• Authentication Methods
  • Username and Password
  • Multi-Factor Authentication (MFA)
  • Single Sign-On (SSO)
  • Snowflake Connection Files
  • Snowflake Connection Objects

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.

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:

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"

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)

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"

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:

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

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.

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"

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("Example", connection=conn)

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.