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 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. This will take you back to the Data Products > Apps page, and you should see RelationalAI listed under Installed Apps.
-
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 stream data via change data capture (CDC) from Snowflake to RAI, ensuring your RAI Native App has the most up-to-date data. - 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.
-
Navigate back to the Data Products > Apps page and wait for the spinner in the INSTALLED column to stop running. When it’s done you’ll see “1 minute ago” in that column.
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.
- 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 following two files:
- Repeat the notebook import process (+ Create Projects > Notebook > Import .ipynb File) and select
simple-start-snowflake.ipynb
. - Follow the instructions in the demo notebook:
- Upload the
relationalai.zip
file to the notebook workspace. - Choose
matplotlib
andnetworkx
from the Python libraries dropdown. - From the vertical ellipsis icon (⋮) in the top-right corner, do Notebook settings > External access and toggle the
S3_RAI_INTERNAL_BUCKET_EGRESS_INTEGRATION
switch to the on position. - Execute the cells in the notebook.
- Upload the
The installation notebook includes explanations of each step — here’s a preview of its contents:
RelationalAI Native App Setup Guide#
Step 1 - Share Continuous Telemetry Data#
To receive support from RelationalAI, you must opt-in to share continuous telemetry data. Telemetry is written to your account’s active event table. 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.
🚨 Note that the
ACCOUNTADMIN
role is used in this guide. This role is needed only for the event-table related operations in Step 1 and 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;
Set Up An Event Table#
The following code block checks whether you have an event table already set up on your account. If you don’t have one, it will set one up for you.
#session = get_active_session()
event_table_query = "SHOW PARAMETERS LIKE 'event_table' in ACCOUNT;"
event_tables = session.sql(event_table_query).collect()
def set_up_event_table():
event_db_name = "TELEMETRY"
event_schema_name = "PUBLIC"
event_table_name = "EVENTS"
event_db_schema = f"{event_db_name}.{event_schema_name}"
event_db_schema_table = f"{event_db_schema}.{event_table_name}"
for command in [
f"CREATE DATABASE IF NOT EXISTS {event_db_name};",
f"CREATE SCHEMA IF NOT EXISTS {event_db_schema};",
f"CREATE EVENT TABLE IF NOT EXISTS {event_db_schema_table};",
f"ALTER ACCOUNT SET EVENT_TABLE = {event_db_schema_table};",
]:
session.sql(command).collect()
if len(event_tables) == 0 or event_tables[0].value == "":
set_up_event_table()
Now that you’ve set up an event table, you can enable telemetry sharing.
By running the next code block, you consent to and enable sharing continuous telemetry data with RelationalAI.
#ALTER APPLICATION relationalai SET SHARE_EVENTS_WITH_PROVIDER = TRUE;
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 cell 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 and subscribe to the release notes to receive notifications about new versions.
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, an engine needs to be configured to be the CDC engine.
We start by creating an engine of size HIGHMEM_X64_S
that we call demo_engine
. This step usually takes between 1 and 5 minutes.
#CALL RELATIONALAI.API.CREATE_ENGINE('demo_engine', 'HIGHMEM_X64_S');
Once the engine creation has finished, we set this engine to be the CDC engine:
#CALL RELATIONALAI.APP.SETUP_CDC('demo_engine');
Step 4 — Setting up Snowflake Notebooks#
To use RelationalAI in Snowflake Notebooks, run the cell below to set up a network rule that will allow the app to pass query results back to the notebook.
To enable users who aren’t account administrators to run RelationalAI in Snowflake Notebooks, see Appendix 2 for how to create a rai_user
role and grant access to this 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;
"""
]
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/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 "Run All"
# feature 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 - Defining a RelationalAI User Role#
- We start by creating a new role that can be granted to any users permitted to use this application.
- We then link the application’s user role to this new role. Note that it is possible to create more fine-grained roles at a later stage.
- Finally, we grant
MONITOR
permissions on the role to allow users to see engine compute pools. This is needed for the relationalai Python library to manage engines.
#if not skip_appendix:
# Create a role for accessing the app
session.sql("CREATE ROLE rai_user;").collect()
# Link the app's user role to the created role.
session.sql("GRANT APPLICATION ROLE relationalai.all_admin TO ROLE rai_user;").collect()
# Grant USAGE on the egress integration to the role
# This is necessary for users with the `rai_user` role to be able to
# run the app in Snowflake Notebooks
session.sql("GRANT USAGE ON INTEGRATION S3_RAI_INTERNAL_BUCKET_EGRESS_INTEGRATION TO ROLE rai_user;").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
*/
/*
## Step 1 - Share Continuous Telemetry Data
*/
/*
To receive support from RelationalAI, you must opt-in to share continuous
telemetry data. Telemetry is written to your account’s active event table.
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.
*/
/*
> 🚨 Note that the `ACCOUNTADMIN` role is used in this guide. This role is
needed only for the event-table related operations in Step 1 and 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;
/*
### Set Up An Event Table
*/
/*
The following code block checks whether you have an event table already
set up on your account. If you don't have one, it will set one up for you.
*/
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):
event_table_query = "SHOW PARAMETERS LIKE 'event_table' in ACCOUNT;"
event_tables = session.sql(event_table_query).collect()
def set_up_event_table():
event_db_name = "TELEMETRY"
event_schema_name = "PUBLIC"
event_table_name = "EVENTS"
event_db_schema = f"{event_db_name}.{event_schema_name}"
event_db_schema_table = f"{event_db_schema}.{event_table_name}"
for command in [
f"CREATE DATABASE IF NOT EXISTS {event_db_name};",
f"CREATE SCHEMA IF NOT EXISTS {event_db_schema};",
f"CREATE EVENT TABLE IF NOT EXISTS {event_db_schema_table};",
f"ALTER ACCOUNT SET EVENT_TABLE = {event_db_schema_table};",
]:
session.sql(command).collect()
if len(event_tables) == 0 or event_tables[0].value == "":
set_up_event_table()
return "Step completed"
$$;
CALL rai_installation_step();
DROP PROCEDURE rai_installation_step();
RETURN 'Step completed';
END;
/*
Now that you've set up an event table, you can enable telemetry sharing.
*/
/*
By running the next code block, you consent to and enable sharing
continuous telemetry data with RelationalAI.
*/
ALTER APPLICATION relationalai SET SHARE_EVENTS_WITH_PROVIDER = TRUE;
/*
## 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 cell 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 and
subscribe to the release notes to receive notifications about new
versions.
*/
/*
## 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, an engine needs to be configured to be the CDC engine.
*/
/*
We start by creating an engine of size `HIGHMEM_X64_S` that we call
`demo_engine`. This step usually takes between 1 and 5 minutes.
*/
CALL RELATIONALAI.API.CREATE_ENGINE('demo_engine', 'HIGHMEM_X64_S');
/*
Once the engine creation has finished, we set this engine to be the CDC
engine:
*/
CALL RELATIONALAI.APP.SETUP_CDC('demo_engine');
/*
## Step 4 — Setting up Snowflake Notebooks
*/
/*
To use RelationalAI in Snowflake Notebooks, run the cell below to set up a
network rule that will allow the app to pass query results back to the
notebook.
*/
/*
To enable users who aren't account administrators to run RelationalAI in
Snowflake Notebooks, see Appendix 2 for how to create a `rai_user` role
and grant access to this 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;
"""
]
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/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 - Defining a RelationalAI User Role
*/
/*
- We start by creating a new role that can be granted to any users
permitted to use this application.
*/
/*
- We then link the application's user role to this new role. Note that it
is possible to create more fine-grained roles at a later stage.
*/
/*
- Finally, we grant `MONITOR` permissions on the role to allow users to
see engine compute pools. This is needed for the relationalai Python
library to manage engines.
*/
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:
# Create a role for accessing the app
session.sql("CREATE ROLE rai_user;").collect()
# Link the app's user role to the created role.
session.sql("GRANT APPLICATION ROLE relationalai.all_admin TO ROLE rai_user;").collect()
# Grant USAGE on the egress integration to the role
# This is necessary for users with the `rai_user` role to be able to
# run the app in Snowflake Notebooks
session.sql("GRANT USAGE ON INTEGRATION S3_RAI_INTERNAL_BUCKET_EGRESS_INTEGRATION TO ROLE rai_user;").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
*/
/*
## Step 1 - Share Continuous Telemetry Data
*/
/*
To receive support from RelationalAI, you must opt-in to share continuous
telemetry data. Telemetry is written to your account’s active event table.
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.
*/
/*
> 🚨 Note that the `ACCOUNTADMIN` role is used in this guide. This role is
needed only for the event-table related operations in Step 1 and 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;
/*
### Set Up An Event Table
*/
/*
The following code block checks whether you have an event table already
set up on your account. If you don't have one, it will set one up for you.
*/
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):
event_table_query = "SHOW PARAMETERS LIKE 'event_table' in ACCOUNT;"
event_tables = session.sql(event_table_query).collect()
def set_up_event_table():
event_db_name = "TELEMETRY"
event_schema_name = "PUBLIC"
event_table_name = "EVENTS"
event_db_schema = f"{event_db_name}.{event_schema_name}"
event_db_schema_table = f"{event_db_schema}.{event_table_name}"
for command in [
f"CREATE DATABASE IF NOT EXISTS {event_db_name};",
f"CREATE SCHEMA IF NOT EXISTS {event_db_schema};",
f"CREATE EVENT TABLE IF NOT EXISTS {event_db_schema_table};",
f"ALTER ACCOUNT SET EVENT_TABLE = {event_db_schema_table};",
]:
session.sql(command).collect()
if len(event_tables) == 0 or event_tables[0].value == "":
set_up_event_table()
return "Step completed"
$$;
CALL rai_installation_step();
DROP PROCEDURE rai_installation_step();
/*
Now that you've set up an event table, you can enable telemetry sharing.
*/
/*
By running the next code block, you consent to and enable sharing
continuous telemetry data with RelationalAI.
*/
ALTER APPLICATION relationalai SET SHARE_EVENTS_WITH_PROVIDER = TRUE;
/*
## 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 cell 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 and
subscribe to the release notes to receive notifications about new
versions.
*/
/*
## 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, an engine needs to be configured to be the CDC engine.
*/
/*
We start by creating an engine of size `HIGHMEM_X64_S` that we call
`demo_engine`. This step usually takes between 1 and 5 minutes.
*/
CALL RELATIONALAI.API.CREATE_ENGINE('demo_engine', 'HIGHMEM_X64_S');
/*
Once the engine creation has finished, we set this engine to be the CDC
engine:
*/
CALL RELATIONALAI.APP.SETUP_CDC('demo_engine');
/*
## Step 4 — Setting up Snowflake Notebooks
*/
/*
To use RelationalAI in Snowflake Notebooks, run the cell below to set up a
network rule that will allow the app to pass query results back to the
notebook.
*/
/*
To enable users who aren't account administrators to run RelationalAI in
Snowflake Notebooks, see Appendix 2 for how to create a `rai_user` role
and grant access to this 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;
"""
]
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/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 - Defining a RelationalAI User Role
*/
/*
- We start by creating a new role that can be granted to any users
permitted to use this application.
*/
/*
- We then link the application's user role to this new role. Note that it
is possible to create more fine-grained roles at a later stage.
*/
/*
- Finally, we grant `MONITOR` permissions on the role to allow users to
see engine compute pools. This is needed for the relationalai Python
library to manage engines.
*/
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:
# Create a role for accessing the app
session.sql("CREATE ROLE rai_user;").collect()
# Link the app's user role to the created role.
session.sql("GRANT APPLICATION ROLE relationalai.all_admin TO ROLE rai_user;").collect()
# Grant USAGE on the egress integration to the role
# This is necessary for users with the `rai_user` role to be able to
# run the app in Snowflake Notebooks
session.sql("GRANT USAGE ON INTEGRATION S3_RAI_INTERNAL_BUCKET_EGRESS_INTEGRATION TO ROLE rai_user;").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.
- Configure Change Data Capture (CDC) to enable users to stream Snowflake data to RAI.
- Create a RAI schema to host models written with the
relationalai
Python package.