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

queryOnce.md

102 lines2.5 KB

1---
2id: queryOnce
3title: queryOnce
4---
5​
6## Call Signature
7​
8```ts
9function queryOnce<TQueryFn, TQuery>(queryFn): Promise<InferResultType<ExtractContext<TQuery>>>;
10```
11​
12Defined in: [packages/db/src/query/query-once.ts:59](https://github.com/TanStack/db/blob/main/packages/db/src/query/query-once.ts#L59)
13​
14Executes a one-shot query and returns the results as an array.
15​
16This function creates a live query collection, preloads it, extracts the results,
17and automatically cleans up the collection. It's ideal for:
18- AI/LLM context building
19- Data export
20- Background processing
21- Testing
22​
23### Type Parameters
24​
25#### TQueryFn
26​
27`TQueryFn` *extends* (`q`) => [`QueryBuilder`](../type-aliases/QueryBuilder.md)\<`any`\>
28​
29#### TQuery
30​
31`TQuery` *extends* [`QueryBuilder`](../type-aliases/QueryBuilder.md)\<`any`\> = `ReturnType`\<`TQueryFn`\>
32​
33### Parameters
34​
35#### queryFn
36​
37`TQueryFn` & `RootQueryFn`\<`TQuery`\>
38​
39A function that receives the query builder and returns a query
40​
41### Returns
42​
43`Promise`\<[`InferResultType`](../type-aliases/InferResultType.md)\<[`ExtractContext`](../type-aliases/ExtractContext.md)\<`TQuery`\>\>\>
44​
45A promise that resolves to an array of query results
46​
47### Example
48​
49```typescript
50// Basic query
51const users = await queryOnce((q) =>
52 q.from({ user: usersCollection })
54​
55// With filtering and projection
56const activeUserNames = await queryOnce((q) =>
57 q.from({ user: usersCollection })
58 .where(({ user }) => eq(user.active, true))
59 .select(({ user }) => ({ name: user.name }))
61```
62​
63## Call Signature
64​
65```ts
66function queryOnce<TQuery>(config): Promise<InferResultType<ExtractContext<TQuery>>>;
67```
68​
69Defined in: [packages/db/src/query/query-once.ts:83](https://github.com/TanStack/db/blob/main/packages/db/src/query/query-once.ts#L83)
70​
71Executes a one-shot query using a configuration object.
72​
73### Type Parameters
74​
75#### TQuery
76​
77`TQuery` *extends* [`QueryBuilder`](../type-aliases/QueryBuilder.md)\<`any`\>
78​
79### Parameters
80​
81#### config
82​
83[`QueryOnceConfig`](../interfaces/QueryOnceConfig.md)\<[`ExtractContext`](../type-aliases/ExtractContext.md)\<`TQuery`\>\> & `object`
84​
85Configuration object with the query function
86​
87### Returns
88​
89`Promise`\<[`InferResultType`](../type-aliases/InferResultType.md)\<[`ExtractContext`](../type-aliases/ExtractContext.md)\<`TQuery`\>\>\>
90​
91A promise that resolves to an array of query results
92​
93### Example
94​
95```typescript
96const recentOrders = await queryOnce({
97 query: (q) =>
98 q.from({ order: ordersCollection })
99 .orderBy(({ order }) => desc(order.createdAt))
100 .limit(100),
101})
102```