Managing RAI Integrations

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.

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.

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.

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:

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:

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:

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

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.

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.

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.

See Also

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