Get Started with RAI in a Snowflake Notebook

Snowflake has two ways to use notebooks, the Warehouse runtime and the Container runtime. The relationalai Python package is supported in both.

Choose a Notebook Runtime

When you create a new notebook, you’ll be prompted to choose a notebook runtime. Here’s a quick comparison of the two runtimes:

Warehouse runtime	Container runtime
Uses a Snowflake virtual warehouse for compute. Supports installing libraries from Snowflake Anaconda or by uploading a ZIP file. Best for data analysis.	Uses a Snowpark Container Services compute pool for compute. Supports installing libraries from pip and conda. Best for AI/ML workloads.

Tip

If you’re not sure which runtime use, we recommend starting with the Container runtime. It offers the smoothest installation experience for the relationalai Python package.

Refer to the Snowflake docs for more information about the two notebook runtimes.

Set Up Notebook Resources

Snowflake notebooks require a Snowflake schema for storing the notebook, a compute pool or warehouse for running the notebook’s Python kernel, and a warehouse for executing SQL queries from the notebook.

Note

These resources may have already been created by your Snowflake administrator as part of the RAI Native App installation process. If so, you can skip this step.

Follow these steps to set up the resources that your notebook will use:

Container runtime

1. Create the database and schema where the notebook will be created:

   CREATE DATABASE <my_db>;
   CREATE SCHEMA <my_db>.<my_schema>;

2. Create a Snowpark Container Services compute pool for your the notebook’s kernel and Python runtime:

   CREATE COMPUTE POOL <my_notebook_compute_pool>
         MIN_NODES = 1
         MAX_NODES = 1
         INSTANCE_FAMILY = CPU_X64_XS;

3. Create a Snowflake virtual warehouse for executing SQL queries from the notebook:

   CREATE WAREHOUSE <my_query_warehouse> WITH WAREHOUSE_SIZE = 'XSMALL';

4. If you’ll be using a different Snowflake role to create the notebook than the role used to create the resources, then you must grant access privileges to the role that will be used to create the notebook:

   -- Grant USAGE, CREATE NOTEBOOK, and CREATE SERVICE privileges on
   -- the database and schema where the notebook will be created.
   GRANT USAGE ON DATABASE <my_db> TO ROLE <my_role>;
   GRANT USAGE ON SCHEMA <my_db>.<my_schema> TO ROLE <my_role>;
   GRANT CREATE NOTEBOOK ON SCHEMA <my_db>.<my_schema> TO ROLE <my_role>;
   GRANT CREATE SERVICE ON SCHEMA <my_db>.<my_schema> TO ROLE <my_role>;
   
   -- Grant USAGE privileges on the notebook compute pool and query warehouses.
   GRANT USAGE ON COMPUTE POOL <my_notebook_compute_pool> TO ROLE <my_role>;
   GRANT USAGE ON WAREHOUSE <my_query_warehouse> TO ROLE <my_role>;

Warehouse runtime

1. Create the database and schema where the notebook will be created:

   CREATE DATABASE <my_db>;
   CREATE SCHEMA <my_db>.<my_schema>;

2. Create a Snowflake virtual warehouse for your notebook to use:

   CREATE WAREHOUSE <my_notebook_warehouse> WITH WAREHOUSE_SIZE = 'XSMALL';

3. Create a Snowflake virtual warehouse for executing SQL queries from the notebook:

   CREATE WAREHOUSE <my_query_warehouse> WITH WAREHOUSE_SIZE = 'XSMALL';

4. If you’ll be using a different Snowflake role to create the notebook than the role used to create the resources, then you must grant access privileges to the role that will be used to create the notebook:

   -- Grant USAGE, CREATE NOTEBOOK, and CREATE SERVICE privileges on
   -- the database and schema where the notebook will be created.
   GRANT USAGE ON DATABASE <my_db> TO ROLE <my_role>;
   GRANT USAGE ON SCHEMA <my_db>.<my_schema> TO ROLE <my_role>;
   GRANT CREATE NOTEBOOK ON SCHEMA <my_db>.<my_schema> TO ROLE <my_role>;
   GRANT CREATE SERVICE ON SCHEMA <my_db>.<my_schema> TO ROLE <my_role>;
   
   -- Grant USAGE privileges on the notebook and query warehouses.
   GRANT USAGE ON WAREHOUSE <my_notebook_warehouse> TO ROLE <my_role>;
   GRANT USAGE ON WAREHOUSE <my_query_warehouse> TO ROLE <my_role>;

Create a Snowflake Notebook

Container runtime

1. Log in to your Snowflake account at https://app.snowflake.com.
2. Create a new notebook:
   1. Click on + Create in the top-left corner of the Snowflake window.
   2. Hover over Notebook in the list of options.
   3. Click on New Notebook in the pop-out menu.
3. Fill out the modal with the information for your new notebook and then click Create:
   1. Name: Give your notebook a name.
   2. Notebook location: Choose the database and schema for creating the notebook.
   3. Python environment: Choose the Run on container option.
   4. Runtime: Choose CPU or GPU.
   5. Compute pool: Select the compute pool that executes the notebook’s Python kernel.
   6. Query warehouse: Select the warehouse for executing SQL queries.
4. When the notebook opens, delete the sample code cells that Snowflake creates for you:
   1. Click on the triple-dot (⋮) dropdown in the top-right corner of the code cell.
   2. Click on Delete in the dropdown menu.

Warehouse runtime

1. Log in to your Snowflake account at https://app.snowflake.com.
2. Create a new notebook:
   1. Click on + Create in the top-left corner of the Snowflake window.
   2. Hover over Notebook in the list of options.
   3. Click on New Notebook in the pop-out menu.
3. Fill out the modal with the information for your new notebook and then click Create:
   1. Name: Give your notebook a name.
   2. Notebook location: Choose the database and schema for creating the notebook.
   3. Python environment: Choose the Run on warehouse option.
   4. Query warehouse: Select the warehouse for executing SQL queries.
   5. Notebook warehouse: Select the warehouse that executes the notebook’s Python kernel.
4. When the notebook opens, delete the sample code cells that Snowflake creates for you:
   1. Click on the triple-dot (⋮) dropdown in the top-right corner of the code cell.
   2. Click on Delete in the dropdown menu.

Set Up External Access

Container runtime

1. Choose Notebook settings from the triple-dot (⋮) dropdown in the top-right corner of the Snowflake Notebooks window.
2. Configure the notebook for access to PyPI:
   1. Switch to the External access tab.
   2. Turn on the PYPI_ACCESS_INTEGRATION toggle. This allows your notebook to install third-party Python packages from PyPI.

      Note

      The PYPI_ACCESS_INTEGRATION integration is created by an administrator as part of the RAI Native App installation process. If you don’t see this integration, contact your administrator.

      Note

      The S3_RAI_INTERNAL_BUCKET_EGRESS_INTEGRATION is for warehouse notebooks only and may be ignored in container runtime notebooks.

   3. Click Save.

Warehouse runtime

1. Choose Notebook settings from the triple-dot (⋮) dropdown in the top-right corner of the Snowflake Notebooks window.
2. Configure the notebook for access to the RAI Native App:
   1. Switch to the External access tab.
   2. Turn on the S3_RAI_INTERNAL_BUCKET_EGRESS_INTEGRATION toggle. This allows your notebook to access data from the RAI Native App.

      Note

      The S3_RAI_INTERNAL_BUCKET_EGRESS_INTEGRATION integration is created by an administrator as part of the RAI Native App installation process. If you don’t see this integration, contact your administrator.

      Caution

      You may see a PYPI_ACCESS_INTEGRATION if your organization has created it for accessing the Python Package Index. Warehouse runtime notebooks cannot use this integration, and enabling it will not allow you to install package from PyPI in your notebook.

   3. Click Save.

Install the relationalai Package

Container runtime

1. In a new Python cell, run the following code to install the relationalai package:

   !pip install relationalai

2. Verify that the package is installed by running the following code:

   import relationalai as rai
   print(rai.__version__)

   You should see the version number of the relationalai package printed in the output.

Warehouse runtime

1. Download the relationalai.zip file.
2. Select the Files tab in the left sidebar and then click on the + button.
3. Drag and drop the relationalai.zip file into the file upload area, then click Upload:
4. In a new Python cell, run the following code to install the relationalai package:

   import sys
   sys.path.append("relationalai.zip")

5. Verify that the package is installed by running the following code:

   import relationalai as rai
   print(rai.__version__)

   You should see the version number of the relationalai package printed in the output.

Run a Test Query

Verify that the relationalai package is installed and working correctly by running the following code:

import relationalai as rai

# Create a model named "MyFirstModel".
model = rai.Model("MyFirstModel")

# Send a test query.
with model.query() as select:
    response = select(1 + 1)

# The results are stored as a pandas DataFrame in the response.results attribute.
print(response.results)
#    v
# 0  2

Note

The first time you run a query, a RAI engine is created for you. Engines are RAI Native App compute resources—similar to Snowflake warehouses—that evaluate queries from RAI models. Note that it may take several minutes to create your engine.

See the Configuration guide for more information about engines and how to configure them.