TanStack
DB v0v0
Docs
CodeRabbit
Cloudflare
AG Grid
SerpAPI
Netlify
OpenRouter
Neon
WorkOS
Clerk
Electric
PowerSync
Sentry
Railway
Prisma
Strapi
Unkey
CodeRabbit
Cloudflare
AG Grid
SerpAPI
Netlify
OpenRouter
Neon
WorkOS
Clerk
Electric
PowerSync
Sentry
Railway
Prisma
Strapi
Unkey
Menu
Getting Started
Guides
Collections
Frameworks
Community
API Reference

QueryCollectionConfig

Interface: QueryCollectionConfig<T, TQueryFn, TError, TQueryKey, TKey, TSchema, TQueryData>

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

Configuration options for creating a Query Collection

Extends

  • BaseCollectionConfig<T, TKey, TSchema>

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?

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

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

Whether the query should automatically run (default: true)

gcTime?

ts
optional gcTime: number;
optional gcTime: number;

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

Time in milliseconds after which the collection will be garbage collected when it has no active subscribers. Defaults to 5 minutes (300000ms).

Overrides

ts
BaseCollectionConfig.gcTime
BaseCollectionConfig.gcTime

meta?

ts
optional meta: Record<string, unknown>;
optional meta: Record<string, unknown>;

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

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

Example

ts
// 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}`
}
// 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?

ts
optional networkMode: NetworkMode;
optional networkMode: NetworkMode;

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

persistedGcTime?

ts
optional persistedGcTime: number;
optional persistedGcTime: number;

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

queryClient

ts
queryClient: QueryClient;
queryClient: QueryClient;

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

The TanStack Query client instance

queryFn

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

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

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

queryKey

ts
queryKey: TQueryKey | TQueryKeyBuilder<TQueryKey>;
queryKey: TQueryKey | TQueryKeyBuilder<TQueryKey>;

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

The query key used by TanStack Query to identify this query

refetchInterval?

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

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

refetchOnMount?

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

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

refetchOnReconnect?

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

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

refetchOnWindowFocus?

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

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

retry?

ts
optional retry: RetryValue<TError>;
optional retry: RetryValue<TError>;

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

retryDelay?

ts
optional retryDelay: RetryDelayValue<TError>;
optional retryDelay: RetryDelayValue<TError>;

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

select()?

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

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

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?

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

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

Edit on GitHub
Home
© 2026 TanStack LLC