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

QueryCollectionUtils.md

288 lines5.7 KB

1---
2id: QueryCollectionUtils
3title: QueryCollectionUtils
4---
5​
6# Interface: QueryCollectionUtils\<TItem, TKey, TInsertInput, TError\>
7​
8Defined in: [packages/query-db-collection/src/query.ts:260](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L260)
9​
10Utility methods available on Query Collections for direct writes and manual operations.
11Direct writes bypass the normal query/mutation flow and write directly to the synced data store.
12​
13## Extends
14​
15- `UtilsRecord`
16​
17## Type Parameters
18​
19### TItem
20​
21`TItem` *extends* `object` = `Record`\<`string`, `unknown`\>
22​
23The type of items stored in the collection
24​
25### TKey
26​
27`TKey` *extends* `string` \| `number` = `string` \| `number`
28​
29The type of the item keys
30​
31### TInsertInput
32​
33`TInsertInput` *extends* `object` = `TItem`
34​
35The type accepted for insert operations
36​
37### TError
38​
39`TError` = `unknown`
40​
41The type of errors that can occur during queries
42​
43## Indexable
44​
45```ts
46[key: string]: any
47```
48​
49## Properties
50​
51### clearError()
52​
53```ts
54clearError: () => Promise<void>;
55```
56​
57Defined in: [packages/query-db-collection/src/query.ts:305](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L305)
58​
59Clear the error state and trigger a refetch of the query
60​
61#### Returns
62​
63`Promise`\<`void`\>
64​
65Promise that resolves when the refetch completes successfully
66​
67#### Throws
68​
69Error if the refetch fails
70​
71***
72​
73### dataUpdatedAt
74​
75```ts
76dataUpdatedAt: number;
77```
78​
79Defined in: [packages/query-db-collection/src/query.ts:296](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L296)
80​
81Get timestamp of last successful data update (in milliseconds)
82​
83***
84​
85### errorCount
86​
87```ts
88errorCount: number;
89```
90​
91Defined in: [packages/query-db-collection/src/query.ts:288](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L288)
92​
93Get the number of consecutive sync failures.
94Incremented only when query fails completely (not per retry attempt); reset on success.
95​
96***
97​
98### fetchStatus
99​
100```ts
101fetchStatus: "idle" | "fetching" | "paused";
102```
103​
104Defined in: [packages/query-db-collection/src/query.ts:298](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L298)
105​
106Get current fetch status
107​
108***
109​
110### isError
111​
112```ts
113isError: boolean;
114```
115​
116Defined in: [packages/query-db-collection/src/query.ts:283](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L283)
117​
118Check if the collection is in an error state
119​
120***
121​
122### isFetching
123​
124```ts
125isFetching: boolean;
126```
127​
128Defined in: [packages/query-db-collection/src/query.ts:290](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L290)
129​
130Check if query is currently fetching (initial or background)
131​
132***
133​
134### isLoading
135​
136```ts
137isLoading: boolean;
138```
139​
140Defined in: [packages/query-db-collection/src/query.ts:294](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L294)
141​
142Check if query is loading for the first time (no data yet)
143​
144***
145​
146### isRefetching
147​
148```ts
149isRefetching: boolean;
150```
151​
152Defined in: [packages/query-db-collection/src/query.ts:292](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L292)
153​
154Check if query is refetching in background (not initial fetch)
155​
156***
157​
158### lastError
159​
160```ts
161lastError: TError | undefined;
162```
163​
164Defined in: [packages/query-db-collection/src/query.ts:281](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L281)
165​
166Get the last error encountered by the query (if any); reset on success
167​
168***
169​
170### refetch
171​
172```ts
173refetch: RefetchFn;
174```
175​
176Defined in: [packages/query-db-collection/src/query.ts:267](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L267)
177​
178Manually trigger a refetch of the query
179​
180***
181​
182### writeBatch()
183​
184```ts
185writeBatch: (callback) => void;
186```
187​
188Defined in: [packages/query-db-collection/src/query.ts:277](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L277)
189​
190Execute multiple write operations as a single atomic batch to the synced data store
191​
192#### Parameters
193​
194##### callback
195​
196() => `void`
197​
198#### Returns
199​
200`void`
201​
202***
203​
204### writeDelete()
205​
206```ts
207writeDelete: (keys) => void;
208```
209​
210Defined in: [packages/query-db-collection/src/query.ts:273](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L273)
211​
212Delete one or more items directly from the synced data store without triggering a query refetch or optimistic update
213​
214#### Parameters
215​
216##### keys
217​
218`TKey` | `TKey`[]
219​
220#### Returns
221​
222`void`
223​
224***
225​
226### writeInsert()
227​
228```ts
229writeInsert: (data) => void;
230```
231​
232Defined in: [packages/query-db-collection/src/query.ts:269](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L269)
233​
234Insert one or more items directly into the synced data store without triggering a query refetch or optimistic update
235​
236#### Parameters
237​
238##### data
239​
240`TInsertInput` | `TInsertInput`[]
241​
242#### Returns
243​
244`void`
245​
246***
247​
248### writeUpdate()
249​
250```ts
251writeUpdate: (updates) => void;
252```
253​
254Defined in: [packages/query-db-collection/src/query.ts:271](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L271)
255​
256Update one or more items directly in the synced data store without triggering a query refetch or optimistic update
257​
258#### Parameters
259​
260##### updates
261​
262`Partial`\<`TItem`\> | `Partial`\<`TItem`\>[]
263​
264#### Returns
265​
266`void`
267​
268***
269​
270### writeUpsert()
271​
272```ts
273writeUpsert: (data) => void;
274```
275​
276Defined in: [packages/query-db-collection/src/query.ts:275](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L275)
277​
278Insert or update one or more items directly in the synced data store without triggering a query refetch or optimistic update
279​
280#### Parameters
281​
282##### data
283​
284`Partial`\<`TItem`\> | `Partial`\<`TItem`\>[]
285​
286#### Returns
287​
288`void`