Worker Job Types
Worker Job Types
Section titled “Worker Job Types”Summary
Section titled “Summary”Worker jobs execute background work that should survive browser closure or take longer than a quick request.
Registration describes a handler, not who may invoke it. The Worker separately checks the exact job type, authenticated role or service identity, environment, tenant, and system scope.
Fields / Parameters
Section titled “Fields / Parameters”| Family | Type | Description |
|---|---|---|
| Data load | Job family | File loads, area syncs, PDF extraction, and virtual file processing. |
| Connector sync | Job family | Web API and application connector synchronization. |
| Dashboard | Job family | Widget compilation, widget deletion, dashboard generation, and refinement. |
| AI generation | Job family | Transform plans, stream plans, and assistant-supported generation. |
| Tenant operations | Job family | Import, purge, transfer preparation, and remapping. The export handler is registered but paused. |
| Maintenance | Job family | Logical view refresh, retention policy, materialization, migrations, and cleanup. Availability varies by exact job type. |
Availability notes
Section titled “Availability notes”| Job type or class | Current submission policy |
|---|---|
WIDGET_COMPILE, REFRESH_LOGICAL_VIEWS, WAREHOUSE_PUBLISH |
Tenant-member authoring jobs. WAREHOUSE_PUBLISH accepts exactly the environment, tenant, and persisted warehouse query id; the Worker owns graph validation, SQL expansion, target-catalog CREATE-vs-SWAP attestation, staged publication, and durable receipts. Successful publication hands the server-owned source query to the same tenant optimizer scope. |
DERIVED_TABLE_REFRESH |
Tenant member for refresh; tenant operator for drop. |
Object-destructive soft-delete jobs and WIDGET_DELETE |
Tenant operator. |
TENANT_PROVISION, TENANT_PURGE |
System owner. |
WEBAPI_SYNC, MATVIEW_REFRESH |
Dispatcher-only over the HTTP mesh path. MATVIEW_REFRESH accepts only environment, tenant, and persisted query id; the Worker reloads the exact catalog and derives the physical target/cascade. |
OPTIMIZER_INDEX_BUILD |
SQL Gateway only. The payload is exactly environment, tenant, physical table, ordered physical columns, and the deterministic index name. The Worker validates before persistence, deduplicates by exact environment + tenant + table + index name, and reloads the exact parent/chunk catalog. Fresh usable prefix coverage returns already-covered without DDL or an ownership claim. Otherwise the Worker emits server-generated online DDL without a wall-clock transport timeout. Cancellation is honored before that non-transactional DDL boundary; after DDL starts the Worker waits for the terminal outcome, reconciles the result, and re-reconciles a fresh catalog before accepting its durable ownership receipt. |
MIRROR_SQLITE_TO_POSTGRES |
Dispatcher, or a system owner with explicit system scope. |
TENANT_EXPORT |
Registered under tenant-operator policy, but execution is paused. New submissions return HTTP 409 / WORKER_JOB_EXECUTION_PAUSED before persistence; after generic run-lifecycle bookkeeping, recovered rows fail before export peer resolution or tenant-data access/effects. |
TENANT_IMPORT |
Registered under tenant-operator policy, but execution is paused. New submissions return HTTP 409 / WORKER_JOB_EXECUTION_PAUSED before persistence; after generic run-lifecycle bookkeeping, recovered rows fail before import peer resolution, archive download, or tenant-data access/effects. |
CHECKPOINT_PURGE |
Registered but dormant: it has no HTTP submitter and automatic scheduling is paused. |
HARD_PURGE_ENTITY |
Registered but dormant: submission and recovered-row execution are paused pending atomic retained-version deletion. |
The Worker has no generic manual index-analysis, create, apply, or drop job.
Observer-driven analysis and its owned index lifecycle belong to SQL Gateway’s
autonomous optimizer and use server-owned statements and telemetry rather than
client SQL.
OPTIMIZER_INDEX_BUILD is the optimizer’s narrow internal effect protocol, not
a client-accessible SQL surface. WIDGET_COMPILE separately retains its
intentional compile-time idx_auto_* lifecycle.
System-scoped job types additionally require a system owner and the explicit system-scope
header. HTTP callers cannot select the Worker’s internal PHYSICAL phase. A service’s
mTLS identity does not grant access beyond its exact service-to-job allowlist.
Example
Section titled “Example”QUEUED → RUNNING → DONE └─────────────→ CANCELLED └──→ ERRORJob identifiers use the j- prefix, for example j-7f3a91c2-d4e. PENDING is a step state inside a job; a newly accepted job itself is QUEUED.
After a Worker restart, an interrupted job may be re-enqueued from the beginning of its handler. This is restart recovery, not mid-handler resume or exactly-once execution.
Job progress and result projections are not bulk-data channels. The retained tenant-export browser marker is a defense-in-depth refusal, not a transfer mechanism. Export and import require a dedicated authorized, size-bounded, backpressured, cancellable streaming architecture before either can be enabled.
Alert notification is not a Worker job family. Sentinel emits browser events and delivers configured external channels directly when an alert changes state.