Skip to content
RelationalAI Docs

Install and run PyRel

PyRel is RelationalAI’s Python package for building semantic models. In this guide you’ll install PyRel, connect a starter project to Snowflake, deploy its semantic model, and query it to answer a business question.

Estimated time
15–30 minutes
Prerequisites
  • A Bash, zsh, or PowerShell terminal.
  • Python 3.10–3.14 to run the project. If Python is not installed, the uv setup in this guide can download it automatically.
  • Network access to install Python packages and connect to your Snowflake account.
  • An administrator must set up RelationalAI in Snowflake and grant your user the RAI_DEVELOPER role and access to a warehouse.
  • Your administrator must also prepare a deployment schema and a metadata schema for you. The same setup page creates both and grants the permissions you need to deploy models.
Download the starter project

Create a project and install PyRel

Section titled “Create a project and install PyRel”

Start by downloading the starter project and installing the Python packages it needs. The project includes a simple model, a query, and CSV data that you’ll work through in this guide.

You can install the required Python packages with uv or pip. If you don’t have a preference, choose uv for fewer setup commands. Your selection applies to commands throughout this guide:

  1. If you haven’t already, download the starter project and save the ZIP file in your Downloads folder.

  2. If you don’t have uv installed, follow the installation instructions.

  3. Open a terminal and run these commands to extract the starter project, enter its folder, and install the required packages:

    If you saved the ZIP file outside Downloads, update its path in the first command:

    Terminal window
    unzip ~/Downloads/supplier-disruption.zip
    cd supplier-disruption
    uv sync
    • Installs PyRel from the relationalai package.
    • Installs pandas to read the starter project’s CSV files.
    • Stores the project’s packages in .venv, separate from other Python projects.

    Run the remaining commands in this guide from the supplier-disruption folder. You’ll configure the Snowflake connection in the next section.

    What if uv can’t find or download a supported Python version?

    uv normally downloads a compatible Python version when you run uv sync. If it does not, install Python 3.13 through uv, then try again:

    Terminal window
    uv python install 3.13
    uv sync

    If Python cannot be downloaded, check your network connection. Your organization may also disable Python downloads through uv. In that case, install Python 3.10 through 3.14 using your organization’s standard method.

    What if the terminal can’t find uv after installation?

    Close and reopen your terminal, then run:

    Terminal window
    uv --version

    If the terminal still cannot find uv, repeat the uv installation instructions for your operating system. Follow any message from the installer about updating your PATH, then open another terminal.

  4. Run these commands to check that PyRel and the rai command were installed:

    Terminal window
    uv run python -c "import relationalai; print('PyRel import OK')"
    uv run rai --version
    • The Python command prints PyRel import OK.
    • The rai command prints the installed CLI version.

    These results verify the installation only. You’ll test the Snowflake connection in the next section.

    What if one of these commands fails?

    Make sure your terminal is in the supplier-disruption folder, run uv sync, and try both commands again.

Optional: Set up a coding agent

Section titled “Optional: Set up a coding agent”

RelationalAI Agent Skills give coding agents guided workflows for PyRel modeling, reasoning, deployment, and operations. You can complete this guide without a coding agent, but if you want agent assistance in later steps, execute this prompt with your agent to get started:

Read https://docs.relational.ai/agent-setup/prompt.md and follow the instructions to set up RelationalAI Agent Skills.

After installation, start a new agent session so the skills are available. For client-specific installation and update instructions, see Install skill files.

Configure your project

Section titled “Configure your project”

PyRel reads your connection settings from raiconfig.yaml in your project folder. If your administrator sent you an invitation link with all required settings, the configuration below is ready to save. Otherwise, the builder expands the fields you need to complete. You can always expand Review or edit configuration details to inspect or change settings. Then save the file, set any required credentials, and verify the connection.

Configure with a coding agent

If you installed RelationalAI Agent Skills, paste this prompt into the new agent session. The prompt updates when you change validated, non-secret settings in the form.

Prompt
/rai-setup Configure this starter project. Ask me one question at a time for my account, warehouse, username, the authentication method my administrator told me to use, and my deployment schemas. Ask for additional non-secret settings only when that authentication method requires them. If I do not know which authentication method to use, explain the supported methods and tell me what to confirm with my administrator instead of guessing. This guide deploys the starter model, so the configuration must include deployment. Use the deployment schema my administrator prepared for me, as `DATABASE.SCHEMA`, and ask for it if you don't already have it. If you don't already have the metadata schema, suggest the deployment schema name followed by `_META`, and ask me to confirm it matches what my administrator set up. Add a top-level `deployment` block with `schema` and `meta_schema` set to those values, a `schedules.on_deploy` entry with `interval_s: 0` and `run_on_deploy: true`, and `outputs.schedule: on_deploy`.


Do not ask me to paste credentials into chat, and do not print, write, or commit credentials. If authentication requires a credential or browser action, tell me how to complete that step locally. Create or update `raiconfig.yaml` in the project root, but do not change other project files. Run `rai connect` from this project to validate the connection. If it fails, explain the error and help me fix it; do not report success unless the command succeeds.

Whether you use the prompt or the form, review the generated configuration and confirm that rai connect succeeds before continuing.

  1. Add connection details

    Enter or review the account identifier and warehouse provided by your administrator. These settings tell PyRel which Snowflake account and warehouse to use.

    Identifies your Snowflake account, usually in the form organization-account.

    Enter the name of any Snowflake warehouse where you have the USAGE privilege. An X-Small warehouse is sufficient.

  2. Choose authentication

    Authentication verifies your identity when PyRel connects to Snowflake. Select the method your administrator configured for you.

  3. Enter your Snowflake username

    Enter or review the username PyRel will use to connect to Snowflake. Your administrator must grant this user the RAI_DEVELOPER role.

  4. Set up model deployment (Public Preview)

    Model deployment makes your model’s outputs available in Snowflake so other tools and applications can use them without running PyRel. You deploy the starter model later in this guide.

    Deployment requires two Snowflake schemas: a deployment schema and a metadata schema. Ask your administrator to prepare both and grant your user the required permissions using Set up RelationalAI in Snowflake.

    Stores the model’s outputs. Enter the dedicated DATABASE.SCHEMA provided by your administrator.

    Stores information PyRel uses to manage and update the deployed model. By default, PyRel names the metadata schema by appending _META to the deployment schema.

  5. Save your configuration

    Copy or download the generated configuration and save it as raiconfig.yaml in your project folder, next to pyproject.toml.

    raiconfig.yaml
    default_connection: sf
    direct_access: true
    connections:
      sf:
        type: snowflake
        authenticator: oauth_authorization_code
        account: ""
        warehouse: ""
        user: ""
        role: RAI_DEVELOPER
        oauth_client_id: <oauth_client_id>
        oauth_redirect_uri: http://localhost:54321/snowflake/oauth-redirect

    Complete these fields to copy or download: Account identifier, Snowflake username, Warehouse, and OAuth client ID.

    If you downloaded the file to your Downloads folder, run the following command from your project folder to move it into place:

    Terminal window
    mv ~/Downloads/raiconfig.yaml .

    Check that raiconfig.yaml is beside pyproject.toml in your project folder. You’ll verify the connection after any required credential setup.

  6. Set your credentials

    No additional credentials are needed for browser sign-in. PyRel will open your browser when you test the connection in the next step.

    Set your Snowflake programmatic access token in the terminal you’ll use to run PyRel. The commands below store it in the SNOWFLAKE_PROGRAMMATIC_ACCESS_TOKEN environment variable, which PyRel reads when connecting to Snowflake.

    Keep this terminal open for the remaining steps. Don’t put the token in raiconfig.yaml or paste it into this page.

    Run this command to enter your token without displaying it:

    Terminal window
    printf 'Snowflake token: '
    IFS= read -r -s SNOWFLAKE_PROGRAMMATIC_ACCESS_TOKEN
    printf '\n'
    export SNOWFLAKE_PROGRAMMATIC_ACCESS_TOKEN

    Then check that the environment variable is set:

    Terminal window
    if [ -n "${SNOWFLAKE_PROGRAMMATIC_ACCESS_TOKEN:-}" ]; then
      printf 'credential set\n'
    else
      printf 'credential missing\n'
    fi

    You should see credential set. If you see credential missing, repeat the token-entry command and check again in the same terminal.

    This only confirms that the variable is set. You’ll test the connection in the next step.

    PyRel uses the private key file you specified in Choose authentication to sign in to Snowflake. If that file is not encrypted, remove private_key_passphrase from raiconfig.yaml and continue to Verify the connection.

    Otherwise, use the command below to store its passphrase in an environment variable. Run it in the terminal you’ll use for PyRel. Your input won’t be displayed:

    Terminal window
    printf 'Private key passphrase: '
    IFS= read -r -s SNOWFLAKE_PRIVATE_KEY_PASSPHRASE
    printf '\n'
    export SNOWFLAKE_PRIVATE_KEY_PASSPHRASE

    Then check that the environment variable is set:

    Terminal window
    if [ -n "${SNOWFLAKE_PRIVATE_KEY_PASSPHRASE:-}" ]; then
      printf 'credential set\n'
    else
      printf 'credential missing\n'
    fi

    You should see credential set. If you see credential missing, repeat the passphrase-entry command and check again in the same terminal.

    This only confirms that the variable is set. You’ll test the connection in the next step.

  7. Verify the connection

    Run the connection check from the supplier-disruption folder, where you saved raiconfig.yaml and pyproject.toml:

    uv
    Terminal window
    uv run rai connect
    pip
    Terminal window
    rai connect
    • PyRel can read raiconfig.yaml, authenticate, and connect to Snowflake.
    • The output shows the account, user, warehouse, and role so you can confirm each value.

    In the next step, you'll use PyRel to query the semantic model in the starter project.

    What if PyRel can’t read my configuration?

    If the error names a setting, correct it in the form and save the updated raiconfig.yaml in your project folder. Then rerun the connection check.

    If PyRel reports that no configuration file was found, make sure raiconfig.yaml is in your project folder beside pyproject.toml, then rerun the connection check. If PyRel loads the wrong configuration, run uv run rai config explain (pip: rai config explain) to see the active configuration and where each value came from.

    What if authentication fails?

    Check the OAuth client ID and redirect URI against the values from your administrator. Rerun the connection check and complete browser sign-in.

    Make sure you set your token in the same terminal where you run the connection check, then try again.

    In raiconfig.yaml, check the path to your private key file. If the key is encrypted, make sure you set its passphrase in the same terminal, then rerun the connection check.

    See Configure Snowflake authentication for method-specific detail.

    What if the connection times out or reports “Failed to connect to DB”?

    Check your network connection and connect to your organization’s VPN if required. If you use PrivateLink, confirm the zone with your administrator. If the connection still fails, ask your administrator to check firewall rules.

    These checks also apply to Snowflake error 250001.

    What if my user lacks the required permissions?

    Run uv run rai whoami (pip: rai whoami) and share the output with your administrator. Ask them to confirm that your user has the RAI_DEVELOPER role, and that this role has warehouse access and the RELATIONALAI.RAI_USER application role.

    After they update the permissions, rerun the connection check.

Run the starter project

Section titled “Run the starter project”

The starter project models a manufacturer that buys parts from several suppliers. Its completed semantic model connects suppliers to the parts they provide and the products that require those parts. You’ll use the included CSV data to answer a hypothetical question: If Northstar Components can’t deliver, which products depend on parts it supplies?

You’ve installed PyRel and verified that the project can connect to Snowflake. Next, you’ll deploy the semantic model to Snowflake, query it to find which products depend on parts supplied by Northstar Components, and then clean up.

Run and explain with a coding agent

If you installed RelationalAI Agent Skills, paste this prompt into the new agent session. The agent will not edit the starter files. It must ask before creating or removing Snowflake objects.

Prompt
/rai-pyrel Read these documentation sections before acting:


- https://docs.relational.ai/get-started/install-and-run-pyrel/index.md#run-the-starter-project
- https://docs.relational.ai/build/meet-pyrel/index.md#explore-the-starter-model
- https://docs.relational.ai/build/meet-pyrel/index.md#understand-the-project-structure


Follow the Install and run PyRel guide’s **Run the starter project** steps for this supplied starter project. Do not edit files, install or upgrade packages, or display configuration or credential values. Use the project’s existing Python environment.


Before deployment, use the guide to explain which Snowflake objects and refresh tasks the command creates, then ask for my explicit confirmation. If I confirm, run the documented deployment command. Continue only if deployment succeeds.


Run the documented query and compare its output with the guide’s expected output. Stop if the command fails or the output does not match. Use the guide’s troubleshooting steps, explain the problem, and help me fix it; do not continue or report success as though the check succeeded.


After a successful query, run the guide’s cleanup preview without `--force` and tell me which deployment and metadata schemas it names. Ask for my explicit confirmation before forced teardown. If I do not confirm, leave the deployment in place and tell me that it remains. Afterward, use the project files and the Meet PyRel model walkthrough to briefly explain how the model, source mappings, relationships, and query produce the result. Preserve the guide’s limits on what the result establishes.

Compare the command output with the expected output below before continuing.

Use the same terminal where you ran rai connect in Verify the connection, and make sure you're in the supplier-disruption folder. Then deploy the model, run the query, and clean up the deployment.

  1. Deploy the model

    First, deploy the model from your project folder using the rai models deploy CLI command:

    uv
    Terminal window
    uv run rai models deploy --path model
    pip
    Terminal window
    rai models deploy --path model
    • --path model loads the model from the model folder.
    • PyRel deploys the model to the schema set by deployment.schema in raiconfig.yaml.
    • PyRel creates output objects in Snowflake and fills them with the model's initial results.
    • The on_deploy schedule in raiconfig.yaml fills the outputs once, when you deploy. It doesn't refresh them again on a timer.
    • The command keeps running until the first data load finishes.
    What if deployment fails with a schema or permissions error?

    Run uv run rai config explain (pip: rai config explain) to check the names of the deployment and metadata schemas. Ask your administrator to confirm that your role has the required permissions on both schemas.

    What if authentication fails when I deploy the model?

    Follow the troubleshooting guidance in Verify the connection. Once the connection check succeeds, retry the command.

    What if deployment fails with an EXECUTE TASK error?

    The deploy fills its tables by running a Snowflake task, and your role needs permission to run it. Ask your administrator to run GRANT EXECUTE TASK ON ACCOUNT TO ROLE RAI_DEVELOPER;. The script from Set up RelationalAI in Snowflake includes this grant. Then deploy again.

  2. Run the query

    After deployment succeeds, run the query:

    uv
    Terminal window
    uv run python find_affected_products.py
    pip
    Terminal window
    python find_affected_products.py
    Output
                  product                part
    0  Cold-chain tracker       Control board
    1  Cold-chain tracker  Temperature sensor
    2     Factory gateway       Control board
    3    Smart thermostat  Temperature sensor

    The rows may appear in a different order.

    If you see this output, PyRel successfully connected to Snowflake, loaded the semantic model, ran the query, and returned results. You can pause here, or read on to learn how the starter project's semantic model works.

    What if Python can’t find the model module?

    If you see ModuleNotFoundError: No module named 'model', run the query command from your project folder. This is the folder containing pyproject.toml and the model folder.

    What if authentication fails when I run the query?

    Follow the troubleshooting guidance in Verify the connection. Once the connection check succeeds, retry the command.

    What if my results don’t match the example output?

    If you see different combinations of products and parts, compare your project files with the code in Understand the project structure, or download a fresh starter project.

  3. Clean up the deployment

    When you’re done with the example, remove the deployed model from Snowflake. This deletes the objects RelationalAI created in your deployment and metadata schemas, but keeps both schemas. Next, Meet PyRel walks through the model and deploys it again.

    Preview the cleanup:

    uv
    Terminal window
    uv run rai models teardown
    pip
    Terminal window
    rai models teardown

    Review the preview and confirm that it names the deployment and metadata schemas you used for this example.

    Then run the following command to remove the model:

    uv
    Terminal window
    uv run rai models teardown --force
    pip
    Terminal window
    rai models teardown --force

Nice work!

You installed PyRel, connected a project to Snowflake, deployed a semantic model, and used it to answer a business question. Next, find out how the model works.

Where to go next

Section titled “Where to go next”

Choose a next step based on your goal: