RelationalAI CLI

This guide presents the main features of the RelationalAI Command-Line Interface, which is used to interact with RelationalAI’s Relational Knowledge Graph System (RKGS).

The rai-cli is open source and is available in the GitHub repository:

RelationalAI/rai-sdk-cli

Contributions and pull requests are welcome.

Note: This guide applies to rai-cli, the latest iteration of the RelationalAI CLI. The relationalai-sdk package is deprecated.

Installation

To use the CLI, you can directly download a binary for your installation from the rai-cli releases (opens in a new tab).

You can find precompiled binaries for MacOS, Linux, and Windows for different architectures. After selecting the one that fits your system, you can unzip the archive and include the rai binary in your system’s path.

Configuration

To connect to the RAI Server using the RelationalAI CLI, you need a configuration file. See SDK Configuration for more details.

The CLI allows you to specify a configuration to use for connecting to the RAI Server. You can specify which configuration to use through the --config and --profile flags. The first flag specifies the file to use, while the second one specifies the name of the configuration. Here’s an example using the ./myconfig file with the default profile to list all databases:

rai --config=./myconfig --profile=default list-databases

To load a different configuration from within a configuration file, you can replace default with a different profile name.

Managing Users

This section covers the CLI commands that you need to manage users.

Creating a User

You can create a user using the create-user command in the CLI. To create a user, you need to specify an email and, optionally, a set of roles for the user:

rai create-user user@relational.ai --role=user

Here, user@relational.ai is a string identifying the user. The --role flag allows you to provide a role for the specific user that is about to be created. The roles currently supported are user and admin. user is the default role if no role is specified.

Disabling and Enabling a User

You can disable a user using the disable-user command:

rai disable-user auth0|123456789

In this case, auth0|123456789 is a string representing a given user’s ID, as returned within the response in the user creation example above.

You can reenable the user by using the enable-user command:

rai enable-user auth0|123456789

Listing Users

You can list users using the CLI list-users command as follows:

rai list-users

Getting Information for a User

You can get information for a user using the CLI get-user command as follows:

rai get-user auth0|123456789

Here, similarly to disable-user above, you need to provide a string ID uniquely identifying the user, such as "auth0|XXXXXXXXXXXXXXXXXX".

Finding Users Using Email

You can look up a user’s details by specifying their email through the CLI find-user command:

rai find-user user@relational.ai

Deleting a User

You can delete a user by using the delete-user command:

rai delete-user auth0|123456789

Managing OAuth Clients

This section covers the CLI commands that you need to manage OAuth clients.

Creating an OAuth Client

You can create an OAuth client as follows:

rai create-oauth-client name --perms=permissions

Here, name is a string identifying the client. permissions is a list of permissions from the following supported permissions:

• create:accesskey
• create:engine
• create:oauth_client
• create:user
• delete:engine
• delete:database
• delete:oauth_client
• list:accesskey
• list:engine
• list:database
• list:oauth_client
• list:permission
• list:role
• list:user
• read:engine
• read:credits_usage
• read:oauth_client
• read:role
• read:user
• rotate:oauth_client_secret
• run:transaction
• update:database
• update:oauth_client
• update:user

Listing OAuth Clients

You can get a list of OAuth clients as follows:

rai list-oauth-clients

Getting Information for an OAuth Client

You can get details for a specific OAuth client, identified by the string client-id, as follows:

rai get-oauth-client client-id

Deleting an OAuth Client

You can delete an OAuth client identified by the string client-id as follows:

rai delete-oauth-client client-id

Managing Engines

This section covers the CLI commands that you need to manage engines.

Creating an Engine

You can create a new engine as follows:

rai create-engine my_engine

By default, the engine size is XS. You can create an engine of a different size by specifying the --size flag:

rai create-engine my_engine --size=S

Valid sizes are given as a string and can be one of:

• XS (extra small).
• S (small).
• M (medium).
• L (large).
• XL (extra large).

Listing Engines

You can list all engines associated with your account using the following command:

rai list-engines

This returns a JSON array containing details for each engine:

[
    {
        "id": "ca******",
        "name": "my_engine",
        "region": "us-east",
        "account_name": "******",
        "created_by": "******",
        "created_on": "2023-07-10T17:15:22.000Z",
        "size": "S",
        "state": "PROVISIONED"
    }
]

To list engines that are in a given state, you can use the --state flag:

rai list-engines --state=PROVISIONED

Possible states are:

• "REQUESTED".
• "PROVISIONING".
• "PROVISIONED".
• "DEPROVISIONING".

Getting Information for an Engine

You can get information for a specific engine using the following command:

rai get-engine my_engine

This gives you the following output:

{
    "id": "******",
    "name": "my_engine",
    "region": "us-east",
    "account_name": "******",
    "created_by": "******",
    "created_on": "2023-07-10T17:15:22.000Z",
    "size": "S",
    "state": "PROVISIONED"
}

Deleting an Engine

You can delete an engine with:

rai delete-engine my_engine

RelationalAI decouples computation from storage. Therefore, deleting an engine does not delete any cloud databases. See Managing Engines for more details.

Managing Databases

This section covers the CLI commands you need to manage databases.

Creating a Database

You can create a database using the following command:

rai create-database my_database

The result from a successful create-database command looks like this:

{
    "id": "******",
    "name": "my_database",
    "region": "us-east",
    "account_name": "******",
    "created_by": "******",
    "created_on": "2023-07-10T17:15:22.000Z",
    "state": "CREATED"
}

Cloning a Database

You can clone a database by specifying the target and source databases, in that order. Here’s an example that clones my_database to my_database_clone:

rai clone-database my_database_clone my_database

Any subsequent changes to either database will not affect the other. Cloning a database fails if the source database does not exist.

Listing Databases

You can list the available databases within your account as follows:

rai list-databases

This returns a JSON array containing details for each database:

[
    {
        "id": "******",
        "name": "my_database",
        "region": "us-east",
        "account_name": "******",
        "created_by": "******",
        "created_on": "2023-07-20T08:03:03.616Z",
        "state": "CREATED"
    }
]

To filter databases by state, you can use the --state flag. For instance:

rai list-databases --state=CREATED

Possible states are:

• "CREATED".
• "CREATING".
• "CREATION_FAILED".
• "DELETED".

Getting Information for a Database

You can get information for a specific database as follows:

rai get-database my_database

This gives you the following output:

{
    "id": "******",
    "name": "my_database",
    "region": "us-east",
    "account_name": "******",
    "created_by": "******",
    "created_on": "2023-07-20T08:03:03.616Z",
    "state": "CREATED"
}

If the database does not exist, a Not found error is returned.

Deleting a Database

You can delete a database using the following command:

rai delete-database my_database

Managing Rel Models

This section covers the CLI commands you can use to manage Rel models.

Rel models are collections of Rel code that can be added, updated, or deleted from a dedicated database. A running engine — and a database — is required to perform operations on models.

Loading a Model

The load-model command loads a Rel model in a given database. It takes as input the database, the engine, the model name, and the filename from which the model is read. If no engine is specified using the --engine flag, the system automatically assigns the latest created engine within the configuration profile you are using. If no name is specified using the --model flag, the filename is used as the name of the model.

For example, consider the following simple Rel model, stored in a file named hello.rel:

def R = "hello", "world"

Here’s an example that loads my_model to my_database using my_engine from the hello.rel file:

rai load-model my_database --engine=my_engine --model=my_model hello.rel

Loading Multiple Models

You can load a number of models using a list of files through the load-models command. Here’s an example that loads model1.rel, model2.rel, and model3.rel in my_database using my_engine:

rai load-models my_database --engine=my_engine model1.rel model2.rel model3.rel

In case you want to group the models in the database, you can use the --prefix string flag. Here’s an example that uses my_model as a prefix:

rai load-models my_database --engine=my_engine model1.rel model2.rel model3.rel --prefix=my_model

Listing Models

You can list the models in a database as follows:

rai list-model-names my_database --engine=my_engine

This returns a JSON array of names:

[
  "rel/alglib",
  "rel/display",
  "rel/graph-basics",
  "rel/graph-centrality",
  "rel/graph-components",
  "rel/graph-degree",
  "rel/graph-measures",
  "rel/graph-paths",
  "rel/histogram",
  "rel/intrinsics",
  "rel/mathopt",
  "rel/mirror",
  "rel/net",
  "rel/stdlib",
  "rel/vega",
  "rel/vegalite"
]

In the example above, you can see all the built-in models associated with a database.

You can also list all the models and their code using the list-models command:

rai list-models my_database --engine=my_engine

Getting Information for a Model

To see the contents of a given model — for example, my_model — you can use:

rai get-model my_database my_model --engine=my_engine

This gives the following output:

{
  "name": "my_model",
  "value": "def my_range(x) = range(1, 10, 1, x)"
}

In the example above, my_model defines a specific range.

Deleting a Model

You can delete a model from a database by using the delete-models command and providing the model’s name like this:

rai delete-models my_database --engine=my_engine model1

Deleting Multiple Models

You can delete more than one model at once by specifying multiple names in the delete-models command like this:

rai delete-models my_database --engine=my_engine model1 model2 model3

Querying a Database

The command for executing queries against the database is exec. Each query is a complete transaction, executed in the context of the provided database.

By default, exec calls execute write queries, which update base relations in the database through the control relations insert and delete.

Here’s a Rel code that loads some CSV data and stores them in the base relation mybaserelation:

def mydata = """
name,lastname,id
John,Smith,1
Peter,Jones,2
"""
 
def config:schema:name="string"
def config:schema:lastname="string"
def config:schema:id="int"
def config:syntax:header_row=1
def config:data = mydata
def delete[:mybaserelation] = mybaserelation
def insert[:mybaserelation] = load_csv[config]

You can execute it as a write query as follows:

rai exec my_database --engine=my_engine --file=csv-example.rel

You can provide exec with a query either through a command-line string or through a file. Here’s an example of the exec command for a read query:

rai exec my_database --engine=my_engine --code="def output[x in {1;2;3}] = x * 2" --readonly

Consider a file simple.rel containing the previous query. You can execute it by specifying the file name as follows:

rai exec my_database --engine=my_engine --file=simple.rel --readonly

The output in both cases is:

/:output/Int64/Int64
1, 2
2, 4
3, 6

Note that the read queries above include the --readonly flag.

Getting Multiple Relations Back

To return multiple relations, you can define subrelations of output. Here’s an example:

rai exec my_database    \
    --engine=my_engine  \ 
    --code="def a = 1;2 def b = 3;4 def output:one = a def output:two = b"

This gives the following output:

// "output", "one", int64
output, one, 1;
output, one, 2

// "output", "two", int64
output, two, 3;
output, two, 4

Result Structure

The response has the following keys:

Transaction

The transaction key is a JSON string with the following fields:

For example:

{
    "id": "******",
    "state": "COMPLETED"
}

Results

The results key is a vector with the following fields:

For example:

// "output", int64
output, 1;
output, 2;
output, 3

Problems

The problems key reports the following:

For example:

rel, catalog, diagnostic, message, 1, Missing closing `}`., <nil>, <nil>, <nil>;
rel, catalog, diagnostic, range, end, character, 1, 1, 19;
rel, catalog, diagnostic, range, end, line, 1, 1, 1;
rel, catalog, diagnostic, range, start, character, 1, 1, 14;
rel, catalog, diagnostic, range, start, line, 1, 1, 1;
rel, catalog, diagnostic, report, 1, 1| def output = {1;2;3
                ^~~~~~
, <nil>, <nil>, <nil>;
rel, catalog, diagnostic, severity, 1, error, <nil>, <nil>, <nil>;
rel, catalog, diagnostic, code, 1, PARSE_ERROR, <nil>, <nil>, <nil>

Printing Responses

The CLI allows you to get responses back in two different formats by specifying the --format flag.

The default format, called pretty, returns results in text form. Here’s an example:

rai exec my_database --engine=my_engine --code="def output='a';'b';'c'"

This is equivalent to:

rai exec my_database --engine=my_engine --format=pretty --code="def output='a';'b';'c'"

This command produces the following output:

/:output/Char
97
98
99

You can change the output format to JSON by changing the --format flag. Here’s the same example producing a JSON output:

rai exec my_database --engine=my_engine --format=json --code="def output='a';'b';'c'"

This command produces the following output:

{
    "GotCompleteResult": true,
    "Transaction": {
        "id": "e3057f0d-27cb-6224-1086-f3d86bafe6ae",
        "state": "COMPLETED"
    },
    "Results": [
        {
            "RelationID": "/:output/Char",
            "Table": [
                [
                    97,
                    98,
                    99
                ]
            ]
        }
    ],
    "Metadata": {
        "relations": [
        {
            "relation_id": {
                "arguments": [
                    {
                        "tag": 3,
                        "constant_type": {
                            "rel_type": {
                                "tag": 1,
                                "primitive_type": 16
                            },
                            "value": {
                                "arguments": [
                                    {
                                        "tag": 16,
                                        "Value": {
                                            "StringVal": "b3V0cHV0"
                                        }
                                    }
                                ]
                            }
                        }
                    },
                    {
                        "tag": 1,
                        "primitive_type": 14
                    }
                ]
            },
            "file_name": "0.arrow"
        }
        ]
    },
    "Problems": []
}

The JSON format has more detailed information on the results, including internal metadata and any potential problems that may have occured.

Here’s an example code that produces a problem since aaa is undefined:

rai exec my_database --engine=my_engine --format=json --code="def output=aaa"

This populates the following text in the "Problems" section of the JSON output:

{
...
    "Problems": [
        {
            "type": "ClientProblem",
            "error_code": "UNDEFINED",
            "is_error": true,
            "is_exception": false,
            "message": "`aaa` is undefined.",
            "report": "1| def output=aaa\n  ^^^\n\nThe problem occurred while compiling declaration `output`:\n1| def output=aaa\n ^^^\n\n"
        }
    ]
}

Loading Data

The load-csv and load-json commands allow you to load data into a database. These are not strictly necessary, since the Rel load utilities can also be used for this task. See the Data I/O: CSV Import and Data I/O: JSON Import guides for more details.

Loading CSV Data

The load-csv command loads CSV data from a file and inserts the result into the base relation specified by the --relation flag. If no relation is specified, the data are loaded in a relation named after the provided data source file.

Additionally, load-csv attempts to guess the schema of the data. For more control over the schema and parsing of the data, load-csv provides additional flags. Specifically:

Here are the contents of an example CSV file with four columns four-cols.csv:

cocktail,quantity,price,date
"martini",2,12.50,"2020-01-01"
"sazerac",4,14.25,"2020-02-02"
"cosmopolitan",4,11.00,"2020-03-03"
"bellini",3,12.25,"2020-04-04"

You can load this file in the relation fourcols using the CLI as follows:

rai load-csv my_database four-cols.csv --relation=fourcols

You can view the loaded data using the exec command:

rai exec my_database --code="def output=fourcols"

This gives the following output:

// "output", "cocktail", int64, string
output, cocktail, 2, martini;
output, cocktail, 3, sazerac;
output, cocktail, 4, cosmopolitan;
output, cocktail, 5, bellini

// "output", "date", int64, string
output, date, 2, 2020-01-01;
output, date, 3, 2020-02-02;
output, date, 4, 2020-03-03;
output, date, 5, 2020-04-04

// "output", "price", int64, string
output, price, 2, 12.50;
output, price, 3, 14.25;
output, price, 4, 11.00;
output, price, 5, 12.25

// "output", "quantity", int64, string
output, quantity, 2, 2;
output, quantity, 3, 4;
output, quantity, 4, 4;
output, quantity, 5, 3

Note that all columns from the CSV file are imported as strings.

You can specify the schema through the --schema flag. Here’s an example that specifies a different schema for each column of the CSV file and loads the data in the fourcols_schema relation:

rai load-csv my_database four-cols.csv  \
    --relation=fourcols_schema          \
    --schema="cocktail:string;quantity:int;price:float;date:date"

You can now view the newly loaded data using the exec command:

rai exec my_database --engine=my_engine --code="def output=fourcols_schema"

This gives the following output:

// "output", "cocktail", int64, string
output, cocktail, 2, martini;
output, cocktail, 3, sazerac;
output, cocktail, 4, cosmopolitan;
output, cocktail, 5, bellini

// "output", "date", int64, time.Time
output, date, 2, 2020-01-01;
output, date, 3, 2020-02-02;
output, date, 4, 2020-03-03;
output, date, 5, 2020-04-04

// "output", "price", int64, float64
output, price, 2, 12.5;
output, price, 3, 14.25;
output, price, 4, 11;
output, price, 5, 12.25

// "output", "quantity", int64, int64
output, quantity, 2, 2;
output, quantity, 3, 4;
output, quantity, 4, 4;
output, quantity, 5, 3

Loading JSON Data

The load-json command loads JSON data from a file and inserts them into the base relation specified through the --relation flag. If no relation is specified, the data are loaded in a relation named after the provided data source file.

Here’s an example JSON file john.json:

{
    "first_name": "John",
    "last_name": "Smith",
    "address": {
        "city": "Seattle",
        "state": "WA" },
    "phone": [
        { "type": "home",
        "number": 206456 },
        { "type": "work",
        "number": 206123 }
    ]
}

You can load these data into a john relation using the CLI as follows:

rai load-json my_database john.json --relation=john

You can view the loaded data as follows:

rai exec my_database --engine=my_engine --code="def output=john"

This gives the following output:

// "output", "last_name", string
output, last_name, Smith
 
// "output", "phone", "[]", int64, "number", int64
output, phone, [], 1, number, 206456;
output, phone, [], 2, number, 206123
 
// "output", "phone", "[]", int64, "type", string
output, phone, [], 1, type, home;
output, phone, [], 2, type, work
 
// "output", "address", "city", string
output, address, city, Seattle
 
// "output", "address", "state", string
output, address, state, WA
 
// "output", "first_name", string
output, first_name, John
 

Using the CLI, you can run:

rai exec my_database --engine=my_engine --code="def delete[:john]=john"

This clears the base relation john.

Listing Base Relations

You can list the base relations in a given database as follows:

rai list-edbs my_database

The result is a JSON list of objects.

RAI Integration Services for Snowflake

The RelationalAI CLI includes specific commands to interact with the RAI Integration Services for Snowflake.

This means that Snowflake names can only contain letters, digits, underscores _, and dollar signs $. For instance, hyphens, -, are not allowed in Snowflake names.

Snowflake Environment Variables

It is possible to store default values for CLI flag options in environment variables. By doing so, you don’t need to explicitly specify these flag options when executing commands. This is convenient for variables that don’t change very often, such as your Snowflake username.

Here is a list of available variables that can be stored in environment variables:

For instance, say you’re creating a RAI integration using the following command:

rai create-snowflake-database-link myintegration  \
    --database=my_sf_db                           \
    --role=integration_user_role                  \
    --username=my_sf_username                     \
    --password=my_sf_password

You can simplify this to:

rai create-snowflake-database-link myintegration

The Snowflake-related information can be stored in environment variables as follows:

export SNOWSQL_USER = my_sf_username
export SNOWSQL_PWD = my_sf_password
export SNOWSQL_ROLE = integration_user_role
export SNOWSQL_DATABASE = my_sf_db

If you want to have the environment variables set permanently, you can store them in your terminal config file, like ~/.bashrc for the Bash shell.

Managing RAI Integrations

This section covers the CLI commands to configure and manage RAI integrations.

A RAI integration is a secure connection between a Snowflake account and a RAI account. It is required for almost any task within the RAI Integration Services, from creating a RAI database link to running a graph algorithm over your data.

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

See RAI Integration for more details.

Creating a RAI Integration

You can create a new RAI integration as follows:

rai create-snowflake-integration myintegration  \
    --account=my_sf_account_name                \
    --admin-username=my_sf_username             \
    --admin-password=my_sf_password             \
    --proxy-username=my_sf_proxy_user           \
    --proxy-password=my_sf_proxy_password

To see all argument and flag options, you can use rai create-snowflake-integration -h.

The mandatory arguments are the following:

Positional Arguments

Flag Arguments

Listing RAI Integrations

You can list all available RAI integrations connected to your RAI account as follows:

rai list-snowflake-integrations

Note that the RAI account is determined by the OAuth client you specified in your RAI profile. If not specified, the RAI profile default is automatically selected.

If the command was successful, you will receive a JSON array that shows the RAI integration information:

List Snowflake integrations ..
Ok (2.6s)

[
    {
        "id": "6f******",
        "kind": "SNOWFLAKE",
        "name": "myintegration",
        "account": "my_rai_account_name",
        "createdBy": "**********@clients",
        "createdOn": "2023-06-26T00:02:00.755Z",
        "state": "CREATED",
        "consentUrl": "https://******",
        "snowflake": {
            "account": "my_sf_account_name"
        }
    }
]

Getting Information for a RAI Integration

You can get information about an existing RAI integration as follows:

rai get-snowflake-integration myintegration

To see all argument and flag options, you can use rai get-snowflake-integration -h.

The mandatory arguments are the following:

Positional Arguments

If successful, you will receive a response that shows the RAI integration information in JSON format:

Get Snowflake integration 'myintegration' ..
Ok (0.7s)

{
    "id": "6f******",
    "kind": "SNOWFLAKE",
    "name": "myintegration",
    "account": "my_rai_account_name",
    "createdBy": "**********@clients",
    "createdOn": "2023-06-26T00:02:00.755Z",
    "state": "CREATED",
    "consentUrl": "https://******",
    "snowflake": {
        "account": "my_sf_account_name"
    }
}

Updating a RAI Integration

You can update an existing RAI integration as follows:

rai update-snowflake-integration myintegration  \
    --rai-client-id=your_client_id              \
    --rai-client-secret=your_client_secret      \
    --proxy-username=my_sf_proxy_user           \
    --proxy-password=my_sf_proxy_password

To see all argument and flag options, you can use rai update-snowflake-integration -h.

The mandatory arguments are the following:

Positional Arguments

Flag Arguments

Deleting a RAI Integration

You can delete an existing RAI integration as follows:

rai delete-snowflake-integration myintegration  \
    --admin-username=my_sf_username             \
    --admin-password=my_sf_password             \

To see all argument and flag options, you can use rai delete-snowflake-integration -h.

The mandatory arguments are the following:

Positional Arguments

Flag Arguments

Managing RAI Database Links

This section covers the CLI commands you need to configure and manage a RAI database link.

A RAI database link is located in a Snowflake database and schema, where it installs the SQL Library for Snowflake. The management of the various RAI resources that are enabled by the SQL Library for Snowflake also happens inside a RAI database link.

A RAI database link is associated with a single RAI integration and uses it to communicate with the RAI resources. However, multiple RAI database links can use the same RAI integration.

See RAI Database Link for more details.

Creating a RAI Database Link

You can create a new RAI database link within a RAI integration as follows:

rai create-snowflake-database-link myintegration  \
    --database=my_sf_db                           \
    --role=integration_user_role                  \
    --schema=rai                                  \
    --username=my_sf_username                     \
    --password=my_sf_password

To see all argument and flag options, you can use rai create-snowflake-database-link -h.

The mandatory arguments are the following:

Positional Arguments

Flag Arguments

Listing RAI Database Links

You can list all available RAI database links within a specific RAI integration, such as myintegration, as follows:

rai list-snowflake-database-links myintegration

To see all argument and flag options, you can use rai list-snowflake-database-links -h.

The mandatory arguments are the following:

Positional Arguments

If successful, you will receive a JSON array that shows the RAI database link information:

List Snowflake database links (myintegration) ..
Ok (1.0s)

[
    {
        "id": "08******",
        "name": "my_sf_db.rai",
        "account": "my_rai_account_name",
        "createdBy": "******n@clients",
        "createdOn": "2023-06-13T23:13:11.492Z",
        "state": "CREATED",
        "integration": "myintegration",
        "snowflake": {
            "database": "my_sf_db",
            "schema": "rai"
        }
    }
]

Getting Information for a RAI Database Link

You can get information about an existing RAI database link as follows:

rai get-snowflake-database-link myintegration  \
    --database=my_sf_db                        \
    --schema=rai

To see all argument and flag options, you can use rai get-snowflake-database-link -h.

The mandatory arguments are the following:

Positional Arguments

Flag Arguments

If successful, you will receive a response that shows the data stream information in JSON format:

{
    "id": "08******",
    "name": "my_sf_db.rai",
    "account": "my_rai_account_name",
    "createdBy": "******n@clients",
    "createdOn": "2023-06-13T23:13:11.492Z",
    "state": "CREATED",
    "integration": "myintegration",
    "snowflake": {
        "database": "my_sf_db",
        "schema": "rai"
    }
}

Updating a RAI Database Link

You can update an existing RAI database link for a specific RAI integration as follows:

rai update-snowflake-database-link myintegration  \
    --database=my_sf_db                           \
    --role=integration_user_role                  \
    --schema=rai                                  \
    --username=my_sf_username                     \
    --password=my_sf_password

To see all argument and flag options, you can use rai update-snowflake-database-link -h.

The mandatory arguments are the following:

Positional Arguments

Flag Arguments

General Remarks

The command rai update-snowflake-database-link only adds new or overwrites existing functions and procedures.

To ensure you have an updated RAI database link — without any outdated functionality — you need to delete and recreate the database link:

rai delete-snowflake-database-link myintegration
rai create-snowflake-database-link myintegration

However, deleting a RAI database link will also delete all your RAI data streams along with other objects managed by the RAI database link.

Deleting a RAI Database Link

You can delete an existing RAI database link as follows:

rai delete-snowflake-database-link myintegration  \
    --database=my_sf_db                           \
    --role=integration_user_role                  \
    --schema=rai                                  \
    --username=my_sf_username                     \
    --password=my_sf_password

To see all argument and flag options, you can use rai delete-snowflake-database-link -h.

The mandatory arguments are the following:

Positional Arguments

Flag Arguments

Managing RAI Data Streams

This section covers the CLI commands you need to manage RAI data streams.

A RAI data stream synchronizes your data from a Snowflake database to a RAI database. It originates from a Snowflake SQL object, such as a table or a view, and targets a RAI base relation. It is associated with a RAI database link, which manages this synchronization.

See RAI Data Streams for more details.

Creating a RAI Data Stream

You can create a RAI data stream using the following command:

rai create-snowflake-data-stream myintegration my_sf_db.rai my_sf_db.my_sf_schema.my_sf_object  \
    --username=my_sf_username                                                                   \
    --password=my_sf_password                                                                   \
    --rai-database=my_rai_db                                                                    \
    --rai-relation=my_rai_relation                                                              \
    --role=integration_user_role                                                                \
    --warehouse=my_sf_wh

To see all argument and flag options, you can use rai create-snowflake-data-stream -h.

The mandatory arguments are the following:

Positional Arguments

Flag Arguments

General Remarks

By default, the RAI database link is located in the Snowflake schema rai. See Creating a RAI Database Link for more details.

Your Snowflake objects can be located in any Snowflake schema. However, it is advisable to locate them within your working schema, for example, my_sf_schema.

Listing RAI Data Streams

You can list all available RAI data streams within a specific RAI integration and database link as follows:

rai list-snowflake-data-streams myintegration my_sf_db.rai

To see all argument and flag options, you can use rai list-snowflake-data-streams -h.

The mandatory arguments are the following:

Positional Arguments

If successful, you will receive a JSON array that shows the RAI data stream information:

List Snowflake dataStreams linked to my_sf_db.rai (myintegration) ..
Ok (2.3s)

[
    {
        "account": "******",
        "id": "******",
        "name": "my_sf_db.my_sf_schema.my_sf_object",
        "integration": "myintegration",
        "dbLink": "my_sf_db.rai",
        "createdBy": "******@****",
        "createdOn": "2023-06-26T19:48:55.650Z",
        "state": "CREATED",
        "snowflake": {
            "database": "my_sf_db",
            "schema": "rai",
            "object": "my_sf_db.my_sf_schema.my_sf_object"
        },
        "rai": {
            "database": "my_rai_db",
            "relation": "my_rai_relation"
        }
    }
]

Getting Information for a RAI Data Stream

You can get information for a specific RAI data stream using the following command:

rai get-snowflake-data-stream myintegration my_sf_db.rai my_sf_db.my_sf_schema.my_sf_object

This command only includes metadata information for the RAI data stream.

If you want to retrieve the status of a specific RAI data stream, you need to use the following command:

rai get-snowflake-data-stream-status myintegration my_sf_db.rai my_sf_db.my_sf_schema.my_sf_object

See Monitor a Data Stream for more details.

To see all argument and flag options, you can use rai get-snowflake-data-stream -h and rai get-snowflake-data-stream-status -h.

The mandatory arguments are the following:

Positional Arguments

If successful, you will receive a response that shows the RAI data stream information with the rai get-snowflake-data-stream command:

Get Snowflake data stream my_sf_db.my_sf_schema.my_sf_object (myintegration) ..
Ok (1.0s)

{
    "account": "******",
    "id": "******",
    "name": "my_sf_db.my_sf_schema.my_sf_object",
    "integration": "myintegration",
    "dbLink": "my_sf_db.rai",
    "createdBy": "******@****",
    "createdOn": "2023-06-26T19:48:55.650Z",
    "state": "CREATED",
    "snowflake": {
        "database": "my_sf_db",
        "schema": "rai",
        "object": "my_sf_db.my_sf_schema.my_sf_object"
    },
    "rai": {
        "database": "my_rai_db",
        "relation": "my_rai_relation"
    }
}

To get the RAI data stream status, use the rai get-snowflake-data-stream-status command:

Get Snowflake data stream status my_sf_db.rai (myintegration) ..

{
    "account": "************",
    "id": "************",
    "name": "myintegration.my_sf_db.my_sf_schema.my_sf_object",
    "raiLoadEnd": ************,
    "snowflakeUnloadStart": ************
}

Deleting a RAI Data Stream

You can delete an existing RAI data stream using the following command:

rai delete-snowflake-data-stream myintegration my_sf_db.rai my_sf_db.my_sf_schema.my_sf_object  \
    --username=my_sf_username                                                                  \
    --password=my_sf_password                                                                  \
    --role=integration_user_role                                                               \
    --warehouse=my_sf_wh

To see all argument and flag options, you can use rai delete-snowflake-data-stream -h.

The mandatory arguments are the following:

Positional Arguments

Flag Arguments