QueryCollectionConfig

Defined in: packages/query-db-collection/src/query.ts:131

Configuration options for creating a Query Collection

Extends#

• Omit<BaseCollectionConfig<T, TKey, TSchema, QueryCollectionHandlerUtils<T, TKey, TSchema, TError>>, "onInsert" | "onUpdate" | "onDelete">

Type Parameters#

T#

T extends object = object

The explicit type of items stored in the collection

TQueryFn#

TQueryFn extends (context) => any = (context) => any

The queryFn type

TError#

TError = unknown

The type of errors that can occur during queries

TQueryKey#

TQueryKey extends QueryKey = QueryKey

The type of the query key

TKey#

TKey extends string | number = string | number

The type of the item keys

TSchema#

TSchema extends StandardSchemaV1 = never

The schema type for validation

TQueryData#

TQueryData = Awaited<ReturnType<TQueryFn>>

Properties#

enabled?#

optional enabled: Enabled<TQueryData, TError, TQueryData, TQueryKey>;

Defined in: packages/query-db-collection/src/query.ts:190

Whether the query should automatically run (default: true)

gcTime?#

optional gcTime: number;

Defined in: packages/query-db-collection/src/query.ts:225

Time in milliseconds after which the collection will be garbage collected when it has no active subscribers. Defaults to 5 minutes (300000ms). Sync started without subscribers gets a minimum 50ms handoff grace period until a subscriber attaches. After the last subscriber leaves, gcTime applies without that startup minimum. Pending preloads retain the collection until they settle. Preloading ready data refreshes the retention period. A persisting transaction that touches the collection also retains it, and the period starts again when the last one completes or fails, preserving any remaining startup grace. Pending manual transactions do not retain it; keep a subscription for draft visibility until commit or rollback. Rolling back a manual transaction that stayed pending preserves the existing GC deadline. Cleanup runs at a host idle opportunity after the delay. A non-positive or non-finite value disables automatic garbage collection.

Overrides#

Omit.gcTime

initialData?#

optional initialData: TQueryData | InitialDataFunction<TQueryData>;

Defined in: packages/query-db-collection/src/query.ts:265

Data used to initialize the TanStack Query cache for an eager collection. The value has the original Query response shape and is projected through the collection's select option before rows are materialized.

initialDataUpdatedAt?#

optional initialDataUpdatedAt: number | () => number | undefined;

Defined in: packages/query-db-collection/src/query.ts:273

The timestamp TanStack Query uses to determine initialData freshness.

meta?#

optional meta: Record<string, unknown>;

Defined in: packages/query-db-collection/src/query.ts:302

Metadata to pass to the query. Available in queryFn via context.meta

Example#

// Using meta for error context
queryFn: async (context) => {
  try {
    return await api.getTodos(userId)
  } catch (error) {
    // Use meta for better error messages
    throw new Error(
      context.meta?.errorMessage || 'Failed to load todos'
    )
  }
},
meta: {
  errorMessage: `Failed to load todos for user ${userId}`
}

networkMode?#

optional networkMode: NetworkMode;

Defined in: packages/query-db-collection/src/query.ts:253

onDelete()?#

optional onDelete: (params) => Promise<void>;

Defined in: packages/query-db-collection/src/query.ts:165

Parameters#

params#

DeleteMutationFnParams<T, TKey, QueryCollectionHandlerUtils<T, TKey, TSchema, TError>>

Returns#

Promise<void>

onInsert()?#

optional onInsert: (params) => Promise<void>;

Defined in: packages/query-db-collection/src/query.ts:151

Mutation handlers must await an explicit refetch or write confirmed data before settling.

Parameters#

params#

InsertMutationFnParams<T, TKey, QueryCollectionHandlerUtils<T, TKey, TSchema, TError>>

Returns#

Promise<void>

onUpdate()?#

optional onUpdate: (params) => Promise<void>;

Defined in: packages/query-db-collection/src/query.ts:158

Parameters#

params#

UpdateMutationFnParams<T, TKey, QueryCollectionHandlerUtils<T, TKey, TSchema, TError>>

Returns#

Promise<void>

persistedGcTime?#

optional persistedGcTime: number;

Defined in: packages/query-db-collection/src/query.ts:280

queryClient#

queryClient: QueryClient;

Defined in: packages/query-db-collection/src/query.ts:186

The TanStack Query client instance

queryFn#

queryFn: TQueryFn extends (context) => any[] | Promise<any[]> ? (context) => T[] | Promise<T[]> : TQueryFn;

Defined in: packages/query-db-collection/src/query.ts:175

Function that fetches data from the server. Must return the complete collection state

queryKey#

queryKey: TQueryKey | TQueryKeyBuilder<TQueryKey>;

Defined in: packages/query-db-collection/src/query.ts:173

The query key used by TanStack Query to identify this query

refetchInterval?#

optional refetchInterval: number | false | (query) => number | false | undefined;

Defined in: packages/query-db-collection/src/query.ts:197

refetchOnMount?#

optional refetchOnMount: boolean | "always" | (query) => boolean | "always";

Defined in: packages/query-db-collection/src/query.ts:246

refetchOnReconnect?#

optional refetchOnReconnect: boolean | "always" | (query) => boolean | "always";

Defined in: packages/query-db-collection/src/query.ts:239

refetchOnWindowFocus?#

optional refetchOnWindowFocus: boolean | "always" | (query) => boolean | "always";

Defined in: packages/query-db-collection/src/query.ts:232

retry?#

optional retry: RetryValue<TError>;

Defined in: packages/query-db-collection/src/query.ts:204

retryDelay?#

optional retryDelay: RetryDelayValue<TError>;

Defined in: packages/query-db-collection/src/query.ts:211

select()?#

optional select: (data) => T[];

Defined in: packages/query-db-collection/src/query.ts:184

Extracts the row array TanStack DB materializes from the Query response. The Query cache keeps the original response shape.

Parameters#

data#

TQueryData

Returns#

T[]

staleTime?#

optional staleTime: StaleTimeFunction<TQueryData, TError, TQueryData, TQueryKey>;

Defined in: packages/query-db-collection/src/query.ts:218