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

QueryCollectionConfig.md

294 lines6.6 KB

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