Manage reasoner jobs

Use this guide when you need to inspect work running on a reasoner or stop work that should no longer continue. It shows how to list jobs, check one job in detail, and cancel a queued or running job with SQL, Python, or the CLI.

Before you start, make sure that:

• The RAI Native App is installed and usable in your Snowflake account.
• You can run SQL in Snowflake with an active warehouse.
• You know the name of the reasoner you want to inspect, or you already have the job ID you want to inspect or cancel.

What jobs are

A RelationalAI job is a unit of work that runs on a reasoner. Jobs include user-initiated work such as evaluating queries from semantic models, as well as app-managed work such as processing changes from data streams.

One reasoner can process more than one job at a time. Each reasoner supports concurrent jobs, and additional work can wait in that reasoner’s queue until capacity is available. That means a reasoner can be available and still feel slow if work is backing up in the queue rather than failing outright.

Concurrent jobs on the same reasoner may impact each other’s performance. Resource-intensive jobs may also increase wait time for other work on the same reasoner.

This guide helps you understand what jobs are running, how long they have been running, and whether any work has been cancelled or failed.

How jobs are managed

PyRel and the RAI Native App create and submit jobs as work needs to run on a reasoner. As an admin, you use this page to inspect those jobs, check the state of one specific job, or cancel work that should no longer continue.

Use this table to choose the task that matches what you need next:

What to do	When to do it
View all jobs	When a reasoner seems slow or blocked and you need to see which jobs are queued, running, or recently finished.
View jobs by status	When you need to interpret the current job states and decide whether work is waiting, running, completed, or failing.
Get job details	When you already have a job ID and need to inspect its state, duration, or abort reason more closely.
Cancel a job	When a queued or running job should no longer continue on the current reasoner.

View all jobs

Requires the eng_user application role.

Use the following interfaces to view all jobs for a reasoner:

SQL

Query the api.jobs view and filter by the REASONER_NAME column. Add REASONER_TYPE if you want to narrow the results to one reasoner type:

-- List jobs for the reasoner named 'my_reasoner'.
SELECT *
FROM relationalai.api.jobs
WHERE REASONER_NAME = 'my_reasoner'
  AND REASONER_TYPE = 'logic';

Output

+--------------------------------------+---------------+---------------+---------+----------------------+-------------------------------+-------------------------------+----------+------------------+------------+--------------+
| ID                                   | REASONER_TYPE | REASONER_NAME | STATE   | CREATED_BY           | CREATED_ON                    | FINISHED_AT                   | DURATION | PAYLOAD           | TIMEOUT_MS | ABORT_REASON |
|--------------------------------------+---------------+---------------+---------+----------------------+-------------------------------+-------------------------------+----------+------------------+------------+--------------|
| 02c8fa31-1234-5678-90ab-abcdef123456 | logic         | my_reasoner   | ABORTED | john.doe@company.com | 2024-10-28 08:00:12.123 -0700 | 2024-10-28 08:00:19.766 -0700 | 7643     | {"kind":"query"} | 86400000   | canceled     |
+--------------------------------------+---------------+---------------+---------+----------------------+-------------------------------+-------------------------------+----------+------------------+------------+--------------+

Python

Create a client with connect_sync() and call client.jobs.list():

from relationalai.client import connect_sync

with connect_sync() as client:
    jobs = client.jobs.list("Logic", name="my_reasoner")
    print(jobs)

CLI

Use the jobs:list command and pass the reasoner name to --name:

# List jobs for the reasoner named 'my_reasoner'.
rai jobs:list --name my_reasoner

Start with ID, STATE, CREATED_ON, FINISHED_AT, and ABORT_REASON. Those fields are usually enough to decide whether you should inspect a job more closely or cancel work that should no longer continue.

View jobs by status

Use the STATE column to understand whether work is waiting, running, finished, or needs follow-up:

State	Description
CREATED	The job has been accepted by the native app but has not yet been sent to the reasoner queue. If it remains in this state, the reasoner’s resources may be at capacity, or the native app has not yet forwarded the job to the reasoner.
QUEUED	The job is in the reasoner’s queue, waiting to be processed. If it remains in this state, the reasoner’s concurrency limit has been reached. Wait for the job to leave the queue or cancel it and rerun on a different reasoner.
RUNNING	The job is currently being processed by the reasoner. A running job may complete normally, be cancelled, or end in an aborted state if an error occurs.
COMPLETED	The job finished successfully.
CANCELED	The job was cancelled and reached its final cancelled state.
ABORTED	The job encountered an error or other issue. Check the ABORT_REASON column for more details.

Note

Occasional CREATED, QUEUED, CANCELED, or ABORTED jobs are normal. If many jobs remain in CREATED or QUEUED, the reasoner may be overloaded or the workload may be backing up faster than it can be processed. If many jobs remain in RUNNING for longer than expected, inspect individual jobs to determine whether the workload is unusually heavy. If many jobs end in ABORTED or CANCELED, inspect ABORT_REASON and the surrounding workload pattern before retrying the same work.

For API details about the STATE and ABORT_REASON columns, see the api.jobs SQL reference.

Related resources:

• Get job details
• Cancel a job
• Scale reasoner capacity

Get job details

Requires the eng_user application role.

Use the following interfaces to inspect one job in detail:

SQL

Pass the reasoner type and job ID to api.get_job():

-- Get details for the job with ID '02c8fa31-1234-5678-90ab-abcdef123456'.
CALL relationalai.api.get_job('logic', '02c8fa31-1234-5678-90ab-abcdef123456');

Output

+--------------------------------------+---------------+---------------+-----------+----------------------+-------------------------------+-------------------------------+----------+------------------+------------+--------------+
| ID                                   | REASONER_TYPE | REASONER_NAME | STATE     | CREATED_BY           | CREATED_ON                    | FINISHED_AT                   | DURATION | PAYLOAD           | TIMEOUT_MS | ABORT_REASON |
|--------------------------------------+---------------+---------------+-----------+----------------------+-------------------------------+-------------------------------+----------+------------------+------------+--------------|
| 02c8fa31-1234-5678-90ab-abcdef123456 | logic         | my_reasoner   | COMPLETED | john.doe@company.com | 2024-10-28 08:00:12.123 -0700 | 2024-10-28 08:00:19.766 -0700 | 7643     | {"kind":"query"} | 86400000   | NULL         |
+--------------------------------------+---------------+---------------+-----------+----------------------+-------------------------------+-------------------------------+----------+------------------+------------+--------------+

Python

Create a client with connect_sync() and call client.jobs.get():

from relationalai.client import connect_sync

with connect_sync() as client:
    job = client.jobs.get("Logic", "02c8fa31-1234-5678-90ab-abcdef123456")
    print(job)

CLI

Use the jobs:get command and pass the job ID to --id:

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

Read the result in this order: STATE, FINISHED_AT, DURATION, then ABORT_REASON. If a job is ABORTED, start with ABORT_REASON, but do not assume it is always the full explanation.

Related resources:

• View all jobs
• Cancel a job
• Monitor reasoner usage

Cancel a job

Requires the eng_user application role.

Use the following interfaces to cancel a queued or running job:

SQL

Pass the reasoner type and job ID to api.cancel_job():

-- Cancel the job with ID '02c8fa31-1234-5678-90ab-abcdef123456'.
CALL relationalai.api.cancel_job('logic', '02c8fa31-1234-5678-90ab-abcdef123456');

Output

+------------------------+
| Cancelling job         |
+------------------------+

Python

Create a client with connect_sync() and call client.jobs.cancel():

from relationalai.client import connect_sync

with connect_sync() as client:
    client.jobs.cancel("Logic", "02c8fa31-1234-5678-90ab-abcdef123456")

CLI

Use the jobs:cancel command and pass the job ID to --id:

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

It may take a few moments for the job to reach its final cancelled state. Monitor the job again and confirm that STATE is reported as CANCELED.

Note

If you keep cancelling jobs because the same reasoner stays backed up, move to Scale reasoner capacity instead of repeating the same workaround.

Related resources:

• View all jobs
• Scale reasoner capacity
• Monitor reasoner usage