pickQueryIndex

pickQueryIndex(props): QueryIndex | undefined

Defined in: packages/core/src/access/pickQueryIndex.ts:106

Chooses the single index a query will use, arbitrating between an access-contributed index and whatever the caller explicitly requested. Convex permits exactly one withIndex per query, so exactly one wins.

1. Caller’s index wins the slot when it names a DIFFERENT index — usually a highly selective lookup; the access filter still enforces the rule per document (hasPermission), so this only ever costs reads, never correctness.
2. Same name ⇒ ranges merge, so the compound constraint (access’s prefix AND the caller’s continuation) is served by one query, no degradation.
3. Free slot (no caller index) ⇒ the access index claims it — the common list-view case, where the view passes no index of its own.

Never authorizes: whichever index wins, the access rule’s filter runs per document. Arbitration decides how many rows get read, not which are allowed.

Parameters

props

Input props.

accessIndex?

QueryIndex

resolveAccessIndex’s result for this query, if any.

callerIndex?

{ name: string; range?: IndexRangeFn; }

The index the caller explicitly requested, if any. Its range is optional, mirroring find’s withIndex arg — a caller may name an index purely to order results.

callerIndex.name

string

callerIndex.range?

IndexRangeFn

Returns

QueryIndex | undefined

The index to apply, or undefined when neither side supplies one (an un-narrowed scan, today’s behavior).

Example

pickQueryIndex({
  accessIndex: { name: "by_author", range: (q) => q.eq("authorId", "u1") },
});
// → { name: "by_author", range: … }  (free slot)