Class: Job¶

A handle to an operation that may still be running.

The operation may already be complete when the handle is created.

The detail getters read what the handle last observed. Submitting an operation returns only a job id, so populating them eagerly would cost an extra round trip on every call:

Job.refresh and Job.status fetch the whole record.
Job.wait records the terminal state it establishes, but not the rest of the record.
Everything is null until one of those runs.

Accessors¶

creationMs¶

get creationMs(): null | number

When the job was created, in milliseconds since the epoch.

Returns¶

null | number

failure¶

get failure(): null | JobFailureInfo

Why the job failed, when it failed and the server reports a reason.

Returns¶

null | JobFailureInfo

id¶

get id(): null | string

Identifies the operation on the server that is running it.

Operations that run in this process have no server id. The value is opaque: parsing it or storing it to resume the job later is not supported.

Returns¶

null | string

jobType¶

get jobType(): null | string

The job's type, as the server names it. Null for an in-process job, which has no server-side record.

Returns¶

null | string

result¶

get result(): any

The job-type-specific terminal result. Null until the job succeeds, so a job that never terminates reports its progress through Job.events instead.

Returns¶

any

spec¶

get spec(): any

The job-type-specific specification it was submitted with.

Returns¶

any

state¶

get state(): null | string

The last observed lifecycle state, without contacting the backend.

Returns¶

null | string

Methods¶

cancel()¶

cancel(): Promise<void>

Request cancellation. Cancelling a finished operation is a no-op.

Returns¶

Promise<void>

events()¶

events(options?): Promise<Table<any>>

This job's recorded lifecycle events.

Where the getters above report a terminal result only once the job reaches one, events are written as the job runs and outlive the workers that produced them. A distributed job records a claim/claim_complete pair per unit of work, each carrying rows_processed, so a job that never finishes still accounts for what it did.

The server caps results at 1000 rows by default and 10,000 at most, and truncates without saying so, so pass limit for a job that emits an event per fragment. filter is a SQL-like expression over the state, updated_by, emitted_from, emitted_by, and claim_entity columns.

Parameters¶

options?: JobEventsOptions

Returns¶

Promise<Table<any>>

refresh()¶

refresh(): Promise<void>

Ask the backend for this job's current state, and for a server-side job its full record, then cache it for the getters above.

Returns¶

Promise<void>

status()¶

status(): Promise<string>

The operation's current lifecycle state: "running", "finished", "failed", or "cancelled".

A point snapshot; unlike Job.wait it does not block or reject on a terminal failure state. Also refreshes the getters above.

Returns¶

Promise<string>

toString()¶

toString(): string

Every field the handle currently knows, one per line, with the JSON payloads indented -- a refresh job's spec and result are the point of printing it.

Returns¶

string

wait()¶

wait(): Promise<void>

Wait until the operation reaches a terminal state.

Returns¶

Promise<void>