Open History to see the last commit
1---
2id: QueryCollectionUtils
3title: QueryCollectionUtils
4---
5
6# Interface: QueryCollectionUtils\<TItem, TKey, TInsertInput, TError\>
7
8Defined in: [packages/query-db-collection/src/query.ts:170](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L170)
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:215](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L215)
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:206](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L206)
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:198](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L198)
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:208](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L208)
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:193](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L193)
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:200](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L200)
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:204](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L204)
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:202](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L202)
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:191](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L191)
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:177](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L177)
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:187](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L187)
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:183](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L183)
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:179](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L179)
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:181](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L181)
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:185](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L185)
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`