What's New in Version 1.24.0

July 24, 20264:03 PM UTC

Version 1.24.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 now warns you when your raiconfig.yaml file contains a key it doesn’t recognize, so a typo no longer passes unnoticed. For example, misspelling account as accont raises a warning that names the unknown key and suggests the closest valid one. Valid configuration produces no warnings, and existing files keep working because this is a warning, not an error.
The inspect module for examining a model’s concepts, relationships, tables, enums, and definitions without an engine connection is now included in the API reference. The module shipped in an earlier release. This change makes its documentation discoverable on the docs site and in your IDE.
The spcs_privatelink_zone connection option is now documented and included as a commented setting in the rai init config template. Set it when you enable Direct Access on a Snowflake PrivateLink account. Omit the leading wildcard from that value.
The rai debugger now groups a deployed model’s compiler passes by block, instead of showing one flat list, so you can tell blocks apart and compare the same pass across them. A new Group by pass toggle flips the view to show every block nested under each pass.

Bug Fixes

Queries now run in Snowflake Workspace notebooks instead of crashing. Before this release, any query in that environment failed with OSError: [Errno 95] Operation not supported because PyRel tried to write its trace and log files to the notebook’s locked-down filesystem. Queries now run and return results there with no configuration needed.
Models that use model.Enum(...) to map a messy raw column onto a fixed set of allowed values now deploy to Snowflake and refresh correctly. This is a common data-cleaning pattern, but on versions 1.22.0 and 1.23.0 it failed to deploy. The only workaround was to drop the enum and store the value in a plain string property instead, which gave up both the fixed set of allowed values and the type safety it provides. That workaround is no longer needed.

For example, the model below defines a Region enum, then tags every site whose raw region text matches a known spelling with the canonical Region.Americas value:
```
Region = model.Enum("Region", ["Americas", "EMEA", "APAC"])
Site.region = model.Property(f"{Site} has region {Region}")

# Sites whose raw region text is one of these spellings become Region.Americas.
model.where(Site.region_raw.in_(["amer", "americas", "north america"])).define(
    Site.region(Region.Americas)
)
```
You would add a similar definition for EMEA and APAC. On 1.22.0 and 1.23.0 this model failed to deploy to Snowflake, but it now deploys and refreshes cleanly.
A composite-key entity is one identified by more than one key. When your model is deployed to Snowflake, PyRel now builds faster, simpler SQL for reading several properties of such an entity. This is SQL that PyRel generates itself, both when it deploys or refreshes your model. It used to re-read the entity’s table once for every property, which was slower. Single-key entities are unaffected.
When a definition sets a property whose value is a composite-key entity, that property’s values are now saved correctly when the model is deployed to Snowflake and refreshed. For example, a property might link each product to its supplier, where a supplier is identified by a company name and a country. Before this release, the refresh reported success but silently dropped rows, so a definition that later read the property saw incomplete data.
Setting a property on an entity that is identified partly by another composite-key entity now works as expected when the model is deployed to Snowflake, instead of failing with a NotImplementedError. For example, a shipment might be identified by a date and a route, where the route is itself identified by two cities.
Reading a property that points from one entity to another no longer adds an all-NULL row for entities that have no value when the model is deployed to Snowflake. For example, if a property links each employee to their manager, an employee with no manager is now left out instead of appearing as a blank row.
Defining a table source from a schema that lists two keys that name the same physical Snowflake column now behaves predictably. Snowflake treats names like a and A as one column, so PyRel collapses the two keys into one column when they share a type, or raises a clear error when their types differ, instead of silently adding a phantom column to the Table object.
Refreshing a deployed model that reads from a Snowflake source table whose name requires quoting now succeeds instead of failing during refresh. This includes names with a space, like DB.SCHEMA."SOURCE B".
rai models pull on a live branch now rejects a merge that would create a cycle in column types with a clear ConflictError that names the cycle, instead of quietly producing a broken model that fails later. Such a cycle happens when, for example, table T1 is typed by T2 while T2 is typed by T1.
Redeploying a model with rai models deploy is more reliable: a model containing two identical definitions no longer fails to deploy, and annotations on a newly added concept or relation now apply on the first deploy. Reordering definitions, and concepts that extend a built-in type, also no longer produce spurious changes on redeploy.
Recovering an interrupted model merge is now reliable: re-running a merge after a conflict no longer duplicates concepts already promoted to the parent, the resume information survives an intervening pull or deploy, and model status now shows when a merge is mid-recovery.
The error message shown when your shared_model.py file has been edited since the last pull or deploy now accurately describes what --force does: it pushes your local edits to the shared model and regenerates the file while keeping a backup, rather than discarding your edits.
Branch safeguard messages during a pull now distinguish a missing sync baseline from a branch that is genuinely behind, report the actual synchronized position, and make clear that a pull with no model changes still updates your local state.
rai doctor report now includes your model’s local-state directory in the diagnostic bundle when your connection sets rai_app_name but no explicit database, instead of leaving it out.
Direct Access connections that use JWT-based key-pair authentication now automatically retry when the app’s service endpoint becomes stale during token exchange, so the connection can recover on its own.
Regenerating a shared model through a pull, merge, or deploy now preserves DECIMAL and other number column types, instead of demoting them to a plain concept.