JobsClient

relationalai.services.jobs.client

JobsClient(
    _gateway: JobsGateway, _config: "Config | None" = None, _closed: bool = False
)

Async-first jobs client.

API behavior depends on the public reasoner_type value:

• Logic routes to transactions.
• Prescriptive / Predictive route to jobs.

Methods

.aclose()

JobsClient.aclose() -> None

Close underlying resources (best-effort).

Note: SQL gateways typically have nothing to close; Direct Access gateways may own an async HTTP client/session.

Returns:

• None - Always returns None.

.get()

JobsClient.get(
    reasoner_type: str, job_id: str, *, include: JobIncludeDict | None = None
) -> Job | None

Get a normalized job/transaction by (reasoner_type, job_id).

By default returns a stable common schema. Use include= to opt into backend-specific expansions (e.g. details, events, artifacts, problems, raw).

Returns:

• Job | None - The job/transaction, or None if not found.

.create()

JobsClient.create(
    reasoner_type: str,
    reasoner_name: str,
    payload: dict[str, Any],
    *,
    timeout_mins: int | None = None
) -> JobOperation

Start a job/transaction and return a non-blocking operation handle.

The returned handle’s id is the job_id/txn_id to poll with wait(...) / wait_for_operation(...).

Note: reasoner_name identifies which reasoner/worker to run on.

Returns:

• JobOperation - An operation handle; call await op.wait(...) to block for completion.

.create_ready()

JobsClient.create_ready(
    reasoner_type: str,
    reasoner_name: str,
    payload: dict[str, Any],
    *,
    timeout_mins: int | None = None,
    timeout_s: float = 900,
    poll_interval_s: float = 0.5,
    include: JobIncludeDict | None = None
) -> Job

Create a job and block until it reaches a terminal state.

Returns:

• Job - The final job/transaction (possibly expanded when include= is provided).

.list()

JobsClient.list(
    reasoner_type: str | None = None,
    *,
    job_id: str | None = None,
    state: str | None = None,
    name: str | None = None,
    created_by: str | None = None,
    only_active: bool = False,
    all_users: bool = False,
    limit: int | None = None,
    include: JobIncludeDict | None = None
) -> list[Job]

List jobs/transactions, optionally filtered and optionally expanded.

• If reasoner_type is None, this lists across all supported job types and merges the results, sorting by created_on (desc).
• include= enables best-effort expansions per returned item.

Returns:

• list[Job] - Matching jobs/transactions (possibly expanded when include= is provided).

.get_events()

JobsClient.get_events(
    reasoner_type: str,
    job_id: str,
    continuation_token: str = "",
    *,
    stream_name: str = "progress"
) -> JobEvents

Get events for a job or transaction.

Works for all reasoner types and backends:

• LOGIC (DA): GET /v1alpha1/transactions/{txn_id}/events/{stream_name}
• LOGIC (SQL): {app}.api.get_own_transaction_events(txn_id, continuation_token)
• Non-LOGIC (DA): GET /v1alpha1/jobs/{job_type}/{job_id}/events/{stream_name}
• Non-LOGIC (SQL): {app}.{schema}.GET_JOB_EVENTS(reasoner_type, job_id, token)

Returns:

• JobEvents - Event page including events and an optional continuation_token.

.cancel()

JobsClient.cancel(reasoner_type: str, job_id: str, *, all_users: bool = False) -> None

Cancel a running job/transaction.

Cancellation is supported for both non-LOGIC jobs and LOGIC transactions.

cancel(all_users=True) is only supported for LOGIC transactions; non-LOGIC jobs reject it.

Returns:

• None - Always returns None.

.wait()

JobsClient.wait(
    reasoner_type: str,
    job_id: str,
    *,
    timeout_s: float = 900,
    poll_interval_s: float = 0.5,
    include: JobIncludeDict | None = None
) -> Job

Poll get(...) until the execution reaches a terminal state.

Returns the final Job (or JobExpanded if include= is provided). Raises JobTimeoutError when timeout_s is exceeded.

Returns:

• Job - The final job/transaction (possibly expanded when include= is provided).

.get_operation()

JobsClient.get_operation(reasoner_type: str, job_id: str) -> Operation

Derive a normalized operation status from the current job state.

Returns:

• Operation - A normalized operation status.