Job, Chain & Worker Queries
Read-only methods for inspecting jobs, chains and workers.
The client provides read-only methods for inspecting chains, jobs and workers. The examples below query an order workflow: a reserve-stock chain blocks a process-order chain, which continues to ship-order.
Lookups
Look up a single chain or job by ID, or a batch of them in one round trip. Batch lookups return a positional array with undefined for each missing ID:
src/queries.ts
const chain = await client.getChain({ id: orderChain.id, typeName: "process-order" });
const job = await client.getJob({ id: orderChain.id });
const chains = await client.getChains({ ids: [orderChain.id, stockChain.id, "missing-id"] });
const jobs = await client.getJobs({ ids: [orderChain.id, stockChain.id] });getChain, getChains, getJob, getJobs, getJobBlockers, and listBlockedJobs accept an optional typeName for type narrowing (listChainJobs, getChainTailJob and getChainTailJobs take chainTypeName) — the return type narrows to the specified type, so a completed process-order chain exposes its typed output. If the entity exists but has a different type, ChainTypeMismatchError or JobTypeMismatchError is thrown.
All query methods accept an optional transaction context in which every field is optional, so a read needs only the transaction handle, not the txHooks some providers carry in their context:
src/queries.ts
const chainInTransaction = await stateAdapter.withTransaction(async (txCtx) =>
client.getChain({ ...txCtx, id: orderChain.id }),
);Types and Counts
Discover which chain and job types exist in the data, and get per-status counts for specific types:
src/queries.ts
const chainTypeNames = await client.getChainTypeNames();
const jobTypeNames = await client.getJobTypeNames();
const [orderChainCounts] = await client.countChainsByTypeName({ typeNames: ["process-order"] });
const [shipJobCounts] = await client.countJobsByTypeName({ typeNames: ["ship-order"] });Paginated Lists
listChains and listJobs require typeName and filter by it. Pass the previous page's nextCursor to read the next page:
src/queries.ts
const firstPage = await client.listChains({
typeName: "process-order",
status: "completed",
limit: 1,
});
const secondPage = await client.listChains({
typeName: "process-order",
status: "completed",
cursor: firstPage.nextCursor ?? undefined,
limit: 1,
});
const shipJobs = await client.listJobs({
typeName: "ship-order",
status: "completed",
orderBy: "createdAt",
});listChains and listJobs route queries to status-specific indexes based on the status and orderBy combination. Each status has a natural default sort order — for example, completed chains default to completedAt descending, pending and blocked jobs to scheduledAt descending. Pass orderBy: "createdAt" to override.
Chain Jobs
listChainJobs lists the jobs within a chain in chain order. A chain's tail job is its latest job in chain order, and the head job while the chain has not continued; getChainTailJobs returns one entry per requested chain ID, undefined for a missing chain:
src/queries.ts
const chainJobs = await client.listChainJobs({
chainId: orderChain.id,
chainTypeName: "process-order",
});
const tailJob = await client.getChainTailJob({ chainId: orderChain.id });
const tailJobs = await client.getChainTailJobs({ chainIds: [orderChain.id, stockChain.id] });getChainTailJob and getChainTailJobs are experimental: they may change in a minor release.
Blockers
Inspect blocker relationships from both directions: getJobBlockers returns the chains a job waits on, and listBlockedJobs lists the jobs a chain blocks:
src/queries.ts
const blockers = await client.getJobBlockers({ jobId: orderChain.id, typeName: "process-order" });
const blockedJobs = await client.listBlockedJobs({ chainId: stockChain.id });Workers
Look up workers by ID (undefined for a worker with no row), count live and expired workers overall and per job type, and list the jobs running under a worker:
src/queries.ts
const workerPage = await client.listWorkers({ limit: 20 });
const workerId = workerPage.items[0].id;
const worker = await client.getWorker({ id: workerId });
const { live, expired } = await client.countWorkers();
const [shipWorkers] = await client.countWorkersByTypeName({ typeNames: ["ship-order"] });
const [runningJobCount] = await client.countRunningJobsByWorkerId({ workerIds: [workerId] });
const runningJobs = await client.listWorkerJobs({ workerId });listWorkers orders workers by startedAt and optionally keeps only those processing a typeName; listWorkerJobs orders jobs by attemptAt. Both sort by that column, then id, ascending unless orderDirection says otherwise, and take no orderBy.
See examples/guides/src/queries.ts for the runnable code. See also the Client API reference and Dashboard.