FindServerArgs

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

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/api/types.ts:216

Per-call access overrides.

See

AccessCallOptions

Inherited from

GenericQueryServerParams.access

---

auth?

optional auth?: VexApiAuth

Defined in: packages/core/src/api/types.ts:223

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/api/find/server.ts:56

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/api/types.ts:241

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/api/types.ts:225

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/api/types.ts:236

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

---

filter?

optional filter?: (q) => ExpressionOrValue<boolean>

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

Filter predicate applied after index narrowing. Equivalent to .filter(q => q.eq(q.field("published"), true)) on the Convex query.

Prefer withIndex for performance — filter scans every document in the range and is O(n). Use filter for secondary conditions that can’t be expressed as index equality ranges.

Parameters

q

FilterBuilder<NamedTableInfo<DataModel, TCollectionSlug extends TableNamesInDataModel<DataModel> ? TCollectionSlug : never>>

Returns

ExpressionOrValue<boolean>

Example

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

---

limit?

optional limit?: number

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

Maximum number of documents to return. Defaults to 100. Applied as the terminal .take(n) on the Convex query.

---

order?

optional order?: "asc" | "desc"

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

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/api/find/server.ts:127

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/api/types.ts:230

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

Inherited from

GenericQueryServerParams.populate

---

withIndex?

optional withIndex?: TCollectionSlug extends TableNamesInDataModel<DataModel> ? object : never

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

Index to use for the query, with an optional equality/range constraint. Equivalent to .withIndex(name, range?) on the Convex query.

Using an index is strongly preferred over filter 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" } })