Python API Release Notes

1.23.1

Python SDK

Jul 22, 2026, 7:36 PM UTC

Version 1.23.1 of the relationalai Python package is now available!

To upgrade, activate your virtual environment and run the following command:

pip install --upgrade relationalai

New Features and Enhancements

A new project you create with rai models init now deploys to Snowflake without you having to add a refresh schedule by hand. Before this release, rai models deploy failed on a brand-new project with an Unscheduled Outputs error, because the generated raiconfig.yaml didn't say how often to refresh the deployed tables and views. The config now includes a default refresh schedule with interval_s: 0, which refreshes the outputs each time you deploy but not on a fixed interval, so the deploy succeeds.

Bug Fixes

If you haven't filled in your Snowflake connection details yet, PyRel now stops with a clear error message naming the values you need to fill in, instead of a confusing raw Snowflake error. For example, a new project's raiconfig.yaml might still have the placeholder account: myorg-myaccount. PyRel runs this check the first time it opens a Snowflake connection, so you see the message early, whether you run a script, run a query, or deploy your model.
The rai debugger can now open the logs from large programs without freezing. The debugger also has a new Collapse all button that closes every open section at once, and opening one section no longer expands the other sections with the same name.
Pulling or merging a shared model now correctly rebuilds models that earlier releases could rebuild incorrectly. When you run rai models pull or rai models merge, PyRel regenerates the shared model's code from your team's changes. Before this release, pull and merging a shared a model could sometimes result in models that failed to build.
You can now call solve() again on the same prescriptive Problem while asking for fewer of its optional sensitivity and conflict results. Before this release, re-solving without a sensitivity or conflict result you had requested earlier raised an error. Now the re-solve succeeds. On current RelationalAI platform versions, it also clears the results you no longer request, so you don't see stale numbers from an earlier solve. You still can't switch between a plain solve and a sensitivity or conflict solve on the same Problem. Create a new Problem for that.

1.23.0

Python SDK

Jul 22, 2026, 1:39 PM UTC

Version 1.23.0 of the relationalai Python package is now available!

To upgrade, activate your virtual environment and run the following command:

pip install --upgrade relationalai

New Features and Enhancements

You can now keep the capitalization of your column names when you deploy a model to Snowflake. By default, PyRel converts unquoted column names to all upper case, so a property named EntityId deploys as the column ENTITYID. To keep the case you declared instead, set preserve_column_case: true in the deployment section of your raiconfig.yaml (DeploymentConfig):
```
deployment:
  preserve_column_case: true   # default: false
```
This applies to column names only, not table names. With the option on, PyRel quotes the columns, so the names become case-sensitive in Snowflake. Query them with the exact case and quotes, such as "EntityId".
You can now name a relationship field that holds more than one kind of entity using the pipe operator | or the union() function. This is useful when a field can point to instances of different concepts, such as an account owned by either an Individual or an Organization:
```
Account.owner = m.Relationship(f"{Account} owned by {(Individual | Organization):owner}")
# equivalently:
Account.owner = m.Relationship(f"{Account} owned by {union(Individual, Organization):owner}")
```
Each option must be a concrete entity type, such as Individual or Organization, rather than a value type like a number or string. A union must list at least two.

Bug Fixes

Fixed a bug that caused some model deployments to fail with a NotImplementedError and produce incomplete output tables.
Fixed a bug that caused the refresh task for some deployed models to fail with a Snowflake error or to produce empty tables.
Fixed queries that read two fields from the same multi-field Property in one select(), such as select(invoice.total["currency"], invoice.total["amount"]), when invoice comes from a nested select() that returns more than one invoice.

Before 1.23.0, PyRel could mix rows across invoices, returning every invoice's field values for each invoice instead of only its own. Now each invoice returns only its own values. This bug only affected Property instances, not Relationship instances, which always return the stored pairs correctly.
```
# `invoice` comes from an inner select(), then an outer select() reads
# two fields of the same multi-field property:
invoice = model.where(Invoice.overdue).select(Invoice)[0]
model.select(invoice.total["currency"], invoice.total["amount"])
```
rai models pull no longer blocks a pull just because your branch has its own local changes. Before this release, PyRel could mistake those local changes for a conflict and block the pull. Now a pull is blocked only when your changes actually conflict with the shared history.

1.22.0

Python SDK

Jul 20, 2026, 5:30 PM UTC

Version 1.22.0 of the relationalai Python package is now available!

To upgrade, activate your virtual environment and run the following command:

pip install --upgrade relationalai

New Features and Enhancements

You can now share your Snowflake connections, and other settings, across projects instead of copying them into every project's raiconfig.yaml. PyRel now discovers a home-level ~/.rai/raiconfig.yaml configuration file and merges it with each project's raiconfig.yaml, so you define shared settings once. Previously, a project file that only named a shared connection (default_connection: my_conn) failed, because PyRel couldn't find where that connection was defined.

For example, define a connection once in the home file, then reference it by name from any project:
```
# ~/.rai/raiconfig.yaml — define the connection once
connections:
  my_conn:
    account: MY_ACCOUNT
    user: MY_USER
    role: MY_ROLE
    warehouse: MY_WH
default_connection: my_conn
```
```
# raiconfig.yaml — in a project; no connection details needed here
default_connection: my_conn
```
Anything you set in a project file still wins, so per-project overrides keep working. Not sure where a setting is coming from? Run rai config:explain to trace each value to its file.
You can now deploy a model from Python code by passing a config to Model, instead of deploying from a raiconfig.yaml file. For those deploys, the rai doctor report troubleshooting report is now accurate. Before this release, it could show parts of your deployment as missing. Now it reflects the configuration your deploy actually used.

Bug Fixes

Improved performance for queries against deployed models that compute several aggregates grouped by the same key with per. Before this release, PyRel compiled these queries to SQL that repeated the same grouping join far more times than needed, so they ran slower while still returning correct results. Now the generated SQL is much smaller and runs faster.
Fixed how PyRel references a Snowflake database, schema, or table used as a data source whose quoted name contains a period, such as a table named "CoNNec.tioNs". Before this release, PyRel split the name on every period and produced an incorrect table reference. Now it keeps the quoted name intact.

1.21.4

Python SDK

Jul 18, 2026, 12:37 AM UTC

Version 1.21.4 of the relationalai Python package is now available!

To upgrade, activate your virtual environment and run the following command:

pip install --upgrade relationalai

New Features and Enhancements

Deployed models now refresh more efficiently when a concept declares primary keys with identify_by. Before this release, PyRel always added a hashed _ID key column to deployed concept tables and joined on it. Now it uses the declared key columns directly, so each refresh does less work and returns the same results.

Bug Fixes

Fixed a correctness problem in deployed models where you identify a concept by a source column whose values can repeat, such as an Order identified by an order id that appears on many line-item rows. Before this release, that concept's deployed table could contain duplicate rows for the same Order, so some queries over it could return wrong results. The table now keeps one row per entity, so those queries return correct results.
Fixed Model.Table] so that you can access Snowflake source columns whose names contain spaces. Before this release, accessing such a column by the name you declared (for example, orders["customer id"]) raised a KeyError even though the column existed. Now it resolves to that column.

1.21.3

Python SDK

Jul 16, 2026, 8:36 PM UTC

Version 1.21.3 of the relationalai Python package is now available!

To upgrade, activate your virtual environment and run the following command:

pip install --upgrade relationalai

New Features and Enhancements

Improved deployed model refresh performance for models with a concept whose identity comes from columns in more than one table. Before this release, if that concept had several properties, PyRel re-read and re-joined those tables once for every property on each refresh, which was slow over large tables. Now PyRel reads and joins them once and fills in all the concept's properties from a single pass, so each refresh does less repeated work and returns the same results.
Improved status reporting for the REFRESH_STATUS procedure.

1.21.2

Python SDK

Jul 16, 2026, 6:50 PM UTC

Version 1.21.2 of the relationalai Python package is now available!

To upgrade, activate your virtual environment and run the following command:

pip install --upgrade relationalai

New Features and Enhancements

Improved the errors you get when deploying a model that uses reasoning not yet supported in deploy mode. Before this release, deploying a model that used prescriptive optimization (Problem) or predictive (GNN) reasoning could fail in a confusing way. Now PyRel raises a clear NotImplementedError explaining that these reasoners are not yet supported in deploy mode and telling you to remove the deployment configuration if you need them.
The starter project created by rai models init now runs its deploy step with rai models deploy --wait, so the first deployment finishes before you query. Before this release, the generated project could return empty results if you queried before that first deployment completed.

Bug Fixes

Fixed a crash when re-deploying a model with rai models deploy where a rule reads a column from a table loaded without an explicit schema. Before this release, re-deploying such a model failed with a ValueError: Cannot translate removal of <column>, even though no column had actually been removed. Now PyRel recognizes that the model is unchanged and the re-deploy completes successfully.

PyRel now reports an error when a concept inherits conflicting identities from more than one parent concept. Before this release, PyRel accepted this and could build a model that behaves incorrectly. Now PyRel raises an Incompatible identify_by relations error that names the two conflicting parents.

To fix it, define the identity once on a shared parent that both concepts extend:

from relationalai.semantics import Model, String

m = Model("Demo")

# Rejected: X and Y each define their own identity, so Z cannot inherit both.
X = m.Concept("X", identify_by={"x_id": String})
Y = m.Concept("Y", identify_by={"y_id": String})
# PyRel raises:
#   Concept Z has supertypes with incompatible identify_by relations: X vs Y
Z = m.Concept("Z", extends=[X, Y])

# Fixed: define the identity once on a shared parent, Base.
# A and B inherit their identity from Base, so C gets one consistent identity.
Base = m.Concept("Base", identify_by={"id": String})
A = m.Concept("A", extends=[Base])
B = m.Concept("B", extends=[Base])
C = m.Concept("C", extends=[A, B])

Fixed rai models pull so it reports a conflict instead of building an invalid model. Before this release, pulling branch changes into a shared model could introduce duplicate property names and cause an error at query time. Now pull raises a conflict error when a branch would introduce a property-name collision, so you can resolve the conflict before continuing.
Fixed std.re.findall() when you call it on a table column. For each row's value, findall() returns every match together with its position (1, 2, 3, and so on) in the value. Before this release, the position counted up across the whole column instead of restarting for each row, and rows with no match were dropped. Now the position restarts at 1 for each row, and rows with no match are kept.

1.21.1

Python SDK

Jul 15, 2026, 12:25 PM UTC

Version 1.21.1 of the relationalai Python package is now available!

To upgrade, activate your virtual environment and run the following command:

pip install --upgrade relationalai

New Features and Enhancements

Reduced query startup time for deploy mode users running in manual mode (auto_deploy=False in deploy mode configuration). PyRel now skips a pre-run deployment check, so queries begin sooner. In manual mode, you will no longer see NO_DEPLOY_STATE or MATCHING_DEPLOY_FAILED during query preparation. This change reduces query latency, but should only be used in development since queries may return stale results because of the skipped check.
Improved troubleshooting in rai doctor for Private Link accounts that use Direct Access. Before this release, many failures looked like generic token-exchange errors. Now doctor output includes a dedicated direct_access_privatelink section with specific categories such as jwt_claim_error, endpoint_routing_error, and grant_error so you can identify the next fix quickly.

For example, run:
```
rai doctor --format json
```
Then check this output fragment:
```
{
  "direct_access_privatelink": {
    "checked": true,
    "ok": false,
    "error_type": "endpoint_routing_error"
  }
}
```
Use error_type to choose your next step: endpoint_routing_error: verify Private Link endpoint routing. jwt_claim_error: verify JWT claim formatting. grant_error: verify grants and scopes.

Bug Fixes

Fixed an issue in the deploy mode workflow (rai models deploy) where deployment could produce an incomplete model in some cases. Before this release, deploy could finish successfully but still miss expected deployed tables or views, causing results to differ from the model you defined. Now deployed outputs fully reflect the model definition.
Fixed issues in deploy mode's shared-model synchronization workflow, where rai models pull and rai models deploy regenerate model source and string logic could change. This affected string expressions, including std.strings.contains() and std.strings.split(). Before this release, filters could be dropped and values derived from split() could fail after export and reload, so results could differ between the original and reloaded model. Now those expressions are preserved after export and reload, so the reloaded model behaves like the original.
```
# In an existing model with Person.name and Person.part,
# these expressions should still behave the same after export and reload.
idx, part = std.strings.split(Person.name, ",")
m.where(Person, std.strings.contains(Person.name, "x")).define(Person.part(part))

# Quick check after export and reload:
# Compare the number of Person rows matching contains("x") before vs. after export and reload.
# Expected outcome: the counts are equal.
```

1.21.0

Python SDK

Jul 13, 2026, 1:26 PM UTC

Version 1.21.0 of the relationalai Python package is now available!

To upgrade, activate your virtual environment and run the following command:

pip install --upgrade relationalai

New Features and Enhancements

PyRel 1.21.0 introduces a new public preview feature called deploy mode that lets you deploy a PyRel model to a Snowflake schema as SQL tables and views. For more information, see Deploy a model.

Improved the clarity of error messages when you define membership between concept types that do not match in Model.define(). Before this release, m.define(Target(Source)) could fail with a generic type-mismatch message that did not tell you how to fix the model. Now the error explains compatible fixes, such as making Target a subtype of Source or using AnyEntity when you intentionally allow heterogeneous membership. This example shows one invalid definition and two valid fixes:

from relationalai.semantics import AnyEntity, Model

m = Model("Demo")
SourceConcept = m.Concept("Order")

# Invalid: TargetConcept does not extend SourceConcept.
TargetConcept = m.Concept("NeedsReview")
m.define(TargetConcept(SourceConcept))

# Valid fix 1: make the target concept a subtype of SourceConcept.
TargetSubtype = m.Concept("OrderThatNeedsReview", extends=[SourceConcept])
m.define(TargetSubtype(SourceConcept))

# Valid fix 2: use AnyEntity when membership should accept mixed concept types.
TargetAnyEntity = m.Concept("NeedsReviewAny", extends=[AnyEntity])
m.define(TargetAnyEntity(SourceConcept))

1.20.1

Python SDK

Jul 9, 2026, 9:29 PM UTC

Version 1.20.1 of the relationalai Python package is now available!

To upgrade, activate your virtual environment and run the following command:

pip install --upgrade relationalai

New Features and Enhancements

Deployed Cortex tools now start returning results faster. Before this release, a deployed tool could spend noticeable time re-checking Snowflake schema information on every call before it ran the actual query. Now PyRel reuses that information across calls, which reduces startup delay for repeated requests.

Bug Fixes

Fixed a bug where ReasonersClient.ensure() and ReasonersClientSync.ensure() could silently reuse an existing prescriptive reasoner even after your configured settings had changed. Before this release, calling ensure("PRESCRIPTIVE") after changing your reasoner size or settings could return the old, mismatched reasoner without any warning. Now PyRel compares your configured settings against the existing reasoner before reusing it, and raises ReasonerConflictError when they do not match so you can resolve the conflict explicitly.
Fixed a bug where querying certain Snowflake columns returned NULL or a SQL error instead of your data. This affected columns whose names use capital letters, special characters such as ., or a word that SQL reserves for its own use, such as ORDER. Before this release, PyRel changed a name like PrimaryAssetId to all uppercase (PRIMARYASSETID) under the hood. Snowflake treats those as two different columns, so it looked for a column that didn't exist and returned NULL. Now PyRel uses the column name exactly as it is stored, so these queries return the correct values.
Fixed a bug where a negated comparison could silently apply a different condition than the one you wrote. Before this release, an expression such as not_(Person.age > 18) could be stored and re-evaluated as not_(Person.age) instead. That selects entities with no recorded age, not entities under 18, and PyRel gave no indication that the condition had changed. Now the comparison is always preserved exactly as written.
Fixed a NameError that could occur when using Model.union() to collect values from multiple properties. Before this release, a union such as m.union(Employee.email, Employee.phone) could fail with NameError: name 'Any' is not defined. Now this expression executes correctly and returns the combined values.

1.20.0

Python SDK

Jul 8, 2026, 10:35 AM UTC

Version 1.20.0 of the relationalai Python package is now available!

To upgrade, activate your virtual environment and run the following command:

pip install --upgrade relationalai

New Features and Enhancements

Multiple Cortex agents can now share the same Snowflake schema by assigning each a unique prefix. Previously, each agent required its own schema, leading to schema sprawl and management overhead. Now you can keep related agents together:

from relationalai.agent.cortex import DeploymentConfig

# Customer service agent
service_config = DeploymentConfig(
    database="APPS",
    schema="AGENTS",
    agent_name="customer_service",
    prefix="service",  # stored procedures: service_RAI_*
)

# Sales agent in the same schema
sales_config = DeploymentConfig(
    database="APPS",
    schema="AGENTS",
    agent_name="sales",
    prefix="sales",  # stored procedures: sales_RAI_*
)

Existing deployments without a prefix continue to work unchanged.

Bug Fixes

Unsupported operators in prescriptive problems now raise clearer error messages. When you use an operator like % or // in a Problem expression, you get a helpful message that points you to fix the operator:
```
# Now raises a NotImplementedError because % is not supported
problem.add_constraint(quantity % 2 == 0)
```

1.19.4

Python SDK

Jul 6, 2026, 9:52 PM UTC

Version 1.19.4 of the relationalai Python package is now available!

To upgrade, activate your virtual environment and run the following command:

pip install --upgrade relationalai

New Features and Enhancements

Predictive dataset diagrams are now easier to render and save. Before this release, you had to call visualize_dataset() and manually render the returned object. Now you can call display_dataset_diagram() to show the diagram in a notebook, or save_dataset_diagram(path) to save it directly to a file such as schema.svg.
Removed the snowflake-ml-python dependency from the relationalai package because one of its transitive dependencies is not compatible with Python 3.13. The snowflake-ml-python dependency was only included if you installed relationalai with the [gnn] extra, such as with pip install relationalai[gnn].
rai config:explain output is now easier to scan. Before this release, fields were listed in declaration order. Now fields are sorted alphabetically across top-level, nested, dictionary, and profile sections.

1.19.3

Python SDK

Jul 2, 2026, 5:34 PM UTC

Version 1.19.3 of the relationalai Python package is now available!

To upgrade, activate your virtual environment and run the following command:

pip install --upgrade relationalai

Bug Fixes

Fixed a regression in 1.19.2 that broke exports into Snowflake destination tables with Table targets when you call .into(Table(...)) on a query result. This now works as expected.
Fixed an issue that caused expressions like where(x | y).define(...) to raise an Unused variable declared error when both sides of the | operator contained calculated values. These expressions now evaluate to the expected value.

1.19.2

Python SDK

Jul 1, 2026, 9:47 PM UTC

Version 1.19.2 of the relationalai Python package is now available!

To upgrade, activate your virtual environment and run the following command:

pip install --upgrade relationalai

New Features and Enhancements

Improved reasoner-name validation in rai reasoners create. Invalid names are now rejected earlier with a clearer message, instead of failing later during provisioning. This makes naming mistakes easier to spot before reasoner setup starts.

Bug Fixes

Fixed a name-resolution regression in rai reasoners create --name. Before 1.19.2, an invalid default reasoner name from configuration (for example, a username-derived fallback) could still block a valid explicit --name value.

1.19.1

Python SDK

Jul 1, 2026, 4:49 PM UTC

Version 1.19.1 of the relationalai Python package is now available!

To upgrade, activate your virtual environment and run the following command:

pip install --upgrade relationalai

Bug Fixes

Fixed queries against Snowflake tables declared with Table when the table name or stored column spelling requires quoting, including case-sensitive names and names that contain spaces, punctuation, and Unicode characters. For example, the following query now resolves both the quoted table name and the quoted column name correctly:
```
from relationalai.semantics import Model

m = Model("demo")
orders = m.Table('"table with spaces"')

m.select(orders["id"], orders["column one"]).to_df()
```
Previously, this could raise a RAIException such as [Unknown Table] Failed to fetch schema for table '"table with spaces"'.

1.19.0

Python SDK

Jul 1, 2026, 1:28 PM UTC

Version 1.19.0 of the relationalai Python package is now available!

To upgrade, activate your virtual environment and run the following command:

pip install --upgrade relationalai

Bug Fixes

Fixed queries that read two fields from the same multi-field Property in one select(), such as select(invoice.total["currency"], invoice.total["amount"]). Before 1.19.0, PyRel could incorrectly return every combination of the fields' values instead of keeping the original pairs together. This bug only impacted Property instances and not Relationship instances, which always return the stored pairs correctly.

1.18.0

Python SDK

Jun 30, 2026, 9:12 PM UTC

Version 1.18.0 of the relationalai Python package is now available!

To upgrade, activate your virtual environment and run the following command:

pip install --upgrade relationalai

New Features and Enhancements

rai doctor report now generates a deterministic diagnosis.md summary and shows the same diagnosis in the debugger report browser. Before 1.18.0, you had to inspect the collected artifacts yourself to identify likely configuration, Snowflake, deploy, schema-cache, trace, or collection problems.
PyRel now fails fast on undefined config references instead of ignoring them or failing later at runtime. For example, a typo in active_profile such as active_profile: localm now raises a clear validation error during config loading.

Bug Fixes

Fixed math.clip() so it returns the clipped value instead of NULL when the input falls below, within, or above the requested bounds.
Fixed how reasoner names are generated. If you don't set custom reasoner names in your configuration, provisioning could previously fail when your username starts with a digit because the generated reasoner name was invalid. PyRel now sanitizes the generated name automatically, for example by turning 12345 into user_12345.
Fixed nested select() values inside union and match branches, and fixed aggregates over scalar subquery values, so those query shapes return the expected rows instead of raising internal compiler or validation errors.
Fixed rank() queries that also return a related value in the same result. Those queries now return the expected table and use NULL when the related value is missing instead of failing validation.

PyRel now raises an Ambiguous concept usage error when one rule reuses the same concept name as both a variable and a concept type in the same line. For example, the following code now raises an error instead of silently misinterpreting the second line:

from relationalai.semantics import Model, String

m = Model("ambiguous")
A = m.Concept("A")
B = m.Concept("B", extends=[A])
C = m.Concept("C", extends=[A])
D = m.Concept("D", extends=[B, C])

A.id = m.Property(f"{A} is identified by {String}")
A.identify_by(A.id)

m.define(A.new(m.data([
    {"id": "w"},
    {"id": "x"},
    {"id": "y"},
    {"id": "z"},
]).to_schema()))
m.define(B(A)).where(A.id.in_(["w", "x", "z"]))
m.define(C(A)).where(A.id.in_(["w", "y", "z"]))

# Unambiguous: B is a variable in both places.
m.define(D(B)).where(C(B))

# Ambiguous: B is variable in D(B) but a concept type in B(C).
m.define(D(B)).where(B(C))  # now raises "Ambiguous concept usage"

Previously, PyRel would silently define every entity of type B as a D in this case because the type expression B(C) doesn't constrain the variable B in .define() in any way.

1.17.0

Python SDK

Jun 25, 2026, 8:27 PM UTC

Version 1.17.0 of the relationalai Python package is now available!

To upgrade, activate your virtual environment and run the following command:

pip install --upgrade relationalai

New Features and Enhancements

Added keyword field binding for Relationship calls. For example, if a relationship has src, transfer, and dst fields, you can write:
```
Account.transferred_to(src=source, transfer=transfer, dst=destination)
```
In addition to not having to pass fields in order, you also get clearer errors for missing fields and unknown fields.
Added support for per(...).product(...) to create a grouped product. Before 1.17.0, only product(...).per(...) was supported.
Combined more rai doctor report troubleshooting information into one zip file. Before 1.17.0, support cases could require both doctor_report_*.zip from rai doctor report and a separate oplog_report_*.zip from rai doctor report-oplog. Now rai doctor report includes that extra information in doctor_report_*.zip.

Bug Fixes and Diagnostics

Fixed cases where duplicated values in prescriptive sum() and count() expressions inside a Problem were counted once in the aggregate instead of multiple times as expected.
Fixed Direct Access for Snowflake Private Link accounts.
Fixed handling for cross-model mix-ups when code uses objects from one Model inside another Model. Some of these cases previously resulted in empty results or confusing errors. PyRel now raises a clear, direct error instead.
Improved the error shown when top(), bottom(), or limit() is used in places that require a single value, such as comparisons or property values.

1.16.0

Python SDK

Jun 23, 2026, 12:00 PM UTC

Version 1.16.0 of the relationalai Python package is now available!

To upgrade, activate your virtual environment and run the following command:

pip install --upgrade relationalai

New Features and Enhancements

You can now use OplogConfig to opt in to model oplog recording during deploys. Set oplog.enabled: true so a successful rai models deploy records the change in the model oplog. That record then lets you use rai models pull, rai models branch, and rai models merge for that model. Before 1.16.0, the public Python API docs did not expose this config section or this opt-in deploy behavior.

1.15.0

Python SDK

Jun 17, 2026, 9:07 PM UTC

Version 1.15.0 of the relationalai Python package is now available!

To upgrade, activate your virtual environment and run the following command:

pip install --upgrade relationalai

New Features and Enhancements

You can now use alias() to give any value an output alias, including Python literals such as 1, which can't call .alias() directly. Before 1.15.0, there was no top-level helper in relationalai.semantics to alias literal values.

1.14.0

Python SDK

Jun 16, 2026, 12:00 PM UTC

Version 1.14.0 of the relationalai Python package is now available!

To upgrade, activate your virtual environment and run the following command:

pip install --upgrade relationalai

Bug Fix

Job commands such as rai jobs create now send background job guidance to stderr instead of stdout. This keeps stdout cleaner for scripts. If your automation relied on those guidance lines, you may need to capture or redirect stderr.

1.13.0

Python SDK

Jun 15, 2026, 6:10 PM UTC

Version 1.13.0 of the relationalai Python package is now available!

To upgrade, activate your virtual environment and run the following command:

pip install --upgrade relationalai

New Features and Enhancements

You can now use std.re regex queries with the SQL backend, including match(), search(), fullmatch(), findall(), and sub(). Before 1.13.0, the SQL backend did not support these regex operations.
The ZIP archive from rai doctor:report now includes a readable summary.md file so you can quickly review status and key diagnostics. Before 1.13.0, you had to inspect raw JSON, YAML, and CSV artifacts for that overview.

Bug Fixes

rai doctor now warns earlier when you use direct_access: true with an unsupported Snowflake authenticator and tells you how to fix it. Before this fix, you might instead hit a later raw token-exchange error.
Deployments and refresh tasks now use the Snowflake role you set in DeploymentConfig.role. Before this fix, PyRel could ignore that setting and use a different role.

1.12.0

Python SDK

Jun 10, 2026, 8:30 PM UTC

Version 1.12.0 of the relationalai Python package is now available!

To upgrade, activate your virtual environment and run the following command:

pip install --upgrade relationalai

New Features and Enhancements

You can now use aggregates.product() to compute the product of numeric values in PyRel queries. Before 1.12.0, the standard aggregates module did not include a built-in product aggregate.
rai doctor:report now includes expanded diagnostics.

1.11.0

Python SDK

Jun 9, 2026, 2:28 PM UTC

Version 1.11.0 of the relationalai Python package is now available!

To upgrade, activate your virtual environment and run the following command:

pip install --upgrade relationalai

Bug Fix

PyRel now stops at the first model compilation error. Before this fix, PyRel could continue and fail later with a less clear error.

1.10.0

Python SDK

Jun 9, 2026, 11:49 AM UTC

Version 1.10.0 of the relationalai Python package is now available!

To upgrade, activate your virtual environment and run the following command:

pip install --upgrade relationalai

New Features and Enhancements

You can now use stddev_samp() in PyRel queries to compute sample standard deviation. Before 1.10.0, you had to compute it outside PyRel or build it from lower-level operations.
rai doctor:report now provides more detail when you troubleshoot deployment-role issues or share environment details with support. It adds Snowflake task execute privilege diagnostics and richer version metadata.

Bug Fixes

Imports for the prescriptive and predictive reasoner packages now work on Python 3.11 or later. Before this fix, imports could fail because of an invalid dataclass default.
SQL-backed select() queries no longer return unexpected duplicate rows when you use distinct().
Some Snowflake deployments no longer fail when models read Snowflake-backed data sources through CDC. Before this fix, deployments could materialize those inputs as unsupported dynamic tables instead of CDC-compatible tables with change tracking.

1.9.0

Python SDK

Jun 4, 2026, 11:12 PM UTC

Version 1.9.0 of the relationalai Python package is now available!

To upgrade, activate your virtual environment and run the following command:

pip install --upgrade relationalai

Upgrade Notes

If your code uses filter_by() on Concept or Ref, it now emits a Python DeprecationWarning in 1.9.0. Your existing code still works in 1.9.0. Use .lookup() instead of filter_by() going forward.

New Features and Enhancements

Prescriptive solve() now helps you inspect solved models and diagnose infeasible ones. Use solve(sensitivity=True) after solving to inspect solve diagnostics such as reduced costs and constraint sensitivity. Use solve(conflict=True) to identify infeasibility conflicts, then check solve_info().conflict_status.
PyRel 1.9.0 improves CLI diagnostics. rai doctor now prints live health checks, and doctor:report collects diagnostic artifacts for support.

Bug Fixes

Fixed a bug where queries using top(), bottom(), or limit() could fail with a SQL parser error.
When raiconfig.yaml contains placeholders, rai doctor now identifies the missing configuration instead of failing with a raw connection error.
If you use grouped optional aggregates over stored relationships, those Snowflake-backed queries now run correctly. Before this fix, they could fail with Unsupported subquery type cannot be evaluated.

1.8.1

Python SDK

May 28, 2026, 10:46 AM UTC

Version 1.8.1 of the relationalai Python package is now available!

To upgrade, activate your virtual environment and run the following command:

pip install --upgrade relationalai

New Features and Enhancements

Added a new LogicReasonerConfig.readonly_queries config option that can help improve performance when you run multiple queries against the same model. It is disabled by default.

1.8.0

Python SDK

May 27, 2026, 8:52 PM UTC

Version 1.8.0 of the relationalai Python package is now available!

To upgrade, activate your virtual environment and run the following command:

pip install --upgrade relationalai

New Features and Enhancements

A standard relationalai install now includes the packages needed for predictive reasoning workflows. You no longer need to install using pip install relationalai[gnn].
If a model contains multiple exports to Snowflake tables, independent exports are now run concurrently.

Bug Fix

Predictive GNN edge tables now load in a stable order. gnn.dataset.tables indices are now deterministic across runs.

1.7.1

Python SDK

May 22, 2026, 8:11 PM UTC

Version 1.7.1 of the relationalai Python package is now available!

To upgrade, activate your virtual environment and run the following command:

pip install --upgrade relationalai

Bug Fixes

Fixed a bug that prevented the creation of concepts with spaces and other special characters in their names.

Fixed a bug that caused some users to see the following error:

Uncaught exception of type 'STATEMENT_ERROR' on line 88 at position 6 : Uncaught exception of type 'STATEMENT_ERROR' on line 46 at position 0 : SQL compilation error:
Window function type [ROW_NUMBER] requires ORDER BY in window specification.

1.7.0

Python SDK

May 22, 2026, 9:28 AM UTC

Version 1.7.0 of the relationalai Python package is now available!

To upgrade, activate your virtual environment and run the following command:

pip install --upgrade relationalai

New Features and Enhancements

Snowflake connections now support authenticator="oauth_client_credentials" for app-to-app OAuth flows. See OAuthClientCredentialsAuth for configuration details.
Added rai reasoners sizes to inspect available reasoner sizes.

Bug Fixes

PyRel now normalizes Snowflake object identifiers the same way that Snowflake does. This prevents errors that claim that existing objects can't be found.

1.6.0

Python SDK

May 20, 2026, 10:47 AM UTC

Version 1.6.0 of the relationalai Python package is now available!

To upgrade, activate your virtual environment and run the following command:

pip install --upgrade relationalai

New Features and Enhancements

Added cleanup commands under rai clean:
- rai clean cache removes the local schema cache file.
- rai clean debugger removes debugger run directories and trace logs.

1.5.0

Python SDK

May 19, 2026, 12:41 PM UTC

Version 1.5.0 of the relationalai Python package is now available!

To upgrade, activate your virtual environment and run the following command:

pip install --upgrade relationalai

New Features and Enhancements

Added diagnostics CLI commands under rai doctor, including doctor:report and doctor:cache:check for cache checks.
PyRel now accepts optional Snowflake connector and session settings in its Snowflake connection config, including client_session_keep_alive, login_timeout, network_timeout, socket_timeout, and session_parameters. Before this change, you could not set these options through PyRel config and had to rely on Snowflake connector defaults. Now you can tune long-running or idle-sensitive Snowflake connections from PyRel config.

Bug Fixes

cumsum_asc() now handles multiple sort keys correctly. Before this change, cumulative sums could be wrong when you ordered by more than one sort key.
Graph validation now catches a few edge cases earlier. Before this change, some invalid node types were not caught until later in the execution path. Now you'll see those errors earlier.
Fixed a bug that caused weighted Jaccard or cosine similarity to behave inconsistently for zero-weight edges.

1.4.2

Python SDK

May 15, 2026, 6:50 PM UTC

Version 1.4.2 of the relationalai Python package is now available!

To upgrade, activate your virtual environment and run the following command:

pip install --upgrade relationalai

New Features and Enhancements

rai config use now supports interactive profile selection. In non-interactive runs, the command still requires an explicit profile.

Bug Fixes

Setting config.model.keep = False on a Model now deletes the RAI resources on exit as intended. Before this fix, the v1 execution path could silently keep the resources even when cleanup was requested.

1.4.1

Python SDK

May 15, 2026, 11:27 AM UTC

Version 1.4.1 of the relationalai Python package is now available!

To upgrade, activate your virtual environment and run the following command:

pip install --upgrade relationalai

New Features and Enhancements

Added a new predictive reasoning API under relationalai.semantics.reasoners.predictive. It includes GNN for training, loading, registering, and predicting with Graph Neural Networks.
rai init now gives clearer step-by-step terminal guidance. New config templates also default to browser-based Snowflake authentication instead of password placeholders. For interactive Snowflake sign-in, see Configure external browser authentication.

Bug Fixes

Fixed prescriptive aggregate correctness bugs when defining a Problem.
Fixed a recursion error caused by some expressions like model.where(count(B) >= 0).define(C.new(val=B)).
rai reasoners:list and the interactive reasoner picker no longer fail if the backend returns unknown reasoner types.
Problem.solve() now sends numeric type metadata to the solver service. This prevents float-valued MiniZinc solves from falling back to an integer-only path and failing with inexact conversion errors.

1.3.1

Python SDK

May 13, 2026, 3:50 PM UTC

Version 1.3.1 of the relationalai Python package is now available!

To upgrade, activate your virtual environment and run the following command:

pip install --upgrade relationalai

Bug Fixes

Fixed a bug where Concept.new() could treat entities with different identity field names as the same entity if the values matched.

1.3.0

Python SDK

May 13, 2026, 11:26 AM UTC

Version 1.3.0 of the relationalai Python package is now available!

To upgrade, activate your virtual environment and run the following command:

pip install --upgrade relationalai

New Features and Enhancements

Added three CLI commands for troubleshooting and environment checks:
- rai version for a quick version check or --verbose output with runtime and install details.
- rai whoami to confirm which identity and profile the CLI is using, or --resolve to compare that with the server-resolved user.
- rai diagnose to capture version, config, and connectivity diagnostics in one command, with optional JSON or YAML output for automation and support workflows.
Problem.display() now supports where= and limit= arguments so you can inspect a filtered subset of rows or cap the output instead of printing the full problem summary.

1.2.2

Python SDK

May 7, 2026, 8:59 PM UTC

Version 1.2.2 of the relationalai Python package is now available!

To upgrade, activate your virtual environment and run the following command:

pip install --upgrade relationalai

New Features and Enhancements

More RAI CLI commands now support JSON and YAML output options, and these output formats has been standardizes across commands for easier integration with automation scripts.

The following commands now all support --output json and --output yaml:
Added a new rai reasoners wait command that blocks until a reasoner is READY. In addition, the rai reasoners create and rai reasoners resume commands now support --wait and --no-wait options.
Cortex agent deployment diagnostics now help you validate your Snowflake setup before deployment:
- Use CortexAgentManager.preflight() to surface missing permission grants and source objects in one pass.
- Use CortexAgentManager.print_setup_sql() to generate the matching GRANT block.
- Run python -m relationalai.agent.cortex.diagnostics to perform the same checks from the command line.

Bug Fixes

Fixed a bug in relationalai.agent.cortex that could cause 404 errors during deployment.

1.2.1

Python SDK

May 6, 2026, 4:59 PM UTC

Version 1.2.1 of the relationalai Python package is now available!

To upgrade, activate your virtual environment and run the following command:

pip install --upgrade relationalai

New Features and Enhancements

PyRel now makes configuration profiles easier to use from the CLI:
- You can override the active profile for a single CLI command using the --profile option or the RAI_PROFILE environment variable.
- Use new CLI commands to manage profiles:
  - rai config profiles to list available profiles
  - rai config current to check which profile is active
  - rai config use to change the active_profile in your config file
The CLI also gives clearer feedback when:
- No profile is selected
- A requested profile does not exist
- An environment override takes precedence over the active_profile in your config

1.2.0

Python SDK

May 5, 2026, 3:31 PM UTC

Version 1.2.0 of the relationalai Python package is now available!

To upgrade, activate your virtual environment and run the following command:

pip install --upgrade relationalai

New Features and Enhancements

The rai CLI now supports space-separated subcommands such as rai jobs list and rai reasoners list. Existing rai jobs:list-style commands still work, but interactive shells now show a one-time deprecation hint so you can migrate at your own pace.
rai completion install adds shell completion setup for bash, zsh, and fish, and rai commands gives you a browsable view of the available CLI command tree.
Graph.cosine_similarity() now supports directed graphs.

Bug Fixes

In scripts, CI, and other non-interactive runs, PyRel now shows the full error details before the final RAIException when type inference or similar compiler checks fail. Before, these failed checks could stop with only a generic see above for details message with the real diagnostic missing.
Problem.solve_for() now works when you solve for an inherited property or relationship. Prior to this fix, if a Parent concept defines a Parent.foo property and the Sub concept inherits it by extending Parent, solve_for(Sub.foo) could raise a TypeError.

1.1.1

Python SDK

Apr 30, 2026, 11:22 PM UTC

Version 1.1.1 of the relationalai Python package is now available!

To upgrade, activate your virtual environment and run the following command:

pip install --upgrade relationalai

New Features and Enhancements

rai jobs:list and rai reasoners:list now make pagination explicit when you use --limit and --offset. Before, paginated table output could look like a complete result set even when it only showed one slice. Now the CLI adds a footer when needed, including a copyable next-page command when more results may be available and a clearer message when an offset is past the end of the result set.
rai now checks whether a newer PyRel release is available and shows an upgrade prompt when your installed version is behind. Standard CLI invocations refresh a cached check in the background, and rai --version checks synchronously so the notice can appear immediately. The notice is suppressed for JSON output, CI, non-interactive runs, and by setting RAI_NO_UPDATE_CHECK=1 in your environment variables.

1.1.0

Python SDK

Apr 29, 2026, 5:05 PM UTC

Version 1.1.0 of the relationalai Python package is now available!

To upgrade, activate your virtual environment and run the following command:

pip install --upgrade relationalai

New Features and Enhancements

Graph.jaccard_similarity() now supports directed graphs, including weighted directed graphs.

Bug Fixes

Fixed jobs filtering in methods such as JobsClient.list() and commands such as rai jobs:list. Before, if you ran them with the reasoner type set to Predictive or Prescriptive, the output could leave out matching jobs when PyRel was configured for Direct Access. Now those jobs are included, as expected.

1.0.19

Python SDK

Apr 28, 2026, 8:46 AM UTC

Version 1.0.19 of the relationalai Python package is now available!

To upgrade, activate your virtual environment and run the following command:

pip install --upgrade relationalai

New Features and Enhancements

Graph.is_acyclic() is now much faster on many large graphs, especially large trees and grids. In benchmarks for the change, the runtime for the largest tested grid graph dropped from about 751 seconds to 47 seconds.

Bug Fixes

Removed unsupported std.re APIs. These APIs would raise errors if you tried to use them. All documentation pertaining to std.re has also been removed.
Fixed active profile selection so that the RAI_ACTIVE_PROFILE environment variable takes precedence over active_profile in raiconfig.yaml.

Fixed prescriptive models that combined filtered aggregates in one expression. Before, PyRel could leak one aggregate's filter into another, so objectives and constraints could silently drop instead of being sent to the solver. For example:

from relationalai.semantics import Float, Integer, Model
from relationalai.semantics.reasoners.prescriptive import Problem

model = Model("ScopedAggregates")
X = model.Concept("X", identify_by={"i": Integer})
X.v = model.Property(f"{X} has {Float:v}")

model.define(X.new(i=1), X.new(i=2))

problem = Problem(model, Float)
problem.solve_for(X.v, name=["v", X.i], lower=0, upper=10)

v = Float.ref()
problem.satisfy(model.require(sum(v).where(X.v(v), X.i == 1) == 1.0))
problem.satisfy(model.require(sum(v).where(X.v(v), X.i == 2) == 4.0))

# The bug was triggered by combining two filtered aggregates in one expression.
problem.minimize(sum(X.v).where(X.i == 1) + sum(X.v).where(X.i == 2))
problem.satisfy(model.require(sum(X.v).where(X.i == 1) <= sum(X.v).where(X.i == 2)))

problem.solve("highs")

print(model.select(problem.num_min_objectives().alias("objective_count")).to_df())
print(model.select(problem.num_constraints().alias("constraint_count")).to_df())
print("objective_value:", problem.solve_info().objective_value)

Output before the fix:

  objective_count
0                0
  constraint_count
0                 2
objective_value: 0.0

Output after the fix:

  objective_count
0                1
  constraint_count
0                 3
objective_value: 5.0

Fixed model.data() calls created on the same source line, such as inside a loop. model.data() creates a temporary data source each time you call it. Before, if two calls happened on the same line, PyRel could mistake them for the same source. That could make later queries fail even when the input data was valid.

For example:

from relationalai.semantics import Integer, Model, String

m = Model("DataLoop")
Item = m.Concept("Item", identify_by={"id": Integer, "name": String})

batches = [
    pd.DataFrame([(1, "a"), (2, "b")], columns=["id", "name"]),
    pd.DataFrame([(3, "c"), (4, "d")], columns=["id", "name"]),
]

for batch in batches:
    m.define(Item.new(m.data(batch).to_schema()))

print(m.select(Item.id, Item.name).to_df())

Output before the fix:

RelQueryError: Query error

Output after the fix:

  id name
0  1   a
1  2   b
2  3   c
3  4   d

Now PyRel gives each same-line data source its own deterministic sequence number, so queries compile and run correctly.

1.0.18

Python SDK

Apr 27, 2026, 4:42 PM UTC

Version 1.0.18 of the relationalai Python package is now available!

To upgrade, activate your virtual environment and run the following command:

pip install --upgrade relationalai

New Features and Enhancements

You can now pass an existing Snowpark session to create_config() with snowflake_session=.

For example:
```
from snowflake.snowpark import Session
from relationalai.config import create_config

snowflake_connection_parameters = {...}
snowpark_session = Session.builder.configs(snowflake_connection_parameters).create()

config = create_config(snowflake_session=snowpark_session)
assert config.get_session() is snowpark_session
```
:::note If you already load config from raiconfig.yaml or another supported config source, queries use the injected session instead of the Snowflake connection from that config. :::

This change makes it easier to use PyRel in environments where you already have a Snowpark session.

Bug Fixes

Fixed nested lookups that could drop rows when the inner lookup had no match. Before, PyRel could skip rows instead of keeping the row and showing NULL for the missing value. For example:

from relationalai.semantics import Integer, Model, String

m = Model("CustomerModel")

Customer = m.Concept("Customer", identify_by={"id": Integer})
Customer.name = m.Property(f"{Customer} has name {String:name}")
ReferralCode = m.Relationship(f"{Integer:customer_id} maps to {String:referral_code}")

m.define(
    Customer.new(id=1, name="Alice"),
    Customer.new(id=2, name="Bob"),
    ReferralCode(1, "ABC123")
)

customer_id = Integer.ref()
code = String.ref()

q = (
  m.where(
    Customer.id == customer_id,
    referral_code := m.where(ReferralCode(customer_id, code)).select(code),
  )
  .select(Customer.name, referral_code.alias("referral_code"))
)

print(q.to_df())

Output before the fix:

  name referral_code
0 Alice ABC123

Output after the fix:

  name referral_code
0 Alice ABC123
1 Bob   NULL

Fixed datetime.date.range() and datetime.datetime.range() when the end value comes from a DSL value like a Concept, Property or Relationship instead of a regular Python date or datetime. Before, the query could return one combined date range instead of a separate date range for each entity. For example:

from relationalai.semantics import Date, Integer, Model, define, select, std

m = Model("dates")

Foo = m.Concept("Foo", identify_by={"id": Integer})
Foo.end_date = m.Property(f"{Foo} has {Date:end_date}")

define(
    Foo.new(id=1, end_date=dt.date(2020, 1, 2)),
    Foo.new(id=2, end_date=dt.date(2020, 1, 4)),
)

select(
    std.datetime.date.range(dt.date(2020, 1, 1), Foo.end_date, freq="D")
).to_df()

Before, that query could return one combined date range instead of a separate date range for each Foo row:

# Before the fix:
  result
0 2020-01-01
1 2020-01-02
2 2020-01-03
3 2020-01-04

Now there are duplicate dates because both Foo rows contribute to the result:

# After the fix:
  result
0 2020-01-01
2 2020-01-02
3 2020-01-02
4 2020-01-03
5 2020-01-04

Fixed inferred field naming for numeric aliases such as Integer. Before, if you let PyRel infer a field name from one of those types, it would generate a name like number_38_0 instead of integer, so string lookups such as Scores["integer"] would fail with a KeyError exception. For example:
```
from relationalai.semantics import Integer, Model, String

m = Model("scores")
# The Integer field is unnamed here, so PyRel infers its field name.
Scores = m.Relationship(f"{String:name} has {Integer}")

# Prior to the fix, this lookup would raise a KeyError.
m.select(Scores["integer"]).to_df()
```
Now PyRel infers the correct field name, so Scores["integer"] resolves to the Integer field.

1.0.17

Python SDK

Apr 24, 2026, 8:34 PM UTC

Version 1.0.17 of the relationalai Python package is now available!

To upgrade, activate your virtual environment and run the following command:

pip install --upgrade relationalai

New Features and Enhancements

PyRel now supports math.round(). You can round to the nearest integer or to a specified number of decimal places inside semantics expressions.
rai debugger now makes compiler output easier to inspect. You can choose which compiler steps to show in one dialog, see clearer color coding, and view job IDs directly in the UI. Before, you had to toggle those steps one by one and query cards did not show the job ID.

You can no longer create a property or relationship on a concept named Relationship, Property, Concept, or Table. If you try to use one of these names, PyRel raises an error such as:

'Relationship' is a reserved name and cannot be used as a relationship name on concept 'Person'.

For example:

from relationalai.semantics import Model, String

m = Model()
Person = m.Concept("Person")

# Allowed
Person.relationship = m.Property(f"{Person} has {String:relationship}")

# Raises the reserved-name error
Person.Relationship = m.Property(f"{Person} has {String:relationship}")

Bug Fixes

Fixed a slowdown when you ran the first query on a second model in the same Python process. Before, PyRel could check data sources from all models instead of only the model you were querying. Now each model keeps its own data sources, so queries check only the relevant ones.

Fixed exports to Snowflake tables when you declare the destination schema with Model.Table(). Before, if the destination schema had more columns than the current export produced, PyRel could leave out the extra declared columns. Now it keeps those columns and fills missing values with NULL, so later writes to the same table can still succeed.

For example:

from relationalai.semantics import Integer, Model, String

m = Model("MyModel")
Order = m.Concept("Order", identify_by={"id": Integer})
Order.status = m.Property(f"{Order} has {String:status}")

# This query exports only order_id and status.
q = m.select(Order.id.alias("order_id"), Order.status)

# The destination schema also declares shipped_at.
out = m.Table(
    "ANALYTICS.PUBLIC.ORDER_EXPORT",
    schema={
        "order_id": Integer,
        "status": String,
        "shipped_at": String,
    },
)

q.into(out).exec()
# In 1.0.17, shipped_at stays in the exported Snowflake table and is filled with NULL.

Fixed fully qualified Snowflake names that use quoted lowercase or mixed-case object names. Before, PyRel could strip the quotes from names such as ANALYTICS.PUBLIC."orders" or ANALYTICS.PUBLIC."SalesSummary". That could make Snowflake read them as ANALYTICS.PUBLIC.ORDERS or ANALYTICS.PUBLIC.SALESSUMMARY, which might be different objects or might not even exist. Now PyRel preserves those quotes.

1.0.16

Python SDK

Apr 23, 2026, 1:32 PM UTC

Version 1.0.16 of the relationalai Python package is now available!

To upgrade, activate your virtual environment and run the following command:

pip install --upgrade relationalai

Performance and Reliability

Repeated Graph API calls are now faster. When you call the same graph method with the same arguments, PyRel reuses the earlier graph relationship instead of rebuilding it. This applies to methods such as reachable(), degree and neighbor methods, and several similarity, clustering, and centrality methods. See Run a graph algorithm and the Graph API reference for details.
Problem.solve() now omits variable and expression when sending jobs to the prescriptive reasoner. This helps avoid exposing business data through generated names. If you need those names in printed solver output, set print_format to a format such as lp, mps, or moi.

Bug Fixes

Fixed property lookups in concept hierarchies with multiple parents. Before, when implicit properties were enabled, PyRel could create the property on the wrong parent and return missing or incorrect data. Now it uses the declared property instead. See Declare relationships and properties.
PyRel now warns about possible typos in implicitly created properties. Before, a near-match property name could silently create a new property. Now PyRel points out the likely mistake sooner. For example, if you access Person.friend after declaring Person.friends, PyRel warns Did you mean: friends.
Fixed supertype membership for derived subtypes. Before, some subtype facts did not propagate all the way up the inheritance chain, so counts and membership queries on parent concepts could be incomplete.

1.0.15

Python SDK

Apr 21, 2026, 5:02 PM UTC

Version 1.0.15 of the relationalai Python package is now available!

To upgrade, activate your virtual environment and run the following command:

pip install --upgrade relationalai

New Features and Enhancements

Added support for a RAI_ACTIVE_PROFILE environment variable as a way to select the active profile. You can now set the active profile with RAI_ACTIVE_PROFILE=<profile_name> in addition to active_profile in raiconfig.yaml. See Use profiles to manage multiple configurations for details.

Performance and Reliability

Reduced Model.Table() overhead on large Snowflake schemas. Before, PyRel could scan the whole schema on each lookup. Now PyRel fetches metadata one table at a time, which reduces cold-start overhead when a model touches many tables in a large schema. For background on declaring Snowflake sources, see Declare data sources.
Improved behavior on read-only notebook and container file systems. Before, PyRel could fail while writing caches or trace files with misleading errors. Now it falls back to a writable temporary directory in those environments.

Bug Fixes

Fixed Snowflake authentication failures that could surface as a misleading No default Session error. PyRel now reports the underlying Snowflake auth failure when it cannot create a new session.
Fixed a startup crash in rai debugger. Before, some launches could fail with RuntimeError: You must call ui.run() to start the server. Now the debugger starts without that reload-related crash.
Fixed Model.data() so rows with mixed integer and floating-point columns preserve integer values. Before, some integer fields could be upcast and show up as values like 1.0 in query results.

1.0.14

Python SDK

Apr 16, 2026, 5:22 PM UTC

Version 1.0.14 of the relationalai Python package is now available!

To upgrade, activate your virtual environment and run the following command:

pip install --upgrade relationalai

New Features and Enhancements

Improved notebook support. Before, rerunning notebook cells could leave behind earlier model state, and diagnostics were less notebook-aware. Now PyRel cleans up prior model declarations more reliably across reruns and renders diagnostics inline in notebooks when possible.
Added reasoner-specific connection overrides in raiconfig.yaml. You can now set reasoners.<type>.connection so a specific reasoner uses a different connection than the global default_connection. For broader reasoner configuration, see Configure reasoners.
Added the rai debugger CLI command.
Added pagination to jobs:list and reasoners:list. Use --limit and --offset to control large result sets.

Bug Fixes

Fixed model.data() so DataFrame columns with PyRel Int128 extension dtypes are inferred as Integer instead of falling back to Any. Before, DataFrames with those columns could fail type inference after round-tripping results back into model.data(). Now those inputs compile without requiring a manual cast.
Fixed correctness issues in unary relationships. Before, queries against unary relationships could produce incorrect results, such as over-counting.
Fixed rank_asc() and rank_desc() when used with distinct(). Before, duplicate values were not always deduplicated before ranking, so repeated values could still be ranked separately instead of once as unique values. Now queries that use these ranking functions with distinct() reliably rank unique values after deduplication.
Fixed an issue where property names could get renamed in query results if the property name contains spaces or special characters like parentheses. This happened when a property was auto-created from a table column name with spaces or parentheses, like height(cm) or full name. Previously, these names could get transformed to height_cm or full_name in results columns, which could cause confusion when working with the results. Now, property names are preserved as-is in results.

1.0.13

Python SDK

Apr 8, 2026, 9:17 PM UTC

Version 1.0.13 of the relationalai Python package is now available!

To upgrade, activate your virtual environment and run the following command:

pip install --upgrade relationalai

New Features and Enhancements

Expanded graph APIs:
- Graph.adamic_adar() now supports weighted and directed graphs.
- Graph.is_acyclic() adds a built-in DAG check for directed graphs.
Added cumsum_asc() for cumulative sums over ascending keys.
Added global --json and --no-color options to the rai CLI to make output easier to handle in automation. --json returns structured output for reasoners:list, reasoners:get, jobs:list, and jobs:get. For example:
```
rai --json jobs:list
rai --no-color reasoners:list
```
Updated rai CLI wait flows so they make fewer unnecessary backend status and result checks before returning. These flows occur when you use --wait with commands like rai reasoners:create and rai reasoners:resume:
```
rai reasoners:create --type Logic --name my_reasoner --wait
rai reasoners:resume --type Logic --name my_reasoner --wait
```
The same improvements also apply when PyRel waits on jobs and reasoners.

Upgrade Notes

If you work with multiple prescriptive solutions, keep the ProblemVariable returned by problem.solve_for(...) and query it directly instead of calling Problem.variable_values(). For example:
```
var = problem.solve_for(...)
sol_idx = Integer.ref()
value = Float.ref()

model.select(sol_idx, value).where(var.values(sol_idx, value))
```
This returns (sol_idx, value) pairs, so you can inspect every solution or filter to one specific solution index. Problem.variable_values() still works, but it is deprecated and no longer preferred.
Problem.load_point() still works as a deprecated no-op for load_point(0), but load_point(k) for k > 0 is no longer supported.

1.0.12

Python SDK

Apr 1, 2026, 1:10 PM UTC

Version 1.0.12 of the relationalai Python package is now available!

To upgrade, activate your virtual environment and run the following command:

pip install --upgrade relationalai

New Features and Enhancements

Added a tables section in raiconfig.yaml so you can set defaults and named sources and export targets. See Use a Snowflake table with Model.Table(). and Export results to Snowflake tables for details and examples.

1.0.11

Python SDK

Mar 31, 2026, 5:06 PM UTC

Version 1.0.11 of the relationalai Python package is now available!

To upgrade, activate your virtual environment and run the following command:

pip install --upgrade relationalai

Bug Fixes

Fixed the warning shown when direct_access: true is used with an unsupported authenticator. Before, the warning could use older terminology that did not match the v1 config fields. Now the warning uses v1 naming, explains the fallback to direct_access: false, and lists the supported authenticator names. For direct access configuration details, see Enable Direct Access.

1.0.10

Python SDK

Mar 30, 2026, 4:59 PM UTC

Version 1.0.10 of the relationalai Python package is now available!

To upgrade, activate your virtual environment and run the following command:

pip install --upgrade relationalai

New Features and Enhancements

PyRel DSL objects now show readable structure in repr(), str(), and .pprint(). Before, inspecting concepts, expressions, fragments, aggregates, refs, fields, and models showed generic values like <ClassName object at 0x...>. Now those representations show the object structure directly, which makes debugging and interactive inspection easier.

Bug Fixes

Fixed primitive-value lists passed to .in_() inside select() queries so they no longer create temporary data tables or mutate model state. Before, filters like Person.name.in_(["Alice", "Bob"]) could register extra model state as a side effect. Now those select() filters compile as literal unions, leave the model unchanged, and still return the expected results.

1.0.9

Python SDK

Mar 28, 2026, 12:45 PM UTC

Version 1.0.9 of the relationalai Python package is now available!

To upgrade, activate your virtual environment and run the following command:

pip install --upgrade relationalai

New Features and Enhancements

Added RAI_CONFIG_FILE_PATH support so PyRel can load a specific config file instead of auto-discovering one. PyRel now checks that path first, raises a clearer error when the override is invalid, and shows the active config file when you run rai config:explain.
Restored Snowflake OAuth authorization-code sign-in for Direct Access. This restores the interactive browser callback and token-exchange sign-in flow that Direct Access workflows use. For setup, see Create an OAuth Security Integration for Direct Access.
Added weighted-graph support to Graph.preferential_attachment(). The graph docs now also clarify how self-loops contribute to degree() and weighted_degree().

Bug Fixes

Fixed Graph.diameter_range() to raise explicit unsupported-graph errors for directed and weighted graphs. Before, those graph types were documented as supported. Now PyRel fails early with an explicit error instead of implying that those modes are available.

1.0.8

Python SDK

Mar 25, 2026, 10:41 PM UTC

Version 1.0.8 of the relationalai Python package is now available!

To upgrade, activate your virtual environment and run the following command:

pip install --upgrade relationalai

Bug Fixes

Fixed .into(table).exec() when exporting to a destination table that does not yet exist. Before, exporting to a new table could fail during setup because PyRel treated the destination as an existing table. Now PyRel treats the destination as a new export target during setup.
Improved the error PyRel raises when you use a concept, relationship, or chain from one non-library model in another model. Before, these references could fail later with an unclear error. Now PyRel raises Cross-model concept usage at the call site. Concepts from library models are still allowed.
Improved the error PyRel raises when you access a relationship field with dot syntax instead of bracket indexing. Before, an expression such as relationship.foo could produce an unhelpful error when foo was a field name rather than a relationship. Now PyRel raises Invalid field access and tells you to use indexing such as relationship["foo"] instead.

1.0.7

Python SDK

Mar 21, 2026, 2:43 PM UTC

Version 1.0.7 of the relationalai Python package is now available!

To upgrade, activate your virtual environment and run the following command:

pip install --upgrade relationalai

New Features and Enhancements

Added Relationship.ref() for relationships declared directly, not attached to a concept attribute. Before, if you used the same standalone relationship twice in one query, PyRel treated both uses as the same query occurrence, so they could not match independently. Now, Relationship.ref() gives you a second occurrence of the same relationship definition, similar to Chain.ref().
Debugger UI packages are now optional. Before, a standard PyRel install included nicegui even if you did not use the debugger. Now a standard install stays smaller, and if you do use the debugger without its extra packages, PyRel tells you to install relationalai[debugger].

Bug Fixes

Fixed select() with not_() so select(not_(expr)) evaluates to a boolean result. Before, selecting a negated expression did not behave the same way as selecting other boolean expressions such as x == 2. Now select(not_(expr)) works like a normal boolean selection.

Upgrade Notes

auto_suspend_mins and await_storage_vacuum are no longer managed in raiconfig.yaml. Before, these reasoner lifecycle settings could appear in raiconfig.yaml, and rai init --migrate could carry them over when converting raiconfig.toml to raiconfig.yaml. Now PyRel warns if they appear in config and leaves them out of the generated raiconfig.yaml during migration. Manage auto_suspend_mins with rai reasoners:alter. Set await_storage_vacuum when you create a reasoner with rai reasoners:create. For broader reasoner configuration, see Configure reasoners.

1.0.6

Python SDK

Mar 19, 2026, 4:10 PM UTC

Version 1.0.6 of the relationalai Python package is now available!

To upgrade, activate your virtual environment and run the following command:

pip install --upgrade relationalai

Bug Fixes

Fixed require() checks that reference columns from data(). Before, a .require() condition that used model.data() columns could emit a warning even when the input rows satisfied the requirement. Now PyRel warns only when the condition is actually violated.
Fixed std.math.isclose() so that it correctly evaluates an absolute-tolerance comparison. Before, std.math.isclose() could silently produce the wrong result in filters and selections.
Fixed lookups on subtypes such as Manager, a subtype of Employee. Before, a lookup such as Manager.approves_budget could use the wrong relationship or raise a type mismatch. Now PyRel resolves the subtype before resolving the relationship.
Improved reserved-name diagnostics for concepts and tables. Before, if you used a reserved name such as alias, new, or require, the error could be unclear or point to the wrong place. Now PyRel points the error at the call site. For reserved table column names, the message also tells you to use table indexing, such as table["alias"].

Deprecations

The use_direct_access config option is now deprecated. Use the top-level direct_access setting instead.

Preferred configuration:

connections:
  snowflake:
    account: my-account
    user: my-user
    password: ${SNOWFLAKE_PASSWORD}
    database: MY_DB
    schema: PUBLIC
    warehouse: COMPUTE_WH

direct_access: true

Deprecated configuration:

connections:
  snowflake:
    account: my-account
    user: my-user
    password: ${SNOWFLAKE_PASSWORD}
    database: MY_DB
    schema: PUBLIC
    warehouse: COMPUTE_WH

use_direct_access: true

Existing use_direct_access entries still work. PyRel warns that they are deprecated and maps them to the top-level direct_access setting. For details, see Configure reasoners.

1.0.5

Python SDK

Mar 17, 2026, 6:06 PM UTC

Version 1.0.5 of the relationalai Python package is now available!

To upgrade, activate your virtual environment and run the following command:

pip install --upgrade relationalai

New Features and Enhancements

Added explicit schema= support to data() and Model.data(). Before, PyRel always inferred column types from the in-memory rows or DataFrame you provided, which made empty inputs and ambiguous columns harder to control. Now you can declare some or all column types explicitly, and the returned Data object preserves those types even when the input is empty.

For example:

from relationalai.semantics import Date, Integer, Model, String

m = Model("OpsModel")

# A daily exceptions feed can legitimately be empty, but downstream logic
# still needs stable column types.
shipment_exceptions = m.data(
    [],
    schema={
        "order_id": Integer,
        "warehouse": String,
        "reason": String,
        "requested_ship_date": Date,
    },
)

# You can still use the schema in model logic, even with no rows.
ShipmentException = m.Concept("ShipmentException")
m.define(ShipmentException.new(shipment_exceptions.to_schema()))

PyRel now supports batching multiple pending table exports into a single model execution. Before, export-heavy workflows had to execute table exports separately. Now you can queue multiple .into() exports and submit them together with m.exec():
```
# Create two export fragments.
m.select(Customer.id, Customer.name).into(customer_table)
m.select(Product.id, Product.name).into(product_table)

# Execute both exports together in a single model execution.
m.exec()
```

Bug Fixes

Improved dtype inference for pandas float columns. Before, dataframe float columns could be inferred as a more generic numeric type. Now PyRel maps pandas float columns to Float, which keeps inferred schemas closer to the original dataframe types.
Fixed table-based schema and column mapping when model.implicit_properties is disabled. model.implicit_properties controls whether PyRel creates undeclared properties automatically. Before, when you turned this option off, Table objects could still implicitly create properties. Now Table objects respect the model.implicit_properties setting, so you can disable implicit properties for tables as well as concepts.

Fixed use of std.datetime.datetime.now() in queries and filters. Before, using the current date and time in a query or filter could fail with an argument error. Now you can use std.datetime.datetime.now() directly in PyRel logic, including in time-based derived definitions.

For example:

from relationalai.semantics import DateTime, Integer, Model, std
from relationalai.semantics.std.datetime import datetime

m = Model("OpsModel")

# Declare the base shipment concept.
Shipment = m.Concept("Shipment", identify_by={"id": Integer})
# Add the promised ship timestamp.
Shipment.promised_ship_at = m.Property(f"{Shipment} promised ship at {DateTime}")
OverdueShipments = m.Concept("OverdueShipments", extends=[Shipment])

# Define some shipment entities.
m.define(
    Shipment.new(id=1, promised_ship_at=datetime(2026, 3, 17, 9, 0)),
    Shipment.new(id=2, promised_ship_at=datetime(2026, 3, 28, 9, 0)),
)

# Define overdue shipments using the current time.
m.define(OverdueShipments(Shipment)).where(
    Shipment.promised_ship_at < std.datetime.datetime.now(),
)

Fixed ProgrammaticAccessTokenAuth so PAT-based Snowflake authentication includes the required user field and expands ~ in token_file_path. Before, Snowflake could reject the PAT as invalid, and token files referenced with ~ could fail with FileNotFoundError. Now PAT authentication works in both cases.
Fixed Problem.solve() so it uses the app name from the model config. Before, Problem.solve() could ignore a custom rai_app_name in the model config. Now it reuses the configured app name.
Fixed create_config() for PyRel running inside an existing Snowflake session, including notebooks, stored procedures, and SPCS containers. Before, the returned config could fail when PyRel later needed a Snowflake SQL connection. Now configs created from active sessions work correctly in those environments.
Fixed notebook diagnostics so notebook users see all collected PyRel diagnostics in a single exception. Before, earlier diagnostics could be easy to miss, so you often saw only the final failure. Now notebook exceptions include the diagnostic context that led to the error.

1.0.4

Python SDK

Mar 12, 2026, 5:06 PM UTC

Version 1.0.4 of the relationalai Python package is now available!

To upgrade, activate your virtual environment and run the following command:

pip install --upgrade relationalai

New Features and Enhancements

Added a new rai config:explain command to inspect the active configuration and where each value came from. Now you can inspect the active config directly from the CLI and optionally show full provenance details with --verbose:
```
rai config:explain
rai config:explain --verbose
```
Improved dtype inference for pandas columns with object dtype when PyRel derives concept types from data. PyRel now does a better job recognizing numbers in pandas object columns. For example, if a column contains decimal values, PyRel now treats it as numeric instead of treating it as text.

Bug Fixes

Fixed an issue with rai connect where invalid Snowflake warehouse names could pass basic connectivity checks. The command now validates the configured warehouse.
Fixed a bug that caused select() to raise a ValueError when selecting a Match object.
Fixed a bug where PyRel would warn about graph validation whenever you selected a Graph.Edge entity. You can now select or inspect Graph.Edge without triggering validation warnings. PyRel waits to validate until you run a graph operation that actually needs it.
Fixed a bug that could cause the client to get disconnected during long-running graph algorithms or other work if a jobs polling attempt was delayed or missed. The maximum polling delay is now short enough to prevent accidental disconnects from transient polling issues.
Fixed a bug that could affect results in some queries involving values that could match multiple types.

1.0.3

Python SDK

Mar 11, 2026, 3:52 PM UTC

Version 1.0.3 of the relationalai Python package is now available!

To upgrade, activate your virtual environment and run the following command:

pip install --upgrade relationalai

New Features and Enhancements

Added a new reasoner library for prescriptive reasoning. See the prescriptive reasoning guides. For API reference docs, see std.reasoners.prescriptive.
Improved typing support for Graph. Graph.__init__() now has overloads so IDEs and static type checkers can catch incorrect combinations of graph constructor parameters.
Made Graph attributes directed and weighted read-only. Mutations to these attributes had no effect on graph behavior. They are now immutable to avoid confusion.
Improved configuration and authentication diagnostics. create_config() now includes the active profile name in YAML validation errors when available.
Improved CLI diagnostics for Snowflake authentication failures. The CLI now surfaces clearer guidance for login and SSO failures.
Added support for the await_storage_vacuum reasoner setting in configuration. You can now set this in raiconfig.yaml under reasoners.*. Use it when you want a reasoner to wait for storage vacuum work to finish before suspending.

:::caution This guidance applies only through PyRel 1.0.6. As of PyRel 1.0.7, you no longer manage reasoner lifecycle settings in raiconfig.yaml. Instead, set await_storage_vacuum when you create a reasoner with rai reasoners:create. For current guidance, see Configure reasoners or What's New in Version 1.0.7. :::

Bug Fixes

Made field access by name in relationships case-insensitive. For example, Thermometer.readings["time"] and Thermometer.readings["Time"] now refer to the same field.
rai init --migrate now produces cleaner raiconfig.yaml output when migrating from raiconfig.toml. Generated YAML no longer includes spurious default fields, places reuse_model under model, and formats profiles and connections more readably.
Fixed ProgrammaticAccessTokenAuth so token_file_path works correctly in v1 configuration. You can now provide either a literal token string or a file path to a Programmatic Access Token in raiconfig.yaml.
Improved type checking for relationships and properties. If a field's target type can't be inferred, PyRel now raises a type mismatch error.

Upgrade Notes

DataConfig.data_freshness_mins is now capped at 30240 minutes (3 weeks). If you set a larger value, PyRel clamps it to 3 weeks and emits a warning during config creation.

1.0.2

Python SDK

Mar 4, 2026, 3:37 PM UTC

Version 1.0.2 of the relationalai Python package is now available!

To upgrade, activate your virtual environment and run the following command:

pip install --upgrade relationalai

Bug Fixes

raiconfig.toml is deprecated, and PyRel now reliably emits a visible warning when it loads a raiconfig.toml config. The warning points you to rai init to migrate or create a raiconfig.yaml.
Fixed an issue in Snowflake stored procedures where importing your package could fail or behave unexpectedly if it triggered config auto-discovery at import time. This could attempt to read config files in a restricted runtime, and raise errors such as ConfigFileNotFoundError.

If your code relied on implicit config loading, update it to construct a Config explicitly and pass it into the SDK objects you create. For example: cfg = create_config(...). In stored procedures, prefer creating the config inside the stored procedure handler rather than at module import time.

See create_config() for the supported config sources and defaults.

1.0.1

Python SDK

Mar 4, 2026, 2:28 AM UTC

Version 1.0.1 of the relationalai Python package is now available!

To upgrade, activate your virtual environment and run the following command:

pip install --upgrade relationalai

New Features and Enhancements

Improved concurrent call handling for ReasonersClient.ensure() and ReasonersClientSync.ensure(). When multiple processes try to create or resume the same reasoner at the same time, ensure() will wait for the in-progress operation to complete instead of failing with a conflict error.

Improved the error raised when a logic reasoner job is aborted because the client disconnected. If that happens, JobsClient.wait() / JobsClientSync.wait() raises JobClientDisconnectedError:

from relationalai.services.jobs.errors import JobClientDisconnectedError

try:
    job = await client.jobs.wait("LOGIC", job_id)
except JobClientDisconnectedError:
    # The client disconnected before the job completed.
    # Retry after restoring connectivity.
    ...

Bug Fixes

Fixed an issue where running reasoner CLI commands, such as rai reasoners:create, could fail with an ImportError.

1.0.0

Python SDK

Mar 2, 2026, 5:25 PM UTC

Version 1.0.0 of the relationalai Python package is now available!

To upgrade, activate your virtual environment and run the following command:

pip install --upgrade relationalai

Breaking Changes

Version 1.0.0 is a major update of the Python SDK that introduces:
- PyRel, a new modeling and query DSL organized around Concept, Property, and Relationship classes, and new chainable query methods like define, where, and select. See Build a semantic model for an introduction to the new modeling and query patterns.
- Improved configuration management with a new raiconfig.yaml format. The v1 SDK treats raiconfig.toml as deprecated, so if you have an existing raiconfig.toml, you should migrate to YAML using rai init --migrate. See Configuring PyRel for details on new configuration patterns.
- A new CLI with updated commands for managing reasoners, which were previously called engines, and job, which were previously called transactions. Check out the CLI reference for details on the new CLI commands and syntax.
:::note For docs on the v0.x versions of the Python SDK and CLI, check out https://v0.docs.relational.ai. :::

Upgrade Notes

Treat this upgrade as a migration. You should expect to make non-trivial changes to your codebase when upgrading from v0.x to v1.0.0. If you need help, contact RelationalAI support for assistance.
Protect existing workflows. Make sure existing production and staging environments install relationalai in a way that doesn't break existing code until you're ready to migrate. For example, if you use pip, you can specify the version in your requirements.txt or setup.py to avoid accidentally upgrading to v1.0.0 before you're ready.

You can pin your project to the latest v0.x version with:
```
relationalai==0.14.3
```
Or, you can use a version specifier to allow the latest v0.x but prevent upgrading to v1.0.0 until you're ready:
```
relationalai>=0.14.0,<1.0.0
```