Open History to see the last commit
1---
2id: QueryCollectionConfig
3title: QueryCollectionConfig
4---
5
6Defined in: [packages/query-db-collection/src/query.ts:107](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L107)
7
8Configuration options for creating a Query Collection
9
10## Extends
11
12- `BaseCollectionConfig`\<`T`, `TKey`, `TSchema`, [`QueryCollectionUtils`](QueryCollectionUtils.md)\<`T`, `TKey`, \[`TSchema`\] *extends* \[`never`\] ? `T` : `InferSchemaInput`\<`TSchema`\>, `TError`\>\>
13
14## Type Parameters
15
16### T
17
18`T` *extends* `object` = `object`
19
20The explicit type of items stored in the collection
21
22### TQueryFn
23
24`TQueryFn` *extends* (`context`) => `any` = (`context`) => `any`
25
26The queryFn type
27
28### TError
29
30`TError` = `unknown`
31
32The type of errors that can occur during queries
33
34### TQueryKey
35
36`TQueryKey` *extends* `QueryKey` = `QueryKey`
37
38The type of the query key
39
40### TKey
41
42`TKey` *extends* `string` \| `number` = `string` \| `number`
43
44The type of the item keys
45
46### TSchema
47
48`TSchema` *extends* `StandardSchemaV1` = `never`
49
50The schema type for validation
51
52### TQueryData
53
54`TQueryData` = `Awaited`\<`ReturnType`\<`TQueryFn`\>\>
55
56## Properties
57
58### enabled?
59
60```ts
61optional enabled: Enabled<TQueryData, TError, TQueryData, TQueryKey>;
62```
63
64Defined in: [packages/query-db-collection/src/query.ts:146](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L146)
65
66Whether the query should automatically run (default: true)
67
68***
69
70### gcTime?
71
72```ts
73optional gcTime: number;
74```
75
76Defined in: [packages/query-db-collection/src/query.ts:181](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L181)
77
78Time in milliseconds after which the collection will be garbage collected
79when it has no active subscribers. Defaults to 5 minutes (300000ms).
80Sync started without subscribers gets a minimum 50ms grace period.
81Pending preloads retain the collection until they settle. Preloading ready
82data refreshes the retention period. A non-positive or non-finite value
83disables automatic garbage collection.
84
85#### Overrides
86
87```ts
88BaseCollectionConfig.gcTime
89```
90
91***
92
93### initialData?
94
95```ts
96optional initialData: TQueryData | InitialDataFunction<TQueryData>;
97```
98
99Defined in: [packages/query-db-collection/src/query.ts:221](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L221)
100
101Data used to initialize the TanStack Query cache for an eager collection.
102The value has the original Query response shape and is projected through
103the collection's select option before rows are materialized.
104
105***
106
107### initialDataUpdatedAt?
108
109```ts
110optional initialDataUpdatedAt: number | () => number | undefined;
111```
112
113Defined in: [packages/query-db-collection/src/query.ts:229](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L229)
114
115The timestamp TanStack Query uses to determine initialData freshness.
116
117***
118
119### meta?
120
121```ts
122optional meta: Record<string, unknown>;
123```
124
125Defined in: [packages/query-db-collection/src/query.ts:258](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L258)
126
127Metadata to pass to the query.
128Available in queryFn via context.meta
129
130#### Example
131
132```ts
133// Using meta for error context
134queryFn: async (context) => {
135 try {
136 return await api.getTodos(userId)
137 } catch (error) {
138 // Use meta for better error messages
139 throw new Error(
140 context.meta?.errorMessage || 'Failed to load todos'
141 )
142 }
143},
144meta: {
145 errorMessage: `Failed to load todos for user ${userId}`
146}
147```
148
149***
150
151### networkMode?
152
153```ts
154optional networkMode: NetworkMode;
155```
156
157Defined in: [packages/query-db-collection/src/query.ts:209](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L209)
158
159***
160
161### persistedGcTime?
162
163```ts
164optional persistedGcTime: number;
165```
166
167Defined in: [packages/query-db-collection/src/query.ts:236](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L236)
168
169***
170
171### queryClient
172
173```ts
174queryClient: QueryClient;
175```
176
177Defined in: [packages/query-db-collection/src/query.ts:142](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L142)
178
179The TanStack Query client instance
180
181***
182
183### queryFn
184
185```ts
186queryFn: TQueryFn extends (context) => any[] | Promise<any[]> ? (context) => T[] | Promise<T[]> : TQueryFn;
187```
188
189Defined in: [packages/query-db-collection/src/query.ts:131](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L131)
190
191Function that fetches data from the server. Must return the complete collection state
192
193***
194
195### queryKey
196
197```ts
198queryKey: TQueryKey | TQueryKeyBuilder<TQueryKey>;
199```
200
201Defined in: [packages/query-db-collection/src/query.ts:129](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L129)
202
203The query key used by TanStack Query to identify this query
204
205***
206
207### refetchInterval?
208
209```ts
210optional refetchInterval: number | false | (query) => number | false | undefined;
211```
212
213Defined in: [packages/query-db-collection/src/query.ts:153](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L153)
214
215***
216
217### refetchOnMount?
218
219```ts
220optional refetchOnMount: boolean | "always" | (query) => boolean | "always";
221```
222
223Defined in: [packages/query-db-collection/src/query.ts:202](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L202)
224
225***
226
227### refetchOnReconnect?
228
229```ts
230optional refetchOnReconnect: boolean | "always" | (query) => boolean | "always";
231```
232
233Defined in: [packages/query-db-collection/src/query.ts:195](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L195)
234
235***
236
237### refetchOnWindowFocus?
238
239```ts
240optional refetchOnWindowFocus: boolean | "always" | (query) => boolean | "always";
241```
242
243Defined in: [packages/query-db-collection/src/query.ts:188](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L188)
244
245***
246
247### retry?
248
249```ts
250optional retry: RetryValue<TError>;
251```
252
253Defined in: [packages/query-db-collection/src/query.ts:160](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L160)
254
255***
256
257### retryDelay?
258
259```ts
260optional retryDelay: RetryDelayValue<TError>;
261```
262
263Defined in: [packages/query-db-collection/src/query.ts:167](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L167)
264
265***
266
267### select()?
268
269```ts
270optional select: (data) => T[];
271```
272
273Defined in: [packages/query-db-collection/src/query.ts:140](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L140)
274
275Extracts the row array TanStack DB materializes from the Query response.
276The Query cache keeps the original response shape.
277
278#### Parameters
279
280##### data
281
282`TQueryData`
283
284#### Returns
285
286`T`[]
287
288***
289
290### staleTime?
291
292```ts
293optional staleTime: StaleTimeFunction<TQueryData, TError, TQueryData, TQueryKey>;
294```
295
296Defined in: [packages/query-db-collection/src/query.ts:174](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L174)