Open History to see the last commit
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 })
55)
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 }))
62)
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```