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

useLiveQuery.md

411 lines9.4 KB

1---
2id: useLiveQuery
3title: useLiveQuery
4---
5​
6# Function: useLiveQuery()
7​
8## Call Signature
9​
10```ts
11function useLiveQuery<TContext>(queryFn, deps?): UseLiveQueryReturn<TContext>;
12```
13​
14Defined in: [useLiveQuery.ts:138](https://github.com/TanStack/db/blob/main/packages/vue-db/src/useLiveQuery.ts#L138)
15​
16Create a live query using a query function
17​
18### Type Parameters
19​
20#### TContext
21​
22`TContext` *extends* `Context`
23​
24### Parameters
25​
26#### queryFn
27​
28(`q`) => `QueryBuilder`\<`TContext`\>
29​
30Query function that defines what data to fetch
31​
32#### deps?
33​
34`unknown`[]
35​
36Array of reactive dependencies that trigger query re-execution when changed
37​
38### Returns
39​
40[`UseLiveQueryReturn`](../interfaces/UseLiveQueryReturn.md)\<`TContext`\>
41​
42Reactive object with query data, state, and status information
43​
44### Examples
45​
46```ts
47// Basic query with object syntax
48const { data, isLoading } = useLiveQuery((q) =>
49 q.from({ todos: todosCollection })
50 .where(({ todos }) => eq(todos.completed, false))
51 .select(({ todos }) => ({ id: todos.id, text: todos.text }))
53```
54​
55```ts
56// With reactive dependencies
57const minPriority = ref(5)
58const { data, state } = useLiveQuery(
59 (q) => q.from({ todos: todosCollection })
60 .where(({ todos }) => gt(todos.priority, minPriority.value)),
61 [minPriority] // Re-run when minPriority changes
63```
64​
65```ts
66// Join pattern
67const { data } = useLiveQuery((q) =>
68 q.from({ issues: issueCollection })
69 .join({ persons: personCollection }, ({ issues, persons }) =>
70 eq(issues.userId, persons.id)
71 )
72 .select(({ issues, persons }) => ({
73 id: issues.id,
74 title: issues.title,
75 userName: persons.name
76 }))
78```
79​
80```ts
81// Handle loading and error states in template
82const { data, isLoading, isError, status } = useLiveQuery((q) =>
83 q.from({ todos: todoCollection })
85​
86// In template:
87// <div v-if="isLoading">Loading...</div>
88// <div v-else-if="isError">Error: {{ status }}</div>
89// <ul v-else>
90// <li v-for="todo in data" :key="todo.id">{{ todo.text }}</li>
91// </ul>
92```
93​
94## Call Signature
95​
96```ts
97function useLiveQuery<TContext>(queryFn, deps?): UseLiveQueryReturn<TContext>;
98```
99​
100Defined in: [useLiveQuery.ts:144](https://github.com/TanStack/db/blob/main/packages/vue-db/src/useLiveQuery.ts#L144)
101​
102Create a live query using a query function
103​
104### Type Parameters
105​
106#### TContext
107​
108`TContext` *extends* `Context`
109​
110### Parameters
111​
112#### queryFn
113​
114(`q`) => `QueryBuilder`\<`TContext`\> \| `null` \| `undefined`
115​
116Query function that defines what data to fetch
117​
118#### deps?
119​
120`unknown`[]
121​
122Array of reactive dependencies that trigger query re-execution when changed
123​
124### Returns
125​
126[`UseLiveQueryReturn`](../interfaces/UseLiveQueryReturn.md)\<`TContext`\>
127​
128Reactive object with query data, state, and status information
129​
130### Examples
131​
132```ts
133// Basic query with object syntax
134const { data, isLoading } = useLiveQuery((q) =>
135 q.from({ todos: todosCollection })
136 .where(({ todos }) => eq(todos.completed, false))
137 .select(({ todos }) => ({ id: todos.id, text: todos.text }))
139```
140​
141```ts
142// With reactive dependencies
143const minPriority = ref(5)
144const { data, state } = useLiveQuery(
145 (q) => q.from({ todos: todosCollection })
146 .where(({ todos }) => gt(todos.priority, minPriority.value)),
147 [minPriority] // Re-run when minPriority changes
149```
150​
151```ts
152// Join pattern
153const { data } = useLiveQuery((q) =>
154 q.from({ issues: issueCollection })
155 .join({ persons: personCollection }, ({ issues, persons }) =>
156 eq(issues.userId, persons.id)
157 )
158 .select(({ issues, persons }) => ({
159 id: issues.id,
160 title: issues.title,
161 userName: persons.name
162 }))
164```
165​
166```ts
167// Handle loading and error states in template
168const { data, isLoading, isError, status } = useLiveQuery((q) =>
169 q.from({ todos: todoCollection })
171​
172// In template:
173// <div v-if="isLoading">Loading...</div>
174// <div v-else-if="isError">Error: {{ status }}</div>
175// <ul v-else>
176// <li v-for="todo in data" :key="todo.id">{{ todo.text }}</li>
177// </ul>
178```
179​
180## Call Signature
181​
182```ts
183function useLiveQuery<TContext>(config, deps?): UseLiveQueryReturn<TContext>;
184```
185​
186Defined in: [useLiveQuery.ts:184](https://github.com/TanStack/db/blob/main/packages/vue-db/src/useLiveQuery.ts#L184)
187​
188Create a live query using configuration object
189​
190### Type Parameters
191​
192#### TContext
193​
194`TContext` *extends* `Context`
195​
196### Parameters
197​
198#### config
199​
200`LiveQueryCollectionConfig`\<`TContext`\>
201​
202Configuration object with query and options
203​
204#### deps?
205​
206`unknown`[]
207​
208Array of reactive dependencies that trigger query re-execution when changed
209​
210### Returns
211​
212[`UseLiveQueryReturn`](../interfaces/UseLiveQueryReturn.md)\<`TContext`\>
213​
214Reactive object with query data, state, and status information
215​
216### Examples
217​
218```ts
219// Basic config object usage
220const { data, status } = useLiveQuery({
221 query: (q) => q.from({ todos: todosCollection }),
222 gcTime: 60000
223})
224```
225​
226```ts
227// With reactive dependencies
228const filter = ref('active')
229const { data, isReady } = useLiveQuery({
230 query: (q) => q.from({ todos: todosCollection })
231 .where(({ todos }) => eq(todos.status, filter.value))
232}, [filter])
233```
234​
235```ts
236// Handle all states uniformly
237const { data, isLoading, isReady, isError } = useLiveQuery({
238 query: (q) => q.from({ items: itemCollection })
239})
240​
241// In template:
242// <div v-if="isLoading">Loading...</div>
243// <div v-else-if="isError">Something went wrong</div>
244// <div v-else-if="!isReady">Preparing...</div>
245// <div v-else>{{ data.length }} items loaded</div>
246```
247​
248## Call Signature
249​
250```ts
251function useLiveQuery<TResult, TKey, TUtils>(liveQueryCollection): UseLiveQueryReturnWithCollection<TResult, TKey, TUtils>;
252```
253​
254Defined in: [useLiveQuery.ts:229](https://github.com/TanStack/db/blob/main/packages/vue-db/src/useLiveQuery.ts#L229)
255​
256Subscribe to an existing query collection (can be reactive)
257​
258### Type Parameters
259​
260#### TResult
261​
262`TResult` *extends* `object`
263​
264#### TKey
265​
266`TKey` *extends* `string` \| `number`
267​
268#### TUtils
269​
270`TUtils` *extends* `Record`\<`string`, `any`\>
271​
272### Parameters
273​
274#### liveQueryCollection
275​
276`MaybeRefOrGetter`\<`Collection`\<`TResult`, `TKey`, `TUtils`, `StandardSchemaV1`\<`unknown`, `unknown`\>, `TResult`\> & `NonSingleResult`\>
277​
278Pre-created query collection to subscribe to (can be a ref)
279​
280### Returns
281​
282[`UseLiveQueryReturnWithCollection`](../interfaces/UseLiveQueryReturnWithCollection.md)\<`TResult`, `TKey`, `TUtils`\>
283​
284Reactive object with query data, state, and status information
285​
286### Examples
287​
288```ts
289// Using pre-created query collection
290const myLiveQuery = createLiveQueryCollection((q) =>
291 q.from({ todos: todosCollection }).where(({ todos }) => eq(todos.active, true))
293const { data, collection } = useLiveQuery(myLiveQuery)
294```
295​
296```ts
297// Reactive query collection reference
298const selectedQuery = ref(todosQuery)
299const { data, collection } = useLiveQuery(selectedQuery)
300​
301// Switch queries reactively
302selectedQuery.value = archiveQuery
303```
304​
305```ts
306// Access query collection methods directly
307const { data, collection, isReady } = useLiveQuery(existingQuery)
308​
309// Use underlying collection for mutations
310const handleToggle = (id) => {
311 collection.value.update(id, draft => { draft.completed = !draft.completed })
313```
314​
315```ts
316// Handle states consistently
317const { data, isLoading, isError } = useLiveQuery(sharedQuery)
318​
319// In template:
320// <div v-if="isLoading">Loading...</div>
321// <div v-else-if="isError">Error loading data</div>
322// <div v-else>
323// <Item v-for="item in data" :key="item.id" v-bind="item" />
324// </div>
325```
326​
327## Call Signature
328​
329```ts
330function useLiveQuery<TResult, TKey, TUtils>(liveQueryCollection): UseLiveQueryReturnWithSingleResultCollection<TResult, TKey, TUtils>;
331```
332​
333Defined in: [useLiveQuery.ts:240](https://github.com/TanStack/db/blob/main/packages/vue-db/src/useLiveQuery.ts#L240)
334​
335Create a live query using a query function
336​
337### Type Parameters
338​
339#### TResult
340​
341`TResult` *extends* `object`
342​
343#### TKey
344​
345`TKey` *extends* `string` \| `number`
346​
347#### TUtils
348​
349`TUtils` *extends* `Record`\<`string`, `any`\>
350​
351### Parameters
352​
353#### liveQueryCollection
354​
355`MaybeRefOrGetter`\<`Collection`\<`TResult`, `TKey`, `TUtils`, `StandardSchemaV1`\<`unknown`, `unknown`\>, `TResult`\> & `SingleResult`\>
356​
357### Returns
358​
359[`UseLiveQueryReturnWithSingleResultCollection`](../interfaces/UseLiveQueryReturnWithSingleResultCollection.md)\<`TResult`, `TKey`, `TUtils`\>
360​
361Reactive object with query data, state, and status information
362​
363### Examples
364​
365```ts
366// Basic query with object syntax
367const { data, isLoading } = useLiveQuery((q) =>
368 q.from({ todos: todosCollection })
369 .where(({ todos }) => eq(todos.completed, false))
370 .select(({ todos }) => ({ id: todos.id, text: todos.text }))
372```
373​
374```ts
375// With reactive dependencies
376const minPriority = ref(5)
377const { data, state } = useLiveQuery(
378 (q) => q.from({ todos: todosCollection })
379 .where(({ todos }) => gt(todos.priority, minPriority.value)),
380 [minPriority] // Re-run when minPriority changes
382```
383​
384```ts
385// Join pattern
386const { data } = useLiveQuery((q) =>
387 q.from({ issues: issueCollection })
388 .join({ persons: personCollection }, ({ issues, persons }) =>
389 eq(issues.userId, persons.id)
390 )
391 .select(({ issues, persons }) => ({
392 id: issues.id,
393 title: issues.title,
394 userName: persons.name
395 }))
397```
398​
399```ts
400// Handle loading and error states in template
401const { data, isLoading, isError, status } = useLiveQuery((q) =>
402 q.from({ todos: todoCollection })
404​
405// In template:
406// <div v-if="isLoading">Loading...</div>
407// <div v-else-if="isError">Error: {{ status }}</div>
408// <ul v-else>
409// <li v-for="todo in data" :key="todo.id">{{ todo.text }}</li>
410// </ul>
411```