RelationalAI adds a semantic modelling and reasoning layer to Snowflake. You build models in Python with PyRel: concepts (suppliers, parts, orders), properties (a supplier's region) and relationships (a part contains another part), plus rules that derive new facts.

This guide builds on the official Start building with PyRel guide: same local setup, a richer model, and a question that shows what PyRel adds next to SQL and an LLM.

The case: a tier-3 supplier stops delivering. Nobody buys from it directly. Which customer orders are at risk, why, and what do we do about it? Answering it means following two networks of unknown depth, the supplier tiers and the bill of materials, and the supplier network contains a cycle. SQL can do it, with complications. PyRel does it with a few rules. Cortex AI_COMPLETE then writes the mitigation plan from the facts PyRel derived.

The notebooks are only the surface for showing these concepts. They run locally in Jupyter for this demonstration, not as a recommended production setup. The reasoning runs in the RelationalAI app inside your Snowflake account, next to the data.

Two notebooks on a synthetic electronics supply chain (20 products, 315 parts, 80 suppliers in four tiers, 1,500 orders):

1. 01_relationalai_setup.ipynb: connect, load the data, first query.
2. 02_supplier_risk_to_plan.ipynb: impact of a supplier failure, a check of the alternative supplier, a mitigation plan and a grounding check.

Get the example files. Use this page's Fork button to open the guide's source folder on GitHub. The notebooks, CSV data and SQL scripts are included in its assets/ folder; they are downloaded from GitHub, not served by this website. Fork the repository if you want your own editable copy. To download just this guide from the public repository, run:

Run the following setup commands from this guide folder. Keep the assets/ directory structure intact so the notebooks can find the data and scripts.

1. Warehouse and schema (administrator). Run assets/scripts/setup.sql as ACCOUNTADMIN. It creates the warehouse RAI_QS_WH, with a 600-second statement timeout, and the schema RAI_QUICKSTART.SUPPLY_CHAIN, and grants both to RAI_DEVELOPER. Nothing else is needed: no integrations, network rules or extra roles. The RelationalAI setup already created the role and the OAuth integration that PyRel signs in with.

2. Python environment. From the guide folder downloaded above, create an environment, install PyRel and Jupyter, and register the environment as a Jupyter kernel:

The last line makes the environment show up as RAI supply chain in the kernel picker of Jupyter, VS Code or Cortex Code, wherever the environment lives. Prefer conda? Use conda create -n rai-supply-chain python=3.12 -y && conda activate rai-supply-chain instead of the first line.

3. Connection. Save the raiconfig.yaml from your invite link in the guide folder, next to assets/, and set the warehouse to RAI_QS_WH:

Check it with rai connect from the guide folder. Then open the notebooks in assets/notebooks/ and select the kernel RAI supply chain. PyRel looks for raiconfig.yaml in the notebook's folder and its parent folders, so it finds the file two levels up.

4. Load the data. Notebook 01 uploads the CSV files from assets/data/ to a stage and runs assets/scripts/load_data.sql. The script creates eleven tables with CHANGE_TRACKING = TRUE and checks the row counts. RelationalAI keeps its copy of source tables in sync through change data capture (CDC), which is why change tracking is on.

The first PyRel query in notebook 01 starts a reasoning engine and indexes the tables. That takes a few minutes; later queries take seconds.

The data is synthetic, with a few cases planted deliberately. assets/data/README.md describes each one, and what the notebooks are looking for. This guide uses these:

PyRel doesn't reason over tables directly. It reasons over an ontology: the business concepts, how they relate, and which table populates what. supply_chain_ontology.py defines it once, and every rule and query in notebook 02 builds on it.

The full model used in this guide is shown below. It describes an electronics manufacturer from order to raw supplier: customers place orders for products, each product is built from a bill of materials of parts, and parts are delivered by suppliers who depend on other suppliers, up to tier 4. It contains seven concepts (the boxes), their attributes (the text in each box) and the links between them (the arrows).

An arrow means "is linked to", not "is a PyRel Relationship". Each arrow is one of three things in the code:

Solid arrows come from the tables. Dashed arrows are facts that the rules in the next section derive. Yes/no facts are marked with flag: inside their concept.

The question flows through it like this: S-T3-07 is down, so everyone who relies_on it is down. A Part whose every Supply has a down supplier has_no_supplier. An Order is at risk if its product's top part includes that part. The diagram was generated with generative AI from supply_chain_ontology.py and the notebook rules.

The tier-1 view. P-141 has two suppliers, in different regions. That looks safe.

The SQL attempt. A recursive CTE can walk up the supplier tiers and down the bill of materials. Because of the cycle, you have to carry the visited path in an array, skip suppliers already on it, and cap the depth. Without that guard, a recursive query over the supplier network can run forever. When we built this guide, one ran for over an hour, which is why RAI_QS_WH has a statement timeout. The notebook shows the guarded query. It gives the right answer, but depth < 10 is a guess, and each follow-up question needs the guard again.

The PyRel rules. "Relies on, at some tier" is two lines: a direct dependency, or a dependency of something you already rely on.

RelationalAI keeps deriving facts until nothing new appears. A known fact isn't derived again, so the cycle ends on its own. The notebook adds four more rules in the same style: is_down, has_no_supplier, includes (any level of the BOM) and needs (quantity per unit, multiplied along the path). A last rule, QualifiedSupply.is_usable, checks that the alternative supplier doesn't itself rely on the failed one.

Expected result:

The notebook builds a small facts pack from what PyRel derived: the dependency chain, the impact by region, the gap until the alternative delivers, and the shortfall. Python computes every number. The LLM gets the JSON and a prompt with three rules: use only the facts, copy numbers exactly, list unknowns as open questions.

The prompt goes in as a bind parameter, so the facts never become part of the SQL text. AI_COMPLETE runs inside Snowflake.

Check the plan. A final cell collects every number in the plan and looks it up in the facts pack. An LLM tends to derive numbers of its own, such as a shortfall from demand and stock. Even when the arithmetic is right, that number hasn't been checked. So the facts pack already contains the derived numbers the plan needs, and the check reports any number that isn't in it. It doesn't judge the advice itself; a planner still reads the plan.

The notebook writes ORDERS_AT_RISK and MITIGATION_PLANS back to the schema, so SQL, dashboards and tasks can use them.

Run the following statements, also available in tear_down.sql:

This leaves the RelationalAI app, its roles and the OAuth integration in place. To stop the app's compute, see Shut down the app.

You found a supplier risk that a tier-1 view hides, using PyRel rules over Snowflake tables from a local notebook, and turned the result into a checked mitigation plan with Cortex.