本页尚未翻译

本页内容仍为英文原文，源自官方文档 sql/ddl/job。中文翻译正在分批进行中。

Job

SHOW JOBS, SHOW JOB EVENTS, DESCRIBE JOB, SHOW ERRORS, and controlling a running job with PAUSE, RESUME and CANCEL.

Applies to: Embedded ❌, Enterprise ✅

A job is not a catalog object (it has no schema and is not namespaced), but it has its own SQL statements, grouped here the same way the catalog objects are.

SHOW JOBS

SHOW JOBS
SHOW JOBS FOR TABLE documents
SHOW JOBS FOR JOB '<parent_job_id>' [LIMIT n]

The unfiltered command lists jobs in the connected database, newest first: id, type, state, creation time -- the SQL counterpart of list_jobs. FOR TABLE filters that listing by the current namespace's table name. FOR JOB lists the parent's direct child jobs using the REST API's child model. Child rows expose their ID, kind, phase, row progress and attempt; unknown values remain NULL. Children are read-only diagnostic identities.

FOR JOB defaults to 1,000 children and accepts LIMIT from 1 to 10,000, following backend continuation pages up to that limit. Child history can be available, not_yet_recorded, or unavailable after archival.

说明

A job you completed weeks ago eventually stops appearing here -- it was archived, not deleted. Two deployment-scheduled jobs sweep the registry on a per-database schedule: job_registry_archive moves terminal jobs out of the active registry into archival storage, and job_events_export separately copies terminal jobs' event histories into a curated system table for metering, where the deployment enables it. A job's events can survive in that exported table after the job itself is archived.

SHOW JOB EVENTS

SHOW JOB EVENTS '<parent_or_child_job_id>' [LIMIT n]

Events are returned newest first. Parent history does not include child history. The default limit is 1,000; valid limits range from 1 to 10,000. The result includes event sequence, state, timestamps, origin, claim and resource/work fields. Child kind and details expose the REST API's allowlisted diagnostics; raw parent payloads are excluded.

DESCRIBE JOB

DESCRIBE JOB '<job_id>' [FORMAT TEXT | TABLE | JSON]
DESC JOB '<job_id>' [FORMAT TEXT | TABLE | JSON]

Both spellings show a finished root job's timing profile. TEXT is the default; TABLE returns typed phase/step rows and JSON returns the profile as one document. A running job has no profile rows.

SHOW ERRORS

SHOW ERRORS ON <table> [FOR JOB '<job-id>'] [LIMIT <n>]

SHOW ERRORS ON documents
SHOW ERRORS ON documents FOR JOB 'job-abc' LIMIT 100

Why rows failed. Reach for this when a refresh reports fewer filled rows than you expected.

Errors and limits

LIMIT	defaults to 10,000; must be between 1 and 100,000
Failed jobs scanned without FOR JOB	32 most recent
Tables the server does not open directly	not supported

Without FOR JOB this surveys recent failures and stops at 32 jobs. When the listing stops at your LIMIT, the message says so. Narrow with FOR JOB rather than raising the limit blindly.

说明

SHOW JOBS, SHOW JOB EVENTS, DESCRIBE JOB and SHOW ERRORS require system USAGE, as do the equivalent REST diagnostics. Explicit table listings additionally use the table-list authorization policy.

PAUSE JOB

PAUSE JOB 'j-ci-abc-def'

RESUME JOB

RESUME JOB 'j-ci-abc-def'

CANCEL JOB

CANCEL JOB 'j-ci-abc-def'

The job id is always a quoted string literal. All three take exactly one and nothing after it: a second token on the line is a syntax error rather than being ignored. Pause requires the deployment's pause-write opt-in and a resumable job type; it may return pausing while workers drain, and resume may return still_pausing until drain finishes.

说明

PAUSE JOB, RESUME JOB and CANCEL JOB require system OPERATE -- a broader privilege than the USAGE that reading job state needs, since these change what a running job does.

说明

Cancellation is a request, matching the SDK's cancel(): it does not guarantee the job stops before doing more work, and asking twice or cancelling a finished job does nothing. CANCEL JOB itself can be unavailable on an Enterprise cluster with no job registry configured, which is a deployment condition rather than something you can work around from SQL.

Compatibility

SHOW JOBS FOR <table> (without the TABLE keyword), SHOW JOB SUMMARY, and SHOW JOB SPLITS retain their existing behavior as compatibility forms. Prefer SHOW JOBS FOR TABLE/FOR JOB and DESCRIBE JOB going forward. See SHOW JOBS FOR JOB for the per-split diagnostics form -- each split is a child job, listed with its own phase and progress. See Watching a refresh for SHOW JOB SPLITS's full column reference and a DESCRIBE JOB example.

What to read next

Query and jobThe handle these statements are the SQL view of.Intelligent Auto-MaintenanceA job type the deployment schedules on its own, without a call.