Open History to see the last commit
1---
2id: queryCollectionOptions
3title: queryCollectionOptions
4---
5
6# Function: queryCollectionOptions()
7
8## Call Signature
9
10```ts
11function queryCollectionOptions<T, TQueryFn, TError, TQueryKey, TKey, TQueryData>(config): CollectionConfig<InferSchemaOutput<T>, TKey, T, QueryCollectionUtils<InferSchemaOutput<T>, TKey, InferSchemaInput<T>, TError>> & object;
12```
13
14Defined in: [packages/query-db-collection/src/query.ts:535](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L535)
15
16Creates query collection options for use with a standard Collection.
17This integrates TanStack Query with TanStack DB for automatic synchronization.
18
19Supports automatic type inference following the priority order:
201. Schema inference (highest priority)
212. QueryFn return type inference (second priority)
22
23### Type Parameters
24
25#### T
26
27`T` *extends* `StandardSchemaV1`\<`unknown`, `unknown`\>
28
29Type of the schema if a schema is provided otherwise it is the type of the values returned by the queryFn
30
31#### TQueryFn
32
33`TQueryFn` *extends* (`context`) => `any`
34
35#### TError
36
37`TError` = `unknown`
38
39The type of errors that can occur during queries
40
41#### TQueryKey
42
43`TQueryKey` *extends* readonly `unknown`[] = readonly `unknown`[]
44
45The type of the query key
46
47#### TKey
48
49`TKey` *extends* `string` \| `number` = `string` \| `number`
50
51The type of the item keys
52
53#### TQueryData
54
55`TQueryData` = `Awaited`\<`ReturnType`\<`TQueryFn`\>\>
56
57### Parameters
58
59#### config
60
61[`QueryCollectionConfig`](../interfaces/QueryCollectionConfig.md)\<`InferSchemaOutput`\<`T`\>, `TQueryFn`, `TError`, `TQueryKey`, `TKey`, `T`, `Awaited`\<`ReturnType`\<`TQueryFn`\>\>\> & `object`
62
63Configuration options for the Query collection
64
65### Returns
66
67`CollectionConfig`\<`InferSchemaOutput`\<`T`\>, `TKey`, `T`, [`QueryCollectionUtils`](../interfaces/QueryCollectionUtils.md)\<`InferSchemaOutput`\<`T`\>, `TKey`, `InferSchemaInput`\<`T`\>, `TError`\>\> & `object`
68
69Collection options with utilities for direct writes and manual operations
70
71### Examples
72
73```ts
74// Type inferred from queryFn return type (NEW!)
75const todosCollection = createCollection(
76 queryCollectionOptions({
77 queryKey: ['todos'],
78 queryFn: async () => {
79 const response = await fetch('/api/todos')
80 return response.json() as Todo[] // Type automatically inferred!
81 },
82 queryClient,
83 getKey: (item) => item.id, // item is typed as Todo
84 })
85)
86```
87
88```ts
89// Explicit type
90const todosCollection = createCollection<Todo>(
91 queryCollectionOptions({
92 queryKey: ['todos'],
93 queryFn: async () => fetch('/api/todos').then(r => r.json()),
94 queryClient,
95 getKey: (item) => item.id,
96 })
97)
98```
99
100```ts
101// Schema inference
102const todosCollection = createCollection(
103 queryCollectionOptions({
104 queryKey: ['todos'],
105 queryFn: async () => fetch('/api/todos').then(r => r.json()),
106 queryClient,
107 schema: todoSchema, // Type inferred from schema
108 getKey: (item) => item.id,
109 })
110)
111```
112
113```ts
114// With persistence handlers
115const todosCollection = createCollection(
116 queryCollectionOptions({
117 queryKey: ['todos'],
118 queryFn: fetchTodos,
119 queryClient,
120 getKey: (item) => item.id,
121 onInsert: async ({ transaction }) => {
122 await api.createTodos(transaction.mutations.map(m => m.modified))
123 },
124 onUpdate: async ({ transaction }) => {
125 await api.updateTodos(transaction.mutations)
126 },
127 onDelete: async ({ transaction }) => {
128 await api.deleteTodos(transaction.mutations.map(m => m.key))
129 }
130 })
131)
132```
133
134```ts
135// The select option extracts the items array from a response with metadata
136const todosCollection = createCollection(
137 queryCollectionOptions({
138 queryKey: ['todos'],
139 queryFn: async () => fetch('/api/todos').then(r => r.json()),
140 select: (data) => data.items, // Extract the array of items
141 queryClient,
142 schema: todoSchema,
143 getKey: (item) => item.id,
144 })
145)
146```
147
148## Call Signature
149
150```ts
151function queryCollectionOptions<T, TQueryFn, TError, TQueryKey, TKey, TQueryData>(config): CollectionConfig<T, TKey, never, QueryCollectionUtils<T, TKey, T, TError>> & object;
152```
153
154Defined in: [packages/query-db-collection/src/query.ts:570](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L570)
155
156Creates query collection options for use with a standard Collection.
157This integrates TanStack Query with TanStack DB for automatic synchronization.
158
159Supports automatic type inference following the priority order:
1601. Schema inference (highest priority)
1612. QueryFn return type inference (second priority)
162
163### Type Parameters
164
165#### T
166
167`T` *extends* `object`
168
169Type of the schema if a schema is provided otherwise it is the type of the values returned by the queryFn
170
171#### TQueryFn
172
173`TQueryFn` *extends* (`context`) => `any` = (`context`) => `any`
174
175#### TError
176
177`TError` = `unknown`
178
179The type of errors that can occur during queries
180
181#### TQueryKey
182
183`TQueryKey` *extends* readonly `unknown`[] = readonly `unknown`[]
184
185The type of the query key
186
187#### TKey
188
189`TKey` *extends* `string` \| `number` = `string` \| `number`
190
191The type of the item keys
192
193#### TQueryData
194
195`TQueryData` = `Awaited`\<`ReturnType`\<`TQueryFn`\>\>
196
197### Parameters
198
199#### config
200
201[`QueryCollectionConfig`](../interfaces/QueryCollectionConfig.md)\<`T`, `TQueryFn`, `TError`, `TQueryKey`, `TKey`, `never`, `TQueryData`\> & `object`
202
203Configuration options for the Query collection
204
205### Returns
206
207`CollectionConfig`\<`T`, `TKey`, `never`, [`QueryCollectionUtils`](../interfaces/QueryCollectionUtils.md)\<`T`, `TKey`, `T`, `TError`\>\> & `object`
208
209Collection options with utilities for direct writes and manual operations
210
211### Examples
212
213```ts
214// Type inferred from queryFn return type (NEW!)
215const todosCollection = createCollection(
216 queryCollectionOptions({
217 queryKey: ['todos'],
218 queryFn: async () => {
219 const response = await fetch('/api/todos')
220 return response.json() as Todo[] // Type automatically inferred!
221 },
222 queryClient,
223 getKey: (item) => item.id, // item is typed as Todo
224 })
225)
226```
227
228```ts
229// Explicit type
230const todosCollection = createCollection<Todo>(
231 queryCollectionOptions({
232 queryKey: ['todos'],
233 queryFn: async () => fetch('/api/todos').then(r => r.json()),
234 queryClient,
235 getKey: (item) => item.id,
236 })
237)
238```
239
240```ts
241// Schema inference
242const todosCollection = createCollection(
243 queryCollectionOptions({
244 queryKey: ['todos'],
245 queryFn: async () => fetch('/api/todos').then(r => r.json()),
246 queryClient,
247 schema: todoSchema, // Type inferred from schema
248 getKey: (item) => item.id,
249 })
250)
251```
252
253```ts
254// With persistence handlers
255const todosCollection = createCollection(
256 queryCollectionOptions({
257 queryKey: ['todos'],
258 queryFn: fetchTodos,
259 queryClient,
260 getKey: (item) => item.id,
261 onInsert: async ({ transaction }) => {
262 await api.createTodos(transaction.mutations.map(m => m.modified))
263 },
264 onUpdate: async ({ transaction }) => {
265 await api.updateTodos(transaction.mutations)
266 },
267 onDelete: async ({ transaction }) => {
268 await api.deleteTodos(transaction.mutations.map(m => m.key))
269 }
270 })
271)
272```
273
274```ts
275// The select option extracts the items array from a response with metadata
276const todosCollection = createCollection(
277 queryCollectionOptions({
278 queryKey: ['todos'],
279 queryFn: async () => fetch('/api/todos').then(r => r.json()),
280 select: (data) => data.items, // Extract the array of items
281 queryClient,
282 schema: todoSchema,
283 getKey: (item) => item.id,
284 })
285)
286```
287
288## Call Signature
289
290```ts
291function queryCollectionOptions<T, TError, TQueryKey, TKey>(config): CollectionConfig<InferSchemaOutput<T>, TKey, T, QueryCollectionUtils<InferSchemaOutput<T>, TKey, InferSchemaInput<T>, TError>> & object;
292```
293
294Defined in: [packages/query-db-collection/src/query.ts:603](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L603)
295
296Creates query collection options for use with a standard Collection.
297This integrates TanStack Query with TanStack DB for automatic synchronization.
298
299Supports automatic type inference following the priority order:
3001. Schema inference (highest priority)
3012. QueryFn return type inference (second priority)
302
303### Type Parameters
304
305#### T
306
307`T` *extends* `StandardSchemaV1`\<`unknown`, `unknown`\>
308
309Type of the schema if a schema is provided otherwise it is the type of the values returned by the queryFn
310
311#### TError
312
313`TError` = `unknown`
314
315The type of errors that can occur during queries
316
317#### TQueryKey
318
319`TQueryKey` *extends* readonly `unknown`[] = readonly `unknown`[]
320
321The type of the query key
322
323#### TKey
324
325`TKey` *extends* `string` \| `number` = `string` \| `number`
326
327The type of the item keys
328
329### Parameters
330
331#### config
332
333[`QueryCollectionConfig`](../interfaces/QueryCollectionConfig.md)\<`InferSchemaOutput`\<`T`\>, (`context`) => `InferSchemaOutput`\<`T`\>[] \| `Promise`\<`InferSchemaOutput`\<`T`\>[]\>, `TError`, `TQueryKey`, `TKey`, `T`, `InferSchemaOutput`\<`T`\>[]\> & `object`
334
335Configuration options for the Query collection
336
337### Returns
338
339`CollectionConfig`\<`InferSchemaOutput`\<`T`\>, `TKey`, `T`, [`QueryCollectionUtils`](../interfaces/QueryCollectionUtils.md)\<`InferSchemaOutput`\<`T`\>, `TKey`, `InferSchemaInput`\<`T`\>, `TError`\>\> & `object`
340
341Collection options with utilities for direct writes and manual operations
342
343### Examples
344
345```ts
346// Type inferred from queryFn return type (NEW!)
347const todosCollection = createCollection(
348 queryCollectionOptions({
349 queryKey: ['todos'],
350 queryFn: async () => {
351 const response = await fetch('/api/todos')
352 return response.json() as Todo[] // Type automatically inferred!
353 },
354 queryClient,
355 getKey: (item) => item.id, // item is typed as Todo
356 })
357)
358```
359
360```ts
361// Explicit type
362const todosCollection = createCollection<Todo>(
363 queryCollectionOptions({
364 queryKey: ['todos'],
365 queryFn: async () => fetch('/api/todos').then(r => r.json()),
366 queryClient,
367 getKey: (item) => item.id,
368 })
369)
370```
371
372```ts
373// Schema inference
374const todosCollection = createCollection(
375 queryCollectionOptions({
376 queryKey: ['todos'],
377 queryFn: async () => fetch('/api/todos').then(r => r.json()),
378 queryClient,
379 schema: todoSchema, // Type inferred from schema
380 getKey: (item) => item.id,
381 })
382)
383```
384
385```ts
386// With persistence handlers
387const todosCollection = createCollection(
388 queryCollectionOptions({
389 queryKey: ['todos'],
390 queryFn: fetchTodos,
391 queryClient,
392 getKey: (item) => item.id,
393 onInsert: async ({ transaction }) => {
394 await api.createTodos(transaction.mutations.map(m => m.modified))
395 },
396 onUpdate: async ({ transaction }) => {
397 await api.updateTodos(transaction.mutations)
398 },
399 onDelete: async ({ transaction }) => {
400 await api.deleteTodos(transaction.mutations.map(m => m.key))
401 }
402 })
403)
404```
405
406```ts
407// The select option extracts the items array from a response with metadata
408const todosCollection = createCollection(
409 queryCollectionOptions({
410 queryKey: ['todos'],
411 queryFn: async () => fetch('/api/todos').then(r => r.json()),
412 select: (data) => data.items, // Extract the array of items
413 queryClient,
414 schema: todoSchema,
415 getKey: (item) => item.id,
416 })
417)
418```
419
420## Call Signature
421
422```ts
423function queryCollectionOptions<T, TError, TQueryKey, TKey>(config): CollectionConfig<T, TKey, never, QueryCollectionUtils<T, TKey, T, TError>> & object;
424```
425
426Defined in: [packages/query-db-collection/src/query.ts:637](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L637)
427
428Creates query collection options for use with a standard Collection.
429This integrates TanStack Query with TanStack DB for automatic synchronization.
430
431Supports automatic type inference following the priority order:
4321. Schema inference (highest priority)
4332. QueryFn return type inference (second priority)
434
435### Type Parameters
436
437#### T
438
439`T` *extends* `object`
440
441Type of the schema if a schema is provided otherwise it is the type of the values returned by the queryFn
442
443#### TError
444
445`TError` = `unknown`
446
447The type of errors that can occur during queries
448
449#### TQueryKey
450
451`TQueryKey` *extends* readonly `unknown`[] = readonly `unknown`[]
452
453The type of the query key
454
455#### TKey
456
457`TKey` *extends* `string` \| `number` = `string` \| `number`
458
459The type of the item keys
460
461### Parameters
462
463#### config
464
465[`QueryCollectionConfig`](../interfaces/QueryCollectionConfig.md)\<`T`, (`context`) => `T`[] \| `Promise`\<`T`[]\>, `TError`, `TQueryKey`, `TKey`, `never`, `T`[]\> & `object`
466
467Configuration options for the Query collection
468
469### Returns
470
471`CollectionConfig`\<`T`, `TKey`, `never`, [`QueryCollectionUtils`](../interfaces/QueryCollectionUtils.md)\<`T`, `TKey`, `T`, `TError`\>\> & `object`
472
473Collection options with utilities for direct writes and manual operations
474
475### Examples
476
477```ts
478// Type inferred from queryFn return type (NEW!)
479const todosCollection = createCollection(
480 queryCollectionOptions({
481 queryKey: ['todos'],
482 queryFn: async () => {
483 const response = await fetch('/api/todos')
484 return response.json() as Todo[] // Type automatically inferred!
485 },
486 queryClient,
487 getKey: (item) => item.id, // item is typed as Todo
488 })
489)
490```
491
492```ts
493// Explicit type
494const todosCollection = createCollection<Todo>(
495 queryCollectionOptions({
496 queryKey: ['todos'],
497 queryFn: async () => fetch('/api/todos').then(r => r.json()),
498 queryClient,
499 getKey: (item) => item.id,
500 })
501)
502```
503
504```ts
505// Schema inference
506const todosCollection = createCollection(
507 queryCollectionOptions({
508 queryKey: ['todos'],
509 queryFn: async () => fetch('/api/todos').then(r => r.json()),
510 queryClient,
511 schema: todoSchema, // Type inferred from schema
512 getKey: (item) => item.id,
513 })
514)
515```
516
517```ts
518// With persistence handlers
519const todosCollection = createCollection(
520 queryCollectionOptions({
521 queryKey: ['todos'],
522 queryFn: fetchTodos,
523 queryClient,
524 getKey: (item) => item.id,
525 onInsert: async ({ transaction }) => {
526 await api.createTodos(transaction.mutations.map(m => m.modified))
527 },
528 onUpdate: async ({ transaction }) => {
529 await api.updateTodos(transaction.mutations)
530 },
531 onDelete: async ({ transaction }) => {
532 await api.deleteTodos(transaction.mutations.map(m => m.key))
533 }
534 })
535)
536```
537
538```ts
539// The select option extracts the items array from a response with metadata
540const todosCollection = createCollection(
541 queryCollectionOptions({
542 queryKey: ['todos'],
543 queryFn: async () => fetch('/api/todos').then(r => r.json()),
544 select: (data) => data.items, // Extract the array of items
545 queryClient,
546 schema: todoSchema,
547 getKey: (item) => item.id,
548 })
549)
550```