Skip to content
RelationalAI Docs

Python package and CLI 2.0.0

Model deployment requires a breaking migration.

How to install this version

Review the changes below before installing. To install this version, activate a compatible Python virtual environment and run:

Terminal window
python -m pip install "relationalai==2.0.0"

For the latest installation instructions, see Start building with PyRel.

Breaking Changes

Section titled “Breaking Changes”
  • Before redeploying a PyRel 1.x model with PyRel 2.0, update its deployment configuration and update SQL queries that read the model to use published views instead of internal objects. PyRel 2.0 rejects the old settings. Some existing op logs that record deployment history are incompatible with PyRel 2.0. If deployment reports an incompatible op log, follow the teardown and redeployment steps. Model deployment is in Public Preview.

New Features and Enhancements

Section titled “New Features and Enhancements”

  • Model deployment history, called an op log, now uses standard Snowflake tables by default, including on accounts without Hybrid Table support. To use Hybrid Tables for faster appends on supported accounts, set oplog.table_type to hybrid before deployment. Changing the table type for an existing deployment requires deleting its op log table and redeploying.

  • You can now call Model.plan_deployment() to review the changes PyRel plans to make in Snowflake instead of using the CLI’s --plan option. The method returns a report without installing or deploying the model.

  • After you review the changes PyRel plans to make, you can require the deployment to match them. Pass the report from Model.plan_deployment() to Model.deploy(reviewed_plan=...), or save it and pass its file with --reviewed-plan to rai models:deploy. If the planned changes differ, PyRel stops before applying them, though setup may already have updated deployment metadata.

  • Model deployment now treats the model defined in your Python code as the complete model by default. Missing definitions can delete existing Snowflake objects, and outdated code can undo newer changes. Use this default only for a main model managed by one pipeline and set oplog.stateless_deploy to false for branches or collaboration.

  • Model deployment now warns and continues after some errors caused by damaged or incompatible deployment history. A later deployment rebuilds that history from the current Python model, and automatic recovery is enabled by default. To prevent new recovery requests, set oplog.auto_recover to false. Recovery does not repair local edits, and installation errors or other hard errors still stop deployment.

  • Deployment plan reports now label SQL to show whether PyRel plans to add, replace, modify, or drop a Snowflake object, when that information is available.

  • Graph Reasoning results can now appear as columns in Snowflake when attached to a top-level concept or used in a definition. Graph Reasoning is in Public Preview.

Bug Fixes

Section titled “Bug Fixes”

  • Fixed an issue that caused an unclear error when a query used Model.where() without specifying what Model.select() should return. The error now suggests returning a Boolean or selecting values for matching rows.

  • Fixed an issue that caused failed deployments to leave Snowflake queries running, risking overwrites of newer results. When PyRel can access Snowflake’s record of queries run in the current session, it cancels any that are still running before the next deployment starts.

  • Fixed an issue that caused the last successfully deployed model to become unavailable for queries when a later deployment failed during preparation or finalization.

  • Fixed an issue that caused SQL queries checking dynamic table refresh status to fail or time out. This happened during deployment for Snowflake tables with quoted names containing apostrophes or backslashes.

  • Fixed an issue that caused CLI help summaries to stop at 45 characters even on wider terminals. rai --help and rai models --help now use the available width, subject to the formatter’s limit.

  • Fixed an issue that caused rai models:list to fail when your Snowflake permissions let you see a model record in another database but not read it. The command now warns and skips that record.

  • Fixed an issue that caused Snowflake objects to return rounded values after a property’s type changed. Deployment now applies the type change before rebuilding objects that read the property through a view, even when the view’s SQL definition has not changed.

  • Fixed an issue that caused queries on models without deployment configuration to raise AttributeError when PyRel looked up the database name. They now use the existing model-name fallback for that lookup.

  • Fixed an issue that caused a deployment plan to report changes and suggest redeployment when the model’s outputs and destinations had not changed.

  • Fixed an issue that caused the rai debugger Refresh Log tab to show dark panels on a light page. It now follows the selected theme.

  • Fixed an issue that caused Snowflake queries joining a table created by model deployment to itself to return rows that should have been filtered out. Deployment now marks primary keys with NORELY so Snowflake keeps the filters instead of removing them based on the key. The keys remain declared, and existing tables receive this setting the next time you deploy the model.

  • Fixed an issue that caused model deployment to lowercase field names generated from entity names even when configured to keep the original capitalization of column names. Deployment now preserves capitalization, such as publishing Strategy as "Strategy", and normalizes reserved names such as group to GROUP. Update SQL and policy references that use the old quoted lowercase names after redeployment.

  • Fixed an issue that caused PyRel queries using math.round() to fail type checking when a numeric expression had an explicit integer type.