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

queryOnce.md

104 lines2.5 KB

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