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

QueryCollectionConfig.md

268 lines5.8 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:95](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L95)
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:124](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L124)
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:159](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L159)
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### meta?
92​
93```ts
94optional meta: Record<string, unknown>;
95```
96​
97Defined in: [packages/query-db-collection/src/query.ts:216](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L216)
98​
99Metadata to pass to the query.
100Available in queryFn via context.meta
101​
102#### Example
103​
104```ts
105// Using meta for error context
106queryFn: async (context) => {
107 try {
108 return await api.getTodos(userId)
109 } catch (error) {
110 // Use meta for better error messages
111 throw new Error(
112 context.meta?.errorMessage || 'Failed to load todos'
113 )
114 }
115},
116meta: {
117 errorMessage: `Failed to load todos for user ${userId}`
119```
120​
121***
122​
123### networkMode?
124​
125```ts
126optional networkMode: NetworkMode;
127```
128​
129Defined in: [packages/query-db-collection/src/query.ts:187](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L187)
130​
131***
132​
133### persistedGcTime?
134​
135```ts
136optional persistedGcTime: number;
137```
138​
139Defined in: [packages/query-db-collection/src/query.ts:194](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L194)
140​
141***
142​
143### queryClient
144​
145```ts
146queryClient: QueryClient;
147```
148​
149Defined in: [packages/query-db-collection/src/query.ts:120](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L120)
150​
151The TanStack Query client instance
152​
153***
154​
155### queryFn
156​
157```ts
158queryFn: TQueryFn extends (context) => any[] | Promise<any[]> ? (context) => T[] | Promise<T[]> : TQueryFn;
159```
160​
161Defined in: [packages/query-db-collection/src/query.ts:109](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L109)
162​
163Function that fetches data from the server. Must return the complete collection state
164​
165***
166​
167### queryKey
168​
169```ts
170queryKey: TQueryKey | TQueryKeyBuilder<TQueryKey>;
171```
172​
173Defined in: [packages/query-db-collection/src/query.ts:107](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L107)
174​
175The query key used by TanStack Query to identify this query
176​
177***
178​
179### refetchInterval?
180​
181```ts
182optional refetchInterval: number | false | (query) => number | false | undefined;
183```
184​
185Defined in: [packages/query-db-collection/src/query.ts:131](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L131)
186​
187***
188​
189### refetchOnMount?
190​
191```ts
192optional refetchOnMount: boolean | "always" | (query) => boolean | "always";
193```
194​
195Defined in: [packages/query-db-collection/src/query.ts:180](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L180)
196​
197***
198​
199### refetchOnReconnect?
200​
201```ts
202optional refetchOnReconnect: boolean | "always" | (query) => boolean | "always";
203```
204​
205Defined in: [packages/query-db-collection/src/query.ts:173](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L173)
206​
207***
208​
209### refetchOnWindowFocus?
210​
211```ts
212optional refetchOnWindowFocus: boolean | "always" | (query) => boolean | "always";
213```
214​
215Defined in: [packages/query-db-collection/src/query.ts:166](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L166)
216​
217***
218​
219### retry?
220​
221```ts
222optional retry: RetryValue<TError>;
223```
224​
225Defined in: [packages/query-db-collection/src/query.ts:138](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L138)
226​
227***
228​
229### retryDelay?
230​
231```ts
232optional retryDelay: RetryDelayValue<TError>;
233```
234​
235Defined in: [packages/query-db-collection/src/query.ts:145](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L145)
236​
237***
238​
239### select()?
240​
241```ts
242optional select: (data) => T[];
243```
244​
245Defined in: [packages/query-db-collection/src/query.ts:118](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L118)
246​
247Extracts the row array TanStack DB materializes from the Query response.
248The Query cache keeps the original response shape.
249​
250#### Parameters
251​
252##### data
253​
254`TQueryData`
255​
256#### Returns
257​
258`T`[]
259​
260***
261​
262### staleTime?
263​
264```ts
265optional staleTime: StaleTimeFunction<TQueryData, TError, TQueryData, TQueryKey>;
266```
267​
268Defined in: [packages/query-db-collection/src/query.ts:152](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L152)