Source: https://tanstack.com/db/latest/docs/reference/query-db-collection/interfaces/QueryCollectionUtils

TanStack

DB v0v0

Search...

+ K

Auto

Log In

TanStack StartRC

Docs Examples GitHub Contributors

TanStack Router

Docs Examples GitHub Contributors

TanStack Query

Docs Examples GitHub Contributors

TanStack Table

Docs Examples Github Contributors

TanStack Formnew

Docs Examples Github Contributors

TanStack DBbeta

Docs Github Contributors

TanStack Virtual

Docs Examples Github Contributors

TanStack Paceralpha

Docs Examples Github Contributors

TanStack Storealpha

Docs Examples Github Contributors

TanStack Devtoolsalpha

Docs Github Contributors

More Libraries

Maintainers Partners Support Learn StatsBETA Discord Merch Blog GitHub Ethos Brand Guide

Documentation

Framework

React

Version

Latest

Search...

+ K

Menu

• Home

• Frameworks

• Contributors

• GitHub

• Discord

Getting Started

• Overview
  
  core

• Quick Start
  
  core

• Installation
  
  core

Guides

• Live Queries
  
  core

• Mutations
  
  core

• Schemas
  
  core

• Error Handling
  
  core

• Creating Collection Options Creators
  
  core

Collections

• Query Collection
  
  core

• Electric Collection
  
  core

• TrailBase Collection
  
  core

• RxDB Collection
  
  core

• PowerSync Collection
  
  core

• LocalStorage Collection
  
  core

• LocalOnly Collection
  
  core

Frameworks

• React
  
  core

• Vue
  
  core

• Angular
  
  core

• Solid
  
  core

• Svelte
  
  core

Community

• Resources & Packages
  
  core

API Reference

• Core API Reference
  
  core

• Collection
  
  core

• createCollection
  
  core

• liveQueryCollectionOptions
  
  core

• createLiveQueryCollection
  
  core

• createOptimisticAction
  
  core

• createTransaction
  
  core

• Electric DB Collection
  
  core

• electricCollectionOptions
  
  core

• Query DB Collection
  
  core

• queryCollectionOptions
  
  core

• RxDB DB Collection
  
  core

• rxdbCollectionOptions
  
  core

• PowerSync Collection
  
  core

• powerSyncCollectionOptions
  
  core

• React Hooks
  
  react

• useLiveQuery
  
  react

Framework

React

Version

Latest

Menu

• Home

• Frameworks

• Contributors

• GitHub

• Discord

Getting Started

• Overview
  
  core

• Quick Start
  
  core

• Installation
  
  core

Guides

• Live Queries
  
  core

• Mutations
  
  core

• Schemas
  
  core

• Error Handling
  
  core

• Creating Collection Options Creators
  
  core

Collections

• Query Collection
  
  core

• Electric Collection
  
  core

• TrailBase Collection
  
  core

• RxDB Collection
  
  core

• PowerSync Collection
  
  core

• LocalStorage Collection
  
  core

• LocalOnly Collection
  
  core

Frameworks

• React
  
  core

• Vue
  
  core

• Angular
  
  core

• Solid
  
  core

• Svelte
  
  core

Community

• Resources & Packages
  
  core

API Reference

• Core API Reference
  
  core

• Collection
  
  core

• createCollection
  
  core

• liveQueryCollectionOptions
  
  core

• createLiveQueryCollection
  
  core

• createOptimisticAction
  
  core

• createTransaction
  
  core

• Electric DB Collection
  
  core

• electricCollectionOptions
  
  core

• Query DB Collection
  
  core

• queryCollectionOptions
  
  core

• RxDB DB Collection
  
  core

• rxdbCollectionOptions
  
  core

• PowerSync Collection
  
  core

• powerSyncCollectionOptions
  
  core

• React Hooks
  
  react

• useLiveQuery
  
  react

On this page

• Interface: QueryCollectionUtils<TItem, TKey, TInsertInput, TError>

• Extends

• Type Parameters

• TItem

• TKey

• TInsertInput

• TError

• Indexable

• Properties

• clearError()

• Returns

• Throws

• dataUpdatedAt

• errorCount

• fetchStatus

• isError

• isFetching

• isLoading

• isRefetching

• lastError

• refetch

• writeBatch()

• Parameters

• callback

• Returns

• writeDelete()

• Parameters

• keys

• Returns

• writeInsert()

• Parameters

• data

• Returns

• writeUpdate()

• Parameters

• updates

• Returns

• writeUpsert()

• Parameters

• data

• Returns

QueryCollectionUtils

Copy Markdown

Interface: QueryCollectionUtils<TItem, TKey, TInsertInput, TError>
==================================================================

Defined in: packages/query-db-collection/src/query.ts:154

Utility methods available on Query Collections for direct writes and manual operations. Direct writes bypass the normal query/mutation flow and write directly to the synced data store.

Extends
-------

• UtilsRecord

Type Parameters
--------------- ### TItem

TItem extends object = Record<string, unknown>

The type of items stored in the collection

### TKey

TKey extends string | number = string | number

The type of the item keys

### TInsertInput

TInsertInput extends object = TItem

The type accepted for insert operations

### TError

TError = unknown

The type of errors that can occur during queries

Indexable
---------

ts

[key: string]: any


[key: string]: any

Properties
---------- ### clearError()

ts

clearError: () => Promise<void>;


clearError: () => Promise<void>;

Defined in: packages/query-db-collection/src/query.ts:199

Clear the error state and trigger a refetch of the query

#### Returns

Promise<void>

Promise that resolves when the refetch completes successfully

#### Throws

Error if the refetch fails

---

### dataUpdatedAt

ts

dataUpdatedAt: number;


dataUpdatedAt: number;

Defined in: packages/query-db-collection/src/query.ts:190

Get timestamp of last successful data update (in milliseconds)

---

### errorCount

ts

errorCount: number;


errorCount: number;

Defined in: packages/query-db-collection/src/query.ts:182

Get the number of consecutive sync failures. Incremented only when query fails completely (not per retry attempt); reset on success.

---

### fetchStatus

ts

fetchStatus: "idle" | "fetching" | "paused";


fetchStatus: "idle" | "fetching" | "paused";

Defined in: packages/query-db-collection/src/query.ts:192

Get current fetch status

---

### isError

ts

isError: boolean;


isError: boolean;

Defined in: packages/query-db-collection/src/query.ts:177

Check if the collection is in an error state

---

### isFetching

ts

isFetching: boolean;


isFetching: boolean;

Defined in: packages/query-db-collection/src/query.ts:184

Check if query is currently fetching (initial or background)

---

### isLoading

ts

isLoading: boolean;


isLoading: boolean;

Defined in: packages/query-db-collection/src/query.ts:188

Check if query is loading for the first time (no data yet)

---

### isRefetching

ts

isRefetching: boolean;


isRefetching: boolean;

Defined in: packages/query-db-collection/src/query.ts:186

Check if query is refetching in background (not initial fetch)

---

### lastError

ts

lastError: TError | undefined;


lastError: TError | undefined;

Defined in: packages/query-db-collection/src/query.ts:175

Get the last error encountered by the query (if any); reset on success

---

### refetch

ts

refetch: RefetchFn;


refetch: RefetchFn;

Defined in: packages/query-db-collection/src/query.ts:161

Manually trigger a refetch of the query

---

### writeBatch()

ts

writeBatch: (callback) => void;


writeBatch: (callback) => void;

Defined in: packages/query-db-collection/src/query.ts:171

Execute multiple write operations as a single atomic batch to the synced data store

#### Parameters ##### callback

() => void

#### Returns

void

---

### writeDelete()

ts

writeDelete: (keys) => void;


writeDelete: (keys) => void;

Defined in: packages/query-db-collection/src/query.ts:167

Delete one or more items directly from the synced data store without triggering a query refetch or optimistic update

#### Parameters ##### keys

TKey | TKey[]

#### Returns

void

---

### writeInsert()

ts

writeInsert: (data) => void;


writeInsert: (data) => void;

Defined in: packages/query-db-collection/src/query.ts:163

Insert one or more items directly into the synced data store without triggering a query refetch or optimistic update

#### Parameters ##### data

TInsertInput | TInsertInput[]

#### Returns

void

---

### writeUpdate()

ts

writeUpdate: (updates) => void;


writeUpdate: (updates) => void;

Defined in: packages/query-db-collection/src/query.ts:165

Update one or more items directly in the synced data store without triggering a query refetch or optimistic update

#### Parameters ##### updates

Partial<TItem> | Partial<TItem>[]

#### Returns

void

---

### writeUpsert()

ts

writeUpsert: (data) => void;


writeUpsert: (data) => void;

Defined in: packages/query-db-collection/src/query.ts:169

Insert or update one or more items directly in the synced data store without triggering a query refetch or optimistic update

#### Parameters ##### data

Partial<TItem> | Partial<TItem>[]

#### Returns

void

Edit on GitHub

Home

Partners Become a Partner