Rai Setup

RelationalAI Setup & Configuration

Covers the relationalai Python package (aka PyRel), which enables PyRel programs and ships the rai CLI.

Summary

What: End-to-end RelationalAI setup and configuration — installing the Python package, connecting to Snowflake, validating the environment, running a starter program, and tuning all configuration surfaces (auth, model, reasoners, engines, execution).

When to use:

• First-time setup: install relationalai, connect to Snowflake, run a starter program
• Running RAI locally on DuckDB for development, prototyping, or demos (no Snowflake)
• Creating or editing raiconfig.yaml
• Choosing or troubleshooting an authentication method
• Tuning reasoner engines, sizes, solver settings
• Troubleshooting connection or config errors

When NOT to use:

• Writing PyRel models or queries — see rai-pyrel
• Designing ontology structure — see rai-ontology
• Solver execution and diagnostics — see rai-prescriptive-results
• Discovering what questions an existing model can answer — see rai-discovery

Overview: For a returning user tweaking config, start from Quick Reference below and the Reference files trigger table — load only the reference matching the task. For a first-time user, drop into First-Time Setup Workflow and walk them through install → connect → validate → starter → next steps. Always finish a connection change by running rai connect — never hand the user a config and assume it works.

Prerequisites

Requires Python 3.10+ and relationalai>=1.20.1.

Some guidance carries inline Requires relationalai ... notes flagging capabilities that need a version above this baseline; when following those blocks, install at least the version they name.

The RelationalAI Native App for Snowflake must be installed in your account by an administrator — request access here; see the Native App docs. (Not required for local DuckDB development — see Local Development with DuckDB below.)

The rai_developer role is the standard role for running PyRel programs. Custom Snowflake roles also work if granted the rai_user application role — see User Access.

Predictive (GNN) workflows need additional schema setup beyond the base install — a customer-owned database + schema with USAGE and CREATE EXPERIMENT/CREATE MODEL granted to APPLICATION RELATIONALAI. Without it the very first gnn.fit() fails. See rai-predictive-modeling § Prerequisites for the DDL. The predictive submodule (relationalai.semantics.reasoners.predictive) also requires a relationalai version that ships it — confirm the minimum with the RelationalAI team before pinning.

Support / docs: support@relational.ai · sales@relational.ai · docs.relational.ai

Quick Reference

rai init      # scaffold a new raiconfig.yaml
rai connect   # validate the connection (run after any connection change)

# Minimal raiconfig.yaml
default_connection: sf
connections:
  sf:
    type: snowflake
    authenticator: username_password
    account: my_account
    warehouse: my_warehouse
    user: my_user
    password: {{ env_var('SNOWFLAKE_PASSWORD') }}

# Programmatic config (no YAML needed)
import os
from relationalai.config import create_config
from relationalai.semantics import Model
config = create_config(
    default_connection="sf",
    connections={
        "sf": {
            "type": "snowflake",
            "authenticator": "username_password",
            "account": os.environ["SNOWFLAKE_ACCOUNT"],
            "warehouse": os.environ["SNOWFLAKE_WAREHOUSE"],
            "user": os.environ["SNOWFLAKE_USER"],
            "password": os.environ["SNOWFLAKE_PASSWORD"],
        }
    },
)
model = Model("my_model", config=config)

Verify: run rai connect before writing model code, and after any connection change.

Before proposing fields in a user's raiconfig.yaml or a create_config(...) call, verify field names against raiconfig-yaml.md or programmatic-config.md. Do not invent kwargs.

First-Time Setup Workflow

Users are expected to be Snowflake users with existing credentials. Walk the user through these steps one-by-one, explaining each and prompting for the inputs you need to run it on their behalf.

Step 1. Install the package

pip install 'relationalai>=1.20.1'
# or
uv add 'relationalai>=1.20.1'

Step 2. Establish the connection

Check whether the user has an existing Snowflake connection (~/.snowflake/config.toml) or DBT connection (~/.dbt/profiles.yml).

• If yes: skip config creation — PyRel auto-discovers these. Run rai or a PyRel program directly.
• If no: run rai init to create a raiconfig.yaml, then fill in account, warehouse, user, authenticator. See raiconfig-yaml.md for the field reference and authentication.md for authenticator choice.

Step 3. Validate the connection

Run rai connect to validate the configuration.

• Remind the user to check their MFA device if using username_password_mfa or externalbrowser.
• On failure, check: (1) credentials, (2) account identifier, (3) warehouse exists and role has access, (4) the Native App is installed. See Common Pitfalls below.

Step 4. Create a sample

Offer a small sample program using inline data. Ask the user for a domain or use case and tailor the sample to it; if they don't have one, use a minimal structural default — one concept, a handful of instances, one derivation rule, one query — so the sample exercises the install without committing to a vertical. For PyRel syntax load rai-pyrel. Ensure the sample runs and the user sees output. Offer to explain the components.

Step 5. Propose next steps

1. Adapt the sample to real Snowflake tables, or
2. Enhance the sample with richer semantics and different analyses, or
3. Point them at the project templates, or
4. When the model is ready to ship, take it to production with rai-deployment — deploy it to a Snowflake schema (then branch, collaborate, and merge), or as a Snowflake CoWork (Cortex) agent.

Local Development with DuckDB (no Snowflake)

For development, prototyping, and demos, PyRel runs against a local DuckDB database — no Snowflake account or Native App. The local path covers the data-and-logic workflow end to end:

• Ontology — concepts, properties, relationships, data loading
• Querying — select, filter, join, aggregate, group
• Rules / logic — derived properties, classification, recursion
• String / regex matching — strings.like and the std.re module (match, search, findall, sub) execute on the local backend (see rai-pyrel)
• Relationship traversal — model a link as a self-referential relationship and answer connectivity questions ("who transacts with whom", one hop from X) with a self-join (see rai-pyrel)

Graph, prescriptive (optimization), and predictive (GNN) reasoners run on a Snowflake connection.

The local path is unlocked by a duckdb connection plus a deployment section (schema + auto_deploy):

from relationalai.config import create_config, DuckDBConnection

config = create_config(
    connections={"local": DuckDBConnection(path=":memory:")},  # or a file path
    default_connection="local",
    deployment={"schema": "main", "auto_deploy": True},
)

Experimental. Local DuckDB execution relies on deploy mode, which the package flags as experimental — confirm the support stance with the RelationalAI team before customer-facing use.

For the full recipe (YAML config, data loading with 3-part FQNs, and gotchas), see local-development.md.

Reference files

Load the reference when the trigger fires — don't read them all upfront.

Common Pitfalls

(For local DuckDB gotchas — 3-part FQNs, the deployment section, schema collisions — see local-development.md.)

Related Skills

• rai-pyrel — PyRel syntax and data loading
• rai-ontology — domain modeling
• rai-deployment — take a built model to production (schema deploy + lifecycle, or Cortex agent)
• rai-discovery — surface answerable questions and route to the right reasoner
• rai-prescriptive-problem — solver selection (includes Gurobi setup); rai-prescriptive-results — solve execution and diagnostics
• rai-health — diagnose engine performance issues