Skip to content
Source
Sign inSign up
TanStack/db
Open History to see the last commit

QueryCollectionConfig.md

296 lines6.9 KB

1---
2id: QueryCollectionConfig
3title: QueryCollectionConfig
4---
5​
6Defined in: [packages/query-db-collection/src/query.ts:108](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L108)
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:147](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L147)
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:182](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L182)
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:222](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L222)
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:230](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L230)
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:259](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L259)
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}`
147```
148​
149***
150​
151### networkMode?
152​
153```ts
154optional networkMode: NetworkMode;
155```
156​
157Defined in: [packages/query-db-collection/src/query.ts:210](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L210)
158​
159***
160​
161### persistedGcTime?
162​
163```ts
164optional persistedGcTime: number;
165```
166​
167Defined in: [packages/query-db-collection/src/query.ts:237](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L237)
168​
169***
170​
171### queryClient
172​
173```ts
174queryClient: QueryClient;
175```
176​
177Defined in: [packages/query-db-collection/src/query.ts:143](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L143)
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:132](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L132)
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:130](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L130)
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:154](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L154)
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:203](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L203)
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:196](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L196)
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:189](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L189)
244​
245***
246​
247### retry?
248​
249```ts
250optional retry: RetryValue<TError>;
251```
252​
253Defined in: [packages/query-db-collection/src/query.ts:161](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L161)
254​
255***
256​
257### retryDelay?
258​
259```ts
260optional retryDelay: RetryDelayValue<TError>;
261```
262​
263Defined in: [packages/query-db-collection/src/query.ts:168](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L168)
264​
265***
266​
267### select()?
268​
269```ts
270optional select: (data) => T[];
271```
272​
273Defined in: [packages/query-db-collection/src/query.ts:141](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L141)
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:175](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L175)