Sanity Library Reference Docs
    Preparing search index...

    Interface InstancesQueryFilter

    Narrows an instance-list read. All conditions AND together; an empty filter means "every in-flight instance in the engine's resource".

    interface InstancesQueryFilter {
        assignment?: {
            roles?: readonly string[];
            states?: readonly AssignmentState[];
            userId: string;
        };
        before?: { id: string; startedAt: string };
        definition?: string;
        document?:
            | `dataset:${string}`
            | `canvas:${string}`
            | `media-library:${string}`
            | `dashboard:${string}`;
        documents?: readonly (
            | `dataset:${string}`
            | `canvas:${string}`
            | `media-library:${string}`
            | `dashboard:${string}`
        )[];
        ids?: readonly string[];
        includeCompleted?: boolean;
        limit?: number;
        stage?: string;
    }
    Index

    Properties

    assignment? before? definition? document? documents? ids? includeCompleted? limit? stage?

    Properties

    assignment?: {
        roles?: readonly string[];
        states?: readonly AssignmentState[];
        userId: string;
    }

    Current viewer assignment filter. unrouted needs no identity match; routed matches literal role members only while no user holds the activity; held matches the direct user and shadows every role.

    before?: { id: string; startedAt: string }

    Keyset cursor into the newest-first order: only instances strictly older than this position. Pass the last row of the previous page, and the next limit rows continue where it ended. A cursor rather than an offset, so rows starting or concluding between pages can't shift what a page holds. Requires limit: pages only exist in the newest-first sliced read.

    Type declaration

    • id: string

      The _id tiebreak for rows sharing startedAt.

    • startedAt: string
    definition?: string

    Version-less definition name the instances were started from.

    document?:
        | `dataset:${string}`
        | `canvas:${string}`
        | `media-library:${string}`
        | `dashboard:${string}`

    Only instances that may reference this document (resource-qualified GDR URI). The lake-side predicate matches the reactive watch-set's workflow, open-stage, activity, ancestor, live-child, and own-id references.

    documents?: readonly (
        | `dataset:${string}`
        | `canvas:${string}`
        | `media-library:${string}`
        | `dashboard:${string}`
    )[]

    The multi-document form of InstancesQueryFilter.document: one predicate matching instances that reference any of the given docs, for consumers discovering instances across many open documents at once. Merged with document when both are set. Callers may defensively recheck with instanceWatchesDocument. A defined but empty array matches nothing (the GROQ-natural reading of membership in an empty set) — omit the field for the unconstrained every-in-flight read.

    ids?: readonly string[]

    Specific instances by bare doc id — OR'd with the document prefilter, so a consumer tracking freshly-started instances (not yet referencing any registered doc) sees them in the same live read. Bare ids only: an instance's _id is never a GDR URI, so a URI here is a caller bug and is rejected. A defined but empty array matches nothing, exactly like InstancesQueryFilter.documents.

    includeCompleted?: boolean

    Include completed/aborted instances (default: in-flight only).

    limit?: number

    Cap the read to the newest limit instances — the query flips to startedAt desc and slices, so a bounded consumer (a dashboard over an unbounded dataset) reads the most recent rows instead of the oldest. Unlimited reads keep the ascending order adapters index by. Must be a positive integer.

    stage?: string

    Current stage name.

    Settings

    Member Visibility

    On This Page

    Properties