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:

  1. 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.
  2. 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.
  3. 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.
  4. Click on the name of the application to open the app.
  5. Click Grant to grant the application the necessary privileges.
    • The EXECUTE TASK and EXECUTE MANAGED TASK privileges are required to share data from your Snowflake account with the RAI Native App.
    • The CREATE WAREHOUSE and CREATE COMPUTE POOL privileges are required by the RAI Native App to create and manage resources for performing service operations.
  6. Click Activate to activate the application.
  7. Switch to the Events and logs tab to enable events and log sharing. Click Enable and select All Events. This step is required to receive support from RelationalAI. The telemetry sent to RelationalAI will contain 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.

II. Set Up the RAI Native App#

To complete the steps in this section:

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

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 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, run the following command:

#CALL RELATIONALAI.APP.RESUME_CDC();

Step 4 — Setting up Snowflake Notebooks#

Snowflake offers two options when you create a new Snowflake Notebook: Run on Warehouse and Run on Container. 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.

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:

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 - 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()

APPENDIX 3 - 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()

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: