Skip to content

Integration Management: RAI Integration

Learn how to manage and configure RAI integrations β€” a core component of the RAI Integration Services for Snowflake.

Introduction

What is a RAI Integration?

A RAI integration is the core element that brings the power of the Relational Knowledge Graph System (RKGS) to Snowflake.

πŸ”Ž

A RAI integration is a secure connection between your Snowflake account and RAI account.

Creating a RAI integration is the first step in setting up the RAI Integration Services for Snowflake.

This secure connection is established via a dedicated RAI OAuth client that is created with every RAI integration.

In detail, a RAI integration consists of two types of Snowflake integrations β€” a Snowflake API integration (opens in a new tab) and a Snowflake storage integration (opens in a new tab).

Everything depends on a RAI integration A RAI integration is essential if you want to perform almost any task within the RAI Integration Services. It is required for everything from creating a RAI database link to running a graph algorithm over your data.

πŸ”Ž

Every RAI database link and its accompanying SQL Library for Snowflake is associated with one RAI integration.

Consequently, all operations within this RAI database link will use the associated RAI integration to communicate with RAI resources.

A RAI integration can have multiple RAI database links. This is useful when multiple Snowflake databases have access to the RAI Integration Services.

Managing a RAI Integration

This section discusses how to create, update, and delete a RAI integration. It also provides details on how to retrieve information for a specific RAI integration.

To run a RAI CLI command, you must always specify your RAI profile, which stores your OAuth credentials. Your RAI profile is defined within your RAI config file located at <HOME_DIR>/.rai/config. See the CLI Configuration for more details.

Note that in some of the subsequent commands, the --profile flag option is omitted for readability. In this case, it is assumed the default RAI profile has the required admin privileges.

Creating a RAI Integration

To create a RAI integration, and register a RAI account with Snowflake, use the following CLI command:

rai create-snowflake-integration <rai_integration_name>  \
    --account=<sf_account_name>                          \
    --admin-username=<sf_username>                       \
    --admin-password=<sf_password>                       \
    --proxy-username=<sf_proxy_user>                     \
    --proxy-password=<sf_proxy_password>                 \
    --profile=<rai_admin_profile>

The first argument, <rai_integration_name>, is the RAI integration name.

⚠

A RAI integration name only supports alphanumeric characters.

The admin-related options refer to your Snowflake admin account. The proxy-related options refer to the proxy user.

With the RAI integration, you also create a dedicated RAI OAuth client called snowflake-<my_rai_integration_name>. This OAuth client will be used when the RAI integration talks to the RAI resources. This OAuth client belongs to the same RAI account as your admin OAuth client.

The table below explains each option for the rai create-snowflake-integration command:

OptionValueDescription
RAI integration name<rai_integration_name>RAI integration name. It can only contain alphanumeric characters.
Account<sf_account_name>Your Snowflake account name.
Admin username<sf_username>Your Snowflake admin username.
Admin password<sf_password>Your Snowflake admin password.
Proxy username<sf_proxy_user>Proxy username.
Proxy password<sf_proxy_password>Proxy password.
RAI profile<rai_admin_profile>RAI profile name.

Getting Information for a RAI Integration

You can retrieve RAI integration status information with the following CLI command:

rai get-snowflake-integration <rai_integration_name>

This gives the following JSON output:

{
    "id": "******",
    "kind": "SNOWFLAKE",
    "name": "<rai_integration_name>",
    "account": "<rai_account_name>",
    "createdBy": "**********@clients",
    "createdOn": "2023-06-26T00:02:00.755Z",
    "state": "CREATED",
    "consentUrl": "https://******",
    "snowflake": {
        "account": "<sf_account_name>"
    }
}

You can also check the RAI integration status by listing all available RAI integrations connected to your RAI account:

rai list-snowflake-integrations

Updating a RAI Integration

Updating the RAI integration means updating the associated proxy user and RAI OAuth client credentials provided during the RAI integration creation. To do so, use the following CLI command:

rai update-snowflake-integration <rai_integration_name>  \
    --rai-client-id=<oauth_client_id>                    \
    --rai-client-secret=<oauth_client_secret>            \
    --proxy-username=<sf_proxy_user>                     \
    --proxy-password=<sf_proxy_password>                 \
    --profile=<rai_admin_profile>

The table below explains each option for the rai update-snowflake-integration command:

OptionValueDescription
RAI integration name<rai_integration_name>RAI integration name.
RAI client ID<oauth_client_id>RAI OAuth client ID associated with the RAI integration.
RAI client secret<oauth_client_secret>RAI OAuth client secret associated with the RAI Integration.
Proxy username<sf_proxy_user>Proxy username associated with the RAI integration.
Proxy password<sf_proxy_password>Proxy password associated with the RAI integration.
RAI profile<rai_admin_profile>RAI profile name.

The update will change the credentials of the RAI OAuth client. You can manually change the permissions of the RAI OAuth client in the RAI Console. See Managing OAuth Clients for more details.

If you update the proxy user credentials, make sure they have also been updated in Snowflake. If you just want to change the password, see Resetting the Password for a User (opens in a new tab). If you want to use a new proxy user, please first create this new SQL user in Snowflake.

Deleting a RAI Integration

To unregister a RAI account with Snowflake, you need to delete the associated RAI integration with the following CLI command:

rai delete-snowflake-integration <rai_integration_name>  \
    --admin-username=<sf_username>                       \
    --admin-password=<sf_password>                       \
    --profile=<rai_admin_profile>

The table below explains each option for the rai delete-snowflake-integration command:

OptionValueDescription
RAI Integration name<rai_integration_name>RAI integration name.
Admin username<sf_username>Your Snowflake admin username.
Admin password<sf_password>Your Snowflake admin password.
RAI profile<rai_admin_profile>RAI profile name.

By deleting a RAI integration, you also delete any RAI database links and all SQL objects (RAI data streams, graphs) associated with it. For details, see Deleting a RAI Database Link.

Proxy User for a RAI Integration

The RAI integration permissions are primarily controlled via the proxy user, which is a dedicated Snowflake user that performs all SQL operations associated with the RAI Integration Services. For example, creating a SQL table that holds the results of a graph algorithm.

πŸ”Ž

You must specify the credentials for the proxy user when you create the RAI integration.

You can create a proxy user sf_proxy_user with a password as follows:

USE ROLE accountadmin;
CREATE USER sf_proxy_user PASSWORD = '<sf_proxy_password>';

Generally, it is advisable to add this proxy user directly to the user role used to manage the access control of the RAI integration:

USE ROLE accountadmin;
GRANT ROLE integration_user_role TO USER sf_proxy_user;

Access Control

Managing a RAI integration requires ACCOUNTADMIN privileges.

Users are granted access to the RAI integration via the Snowflake user role <integration_user_role>, which is specified when creating a RAI database link.

Privilege for Integration Usage As an ACCOUNTADMIN you need to grant usage privileges to this user role.

⚠

You need to grant usage privileges to two Snowflake integrations β€” an API integration and a storage integration. Both integrations are part of the RAI integration.

USE ROLE accountadmin;
 
-- Assign permissions on integration objects to user role.
GRANT USAGE ON INTEGRATION <rai_integration_name>  TO <integration_user_role>;
GRANT USAGE ON INTEGRATION <rai_integration_name>_storint TO <integration_user_role>;

The API integration has the same name as the RAI integration, <rai_integration_name>. The storage integration has the name <rai_integration_name>_storint. It has the suffix _storint added to its name.

πŸ”Ž

These integration-specific privileges need to be granted with every new RAI integration.

Privilege for Executing Tasks This user role also needs to be able to execute Snowflake tasks (opens in a new tab) as tasks are part of the RAI data streams which use the RAI integration.

USE ROLE accountadmin;
 
GRANT EXECUTE managed task ON account TO <integration_user_role>;
GRANT EXECUTE task ON account TO <integration_user_role>;

This permission is independent of the specific integration and only needs to be granted once.

General Snowflake Privilege

It’s best practice to grant the following schema and warehouse privileges to the <integration_user_role> as well:

USE ROLE accountadmin;
 
GRANT USAGE ON DATABASE my_sf_db TO ROLE <integration_user_role>;
GRANT CREATE SCHEMA ON DATABASE my_sf_db TO ROLE <<integration_user_role>>;
GRANT USAGE ON ALL SCHEMAS IN DATABASE my_sf_db TO ROLE integration_user_role;
 
GRANT OPERATE ON WAREHOUSE my_sf_wh TO ROLE <integration_user_role>;
GRANT USAGE ON WAREHOUSE my_sf_wh TO ROLE <integration_user_role>;

Add a Proxy User to the Integration User Role

The proxy user you create to manage the RAI integration permissions needs to be added to the user role integration_user_role so that the proxy can execute tasks and use the RAI integration.

USE ROLE accountadmin;
GRANT ROLE integration_user_role TO USER sf_proxy_user;

Authentication

A RAI integration authenticates itself on the RAI side via the RAI OAuth client. This OAuth client is created when you create a RAI integration. The name of the OAuth client is snowflake-<my_rai_integration_name>.

A RAI integration can only link to one RAI account because the associated OAuth client can only belong to one RAI account. If multiple RAI accounts are linked with a Snowflake account, each RAI account needs its own RAI integration.

πŸ”Ž

Updating a RAI integration means updating the associated OAuth client.

For more details, see Updating a RAI Integration.

You can change the permissions of the OAuth client of the RAI integration, though it is not advisable to do so.

Global Integration Parameters

By default, Snowflake’s timeout limit for queries is set to ten minutes. This may not be enough for long-running queries executing algorithms within the SQL Library for Snowflake.

You can request an extension to this timeout limit and increase it. This is based on your expected needs in terms of:

  1. Data size.
  2. The graph algorithms that your account users intend to use.
⚠

If you need to increase your Snowflake account timeout limit, please get in touch with your RAI contact person.

See Also

For more information on configuring and managing RAI database links, check out the RAI Database Link guide.

Was this doc helpful?