RelationalAI Native App Installation#
This guide provides a step-by-step walkthrough for installing and setting up the RelationalAI (RAI) Native App for Snowflake.
I. Install the RAI Native App for Snowflake#
Log in to Snowsight as an ORGADMIN
or ACCOUNTADMIN
and follow these steps to install the RAI Native App:
- View the RelationalAI marketplace listing and fill out the access request form. A RelationalAI representative will notify you when access is enabled for your account.
- Once access is enabled, navigate to Data Products > Apps in the left-hand sidebar in Snowsight. You should see RelationalAI under Recently Shared with You. Click Buy to open a dialogue box with pricing details. Click the Buy button in the dialogue box to proceed. Click “View your apps” in the resulting modal to go back to the Data Products > Apps page. You should see RelationalAI listed under Installed Apps.
- You may see a spinner in the INSTALLED column, indicating that the app is still being installed. Wait until installation completes, at which point you’ll see a message like “1 minute ago” in that column.
- Click on the name of the application to open the app.
- Click Grant to grant the application the necessary privileges.
- The
EXECUTE TASK
andEXECUTE MANAGED TASK
privileges are required to share data from your Snowflake account with the RAI Native App. - The
CREATE WAREHOUSE
andCREATE COMPUTE POOL
privileges are required by the RAI Native App to create and manage resources for performing service operations.
- The
- Click Activate to activate the application.
II. Set Up the RAI Native App#
To complete the steps in this section:
- Download the installation notebook.
- Go to https://app.snowflake.com and select + Create Projects > Notebook > Import .ipynb File at the top of the left sidebar.
- Upload the
relationalai-installation.ipynb
file. - Choose a database and schema to save the notebook in.
- Any database and schema will do — you can delete the notebook after installation.
- If you don’t have any database available in the dropdown, you can create one by doing
create database <name>;
from a SQL worksheet.
- Choose Run on warehouse and click Create.
- Upload the
- Click the Run All button or run the cells one at a time.
If, after completing the installation steps above, you want to run a demo notebook in Snowsight, then:
- Download the Simple Start Notebook
- Refresh the browser page and use the account menu button in the bottom-left corner to switch your role to
RAI_USER
. - Repeat the notebook import process (+ Create Projects > Notebook > Import .ipynb File) and select
simple-start-snowflake.ipynb
. This time choose Run on container, and select the compute pool you created in the installation notebook (NOTEBOOK_CPU_XS
). - Follow the instructions in the demo notebook:
- From the vertical ellipsis icon (⋮) in the top-right corner, do Notebook settings > External access and toggle the
PYPI_ACCESS_INTEGRATION
switch to the on position. - Execute the cells in the notebook. The first one installs the RelationalAI library as well as the other two libraries used in the notebook (
matplotlib
andnetworkx
).
- From the vertical ellipsis icon (⋮) in the top-right corner, do Notebook settings > External access and toggle the
The installation notebook includes explanations of each step — here’s a preview of its contents:
RelationalAI Native App Setup Guide#
🚨 Note that the
ACCOUNTADMIN
role is used in this guide. This role is needed for Step 1 and for creating the network rule in Step 4. To manage roles specific the RelationalAI Native App, see Appendix 2 at the bottom of this notebook.
#USE ROLE ACCOUNTADMIN;
Step 1 - Share Continuous Telemetry Data#
To receive support from RelationalAI, you must opt-in to sharing continuous telemetry data. This telemetry contains operational information such as internal system logs or engine sizes and usage data such as model attributes or obfuscated query plan information. Customer data and personally identifiable information are not included in continuous telemetry data.
To enable sharing, click the Enable button under Data Products > Apps > RelationalAI under the Events and logs tab in Snowsight. Run the cell below to check that this step has been completed.
#session = get_active_session()
app_data = session.sql("describe application relationalai;").collect()
sharing_enabled = dict(app_data)["share_events_with_provider"]
if sharing_enabled:
print("Continuous telemetry data sharing is enabled.")
else:
print("Please enable sharing of continuous telemetry data in Snowsight.")
Step 2 - Activate the RAI Native App#
The Grant button under Data Products > Apps > RelationalAI in Snowsight runs the following SQL command to grant the necessary permissions to the app. If you haven’t clicked that button yet, you can run the code here instead. It doesn’t hurt to run it again if you’re not sure.
#GRANT
EXECUTE TASK,
EXECUTE MANAGED TASK,
CREATE COMPUTE POOL,
CREATE WAREHOUSE
ON ACCOUNT TO APPLICATION RELATIONALAI;
Now execute the following three cells to create the RAI service (this usually takes between 5 and 15 minutes):
#import sys
import time
import json
import itertools
def poll(f):
last_message = ""
dots = itertools.cycle(["⠧", "⠏", "⠛", "⠹", "⠼", "⠶"])
def status(message):
spaces = " " * (len("⠿ " + last_message) - len(message))
sys.stdout.write("\r" + message + spaces)
sys.stdout.flush()
for ctr in itertools.count():
if ctr % 10 == 0:
result = f()
if isinstance(result, str):
message = next(dots) + " " + result
status(message)
last_message = result
if result is True:
status("⠿ Done!")
return
else:
message = next(dots) + " " + last_message
status(message)
time.sleep(0.5)
#def activate():
try:
session.sql("CALL RELATIONALAI.APP.ACTIVATE();").collect()
return True
except Exception as e:
if "Unknown user-defined function" in str(e):
return "Waiting for app installation to complete..."
else:
raise e
poll(activate)
#def check():
result = session.sql("CALL RELATIONALAI.APP.SERVICE_STATUS();").collect()
status = json.loads(result[0]["SERVICE_STATUS"])[0]["message"]
if status.startswith("UNKNOWN"):
status = "Working"
if status.startswith("Readiness probe"):
status = "Almost done"
if status == "Running":
return True
else:
return status + "..."
poll(check)
🚨 IMPORTANT While RelationalAI is in preview mode, you must upgrade the application weekly after RAI releases an updated native app. Please review the Upgrades section of the RelationalAI Native App documentation.
Step 3 - Setting up Change Data Capture#
Streams share Snowflake data with the RAI Native App using change data capture (CDC) to capture source table and view changes once every minute.
To enable CDC, run the following command:
#CALL RELATIONALAI.APP.RESUME_CDC();
Step 4 - Creating a rai_user
role#
The SQL code block below creates a new role that can be granted to any users permitted to use the RelationalAI application. We link the application’s all_admin
role to this new role.
#-- Create a role for accessing the app
CREATE ROLE rai_user;
-- Link the app's `all_admin` role to the created role.
GRANT APPLICATION ROLE relationalai.all_admin TO ROLE rai_user;
You may want to run additional commands of the form GRANT ROLE rai_user TO ROLE <role_name>
or GRANT ROLE rai_user TO USER <user_name>
to ensure that other roles can access the app. For example, to grant the rai_user
role to yourself, run the following cell:
## optional: grant the rai_user role to yourself
current_user = get_active_session().sql("SELECT CURRENT_USER() AS USERNAME;").collect()[0]["USERNAME"]
session.sql(f'GRANT ROLE rai_user TO USER "{current_user}"').collect()
Our Simple Start notebook uses a table called RAI_DEMO.SIMPLE_START.CONNECTIONS
. If you want to be able to run that notebook, either grant permissions to the rai_user
role or run the following SQL to create the table now. You can clean up this database when you’re done with the demo notebook by running DROP DATABASE RAI_DEMO CASCADE;
#CREATE DATABASE IF NOT EXISTS RAI_DEMO;
CREATE SCHEMA IF NOT EXISTS RAI_DEMO.SIMPLE_START;
CREATE OR REPLACE TABLE RAI_DEMO.SIMPLE_START.CONNECTIONS (
STATION_1 INT,
STATION_2 INT
);
INSERT INTO RAI_DEMO.SIMPLE_START.CONNECTIONS (STATION_1, STATION_2) VALUES
(1, 2),
(1, 3),
(3, 4),
(1, 4),
(4, 5),
(5, 7),
(6, 7),
(6, 8),
(7, 8);
GRANT USAGE ON DATABASE RAI_DEMO TO ROLE rai_user;
GRANT USAGE ON SCHEMA RAI_DEMO.SIMPLE_START TO ROLE rai_user;
GRANT SELECT ON TABLE RAI_DEMO.SIMPLE_START.CONNECTIONS TO ROLE RAI_USER;
ALTER TABLE RAI_DEMO.SIMPLE_START.CONNECTIONS SET CHANGE_TRACKING = TRUE;
-- optional: give rai_user more extensive permissions in the RAI_DEMO database
-- this step is necessary for the user to be able to run all the demo notebooks
GRANT CREATE SCHEMA ON DATABASE RAI_DEMO TO ROLE rai_user;
GRANT CREATE TABLE ON SCHEMA RAI_DEMO.SIMPLE_START TO ROLE rai_user;
GRANT CREATE TABLE ON FUTURE SCHEMAS IN DATABASE RAI_DEMO TO ROLE rai_user;
GRANT SELECT ON ALL TABLES IN SCHEMA RAI_DEMO.SIMPLE_START TO ROLE rai_user;
GRANT SELECT ON FUTURE TABLES IN DATABASE RAI_DEMO TO ROLE rai_user;
Step 5 — Setting up Snowflake Notebooks#
Snowflake offers two options when you create a new Snowflake Notebook: Run on Warehouse and Run on Container. We recommend using container notebooks because they support the use of pip
to install the latest version of the RelationalAI Python library.
For more information on using RelationalAI in Snowflake Notebooks, see Using RAI in a Cloud Notebook in the RelationalAI documentation.
Container Notebooks#
Container notebooks do require a bit of additional setup because (1) they can’t be executed with account administrator privileges, and (2) they require you to select a compute pool when creating a notebook.
The SQL code below sets up all the necessary resources and permissions to simplify the process of using Container notebooks:
#-- create a database to contain the notebooks
CREATE DATABASE rai_notebooks;
-- create a warehouse to select when creating a notebook
CREATE WAREHOUSE notebooks_wh;
-- create a compute pool to use when creating a notebook
CREATE COMPUTE POOL NOTEBOOK_CPU_XS
MIN_NODES = 1
MAX_NODES = 15
INSTANCE_FAMILY = CPU_X64_XS
AUTO_RESUME = true
AUTO_SUSPEND_SECS = 1800
COMMENT = "Pool for Snowflake Notebooks on Container Runtime";
-- grant the necessary permissions to the rai_user role
GRANT USAGE ON DATABASE rai_notebooks TO ROLE rai_user;
GRANT USAGE ON SCHEMA rai_notebooks.public TO ROLE rai_user;
GRANT CREATE NOTEBOOK ON SCHEMA rai_notebooks.public TO ROLE rai_user;
GRANT USAGE ON WAREHOUSE notebooks_wh TO ROLE rai_user;
GRANT USAGE ON COMPUTE POOL NOTEBOOK_CPU_XS TO ROLE rai_user;
GRANT CREATE SERVICE ON SCHEMA rai_notebooks.public TO ROLE rai_user;
If you want to be able to install Python packages from PyPI in your notebooks, run the code below to set up an External Access Integration:
If you don’t want to enable a PyPI integration, you can skip this step. Notebook users can import the RelationalAI Python library by uploading a ZIP file instead.
#-- grant the necessary permissions to the rai_user role
CREATE OR REPLACE NETWORK RULE pypi_network_rule
MODE = EGRESS
TYPE = HOST_PORT
VALUE_LIST = ('pypi.org', 'pypi.python.org', 'pythonhosted.org', 'files.pythonhosted.org');
CREATE OR REPLACE EXTERNAL ACCESS INTEGRATION pypi_access_integration
ALLOWED_NETWORK_RULES = (pypi_network_rule)
ENABLED = true;
GRANT USAGE ON INTEGRATION pypi_access_integration TO ROLE rai_user;
Warehouse Notebooks#
The RelationalAI Python library requires an External Access Integration to work on notebooks that run on a warehouse. This integration allows the app to pass query results back to the notebook. Run the following code to set up the integration:
#session = get_active_session()
system_allowlist = session.sql("""
SELECT value:host AS URL
FROM TABLE(FLATTEN(input=>parse_json(SYSTEM$ALLOWLIST())))
WHERE value:type = 'STAGE'
""").collect()
if system_allowlist:
urls = ", ".join(row.URL.replace('"', "'") for row in system_allowlist)
egress_rule_commands = [
f"""
CREATE OR REPLACE NETWORK RULE S3_RAI_INTERNAL_BUCKET_EGRESS
MODE = EGRESS
TYPE = HOST_PORT
VALUE_LIST = ({urls});
""",
"""
CREATE OR REPLACE EXTERNAL ACCESS INTEGRATION S3_RAI_INTERNAL_BUCKET_EGRESS_INTEGRATION
ALLOWED_NETWORK_RULES = (S3_RAI_INTERNAL_BUCKET_EGRESS)
ENABLED = true;
""",
"""
GRANT USAGE ON INTEGRATION S3_RAI_INTERNAL_BUCKET_EGRESS_INTEGRATION TO ROLE rai_user;
"""
]
for command in egress_rule_commands:
session.sql(command).collect()
print("Network rule set up successfully.")
Congratulations! Your RelationalAI app is now ready to use.#
Next Steps#
To get up and running with RelationalAI in Snowflake Notebooks, download the Simple Start Snowflake Notebook, upload it to your Snowflake account (https://app.snowflake.com > + icon in left sidebar > Notebooks > Import .ipynb file), and follow the instructions in the notebook.
To use a local Python installation instead, download the Simple Start Jupyter notebook and follow the instructions for running the notebook.
For a more detailed example and more information about the RelationalAI Python library, check out the Getting Started guide.
Links:
- Simple Start Notebook: https://relational.ai/notebooks/simple-start.ipynb
- Example Notebooks: https://relational.ai/docs/develop/example-notebooks
- Docs: https://relational.ai/docs
APPENDIX 1 - Deactivate the RAI Native App#
To reduce costs when you are not using the RAI Native App, suspend CDC, and delete all engines.
🚨 Note that this task requires the
app_admin
application role.
#session = get_active_session()
# note: the use of `skip_appendix` in the Appendices makes the notebook's
# "Run All" action skip these cells
skip_appendix = True
# Deactivate the app
if not skip_appendix:
session.sql("CALL RELATIONALAI.APP.DEACTIVATE();").collect()
# To re-activate the app:
# session.sql("CALL RELATIONALAI.APP.ACTIVATE();").collect()
APPENDIX 2 - App Upgrades#
Your RAI Native App is automatically upgraded every Monday at 10:00 UTC. During upgrades, the application cannot process RAI transactions.
If you prefer to schedule upgrades for a different day and time, use the schedule_upgrade()
procedure:
#if not skip_appendix:
# Schedule upgrades for Wednesdays at 15:00 UTC. Times are in 24-hour format.
session.sql("CALL relationalai.app.schedule_upgrade('WEDNESDAY', '15:00');").collect()
If you prefer not to use a Snowflake notebook, you can instead complete the app installation by copying the code block below and pasting it into a Snowflake SQL worksheet to run it.
If you hover over the code block, you’ll see a copy button in the top-right corner.
/*
Before running this worksheet, replace <db> and <schema> below with a
database name and schema name from your account.
This schema will be used by the worksheet to store temporary stored
procedures which are dropped immediately after they are called.
Note also that some of the operations in the worksheet require
accountadmin privileges
*/
USE DATABASE <db>;
USE SCHEMA <schema>;
/*
# RelationalAI Native App Setup Guide
*/
/*
> 🚨 Note that the `ACCOUNTADMIN` role is used in this guide. This role is
needed for Step 1 and for creating the network rule in Step 4. To manage
roles specific the RelationalAI Native App, see Appendix 2 at the bottom
of this notebook.
*/
USE ROLE ACCOUNTADMIN;
/*
## Step 1 - Share Continuous Telemetry Data
*/
/*
To receive support from RelationalAI, you must opt-in to sharing
continuous telemetry data. This telemetry contains operational information
such as internal system logs or engine sizes and usage data such as model
attributes or obfuscated query plan information. Customer data and
personally identifiable information are not included in continuous
telemetry data.
*/
/*
To enable sharing, click the *Enable* button under *Data Products > Apps >
RelationalAI* under the *Events and logs* tab in Snowsight. Run the cell
below to check that this step has been completed.
*/
BEGIN
CREATE OR REPLACE PROCEDURE rai_installation_step()
RETURNS STRING
LANGUAGE PYTHON
RUNTIME_VERSION = '3.10'
PACKAGES = ('snowflake-snowpark-python')
HANDLER = 'main'
EXECUTE AS CALLER
AS
$$
def main(session):
app_data = session.sql("describe application relationalai;").collect()
sharing_enabled = dict(app_data)["share_events_with_provider"]
if sharing_enabled:
print("Continuous telemetry data sharing is enabled.")
else:
print("Please enable sharing of continuous telemetry data in Snowsight.")
return "Step completed"
$$;
CALL rai_installation_step();
DROP PROCEDURE rai_installation_step();
RETURN 'Step completed';
END;
/*
## Step 2 - Activate the RAI Native App
*/
/*
The *Grant* button under *Data Products > Apps > RelationalAI* in
Snowsight runs the following SQL command to grant the necessary
permissions to the app. If you haven't clicked that button yet, you can
run the code here instead. It doesn't hurt to run it again if you're not
sure.
*/
GRANT
EXECUTE TASK,
EXECUTE MANAGED TASK,
CREATE COMPUTE POOL,
CREATE WAREHOUSE
ON ACCOUNT TO APPLICATION RELATIONALAI;
/*
Now execute the following three cells to create the RAI service (this
usually takes between 5 and 15 minutes):
*/
BEGIN
CREATE OR REPLACE PROCEDURE rai_installation_step()
RETURNS STRING
LANGUAGE PYTHON
RUNTIME_VERSION = '3.10'
PACKAGES = ('snowflake-snowpark-python')
HANDLER = 'main'
EXECUTE AS CALLER
AS
$$
def main(session):
import sys
import time
import json
import itertools
def poll(f):
last_message = ""
dots = itertools.cycle([".", ".", ".", ".", ".", "."])
def status(message):
spaces = " " * (len(". " + last_message) - len(message))
sys.stdout.write("\r" + message + spaces)
sys.stdout.flush()
for ctr in itertools.count():
if ctr % 10 == 0:
result = f()
if isinstance(result, str):
message = next(dots) + " " + result
status(message)
last_message = result
if result is True:
status(". Done!")
return
else:
message = next(dots) + " " + last_message
status(message)
time.sleep(0.5)
def activate():
try:
session.sql("CALL RELATIONALAI.APP.ACTIVATE();").collect()
return True
except Exception as e:
if "Unknown user-defined function" in str(e):
return "Waiting for app installation to complete..."
else:
raise e
poll(activate)
return "Step completed"
$$;
CALL rai_installation_step();
DROP PROCEDURE rai_installation_step();
RETURN 'Step completed';
END;
BEGIN
CREATE OR REPLACE PROCEDURE rai_installation_step()
RETURNS STRING
LANGUAGE PYTHON
RUNTIME_VERSION = '3.10'
PACKAGES = ('snowflake-snowpark-python')
HANDLER = 'main'
EXECUTE AS CALLER
AS
$$
def main(session):
import sys
import time
import json
import itertools
def poll(f):
last_message = ""
dots = itertools.cycle([".", ".", ".", ".", ".", "."])
def status(message):
spaces = " " * (len(". " + last_message) - len(message))
sys.stdout.write("\r" + message + spaces)
sys.stdout.flush()
for ctr in itertools.count():
if ctr % 10 == 0:
result = f()
if isinstance(result, str):
message = next(dots) + " " + result
status(message)
last_message = result
if result is True:
status(". Done!")
return
else:
message = next(dots) + " " + last_message
status(message)
time.sleep(0.5)
def check():
result = session.sql("CALL RELATIONALAI.APP.SERVICE_STATUS();").collect()
status = json.loads(result[0]["SERVICE_STATUS"])[0]["message"]
if status.startswith("UNKNOWN"):
status = "Working"
if status.startswith("Readiness probe"):
status = "Almost done"
if status == "Running":
return True
else:
return status + "..."
poll(check)
return "Step completed"
$$;
CALL rai_installation_step();
DROP PROCEDURE rai_installation_step();
RETURN 'Step completed';
END;
/*
> 🚨 **IMPORTANT**
*/
/*
> While RelationalAI is in preview mode, you must upgrade the application
weekly after RAI releases an updated native app. Please review the
Upgrades section of the RelationalAI Native App documentation.
*/
/*
## Step 3 - Setting up Change Data Capture
*/
/*
Streams share Snowflake data with the RAI Native App using change data
capture (CDC) to capture source table and view changes once every minute.
*/
/*
To enable CDC, run the following command:
*/
CALL RELATIONALAI.APP.RESUME_CDC();
/*
## Step 4 - Creating a `rai_user` role
*/
/*
The SQL code block below creates a new role that can be granted to any
users permitted to use the RelationalAI application. We link the
application's `all_admin` role to this new role.
*/
-- Create a role for accessing the app
CREATE ROLE rai_user;
-- Link the app's `all_admin` role to the created role.
GRANT APPLICATION ROLE relationalai.all_admin TO ROLE rai_user;
/*
You may want to run additional commands of the form `GRANT ROLE rai_user
TO ROLE <role_name>` or `GRANT ROLE rai_user TO USER
<user_name>` to ensure that other roles can access the app. For
example, to grant the `rai_user` role to yourself, run the following cell:
*/
BEGIN
CREATE OR REPLACE PROCEDURE rai_installation_step()
RETURNS STRING
LANGUAGE PYTHON
RUNTIME_VERSION = '3.10'
PACKAGES = ('snowflake-snowpark-python')
HANDLER = 'main'
EXECUTE AS CALLER
AS
$$
def main(session):
# optional: grant the rai_user role to yourself
current_user = get_active_session().sql("SELECT CURRENT_USER() AS USERNAME;").collect()[0]["USERNAME"]
session.sql(f'GRANT ROLE rai_user TO USER "{current_user}"').collect()
return "Step completed"
$$;
CALL rai_installation_step();
DROP PROCEDURE rai_installation_step();
RETURN 'Step completed';
END;
/*
Our Simple Start notebook uses a table called
`RAI_DEMO.SIMPLE_START.CONNECTIONS`. If you want to be able to run that
notebook, either grant permissions to the `rai_user` role or run the
following SQL to create the table now. You can clean up this database when
you're done with the demo notebook by running `DROP DATABASE RAI_DEMO
CASCADE;`
*/
CREATE DATABASE IF NOT EXISTS RAI_DEMO;
CREATE SCHEMA IF NOT EXISTS RAI_DEMO.SIMPLE_START;
CREATE OR REPLACE TABLE RAI_DEMO.SIMPLE_START.CONNECTIONS (
STATION_1 INT,
STATION_2 INT
);
INSERT INTO RAI_DEMO.SIMPLE_START.CONNECTIONS (STATION_1, STATION_2) VALUES
(1, 2),
(1, 3),
(3, 4),
(1, 4),
(4, 5),
(5, 7),
(6, 7),
(6, 8),
(7, 8);
GRANT USAGE ON DATABASE RAI_DEMO TO ROLE rai_user;
GRANT USAGE ON SCHEMA RAI_DEMO.SIMPLE_START TO ROLE rai_user;
GRANT SELECT ON TABLE RAI_DEMO.SIMPLE_START.CONNECTIONS TO ROLE RAI_USER;
ALTER TABLE RAI_DEMO.SIMPLE_START.CONNECTIONS SET CHANGE_TRACKING = TRUE;
-- optional: give rai_user more extensive permissions in the RAI_DEMO database
-- this step is necessary for the user to be able to run all the demo notebooks
GRANT CREATE SCHEMA ON DATABASE RAI_DEMO TO ROLE rai_user;
GRANT CREATE TABLE ON SCHEMA RAI_DEMO.SIMPLE_START TO ROLE rai_user;
GRANT CREATE TABLE ON FUTURE SCHEMAS IN DATABASE RAI_DEMO TO ROLE rai_user;
GRANT SELECT ON ALL TABLES IN SCHEMA RAI_DEMO.SIMPLE_START TO ROLE rai_user;
GRANT SELECT ON FUTURE TABLES IN DATABASE RAI_DEMO TO ROLE rai_user;
/*
## Step 5 — Setting up Snowflake Notebooks
*/
/*
Snowflake offers two options when you create a new Snowflake Notebook:
*Run on Warehouse* and *Run on Container*. We recommend using container
notebooks because they support the use of `pip` to install the latest
version of the RelationalAI Python library.
*/
/*
For more information on using RelationalAI in Snowflake Notebooks, see
Using RAI in a Cloud Notebook in the RelationalAI documentation.
*/
/*
### Container Notebooks
*/
/*
Container notebooks do require a bit of additional setup because (1) they
can't be executed with account administrator privileges, and (2) they
require you to select a compute pool when creating a notebook.
*/
/*
The SQL code below sets up all the necessary resources and permissions to
simplify the process of using Container notebooks:
*/
-- create a database to contain the notebooks
CREATE DATABASE rai_notebooks;
-- create a warehouse to select when creating a notebook
CREATE WAREHOUSE notebooks_wh;
-- create a compute pool to use when creating a notebook
CREATE COMPUTE POOL NOTEBOOK_CPU_XS
MIN_NODES = 1
MAX_NODES = 15
INSTANCE_FAMILY = CPU_X64_XS
AUTO_RESUME = true
AUTO_SUSPEND_SECS = 1800
COMMENT = "Pool for Snowflake Notebooks on Container Runtime";
-- grant the necessary permissions to the rai_user role
GRANT USAGE ON DATABASE rai_notebooks TO ROLE rai_user;
GRANT USAGE ON SCHEMA rai_notebooks.public TO ROLE rai_user;
GRANT CREATE NOTEBOOK ON SCHEMA rai_notebooks.public TO ROLE rai_user;
GRANT USAGE ON WAREHOUSE notebooks_wh TO ROLE rai_user;
GRANT USAGE ON COMPUTE POOL NOTEBOOK_CPU_XS TO ROLE rai_user;
GRANT CREATE SERVICE ON SCHEMA rai_notebooks.public TO ROLE rai_user;
/*
If you want to be able to install Python packages from PyPI in your
notebooks, run the code below to set up an External Access Integration:
*/
/*
> If you don't want to enable a PyPI integration, you can skip this step.
Notebook users can import the RelationalAI Python library by uploading a
ZIP file instead.
*/
-- grant the necessary permissions to the rai_user role
CREATE OR REPLACE NETWORK RULE pypi_network_rule
MODE = EGRESS
TYPE = HOST_PORT
VALUE_LIST = ('pypi.org', 'pypi.python.org', 'pythonhosted.org', 'files.pythonhosted.org');
CREATE OR REPLACE EXTERNAL ACCESS INTEGRATION pypi_access_integration
ALLOWED_NETWORK_RULES = (pypi_network_rule)
ENABLED = true;
GRANT USAGE ON INTEGRATION pypi_access_integration TO ROLE rai_user;
/*
### Warehouse Notebooks
*/
/*
The RelationalAI Python library requires an External Access Integration to
work on notebooks that run on a warehouse. This integration allows the app
to pass query results back to the notebook. Run the following code to set
up the integration:
*/
BEGIN
CREATE OR REPLACE PROCEDURE rai_installation_step()
RETURNS STRING
LANGUAGE PYTHON
RUNTIME_VERSION = '3.10'
PACKAGES = ('snowflake-snowpark-python')
HANDLER = 'main'
EXECUTE AS CALLER
AS
$$
def main(session):
system_allowlist = session.sql("""
SELECT value:host AS URL
FROM TABLE(FLATTEN(input=>parse_json(SYSTEM$ALLOWLIST())))
WHERE value:type = 'STAGE'
""").collect()
if system_allowlist:
urls = ", ".join(row.URL.replace('"', "'") for row in system_allowlist)
egress_rule_commands = [
f"""
CREATE OR REPLACE NETWORK RULE S3_RAI_INTERNAL_BUCKET_EGRESS
MODE = EGRESS
TYPE = HOST_PORT
VALUE_LIST = ({urls});
""",
"""
CREATE OR REPLACE EXTERNAL ACCESS INTEGRATION S3_RAI_INTERNAL_BUCKET_EGRESS_INTEGRATION
ALLOWED_NETWORK_RULES = (S3_RAI_INTERNAL_BUCKET_EGRESS)
ENABLED = true;
""",
"""
GRANT USAGE ON INTEGRATION S3_RAI_INTERNAL_BUCKET_EGRESS_INTEGRATION TO ROLE rai_user;
"""
]
for command in egress_rule_commands:
session.sql(command).collect()
print("Network rule set up successfully.")
return "Step completed"
$$;
CALL rai_installation_step();
DROP PROCEDURE rai_installation_step();
RETURN 'Step completed';
END;
/*
## Congratulations! Your RelationalAI app is now ready to use.
*/
/*
# Next Steps
*/
/*
To get up and running with RelationalAI in Snowflake Notebooks, download
the Simple Start Snowflake Notebook, upload it to your Snowflake account
(https://app.snowflake.com > + icon in left sidebar > Notebooks > Import
.ipynb file), and follow the instructions in the notebook.
*/
/*
To use a local Python installation instead, download the Simple Start
Jupyter notebook and follow the instructions for running the notebook.
*/
/*
For a more detailed example and more information about the RelationalAI
Python library, check out the Getting Started guide.
*/
/*
Links:
*/
/*
- Simple Start Notebook:
https://relational.ai/notebooks/simple-start.ipynb
*/
/*
- Example Notebooks: https://relational.ai/docs/develop/example-notebooks
*/
/*
- Docs: https://relational.ai/docs
*/
/*
## APPENDIX 1 - Deactivate the RAI Native App
*/
/*
To reduce costs when you are not using the RAI Native App, suspend CDC,
and delete all engines.
*/
/*
> 🚨 Note that this task requires the `app_admin` application role.
*/
/*
## APPENDIX 2 - App Upgrades
*/
/*
Your RAI Native App is automatically upgraded every Monday at 10:00 UTC.
During upgrades, the application cannot process RAI transactions.
*/
/*
If you prefer to schedule upgrades for a different day and time, use the
`schedule_upgrade()` procedure:
*/
BEGIN
CREATE OR REPLACE PROCEDURE rai_installation_step()
RETURNS STRING
LANGUAGE PYTHON
RUNTIME_VERSION = '3.10'
PACKAGES = ('snowflake-snowpark-python')
HANDLER = 'main'
EXECUTE AS CALLER
AS
$$
def main(session):
skip_appendix = True
if not skip_appendix:
# Schedule upgrades for Wednesdays at 15:00 UTC. Times are in 24-hour format.
session.sql("CALL relationalai.app.schedule_upgrade('WEDNESDAY', '15:00');").collect()
return "Step completed"
$$;
CALL rai_installation_step();
DROP PROCEDURE rai_installation_step();
RETURN 'Step completed';
END;
SnowSQL, the Snowflake command-line client, does not correctly parse some of the Snowflake SQL constructs used in the SQL Worksheet. Therefore, if you prefer to use the command line client, you should instead copy the contents of the code block below and paste it into a file to run it.
If you hover over the code block, you’ll see a copy button in the top-right corner.
/*
Before running this worksheet, replace <db> and <schema> below with a
database name and schema name from your account.
This schema will be used by the worksheet to store temporary stored
procedures which are dropped immediately after they are called.
Note also that some of the operations in the worksheet require
accountadmin privileges
*/
USE DATABASE <db>;
USE SCHEMA <schema>;
/*
# RelationalAI Native App Setup Guide
*/
/*
> 🚨 Note that the `ACCOUNTADMIN` role is used in this guide. This role is
needed for Step 1 and for creating the network rule in Step 4. To manage
roles specific the RelationalAI Native App, see Appendix 2 at the bottom
of this notebook.
*/
USE ROLE ACCOUNTADMIN;
/*
## Step 1 - Share Continuous Telemetry Data
*/
/*
To receive support from RelationalAI, you must opt-in to sharing
continuous telemetry data. This telemetry contains operational information
such as internal system logs or engine sizes and usage data such as model
attributes or obfuscated query plan information. Customer data and
personally identifiable information are not included in continuous
telemetry data.
*/
/*
To enable sharing, click the *Enable* button under *Data Products > Apps >
RelationalAI* under the *Events and logs* tab in Snowsight. Run the cell
below to check that this step has been completed.
*/
CREATE OR REPLACE PROCEDURE rai_installation_step()
RETURNS STRING
LANGUAGE PYTHON
RUNTIME_VERSION = '3.10'
PACKAGES = ('snowflake-snowpark-python')
HANDLER = 'main'
EXECUTE AS CALLER
AS
$$
def main(session):
app_data = session.sql("describe application relationalai;").collect()
sharing_enabled = dict(app_data)["share_events_with_provider"]
if sharing_enabled:
print("Continuous telemetry data sharing is enabled.")
else:
print("Please enable sharing of continuous telemetry data in Snowsight.")
return "Step completed"
$$;
CALL rai_installation_step();
DROP PROCEDURE rai_installation_step();
/*
## Step 2 - Activate the RAI Native App
*/
/*
The *Grant* button under *Data Products > Apps > RelationalAI* in
Snowsight runs the following SQL command to grant the necessary
permissions to the app. If you haven't clicked that button yet, you can
run the code here instead. It doesn't hurt to run it again if you're not
sure.
*/
GRANT
EXECUTE TASK,
EXECUTE MANAGED TASK,
CREATE COMPUTE POOL,
CREATE WAREHOUSE
ON ACCOUNT TO APPLICATION RELATIONALAI;
/*
Now execute the following three cells to create the RAI service (this
usually takes between 5 and 15 minutes):
*/
CREATE OR REPLACE PROCEDURE rai_installation_step()
RETURNS STRING
LANGUAGE PYTHON
RUNTIME_VERSION = '3.10'
PACKAGES = ('snowflake-snowpark-python')
HANDLER = 'main'
EXECUTE AS CALLER
AS
$$
def main(session):
import sys
import time
import json
import itertools
def poll(f):
last_message = ""
dots = itertools.cycle([".", ".", ".", ".", ".", "."])
def status(message):
spaces = " " * (len(". " + last_message) - len(message))
sys.stdout.write("\r" + message + spaces)
sys.stdout.flush()
for ctr in itertools.count():
if ctr % 10 == 0:
result = f()
if isinstance(result, str):
message = next(dots) + " " + result
status(message)
last_message = result
if result is True:
status(". Done!")
return
else:
message = next(dots) + " " + last_message
status(message)
time.sleep(0.5)
def activate():
try:
session.sql("CALL RELATIONALAI.APP.ACTIVATE();").collect()
return True
except Exception as e:
if "Unknown user-defined function" in str(e):
return "Waiting for app installation to complete..."
else:
raise e
poll(activate)
return "Step completed"
$$;
CALL rai_installation_step();
DROP PROCEDURE rai_installation_step();
CREATE OR REPLACE PROCEDURE rai_installation_step()
RETURNS STRING
LANGUAGE PYTHON
RUNTIME_VERSION = '3.10'
PACKAGES = ('snowflake-snowpark-python')
HANDLER = 'main'
EXECUTE AS CALLER
AS
$$
def main(session):
import sys
import time
import json
import itertools
def poll(f):
last_message = ""
dots = itertools.cycle([".", ".", ".", ".", ".", "."])
def status(message):
spaces = " " * (len(". " + last_message) - len(message))
sys.stdout.write("\r" + message + spaces)
sys.stdout.flush()
for ctr in itertools.count():
if ctr % 10 == 0:
result = f()
if isinstance(result, str):
message = next(dots) + " " + result
status(message)
last_message = result
if result is True:
status(". Done!")
return
else:
message = next(dots) + " " + last_message
status(message)
time.sleep(0.5)
def check():
result = session.sql("CALL RELATIONALAI.APP.SERVICE_STATUS();").collect()
status = json.loads(result[0]["SERVICE_STATUS"])[0]["message"]
if status.startswith("UNKNOWN"):
status = "Working"
if status.startswith("Readiness probe"):
status = "Almost done"
if status == "Running":
return True
else:
return status + "..."
poll(check)
return "Step completed"
$$;
CALL rai_installation_step();
DROP PROCEDURE rai_installation_step();
/*
> 🚨 **IMPORTANT**
*/
/*
> While RelationalAI is in preview mode, you must upgrade the application
weekly after RAI releases an updated native app. Please review the
Upgrades section of the RelationalAI Native App documentation.
*/
/*
## Step 3 - Setting up Change Data Capture
*/
/*
Streams share Snowflake data with the RAI Native App using change data
capture (CDC) to capture source table and view changes once every minute.
*/
/*
To enable CDC, run the following command:
*/
CALL RELATIONALAI.APP.RESUME_CDC();
/*
## Step 4 - Creating a `rai_user` role
*/
/*
The SQL code block below creates a new role that can be granted to any
users permitted to use the RelationalAI application. We link the
application's `all_admin` role to this new role.
*/
-- Create a role for accessing the app
CREATE ROLE rai_user;
-- Link the app's `all_admin` role to the created role.
GRANT APPLICATION ROLE relationalai.all_admin TO ROLE rai_user;
/*
You may want to run additional commands of the form `GRANT ROLE rai_user
TO ROLE <role_name>` or `GRANT ROLE rai_user TO USER
<user_name>` to ensure that other roles can access the app. For
example, to grant the `rai_user` role to yourself, run the following cell:
*/
CREATE OR REPLACE PROCEDURE rai_installation_step()
RETURNS STRING
LANGUAGE PYTHON
RUNTIME_VERSION = '3.10'
PACKAGES = ('snowflake-snowpark-python')
HANDLER = 'main'
EXECUTE AS CALLER
AS
$$
def main(session):
# optional: grant the rai_user role to yourself
current_user = get_active_session().sql("SELECT CURRENT_USER() AS USERNAME;").collect()[0]["USERNAME"]
session.sql(f'GRANT ROLE rai_user TO USER "{current_user}"').collect()
return "Step completed"
$$;
CALL rai_installation_step();
DROP PROCEDURE rai_installation_step();
/*
Our Simple Start notebook uses a table called
`RAI_DEMO.SIMPLE_START.CONNECTIONS`. If you want to be able to run that
notebook, either grant permissions to the `rai_user` role or run the
following SQL to create the table now. You can clean up this database when
you're done with the demo notebook by running `DROP DATABASE RAI_DEMO
CASCADE;`
*/
CREATE DATABASE IF NOT EXISTS RAI_DEMO;
CREATE SCHEMA IF NOT EXISTS RAI_DEMO.SIMPLE_START;
CREATE OR REPLACE TABLE RAI_DEMO.SIMPLE_START.CONNECTIONS (
STATION_1 INT,
STATION_2 INT
);
INSERT INTO RAI_DEMO.SIMPLE_START.CONNECTIONS (STATION_1, STATION_2) VALUES
(1, 2),
(1, 3),
(3, 4),
(1, 4),
(4, 5),
(5, 7),
(6, 7),
(6, 8),
(7, 8);
GRANT USAGE ON DATABASE RAI_DEMO TO ROLE rai_user;
GRANT USAGE ON SCHEMA RAI_DEMO.SIMPLE_START TO ROLE rai_user;
GRANT SELECT ON TABLE RAI_DEMO.SIMPLE_START.CONNECTIONS TO ROLE RAI_USER;
ALTER TABLE RAI_DEMO.SIMPLE_START.CONNECTIONS SET CHANGE_TRACKING = TRUE;
-- optional: give rai_user more extensive permissions in the RAI_DEMO database
-- this step is necessary for the user to be able to run all the demo notebooks
GRANT CREATE SCHEMA ON DATABASE RAI_DEMO TO ROLE rai_user;
GRANT CREATE TABLE ON SCHEMA RAI_DEMO.SIMPLE_START TO ROLE rai_user;
GRANT CREATE TABLE ON FUTURE SCHEMAS IN DATABASE RAI_DEMO TO ROLE rai_user;
GRANT SELECT ON ALL TABLES IN SCHEMA RAI_DEMO.SIMPLE_START TO ROLE rai_user;
GRANT SELECT ON FUTURE TABLES IN DATABASE RAI_DEMO TO ROLE rai_user;
/*
## Step 5 — Setting up Snowflake Notebooks
*/
/*
Snowflake offers two options when you create a new Snowflake Notebook:
*Run on Warehouse* and *Run on Container*. We recommend using container
notebooks because they support the use of `pip` to install the latest
version of the RelationalAI Python library.
*/
/*
For more information on using RelationalAI in Snowflake Notebooks, see
Using RAI in a Cloud Notebook in the RelationalAI documentation.
*/
/*
### Container Notebooks
*/
/*
Container notebooks do require a bit of additional setup because (1) they
can't be executed with account administrator privileges, and (2) they
require you to select a compute pool when creating a notebook.
*/
/*
The SQL code below sets up all the necessary resources and permissions to
simplify the process of using Container notebooks:
*/
-- create a database to contain the notebooks
CREATE DATABASE rai_notebooks;
-- create a warehouse to select when creating a notebook
CREATE WAREHOUSE notebooks_wh;
-- create a compute pool to use when creating a notebook
CREATE COMPUTE POOL NOTEBOOK_CPU_XS
MIN_NODES = 1
MAX_NODES = 15
INSTANCE_FAMILY = CPU_X64_XS
AUTO_RESUME = true
AUTO_SUSPEND_SECS = 1800
COMMENT = "Pool for Snowflake Notebooks on Container Runtime";
-- grant the necessary permissions to the rai_user role
GRANT USAGE ON DATABASE rai_notebooks TO ROLE rai_user;
GRANT USAGE ON SCHEMA rai_notebooks.public TO ROLE rai_user;
GRANT CREATE NOTEBOOK ON SCHEMA rai_notebooks.public TO ROLE rai_user;
GRANT USAGE ON WAREHOUSE notebooks_wh TO ROLE rai_user;
GRANT USAGE ON COMPUTE POOL NOTEBOOK_CPU_XS TO ROLE rai_user;
GRANT CREATE SERVICE ON SCHEMA rai_notebooks.public TO ROLE rai_user;
/*
If you want to be able to install Python packages from PyPI in your
notebooks, run the code below to set up an External Access Integration:
*/
/*
> If you don't want to enable a PyPI integration, you can skip this step.
Notebook users can import the RelationalAI Python library by uploading a
ZIP file instead.
*/
-- grant the necessary permissions to the rai_user role
CREATE OR REPLACE NETWORK RULE pypi_network_rule
MODE = EGRESS
TYPE = HOST_PORT
VALUE_LIST = ('pypi.org', 'pypi.python.org', 'pythonhosted.org', 'files.pythonhosted.org');
CREATE OR REPLACE EXTERNAL ACCESS INTEGRATION pypi_access_integration
ALLOWED_NETWORK_RULES = (pypi_network_rule)
ENABLED = true;
GRANT USAGE ON INTEGRATION pypi_access_integration TO ROLE rai_user;
/*
### Warehouse Notebooks
*/
/*
The RelationalAI Python library requires an External Access Integration to
work on notebooks that run on a warehouse. This integration allows the app
to pass query results back to the notebook. Run the following code to set
up the integration:
*/
CREATE OR REPLACE PROCEDURE rai_installation_step()
RETURNS STRING
LANGUAGE PYTHON
RUNTIME_VERSION = '3.10'
PACKAGES = ('snowflake-snowpark-python')
HANDLER = 'main'
EXECUTE AS CALLER
AS
$$
def main(session):
system_allowlist = session.sql("""
SELECT value:host AS URL
FROM TABLE(FLATTEN(input=>parse_json(SYSTEM$ALLOWLIST())))
WHERE value:type = 'STAGE'
""").collect()
if system_allowlist:
urls = ", ".join(row.URL.replace('"', "'") for row in system_allowlist)
egress_rule_commands = [
f"""
CREATE OR REPLACE NETWORK RULE S3_RAI_INTERNAL_BUCKET_EGRESS
MODE = EGRESS
TYPE = HOST_PORT
VALUE_LIST = ({urls});
""",
"""
CREATE OR REPLACE EXTERNAL ACCESS INTEGRATION S3_RAI_INTERNAL_BUCKET_EGRESS_INTEGRATION
ALLOWED_NETWORK_RULES = (S3_RAI_INTERNAL_BUCKET_EGRESS)
ENABLED = true;
""",
"""
GRANT USAGE ON INTEGRATION S3_RAI_INTERNAL_BUCKET_EGRESS_INTEGRATION TO ROLE rai_user;
"""
]
for command in egress_rule_commands:
session.sql(command).collect()
print("Network rule set up successfully.")
return "Step completed"
$$;
CALL rai_installation_step();
DROP PROCEDURE rai_installation_step();
/*
## Congratulations! Your RelationalAI app is now ready to use.
*/
/*
# Next Steps
*/
/*
To get up and running with RelationalAI in Snowflake Notebooks, download
the Simple Start Snowflake Notebook, upload it to your Snowflake account
(https://app.snowflake.com > + icon in left sidebar > Notebooks > Import
.ipynb file), and follow the instructions in the notebook.
*/
/*
To use a local Python installation instead, download the Simple Start
Jupyter notebook and follow the instructions for running the notebook.
*/
/*
For a more detailed example and more information about the RelationalAI
Python library, check out the Getting Started guide.
*/
/*
Links:
*/
/*
- Simple Start Notebook:
https://relational.ai/notebooks/simple-start.ipynb
*/
/*
- Example Notebooks: https://relational.ai/docs/develop/example-notebooks
*/
/*
- Docs: https://relational.ai/docs
*/
/*
## APPENDIX 1 - Deactivate the RAI Native App
*/
/*
To reduce costs when you are not using the RAI Native App, suspend CDC,
and delete all engines.
*/
/*
> 🚨 Note that this task requires the `app_admin` application role.
*/
/*
## APPENDIX 2 - App Upgrades
*/
/*
Your RAI Native App is automatically upgraded every Monday at 10:00 UTC.
During upgrades, the application cannot process RAI transactions.
*/
/*
If you prefer to schedule upgrades for a different day and time, use the
`schedule_upgrade()` procedure:
*/
CREATE OR REPLACE PROCEDURE rai_installation_step()
RETURNS STRING
LANGUAGE PYTHON
RUNTIME_VERSION = '3.10'
PACKAGES = ('snowflake-snowpark-python')
HANDLER = 'main'
EXECUTE AS CALLER
AS
$$
def main(session):
skip_appendix = True
if not skip_appendix:
# Schedule upgrades for Wednesdays at 15:00 UTC. Times are in 24-hour format.
session.sql("CALL relationalai.app.schedule_upgrade('WEDNESDAY', '15:00');").collect()
return "Step completed"
$$;
CALL rai_installation_step();
DROP PROCEDURE rai_installation_step();
III. Install the RAI CLI (Optional)#
Although you may manage the RAI Native App using SQL procedures, the RAI command-line interface (CLI) provides a more streamlined experience for common management tasks.
The RAI CLI is included in the relationalai
Python package,
which supports Python 3.9, 3.10, and 3.11.
Besides the CLI, the relationalai
package serves as the main interface for
creating and managing models in RAI and accessing the advanced features of the RAI Native App.
To install the package, follow the installation instructions.
Next Steps#
Now that you’ve installed and configured the RAI Native App for Snowflake, you may want to:
- Assign application roles to manage user access to the RAI Native App.
- Read the management guides to learn more about managing the RAI Native App.