Python SDK
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
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.Python SDK
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
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.Python SDK
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
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.
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.
Python SDK
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
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.
Python SDK
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
Python SDK
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
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.
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.
Python SDK
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
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.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.
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.
Python SDK
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
LogicReasonerConfig.readonly_queries config option that can help improve performance when you run multiple queries against the same model.
It is disabled by default.Python SDK
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
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.
gnn.dataset.tables indices are now deterministic across runs.Python SDK
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
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.
Python SDK
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
authenticator="oauth_client_credentials" for app-to-app OAuth flows. See OAuthClientCredentialsAuth for configuration details.rai reasoners sizes to inspect available reasoner sizes.Python SDK
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
rai clean:rai clean cache removes the local schema cache file.rai clean debugger removes debugger run directories and trace logs.Python SDK
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
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.
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.
Python SDK
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
rai config use now supports interactive profile selection.
In non-interactive runs, the command still requires an explicit profile.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.Python SDK
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
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.
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.
Python SDK
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
Concept.new() could treat entities with different identity field names as the same entity if the values matched.Python SDK
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
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.
Python SDK
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
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:
CortexAgentManager.preflight() to surface missing permission grants and source objects in one pass.CortexAgentManager.print_setup_sql() to generate the matching GRANT block.python -m relationalai.agent.cortex.diagnostics to perform the same checks from the command line.Python SDK
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
PyRel now makes configuration profiles easier to use from the CLI:
--profile option or the RAI_PROFILE environment variable.rai config profiles to list available profilesrai config current to check which profile is activerai config use to change the active_profile in your config fileThe CLI also gives clearer feedback when:
active_profile in your configPython SDK
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
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.
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.
Python SDK
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
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.
Python SDK
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
Graph.jaccard_similarity() now supports directed graphs, including weighted directed graphs.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.Python SDK
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
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.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.
Python SDK
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
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.
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.
Python SDK
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
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}")
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.
Python SDK
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
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.
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.
Python SDK
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
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.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.
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.
Python SDK
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
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.
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.
Python SDK
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
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.
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.
Python SDK
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
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.Python SDK
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
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.Python SDK
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
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..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.Python SDK
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
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().
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.Python SDK
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
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.
Python SDK
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
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].
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.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.Python SDK
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
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"].
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.
Python SDK
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
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()
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.
Python SDK
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
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.
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.
Python SDK
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
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.
:::
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.
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.Python SDK
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
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.
Python SDK
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
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.
...
rai reasoners:create, could fail with an ImportError.Python SDK
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
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.
:::
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