Manage the RAI Native App's Compute Resources

The RelationalAI (RAI) Native App requires compute resources to evaluate queries from RAI Python models. This section provides an overview of these compute resources and how they are managed. For information on costs associated with these resources, see Cost Management.

App Warehouse

The RAI Native App utilizes an X-SMALL Snowflake warehouse for Snowflake interoperability. This warehouse is named RELATIONAL_AI_ERP_WAREHOUSE and is fully managed by the native app. It is automatically provisioned when you activate the app and suspended when you deactivate the app.

See the Snowflake documentation for information on warehouses.

Compute Pools

Snowflake compute pools are collections of compute resources that are managed as a shared pool. The RAI Native App uses compute pools to host engines that process queries from RAI Python models.

When you install the RAI Native App, the following compute pools are automatically provisioned:

Name	Snowflake Instance Family	Supported Cloud Platforms	Description
RELATIONAL_AI_ERP_COMPUTE_POOL	CPU_X64_XS	AWS, Azure	Used for internal app operations.
RELATIONAL_AI_COMPILE_CACHE_SPCS	HIGHMEM_X64_M	AWS, Azure	Used for internal app operations.
RELATIONAL_AI_HIGHMEM_X64_S	HIGHMEM_X64_S	AWS, Azure	Runs engines that execute queries from RAI Python models.
RELATIONAL_AI_HIGHMEM_X64_M	HIGHMEM_X64_M	AWS, Azure	Runs engines that execute queries from RAI Python models.
RELATIONAL_AI_HIGHMEM_X64_L	HIGHMEM_X64_L	AWS only	Runs engines that execute queries from RAI Python models.
RELATIONAL_AI_HIGHMEM_X64_SL	HIGHMEM_X64_SL	Azure only	Runs engines that execute queries from RAI Python models.
RELATIONAL_AI_CPU_X64_S	CPU_X64_S	AWS, Azure	Reserved for future use.
RELATIONAL_AI_CPU_X64_M	CPU_X64_M	AWS, Azure	Reserved for future use.

These compute pools are fully managed by the RAI Native App. They are automatically suspended when you deactivate the app and resumed when you activate the app.

Tip

You are only charged for resources consumed by the engines running on a compute pool, so unused compute pools do not incur costs. See Cost Management for more information.

Engines

Engines are virtual machines that process queries and other transactions from RAI Python models. They are hosted in the compute pools managed by the RAI Native App. Like Snowflake virtual warehouses, engines can be independently created for workload isolation or scaling purposes.

Logic Engines

Every RAI Python model requires a logic engine to process rules and queries. When a user queries a model using the Python API, the RAI Native App resumes the user’s configured logic engine if it is suspended, or automatically creates a new engine for the user if one does not exist.

Note

Auto-created rules engines are automatically suspended after 60 minutes of inactivity. See Change Engine Auto-Suspend Time for details on altering the auto-suspend time for an engine.

By default, each user has a dedicated engine. This ensures transactions are isolated per user by default, though a user may run multiple concurrent transactions on their engine.

If you need fine-grained control over resource allocation, you can create and manage engines manually using SQL, Python, or the RAI CLI. RAI models can then be configured to use specific engines using configuration keys:

Configuration Key	Description
engine	Name of the engine to use. Defaults to the user’s Snowflake username with dots replaced by underscores—for example, w.riker@relational.ai becomes w_riker.
engine_size	Size of the engine. Defaults to HIGHMEM_X64_S. See Engine Sizes for details.

Resource

See Engine Management to the learn how to create and manage logic engines.

Solver Engines Preview

Solver engines process transactions sent using the relationalai Python package’s SolverModel API. When a user calls SolverModel.solve(), their solver engine resumes if suspended, or a new one is created using the configured solver engine name.

Resource

See the Solver Engines section of the Working with Solver Models guide for more information on how solver engines work. Refer to the solvers.Provider reference for details on managing solver engines.

CDC Engine

If you have enabled the CDC Service, an engine named CDC_MANAGED_ENGINE is automatically provisioned whenever changes to a data stream are detected. This engine processes changes to Snowflake tables and views shared with the RAI Native App for use in RAI models. It is suspended automatically after 30 minutes of inactivity or when you disable the CDC Service.

By default, the CDC_MANAGED_ENGINE is provisioned in the app’s HIGHMEM_X64_S compute pool. However, you may alter the CDC engine size if needed.

Engine Sizes

An engine’s size refers to the instance family of the compute pool it is hosted on. Different instance families provide varying levels of CPU, memory, and storage resources. The RAI Native App currently supports the following engine sizes:

Engine Size	Supported Engine Types	Supported Cloud Platforms	Description
HIGHMEM_X64_S	CDC, Logic, Solver	AWS, Azure	Optimized for small workloads
HIGHMEM_X64_M	CDC, Logic, Solver	AWS, Azure	Optimized for medium workloads
HIGHMEM_X64_L	CDC, Logic	AWS only	Optimized for large workloads
HIGHMEM_X64_SL	CDC, Logic	Azure only	Optimized for large workloads

Resource

Refer to the Snowflake documentation for CPU, memory, and storage details for each instance family.

Engine Suspension

By default, new engines automatically suspend after one hour of inactivity. You may also manually suspend an engine to save costs when it is not in use. While suspended, an engine does not consume compute resources. Transactions sent to a suspended engine will fail until the engine is resumed.

To change the inactivity window for an engine:

1. Set the auto_suspend_mins option when creating a new engine.

2. Use the api.alter_engine_auto_suspend_mins() procedure to update the auto-suspend time for an existing engine. See Change Engine Auto-Suspend Time for details.

3. Set the auto_suspend_mins configuration key in a user’s raiconfig.toml file or a Config object. If unset, the default value of 60 minutes applies. Changes to this key take effect the next time the user creates a model.

Suspended engines automatically resume via the RAI Python API when users execute a query. You can also manually resume a suspended engine.

Note

Auto-suspension saves costs by avoiding unnecessary resource use. However, it may cause latency when queries require resuming the engine. To avoid latency, set auto_suspend_mins to 0 to disable auto-suspension.

Concurrent Transactions

Each engine supports up to 8 concurrent transactions and has a queue capacity of 128 transactions with first-in/first-out priority. However, engines may process resource-intensive transactions, like large-scale graph algorithms, sequentially.

By default, each user has a dedicated engine created for them automatically the first time they create a model. This ensures transactions are isolated per user by default, though a user can run multiple concurrent transactions on their engine.

Concurrent transactions on the same engine may impact each other’s performance. To avoid coordination issues, especially when resource-intensive transactions are involved, consider creating a dedicated engine for each workload.

You can determine if an engine is overloaded by monitoring it for a large number of transactions in the QUEUED or CREATED state. See Monitor Engine Transactions for details.

Engine Management

You can manage engines using SQL, Python, or the RAI CLI.

Create an Engine

Requires the eng_admin application role.

SQL

To create an engine, pass strings with the desired engine name and size to the api.create_engine() procedure:

CALL relationalai.api.create_engine(
    'my_engine',
    'HIGHMEM_X64_S',  -- Change to HIGHMEM_X64_M for a larger engine.
    {'auto_suspend_mins': 60}, -- Auto-suspend after 60 minutes of inactivity.
    NULL
);
/*+----------+
  | Success. |
  +----------+ */

Python

To create an engine using Python, create a Provider instance and use its .sql() method to execute the api.create_engine() procedure.

import relationalai as rai

# Get a provider instance.
app = rai.Provider()

# Create a HIGHMEM_X64_S engine configured to auto-suspend after 60 minutes of inactivity.
app.sql("""
CALL relationalai.api.create_engine(
    'my_engine',
    'HIGHMEM_X64_S'  -- Change to HIGHMEM_X64_M for a larger engine.
    {'auto_suspend_mins': 60}, -- Auto-suspend after 60 minutes of inactivity.
    NULL
);
""")

CLI

To create an engine using the RAI CLI, run the engines:create command with the desired engine name and size provided as arguments to the --name and --size options:

# Create a HIGHMEM_X64_S engine.
rai engines:create --name my_engine --size HIGHMEM_X64_S --auto_suspend_mins 60

# Create a HIGHMEM_X64_M engine.
rai engines:create --name my_engine --size HIGHMEM_X64_M --auto_suspend_mins 60

Engine names must be between 3 and 50 characters long and can contain only a-z, A-Z, 0-9, and _ characters. Note that it may take several minutes for the engine to be provisioned and ready for use.

Note

An engine’s size is the same as its host compute pool’s instance family. See Compute Pools for details on the available instance families.

Delete an Engine

Requires the eng_admin application role.

SQL

To delete an engine, pass the engine name to the api.delete_engine() procedure:

-- Delete the engine named 'my_engine'.
CALL relationalai.api.delete_engine('my_engine');
/*+-----------+----------------------+
  | NAME      | MESSAGE              |
  |-----------+----------------------|
  | my_engine | deleted successfully |
  +-----------+----------------------+ */

Python

To delete an engine using Python, create a Provider instance and use its .sql() method to execute the api.delete_engine() procedure:

import relationalai as rai

# Get a provider instance.
app = rai.Provider()

# Delete the engine named 'my_engine'.
app.sql("CALL relationalai.api.delete_engine('my_engine')")

CLI

To delete an engine using the RAI CLI, run the engines:delete command with the engine name provided as an argument to the --name option:

rai engines:delete --name my_engine

When an engine is deleted, all current and queued transactions are cancelled. Any new transactions submitted to the engine will fail.

View Available Engines

Requires the eng_user application role.

SQL

To list all engines, query the api.engines view:

SELECT * FROM relationalai.api.engines;
/*+------------------------+--------------+------+-------+-----------------------+--------------------------------+-------------------------------+-----------------------------+-------------------------+
  | NAME                   | ID           | SIZE | STATUS | CREATED_BY           | CREATED_ON                     | UPDATED_ON                    | COMPUTE_POOL                | VERSION                 |
  |------------------------+--------------+------+--------+----------------------+--------------------------------+-------------------------------+-----------------------------+-------------------------|
  | CDC_MANAGED_ENGINE     | b7c1d8f9a2b3 | S    | READY  | SYSTEM               | 2024-10-27 15:22:15.500 -0700  | 2024-10-27 15:22:16.731 -0700 | RELATIONAL_AI_HIGHMEM_X64_S | 2024.10.27-e829e39d     |
  | john_doe               | e4f5a6d7c8e9 | M    | READY  | john.doe@company.com | 2024-10-27 17:29:53.110 -0700  | 2024-10-27 17:29:54.319 -0700 | RELATIONAL_AI_CPU_X64_M     | 2024.10.27-e829e39d     |
  +------------------------+--------------+------+--------+----------------------+--------------------------------+-------------------------------+-----------------------------+-------------------------+ */

Refer to the reference docs for details about each column in the api.engines view.

Python

To list all engines using Python, create a Provider instance and use its .sql() method to query the api.engines view:

import relationalai as rai

# Get a provider instance.
app = rai.Provider()

# List all engines.
engines = app.sql("SELECT * FROM relationalai.api.engines")
print(engines)

CLI

To list all engines using the RAI CLI, run the engines:list command:

rai engines:list

Get Engine Details

Requires the eng_user application role.

SQL

To get details about a specific engine, pass the engine name to the api.get_engine() procedure:

-- Get details about the CDC engine. Note that if CDC is disabled, this engine may not exist.
CALL relationalai.api.get_engine('CDC_MANAGED_ENGINE');
/*+---------------------+--------------+-------------------------+------+--------+------------+-------------------------------+------------------------------ +-----------------------------+
  | NAME                | ID           | VERSION                 | SIZE | STATUS | CREATED_BY | CREATED_ON                    | UPDATED_ON                    | COMPUTE_POOL                |
  |---------------------+--------------+-------------------------+------+--------+------------+-------------------------------+-------------------------------+-----------------------------|
  | CDC_MANAGED_ENGINE  | a9d7f3b2c8e4 | 2024.10.27-e829e39d     | S    | READY  | SYSTEM     | 2024-10-27 15:22:15.500 -0700 | 2024-10-27 15:22:16.731 -0700 | RELATIONAL_AI_HIGHMEM_X64_S |
  +---------------------+--------------+-------------------------+------+--------+------------+-------------------------------+-------------------------------+-----------------------------+ */

Python

To get details about a specific engine using Python, create a Provider instance and use its .sql() method to execute the api.get_engine() procedure:

import relationalai as rai

# Get a provider instance.
app = rai.Provider()

# Get details about the engine named 'my_engine'.
engine = app.sql("CALL relationalai.api.get_engine('my_engine')")
print(engine)

CLI

To get details about a specific engine using the RAI CLI, run the engines:get command with the engine name provided as an argument to the --name option:

rai engines:get --name my_engine

View Idle Engines

Requires the eng_user application role.

SQL

Engines that have been automatically scheduled for suspension due to inactivity are considered idle. You can view idle engines by filtering the api.engines view on the for rows where the STATUS column is READY and the SUSPENDS_AT column is not null:

SELECT * FROM relationalai.api.engines
WHERE STATUS = 'READY' AND SUSPENDS_AT IS NOT NULL;

Python

Engines that have been automatically scheduled for suspension due to inactivity are considered idle. To view idle engines using Python, create a Provider instance and use its .sql() method to query the api.engines view:

import relationalai as rai

# Get a provider instance.
app = rai.Provider()

# List all idle engines.
idle_engines = app.sql("""
SELECT * FROM relationalai.api.engines
WHERE STATUS = 'READY' AND SUSPENDS_AT IS NOT NULL;
""")

print(idle_engines)

Suspend an Engine

Requires the eng_admin application role.

SQL

To suspend an engine, pass the engine name to the api.suspend_engine() procedure:

-- Suspend the engine named 'my_engine'.
CALL relationalai.api.suspend_engine('my_engine');
/*+-------------+------------------------+
  | NAME        | MESSAGE                |
  +-------------+------------------------+
  | my_engine   | suspended successfully |
  +-------------+------------------------+ */

CLI

To suspend an engine, run the engines:suspend command with the engine name provided as an argument to the --name option:

$ rai engines:suspend --name my_engine

---------------------------------------------------

▰▰▰▰ Engine 'my_engine' suspended

---------------------------------------------------

Python

To suspend an engine using Python, create a Provider instance and use its .sql() method to execute the api.suspend_engine() procedure:

import relationalai as rai

# Get a provider instance.
app = rai.Provider()

# Suspend the engine named 'my_engine'.
app.sql("CALL relationalai.api.suspend_engine('my_engine')")

Resume a Suspended Engine

Requires the eng_admin application role.

SQL

To resume a suspended engine, pass the engine name to the api.resume_engine() procedure:

-- Resume the engine 'my_engine' if it is suspended.
CALL relationalai.api.resume_engine('my_engine');
/*+-----------+----------------------+
  | NAME      | MESSAGE              |
  |-----------+----------------------|
  | my_engine | resumed successfully |
  +-----------+----------------------+ */

CLI

To resume a suspended engine, run the engines:resume command with the engine name provided as an argument to the --name option:

$ rai engines:resume --name my_engine

---------------------------------------------------

▰▰▰▰ Engine 'my_engine' resumed

---------------------------------------------------

Python

To resume a suspended engine using Python, create a Provider instance and use its .sql() method to execute the api.resume_engine() procedure:

import relationalai as rai

# Get a provider instance.
app = rai.Provider()

# Resume the engine named 'my_engine'.
app.sql("CALL relationalai.api.resume_engine('my_engine')")

Change Engine Auto-Suspend Time

Requires the eng_admin application role.

SQL

To change the auto-suspend time for an engine, pass the engine name and the desired auto-suspend time in minutes to the api.alter_engine_auto_suspend_mins() procedure:

-- Set the auto-suspend time for the engine 'my_engine' to 30 minutes.
CALL relationalai.api.alter_engine_auto_suspend_mins('my_engine', 30);
/*+---------+
  | Success |
  +---------+ */

Python

To change the auto-suspend time for an engine, create a Provider instance and use its .sql() method to execute the api.alter_engine_auto_suspend_mins() procedure:

import relationalai as rai

# Get a provider instance.
app = rai.Provider()

# Set the auto-suspend time for the engine 'my_engine' to 30 minutes.
app.sql("CALL relationalai.api.alter_engine_auto_suspend_mins('my_engine', 30)")

Note

Setting the auto-suspend time to 0 will prevent the engine from suspending due to inactivity.

Resize an Engine

Requires the eng_admin application role.

SQL

Engines cannot be resized on-the-fly. To resize an engine, first delete the engine and then create a new engine with the same name and a different size:

-- Delete the engine named 'my_engine'.
CALL relationalai.api.delete_engine('my_engine');
/*+-----------+----------------------+
  | NAME      | MESSAGE              |
  |-----------+----------------------|
  | my_engine | deleted successfully |
  +-----------+----------------------+ */

-- Create a HIGHMEM_X64_M engine with the same name.
CALL relationalai.api.create_engine('my_engine', 'HIGHMEM_X64_M');
/*+----------+
  | Success. |
  +----------+ */

Python

Engines cannot be resized on-the-fly. To resize an engine, first delete the engine and then create a new engine with the same name and a different size:

import relationalai as rai

# Get a provider instance.
app = rai.Provider()

# Delete the engine named 'my_engine'.
app.sql("CALL relationalai.api.delete_engine('my_engine')")

# Create a HIGHMEM_X64_M engine with the same name.
app.sql("CALL relationalai.api.create_engine('my_engine', 'HIGHMEM_X64_M')")

CLI

Engines cannot be resized on-the-fly. To resize an engine, first delete the engine and then create a new engine with the same name and a different size:

# Delete the engine named 'my_engine'.
rai engines:delete --name my_engine

# Create a HIGHMEM_X64_M engine with the same name.
rai engines:create --name my_engine --size HIGHMEM_X64_M

Monitor Engine Transactions

Requires the eng_user application role.

SQL

You can view an engine’s transactions by querying the api.transactions view a filtering by the ENGINE_NAME column:

-- List transactions for the engine named 'my_engine'.
SELECT * FROM relationalai.api.transactions WHERE ENGINE_NAME = 'my_engine';
/*+--------------------------------------+---------------+-----------+-----------+-----------------------+----------+-------------------------------+-------------------------------+-------------+
  | ID                                   | DATABASE_NAME | STATE     | READ_ONLY | CREATED_BY            | DURATION | CREATED_ON                    | FINISHED_AT                   | ENGINE_NAME |
  |--------------------------------------+---------------+-----------+-----------+-----------------------+----------+-------------------------------+-------------------------------+-------------|
  | 02c8fa31-1234-5678-90ab-abcdef123456 | MyModel       | ABORTED   | TRUE      | john.doe@company.com  | 7643     | 2024-10-28 08:00:12.123 -0700 | 2024-10-28 08:00:19.766 -0700 | my_engine   |
  | 03d9ab41-2345-6789-01bc-bcdef2345678 | MyModel       | COMPLETED | TRUE      | john.doe@company.com  | 500      | 2024-10-28 08:02:15.456 -0700 | 2024-10-28 08:02:15.956 -0700 | my_engine   |
  | 04e8bc52-3456-7890-12cd-cdef34567890 | MyModel       | RUNNING   | FALSE     | john.doe@company.com  | 3200     | 2024-10-28 08:05:00.789 -0700 | 2024-10-28 08:05:03.989 -0700 | my_engine   |
  +--------------------------------------+---------------+-----------+-----------+-----------------------+----------+-------------------------------+-------------------------------+-------------+ */

Python

To list all transactions using Python, create a Provider instance and use its .sql() method to query the api.transactions view:

import relationalai as rai

# Get a provider instance.
app = rai.Provider()

# List all transactions for the engine named 'my_engine'.
engine = 'my_engine'
transactions = app.sql(f"SELECT * FROM relationalai.api.transactions WHERE engine_name = {engine}")
print(transactions)

CLI

You can monitor an engine’s transactions by passing the engine name to the transactions:list command’s --engine option:

# List transactions for the engine named 'my_engine'. The `--all-users` flag
# ensures that transactions from all users are included in the list.
rai transactions:list --all-users --engine my_engine

Note that multiple transactions for the same engine may be RUNNING simultaneously. See Concurrent Transactions for information on how concurrent transactions are handled.

Take note of the following states. While occasional occurrences are normal, a high volume may indicate potential issues:

Status	Description
CREATED	The transaction has been accepted but is not yet in the engine queue. If it remains in this state, the engine’s resources are at capacity. Consider increasing the engine size or cancelling the transaction and running it on a different engine.
QUEUED	The transaction is in the engine’s queue. If it remains in this state, the engine’s concurrency limit has been reached. Wait for the transaction to leave the queue or cancel it and rerun on a different engine.
ABORTED	The transaction was cancelled or failed due to an error. Check the ABORT_REASON column for more details.

Get Transaction Details

Requires the eng_user application role.

SQL

To get details about a specific transaction, pass the transaction ID to the api.get_transaction() procedure:

-- Get details for the transaction with ID '02c8fa31-1234-5678-90ab-abcdef123456'.
CALL relationalai.api.get_transaction('02c8fa31-1234-5678-90ab-abcdef123456');

/*+--------------------------------------+---------------+-----------+--------------+-----------+-----------------------+----------+-------------------------------+-------------------------------+-------------+
  | ID                                   | DATABASE_NAME | STATE     | ABORT_REASON | READ_ONLY | CREATED_BY            | DURATION | CREATED_ON                    | FINISHED_AT                   | ENGINE_NAME |
  |--------------------------------------+---------------+-----------+--------------+-----------+-----------------------+----------+-------------------------------+-------------------------------+-------------|
  | 02c8fa31-1234-5678-90ab-abcdef123456 | MyModel       | COMPLETED | NULL         | TRUE      | john.doe@company.com  | 7643     | 2024-10-28 08:00:12.123 -0700 | 2024-10-28 08:00:19.766 -0700 | my_engine   |
  +--------------------------------------+---------------+-----------+--------------+-----------+-----------------------+----------+-------------------------------+-------------------------------+-------------+ */

Python

To get details about a specific transaction, create a Provider instance and use its .sql() method to execute the api.get_transaction() procedure:

import relationalai as rai

# Get a provider instance.
app = rai.Provider()

# Get details for the transaction with ID '02c8fa31-1234-5678-90ab-abcdef123456'.
transaction = app.sql("CALL relationalai.api.get_transaction('02c8fa31-1234-5678-90ab-abcdef123456')")
print(transaction)

CLI

To get details about a specific transaction, pass the transaction’s ID to the --id option of the transactions:get command:

# Get details for the transaction with ID '02c8fa31-1234-5678-90ab-abcdef123456'.
rai transactions:get --id 02c8fa31-1234-5678-90ab-abcdef123456

Cancel a Transaction

Requires the eng_user application role.

SQL

To cancel a transaction, pass the transaction ID to the api.cancel_transaction() procedure:

-- Cancel the transaction with ID '02c8fa31-1234-5678-90ab-abcdef123456'.
CALL relationalai.api.cancel_transaction('02c8fa31-1234-5678-90ab-abcdef123456');
/*+------------------------+
  | Cancelling transaction |
  +------------------------+ */

Python

To cancel a transaction, create a Provider instance and use its .sql() method to execute the api.cancel_transaction() procedure:

import relationalai as rai

# Get a provider instance.
app = rai.Provider()

# Cancel the transaction with ID '02c8fa31-1234-5678-90ab-abcdef123456'.
app.sql("CALL relationalai.api.cancel_transaction('02c8fa31-1234-5678-90ab-abcdef123456')")

CLI

To cancel a transaction using, pass the transaction’s ID to the --id option of the transactions:cancel command:

# Cancel the transaction with ID '02c8fa31-1234-5678-90ab-abcdef123456'.
rai transactions:cancel --id 02c8fa31-1234-5678-90ab-abcdef123456

It may take a few moments for the transaction to be cancelled. You may monitor the transaction and confirm that it has been cancelled once the STATE is reported as CANCELED.