> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lancedb.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://docs.lancedb.com/basics/jobs.md) 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

```sql SQL icon="database" theme={"theme":{"light":"vitesse-light","dark":"catppuccin-mocha"}}
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.

> [!NOTE]
>
> 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

```sql SQL icon="database" theme={"theme":{"light":"vitesse-light","dark":"catppuccin-mocha"}}
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

```sql SQL icon="database" theme={"theme":{"light":"vitesse-light","dark":"catppuccin-mocha"}}
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

```sql SQL icon="database" theme={"theme":{"light":"vitesse-light","dark":"catppuccin-mocha"}}
SHOW ERRORS ON <table> [FOR JOB '<job-id>'] [LIMIT <n>]
```

```sql SQL icon="database" theme={"theme":{"light":"vitesse-light","dark":"catppuccin-mocha"}}
SHOW ERRORS ON documents
SHOW ERRORS ON documents FOR JOB 'job-abc' LIMIT 100
```

Why rows failed. Reach for this when a [refresh](https://docs.lancedb.com/sql/dml/refresh-column.md) 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.

> [!NOTE]
>
> `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

```sql SQL icon="database" theme={"theme":{"light":"vitesse-light","dark":"catppuccin-mocha"}}
PAUSE JOB 'j-ci-abc-def'
```

## RESUME JOB

```sql SQL icon="database" theme={"theme":{"light":"vitesse-light","dark":"catppuccin-mocha"}}
RESUME JOB 'j-ci-abc-def'
```

## CANCEL JOB

```sql SQL icon="database" theme={"theme":{"light":"vitesse-light","dark":"catppuccin-mocha"}}
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.

> [!NOTE]
>
> `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.

> [!NOTE]
>
> Cancellation is a request, matching the SDK's
> [`cancel()`](https://docs.lancedb.com/basics/jobs#managing): 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`](#show) for the per-split diagnostics
form -- each split is a child job, listed with its own phase and progress.
See [Watching a refresh](https://docs.lancedb.com/sql/dml/refresh.md#watching) for `SHOW JOB SPLITS`'s
full column reference and a `DESCRIBE JOB` example.

## What to read next

> [card] [Query and job](https://docs.lancedb.com/basics/jobs.md)
>
> The handle these statements are the SQL view of.

> [card] [Intelligent Auto-Maintenance](https://docs.lancedb.com/enterprise/intelligent-auto-maintenance.md#cleanup)
>
> A job type the deployment schedules on its own, without a call.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.