FindServerArgs

Defined in: packages/core/src/collections/api/find/server.ts:57

Server-side args for find. Extends GenericQueryServerParams to inherit ctx, populate, depth, and config (with their mutual-exclusion constraints). All query-chain options map to ctx.db.query() equivalents applied in order: withIndex → order → filter → take.

Extends

GenericQueryServerParams<DataModel, TCollectionSlug, TPopulate, D>

Type Parameters

DataModel

DataModel extends GenericDataModel

The Convex data model (inferred from ctx).

TCollectionSlug

TCollectionSlug extends CollectionSlug

Collection slug.

TPopulate

TPopulate extends PopulateShape<TCollectionSlug>

Populate object.

D

D extends number = 0

Depth literal (0 = no depth, default).

Properties

access?

optional access?: AccessCallOptions<QueryCallAction>

Defined in: packages/core/src/collections/api/types.ts:143

Per-call access overrides.

See

AccessCallOptions

Inherited from

GenericQueryServerParams.access

auth?

optional auth?: VexApiAuth

Defined in: packages/core/src/collections/api/types.ts:150

The auth config of the current user making the query.

Example

{ user: {...}, organization: {...} }

Inherited from

GenericQueryServerParams.auth

collection

collection: TCollectionSlug

Defined in: packages/core/src/collections/api/find/server.ts:64

The collection to query — must match a registered collection slug.

config?

optional config?: [TPopulate] extends [Record<string, never>] ? VexConfig : never

Defined in: packages/core/src/collections/api/types.ts:168

The resolved VexConfig. Required alongside depth; passed from the queryApi factory closure so the Convex handler has schema info.

Inherited from

GenericQueryServerParams.config

ctx

ctx: GenericQueryCtx<DataModel>

Defined in: packages/core/src/collections/api/types.ts:152

Discriminator: server args MUST supply a Convex query context.

Inherited from

GenericQueryServerParams.ctx

depth?

optional depth?: [TPopulate] extends [Record<string, never>] ? D : never

Defined in: packages/core/src/collections/api/types.ts:163

Auto-populate all relationship fields to this many levels. Becomes never when TPopulate is non-empty. Use populate for consumer-facing code; this is an internal escape hatch for CollectionListView.

Inherited from

GenericQueryServerParams.depth

drafts?

optional drafts?: boolean

Defined in: packages/core/src/collections/api/find/server.ts:158

Include draft rows for a versioned collection. Defaults to false.

The two-row draft model (design-review.md §1) means an unfiltered query on a versioned collection returns the same logical document twice — once vex_status: "published", once vex_status: "draft" — so find injects a published-only constraint unless this is true. Ignored for a collection that doesn’t declare versions.drafts.

Also switches the RBAC action this call resolves against, from "read" to "readDrafts" (DRAFT_ACTIONS.readDrafts) — but only when the caller’s role grants readDrafts at all. A caller without it silently falls back to the published-only read (the same non-throwing fallback getGlobal uses), so one set of query args serves every caller: the admin list view and its server prefetch can both always send drafts: true for a versioned collection without knowing who is asking.

limit?

optional limit?: number

Defined in: packages/core/src/collections/api/find/server.ts:71

Maximum number of documents to return, applied as the terminal .take(n) on the Convex query. Omit it, or pass 0, to return every matching document (.collect()). Ignored when paginationOpts is set.

order?

optional order?: "asc" | "desc"

Defined in: packages/core/src/collections/api/find/server.ts:77

Result ordering. Equivalent to .order("asc" | "desc") on the Convex query. Defaults to "asc" (insertion order).

paginationOpts?

optional paginationOpts?: PaginationOptions

Defined in: packages/core/src/collections/api/find/server.ts:139

Pagination options. When provided, the function returns a PaginationResult with { page, continueCursor, isDone } instead of a plain array.

Uses Convex’s native .paginate(opts) API under the hood.

populate?

optional populate?: [D] extends [0] ? TPopulate : never

Defined in: packages/core/src/collections/api/types.ts:157

Recursive populate object, type-narrowed against RelationshipKeysOf<TCollectionSlug>. Mutually exclusive with depth — becomes never when D ≠ 0.

Inherited from

GenericQueryServerParams.populate

sort?

optional sort?: CollectionTableSort<AccessDocFieldFor<TCollectionSlug>>

Defined in: packages/core/src/collections/api/find/server.ts:131

Portable sort — { field, order }. The server resolves field to an index via resolveQueryIndex, which also pushes matching equalities from where into that index’s range when one is available (Design Decision 36) — callers never name an index directly (Design Decision 5). Mutually exclusive with withIndex — passing both throws a VexError.

The resolved index competes for the query’s one withIndex slot through the same pickConvexQueryIndex arbitration as withIndex (an access-constraint index wins a free slot; a same-named index merges ranges; a differently-named caller index displaces it and the access rule falls back to .filter()) — sort carries no precedence of its own over an access-contributed index.

Rejected with a VexAccessError when the caller cannot read sort.field (Design Decision 26) — sort order alone would leak the field’s values.

Example

find({ ctx, collection: "posts", sort: { field: "publishedAt", order: "desc" } })

where?

optional where?: VexWhere<TCollectionSlug>

Defined in: packages/core/src/collections/api/find/server.ts:92

Predicate over the collection’s fields, applied after index narrowing. Fields are referenced by name; combine with q.and / q.or / q.not.

Prefer withIndex for performance: on Convex, where scans every document in the narrowed range.

Example

find({ ctx, collection: "posts", where: (q) => q.eq("published", true) })
find({ ctx, collection: "posts", where: { field: "published", op: "eq", value: true } })

withIndex?

optional withIndex?: VexWithIndex<TCollectionSlug>

Defined in: packages/core/src/collections/api/find/server.ts:105

Index to read through, with an optional range over its fields in declaration order. Strongly preferred over where for performance.

Example

find({ ctx, collection: "posts", withIndex: { name: "by_slug", range: (q) => q.eq("slug", "hello") } })
find({ ctx, collection: "posts", withIndex: { name: "by_score", range: (q) => q.gte("score", 50) } })
find({ ctx, collection: "posts", withIndex: { name: "by_publishedAt" } })