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

BaseQueryBuilder.md

1,030 lines25.5 KB

1---
2id: BaseQueryBuilder
3title: BaseQueryBuilder
4---
5​
6Defined in: [packages/db/src/query/builder/index.ts:136](https://github.com/TanStack/db/blob/main/packages/db/src/query/builder/index.ts#L136)
7​
8## Type Parameters
9​
10### TContext
11​
12`TContext` *extends* [`Context`](../interfaces/Context.md) = [`Context`](../interfaces/Context.md)
13​
14## Constructors
15​
16### Constructor
17​
18```ts
19new BaseQueryBuilder<TContext>(query, resolveCollection?): BaseQueryBuilder<TContext>;
20```
21​
22Defined in: [packages/db/src/query/builder/index.ts:139](https://github.com/TanStack/db/blob/main/packages/db/src/query/builder/index.ts#L139)
23​
24#### Parameters
25​
26##### query
27​
28`Partial`\<[`QueryIR`](../@tanstack/namespaces/IR/interfaces/QueryIR.md)\> = `{}`
29​
30##### resolveCollection?
31​
32`CollectionResolver`
33​
34#### Returns
35​
36`BaseQueryBuilder`\<`TContext`\>
37​
38## Accessors
39​
40### fn
41​
42#### Get Signature
43​
44```ts
45get fn(): object;
46```
47​
48Defined in: [packages/db/src/query/builder/index.ts:924](https://github.com/TanStack/db/blob/main/packages/db/src/query/builder/index.ts#L924)
49​
50Functional variants of the query builder
51These are imperative function that are called for ery row.
52Warning: that these cannot be optimized by the query compiler, and may prevent
53some type of optimizations being possible.
54​
55##### Example
56​
57```ts
58q.fn.select((row) => ({
59 name: row.user.name.toUpperCase(),
60 age: row.user.age + 1,
61}))
62```
63​
64##### Returns
65​
66###### having()
67​
68```ts
69having(callback): QueryBuilder<TContext>;
70```
71​
72Filter grouped rows using a function that operates on each aggregated row
73Warning: This cannot be optimized by the query compiler
74​
75###### Parameters
76​
77###### callback
78​
79(`row`) => `any`
80​
81A function that receives an aggregated row (with $selected when select() was called) and returns a boolean
82​
83###### Returns
84​
85[`QueryBuilder`](../type-aliases/QueryBuilder.md)\<`TContext`\>
86​
87A QueryBuilder with functional having filter applied
88​
89###### Example
90​
91```ts
92// Functional having (not optimized)
93query
94 .from({ posts: postsCollection })
95 .groupBy(({posts}) => posts.userId)
96 .select(({posts}) => ({ userId: posts.userId, count: count(posts.id) }))
97 .fn.having(({ $selected }) => $selected.count > 5)
98```
99​
100###### select()
101​
102```ts
103select<TFuncSelectResult>(callback): FnSelectQueryResult<TContext, TFuncSelectResult>;
104```
105​
106Select fields using a function that operates on each row
107Warning: This cannot be optimized by the query compiler
108​
109###### Type Parameters
110​
111###### TFuncSelectResult
112​
113`TFuncSelectResult`
114​
115###### Parameters
116​
117###### callback
118​
119(`row`) => `TFuncSelectResult`
120​
121A function that receives a row and returns the selected value
122​
123###### Returns
124​
125`FnSelectQueryResult`\<`TContext`, `TFuncSelectResult`\>
126​
127A QueryBuilder with functional selection applied
128​
129###### Example
130​
131```ts
132// Functional select (not optimized)
133query
134 .from({ users: usersCollection })
135 .fn.select(row => ({
136 name: row.users.name.toUpperCase(),
137 age: row.users.age + 1,
138 }))
139```
140​
141Child query builders, query expressions, and helpers such as eq(),
142toArray(), and materialize() cannot be returned from fn.select(). Use
143them as fields in select() so the compiler can add them to the query
144graph.
145​
146Compiled Collection-valued includes cannot be inputs to fn.select(),
147including nested descendants. Use toArray() or materialize() in the
148upstream select(), or do parent-only functional work before adding
149live Collection includes with select().
150​
151###### where()
152​
153```ts
154where(callback): QueryBuilder<TContext>;
155```
156​
157Filter rows using a function that operates on each row
158Warning: This cannot be optimized by the query compiler
159​
160###### Parameters
161​
162###### callback
163​
164(`row`) => `any`
165​
166A function that receives a row and returns a boolean
167​
168###### Returns
169​
170[`QueryBuilder`](../type-aliases/QueryBuilder.md)\<`TContext`\>
171​
172A QueryBuilder with functional filtering applied
173​
174###### Example
175​
176```ts
177// Functional where (not optimized)
178query
179 .from({ users: usersCollection })
180 .fn.where(row => row.users.name.startsWith('A'))
181```
182​
183## Methods
184​
185### \_getQuery()
186​
187```ts
188_getQuery(): QueryIR;
189```
190​
191Defined in: [packages/db/src/query/builder/index.ts:1021](https://github.com/TanStack/db/blob/main/packages/db/src/query/builder/index.ts#L1021)
192​
193#### Returns
194​
195[`QueryIR`](../@tanstack/namespaces/IR/interfaces/QueryIR.md)
196​
197***
198​
199### distinct()
200​
201```ts
202distinct(): QueryBuilder<TContext>;
203```
204​
205Defined in: [packages/db/src/query/builder/index.ts:857](https://github.com/TanStack/db/blob/main/packages/db/src/query/builder/index.ts#L857)
206​
207Specify that the query should return distinct rows.
208Deduplicates rows based on the selected columns.
209​
210#### Returns
211​
212[`QueryBuilder`](../type-aliases/QueryBuilder.md)\<`TContext`\>
213​
214A QueryBuilder with distinct enabled
215​
216#### Example
217​
218```ts
219// Get countries our users are from
220query
221 .from({ users: usersCollection })
222 .select(({users}) => ({ country: users.country }))
223 .distinct()
224```
225​
226***
227​
228### findOne()
229​
230```ts
231findOne(): QueryBuilder<TContext & SingleResult>;
232```
233​
234Defined in: [packages/db/src/query/builder/index.ts:877](https://github.com/TanStack/db/blob/main/packages/db/src/query/builder/index.ts#L877)
235​
236Specify that the query should return a single result
237​
238#### Returns
239​
240[`QueryBuilder`](../type-aliases/QueryBuilder.md)\<`TContext` & [`SingleResult`](../type-aliases/SingleResult.md)\>
241​
242A QueryBuilder that returns the first result
243​
244#### Example
245​
246```ts
247// Get the user matching the query
248query
249 .from({ users: usersCollection })
250 .where(({users}) => eq(users.id, 1))
251 .findOne()
252```
253​
254***
255​
256### from()
257​
258```ts
259from<TSource>(source): QueryBuilder<ContextFromSource<TSource>>;
260```
261​
262Defined in: [packages/db/src/query/builder/index.ts:249](https://github.com/TanStack/db/blob/main/packages/db/src/query/builder/index.ts#L249)
263​
264Specify the source table or subquery for the query
265​
266#### Type Parameters
267​
268##### TSource
269​
270`TSource` *extends* [`Source`](../type-aliases/Source.md)
271​
272#### Parameters
273​
274##### source
275​
276[`SingleSource`](../type-aliases/SingleSource.md)\<`TSource`\>
277​
278An object with a single key-value pair where the key is the table alias and the value is a Collection or subquery
279​
280#### Returns
281​
282[`QueryBuilder`](../type-aliases/QueryBuilder.md)\<[`ContextFromSource`](../type-aliases/ContextFromSource.md)\<`TSource`\>\>
283​
284A QueryBuilder with the specified source
285​
286#### Example
287​
288```ts
289// Query from a collection
290query.from({ users: usersCollection })
291​
292// Query from a subquery
293const activeUsers = query.from({ u: usersCollection }).where(({u}) => u.active)
294query.from({ activeUsers })
295```
296​
297***
298​
299### fullJoin()
300​
301```ts
302fullJoin<TSource>(source, onCallback): QueryBuilder<MergeContextWithJoinType<TContext, SchemaFromSource<TSource>, "full">>;
303```
304​
305Defined in: [packages/db/src/query/builder/index.ts:484](https://github.com/TanStack/db/blob/main/packages/db/src/query/builder/index.ts#L484)
306​
307Perform a FULL JOIN with another table or subquery
308​
309#### Type Parameters
310​
311##### TSource
312​
313`TSource` *extends* [`Source`](../type-aliases/Source.md)
314​
315#### Parameters
316​
317##### source
318​
319`TSource`
320​
321An object with a single key-value pair where the key is the table alias and the value is a Collection or subquery
322​
323##### onCallback
324​
325[`JoinOnCallback`](../type-aliases/JoinOnCallback.md)\<[`MergeContextForJoinCallback`](../type-aliases/MergeContextForJoinCallback.md)\<`TContext`, \{ \[K in string \| number \| symbol\]: \{ \[K in string \| number \| symbol\]: TSource\[K\] extends CollectionImpl\<any, any, any, any, any\> ? InferCollectionType\<any\[any\]\> : TSource\[K\] extends CollectionOptionsIdentity\<any, any, any, any, any\> ? InferCollectionType\<any\[any\]\> : TSource\[K\] extends QueryBuilder\<TContext\> ? ResultValue\<TContext\> : never \}\[K\] \}\>\>
326​
327A function that receives table references and returns the join condition
328​
329#### Returns
330​
331[`QueryBuilder`](../type-aliases/QueryBuilder.md)\<[`MergeContextWithJoinType`](../type-aliases/MergeContextWithJoinType.md)\<`TContext`, [`SchemaFromSource`](../type-aliases/SchemaFromSource.md)\<`TSource`\>, `"full"`\>\>
332​
333A QueryBuilder with the full joined table available
334​
335#### Example
336​
337```ts
338// Full join users with posts
339query
340 .from({ users: usersCollection })
341 .fullJoin({ posts: postsCollection }, ({users, posts}) => eq(users.id, posts.userId))
342```
343​
344***
345​
346### groupBy()
347​
348```ts
349groupBy(callback): QueryBuilder<TContext>;
350```
351​
352Defined in: [packages/db/src/query/builder/index.ts:779](https://github.com/TanStack/db/blob/main/packages/db/src/query/builder/index.ts#L779)
353​
354Group rows by one or more columns for aggregation
355​
356#### Parameters
357​
358##### callback
359​
360[`GroupByCallback`](../type-aliases/GroupByCallback.md)\<`TContext`\>
361​
362A function that receives table references and returns the field(s) to group by
363​
364#### Returns
365​
366[`QueryBuilder`](../type-aliases/QueryBuilder.md)\<`TContext`\>
367​
368A QueryBuilder with grouping applied (enables aggregate functions in SELECT and HAVING)
369​
370#### Example
371​
372```ts
373// Group by a single column
374query
375 .from({ posts: postsCollection })
376 .groupBy(({posts}) => posts.userId)
377 .select(({posts, count}) => ({
378 userId: posts.userId,
379 postCount: count()
380 }))
381​
382// Group by multiple columns
383query
384 .from({ sales: salesCollection })
385 .groupBy(({sales}) => [sales.region, sales.category])
386 .select(({sales, sum}) => ({
387 region: sales.region,
388 category: sales.category,
389 totalSales: sum(sales.amount)
390 }))
391```
392​
393***
394​
395### having()
396​
397```ts
398having(callback): QueryBuilder<TContext>;
399```
400​
401Defined in: [packages/db/src/query/builder/index.ts:578](https://github.com/TanStack/db/blob/main/packages/db/src/query/builder/index.ts#L578)
402​
403Filter grouped rows based on aggregate conditions
404​
405#### Parameters
406​
407##### callback
408​
409[`WhereCallback`](../type-aliases/WhereCallback.md)\<`TContext`\>
410​
411A function that receives table references and returns an expression
412​
413#### Returns
414​
415[`QueryBuilder`](../type-aliases/QueryBuilder.md)\<`TContext`\>
416​
417A QueryBuilder with the having condition applied
418​
419#### Example
420​
421```ts
422// Filter groups by count
423query
424 .from({ posts: postsCollection })
425 .groupBy(({posts}) => posts.userId)
426 .having(({posts}) => gt(count(posts.id), 5))
427​
428// Filter by average
429query
430 .from({ orders: ordersCollection })
431 .groupBy(({orders}) => orders.customerId)
432 .having(({orders}) => gt(avg(orders.total), 100))
433​
434// Multiple having calls are ANDed together
435query
436 .from({ orders: ordersCollection })
437 .groupBy(({orders}) => orders.customerId)
438 .having(({orders}) => gt(count(orders.id), 5))
439 .having(({orders}) => gt(avg(orders.total), 100))
440```
441​
442***
443​
444### innerJoin()
445​
446```ts
447innerJoin<TSource>(source, onCallback): QueryBuilder<MergeContextWithJoinType<TContext, SchemaFromSource<TSource>, "inner">>;
448```
449​
450Defined in: [packages/db/src/query/builder/index.ts:458](https://github.com/TanStack/db/blob/main/packages/db/src/query/builder/index.ts#L458)
451​
452Perform an INNER JOIN with another table or subquery
453​
454#### Type Parameters
455​
456##### TSource
457​
458`TSource` *extends* [`Source`](../type-aliases/Source.md)
459​
460#### Parameters
461​
462##### source
463​
464`TSource`
465​
466An object with a single key-value pair where the key is the table alias and the value is a Collection or subquery
467​
468##### onCallback
469​
470[`JoinOnCallback`](../type-aliases/JoinOnCallback.md)\<[`MergeContextForJoinCallback`](../type-aliases/MergeContextForJoinCallback.md)\<`TContext`, \{ \[K in string \| number \| symbol\]: \{ \[K in string \| number \| symbol\]: TSource\[K\] extends CollectionImpl\<any, any, any, any, any\> ? InferCollectionType\<any\[any\]\> : TSource\[K\] extends CollectionOptionsIdentity\<any, any, any, any, any\> ? InferCollectionType\<any\[any\]\> : TSource\[K\] extends QueryBuilder\<TContext\> ? ResultValue\<TContext\> : never \}\[K\] \}\>\>
471​
472A function that receives table references and returns the join condition
473​
474#### Returns
475​
476[`QueryBuilder`](../type-aliases/QueryBuilder.md)\<[`MergeContextWithJoinType`](../type-aliases/MergeContextWithJoinType.md)\<`TContext`, [`SchemaFromSource`](../type-aliases/SchemaFromSource.md)\<`TSource`\>, `"inner"`\>\>
477​
478A QueryBuilder with the inner joined table available
479​
480#### Example
481​
482```ts
483// Inner join users with posts
484query
485 .from({ users: usersCollection })
486 .innerJoin({ posts: postsCollection }, ({users, posts}) => eq(users.id, posts.userId))
487```
488​
489***
490​
491### join()
492​
493```ts
494join<TSource, TJoinType>(
495 source,
496 onCallback,
497type): QueryBuilder<MergeContextWithJoinType<TContext, SchemaFromSource<TSource>, TJoinType>>;
498```
499​
500Defined in: [packages/db/src/query/builder/index.ts:336](https://github.com/TanStack/db/blob/main/packages/db/src/query/builder/index.ts#L336)
501​
502Join another table or subquery to the current query
503​
504#### Type Parameters
505​
506##### TSource
507​
508`TSource` *extends* [`Source`](../type-aliases/Source.md)
509​
510##### TJoinType
511​
512`TJoinType` *extends* `"inner"` \| `"left"` \| `"right"` \| `"full"` = `"left"`
513​
514#### Parameters
515​
516##### source
517​
518`TSource`
519​
520An object with a single key-value pair where the key is the table alias and the value is a Collection or subquery
521​
522##### onCallback
523​
524[`JoinOnCallback`](../type-aliases/JoinOnCallback.md)\<[`MergeContextForJoinCallback`](../type-aliases/MergeContextForJoinCallback.md)\<`TContext`, \{ \[K in string \| number \| symbol\]: \{ \[K in string \| number \| symbol\]: TSource\[K\] extends CollectionImpl\<any, any, any, any, any\> ? InferCollectionType\<any\[any\]\> : TSource\[K\] extends CollectionOptionsIdentity\<any, any, any, any, any\> ? InferCollectionType\<any\[any\]\> : TSource\[K\] extends QueryBuilder\<TContext\> ? ResultValue\<TContext\> : never \}\[K\] \}\>\>
525​
526A function that receives table references and returns the join condition
527​
528##### type
529​
530`TJoinType` = `...`
531​
532The type of join: 'inner', 'left', 'right', or 'full' (defaults to 'left')
533​
534#### Returns
535​
536[`QueryBuilder`](../type-aliases/QueryBuilder.md)\<[`MergeContextWithJoinType`](../type-aliases/MergeContextWithJoinType.md)\<`TContext`, [`SchemaFromSource`](../type-aliases/SchemaFromSource.md)\<`TSource`\>, `TJoinType`\>\>
537​
538A QueryBuilder with the joined table available
539​
540#### Example
541​
542```ts
543// Left join users with posts
544query
545 .from({ users: usersCollection })
546 .join({ posts: postsCollection }, ({users, posts}) => eq(users.id, posts.userId))
547​
548// Inner join with explicit type
549query
550 .from({ u: usersCollection })
551 .join({ p: postsCollection }, ({u, p}) => eq(u.id, p.userId), 'inner')
552```
553​
554// Join with a subquery
555const activeUsers = query.from({ u: usersCollection }).where(({u}) => u.active)
556query
557 .from({ activeUsers })
558 .join({ p: postsCollection }, ({u, p}) => eq(u.id, p.userId))
559​
560***
561​
562### leftJoin()
563​
564```ts
565leftJoin<TSource>(source, onCallback): QueryBuilder<MergeContextWithJoinType<TContext, SchemaFromSource<TSource>, "left">>;
566```
567​
568Defined in: [packages/db/src/query/builder/index.ts:406](https://github.com/TanStack/db/blob/main/packages/db/src/query/builder/index.ts#L406)
569​
570Perform a LEFT JOIN with another table or subquery
571​
572#### Type Parameters
573​
574##### TSource
575​
576`TSource` *extends* [`Source`](../type-aliases/Source.md)
577​
578#### Parameters
579​
580##### source
581​
582`TSource`
583​
584An object with a single key-value pair where the key is the table alias and the value is a Collection or subquery
585​
586##### onCallback
587​
588[`JoinOnCallback`](../type-aliases/JoinOnCallback.md)\<[`MergeContextForJoinCallback`](../type-aliases/MergeContextForJoinCallback.md)\<`TContext`, \{ \[K in string \| number \| symbol\]: \{ \[K in string \| number \| symbol\]: TSource\[K\] extends CollectionImpl\<any, any, any, any, any\> ? InferCollectionType\<any\[any\]\> : TSource\[K\] extends CollectionOptionsIdentity\<any, any, any, any, any\> ? InferCollectionType\<any\[any\]\> : TSource\[K\] extends QueryBuilder\<TContext\> ? ResultValue\<TContext\> : never \}\[K\] \}\>\>
589​
590A function that receives table references and returns the join condition
591​
592#### Returns
593​
594[`QueryBuilder`](../type-aliases/QueryBuilder.md)\<[`MergeContextWithJoinType`](../type-aliases/MergeContextWithJoinType.md)\<`TContext`, [`SchemaFromSource`](../type-aliases/SchemaFromSource.md)\<`TSource`\>, `"left"`\>\>
595​
596A QueryBuilder with the left joined table available
597​
598#### Example
599​
600```ts
601// Left join users with posts
602query
603 .from({ users: usersCollection })
604 .leftJoin({ posts: postsCollection }, ({users, posts}) => eq(users.id, posts.userId))
605```
606​
607***
608​
609### limit()
610​
611```ts
612limit(count): QueryBuilder<TContext>;
613```
614​
615Defined in: [packages/db/src/query/builder/index.ts:812](https://github.com/TanStack/db/blob/main/packages/db/src/query/builder/index.ts#L812)
616​
617Limit the number of rows returned by the query
618`orderBy` is required for `limit`
619​
620#### Parameters
621​
622##### count
623​
624`number`
625​
626Maximum number of rows to return
627​
628#### Returns
629​
630[`QueryBuilder`](../type-aliases/QueryBuilder.md)\<`TContext`\>
631​
632A QueryBuilder with the limit applied
633​
634#### Example
635​
636```ts
637// Get top 5 posts by likes
638query
639 .from({ posts: postsCollection })
640 .orderBy(({posts}) => posts.likes, 'desc')
641 .limit(5)
642```
643​
644***
645​
646### offset()
647​
648```ts
649offset(count): QueryBuilder<TContext>;
650```
651​
652Defined in: [packages/db/src/query/builder/index.ts:836](https://github.com/TanStack/db/blob/main/packages/db/src/query/builder/index.ts#L836)
653​
654Skip a number of rows before returning results
655`orderBy` is required for `offset`
656​
657#### Parameters
658​
659##### count
660​
661`number`
662​
663Number of rows to skip
664​
665#### Returns
666​
667[`QueryBuilder`](../type-aliases/QueryBuilder.md)\<`TContext`\>
668​
669A QueryBuilder with the offset applied
670​
671#### Example
672​
673```ts
674// Get second page of results
675query
676 .from({ posts: postsCollection })
677 .orderBy(({posts}) => posts.createdAt, 'desc')
678 .offset(page * pageSize)
679 .limit(pageSize)
680```
681​
682***
683​
684### orderBy()
685​
686```ts
687orderBy(callback, options): QueryBuilder<TContext>;
688```
689​
690Defined in: [packages/db/src/query/builder/index.ts:703](https://github.com/TanStack/db/blob/main/packages/db/src/query/builder/index.ts#L703)
691​
692Sort the query results by one or more columns
693​
694#### Parameters
695​
696##### callback
697​
698[`OrderByCallback`](../type-aliases/OrderByCallback.md)\<`TContext`\>
699​
700A function that receives table references and returns the field to sort by
701​
702##### options
703​
704[`OrderByDirection`](../@tanstack/namespaces/IR/type-aliases/OrderByDirection.md) | `OrderByOptions`
705​
706#### Returns
707​
708[`QueryBuilder`](../type-aliases/QueryBuilder.md)\<`TContext`\>
709​
710A QueryBuilder with the ordering applied
711​
712#### Example
713​
714```ts
715// Sort by a single column
716query
717 .from({ users: usersCollection })
718 .orderBy(({users}) => users.name)
719​
720// Sort descending
721query
722 .from({ users: usersCollection })
723 .orderBy(({users}) => users.createdAt, 'desc')
724​
725// Multiple sorts (chain orderBy calls)
726query
727 .from({ users: usersCollection })
728 .orderBy(({users}) => users.lastName)
729 .orderBy(({users}) => users.firstName)
730```
731​
732***
733​
734### rightJoin()
735​
736```ts
737rightJoin<TSource>(source, onCallback): QueryBuilder<MergeContextWithJoinType<TContext, SchemaFromSource<TSource>, "right">>;
738```
739​
740Defined in: [packages/db/src/query/builder/index.ts:432](https://github.com/TanStack/db/blob/main/packages/db/src/query/builder/index.ts#L432)
741​
742Perform a RIGHT JOIN with another table or subquery
743​
744#### Type Parameters
745​
746##### TSource
747​
748`TSource` *extends* [`Source`](../type-aliases/Source.md)
749​
750#### Parameters
751​
752##### source
753​
754`TSource`
755​
756An object with a single key-value pair where the key is the table alias and the value is a Collection or subquery
757​
758##### onCallback
759​
760[`JoinOnCallback`](../type-aliases/JoinOnCallback.md)\<[`MergeContextForJoinCallback`](../type-aliases/MergeContextForJoinCallback.md)\<`TContext`, \{ \[K in string \| number \| symbol\]: \{ \[K in string \| number \| symbol\]: TSource\[K\] extends CollectionImpl\<any, any, any, any, any\> ? InferCollectionType\<any\[any\]\> : TSource\[K\] extends CollectionOptionsIdentity\<any, any, any, any, any\> ? InferCollectionType\<any\[any\]\> : TSource\[K\] extends QueryBuilder\<TContext\> ? ResultValue\<TContext\> : never \}\[K\] \}\>\>
761​
762A function that receives table references and returns the join condition
763​
764#### Returns
765​
766[`QueryBuilder`](../type-aliases/QueryBuilder.md)\<[`MergeContextWithJoinType`](../type-aliases/MergeContextWithJoinType.md)\<`TContext`, [`SchemaFromSource`](../type-aliases/SchemaFromSource.md)\<`TSource`\>, `"right"`\>\>
767​
768A QueryBuilder with the right joined table available
769​
770#### Example
771​
772```ts
773// Right join users with posts
774query
775 .from({ users: usersCollection })
776 .rightJoin({ posts: postsCollection }, ({users, posts}) => eq(users.id, posts.userId))
777```
778​
779***
780​
781### select()
782​
783#### Call Signature
784​
785```ts
786select<TSelectObject>(callback): QueryBuilder<WithResult<TContext, ResultTypeFromSelect<TSelectObject>>>;
787```
788​
789Defined in: [packages/db/src/query/builder/index.ts:644](https://github.com/TanStack/db/blob/main/packages/db/src/query/builder/index.ts#L644)
790​
791Select specific columns or computed values from the query
792​
793##### Type Parameters
794​
795###### TSelectObject
796​
797`TSelectObject` *extends* `SelectShape`
798​
799##### Parameters
800​
801###### callback
802​
803(`refs`) => `NonScalarSelectObject`\<`TSelectObject`\>
804​
805A function that receives table references and returns an object with selected fields or expressions
806​
807##### Returns
808​
809[`QueryBuilder`](../type-aliases/QueryBuilder.md)\<[`WithResult`](../type-aliases/WithResult.md)\<`TContext`, [`ResultTypeFromSelect`](../type-aliases/ResultTypeFromSelect.md)\<`TSelectObject`\>\>\>
810​
811A QueryBuilder that returns only the selected fields
812​
813##### Example
814​
815```ts
816// Select specific columns
817query
818 .from({ users: usersCollection })
819 .select(({users}) => ({
820 name: users.name,
821 email: users.email
822 }))
823​
824// Select with computed values
825query
826 .from({ users: usersCollection })
827 .select(({users}) => ({
828 fullName: concat(users.firstName, ' ', users.lastName),
829 ageInMonths: mul(users.age, 12)
830 }))
831​
832// Select with aggregates (requires GROUP BY)
833query
834 .from({ posts: postsCollection })
835 .groupBy(({posts}) => posts.userId)
836 .select(({posts, count}) => ({
837 userId: posts.userId,
838 postCount: count(posts.id)
839 }))
840```
841​
842#### Call Signature
843​
844```ts
845select<TSelectValue>(callback): QueryBuilder<WithResult<TContext, ResultTypeFromSelectValue<TSelectValue>>>;
846```
847​
848Defined in: [packages/db/src/query/builder/index.ts:649](https://github.com/TanStack/db/blob/main/packages/db/src/query/builder/index.ts#L649)
849​
850Select specific columns or computed values from the query
851​
852##### Type Parameters
853​
854###### TSelectValue
855​
856`TSelectValue` *extends* `ScalarSelectValue`
857​
858##### Parameters
859​
860###### callback
861​
862(`refs`) => `TSelectValue`
863​
864A function that receives table references and returns an object with selected fields or expressions
865​
866##### Returns
867​
868[`QueryBuilder`](../type-aliases/QueryBuilder.md)\<[`WithResult`](../type-aliases/WithResult.md)\<`TContext`, `ResultTypeFromSelectValue`\<`TSelectValue`\>\>\>
869​
870A QueryBuilder that returns only the selected fields
871​
872##### Example
873​
874```ts
875// Select specific columns
876query
877 .from({ users: usersCollection })
878 .select(({users}) => ({
879 name: users.name,
880 email: users.email
881 }))
882​
883// Select with computed values
884query
885 .from({ users: usersCollection })
886 .select(({users}) => ({
887 fullName: concat(users.firstName, ' ', users.lastName),
888 ageInMonths: mul(users.age, 12)
889 }))
890​
891// Select with aggregates (requires GROUP BY)
892query
893 .from({ posts: postsCollection })
894 .groupBy(({posts}) => posts.userId)
895 .select(({posts, count}) => ({
896 userId: posts.userId,
897 postCount: count(posts.id)
898 }))
899```
900​
901***
902​
903### unionAll()
904​
905#### Call Signature
906​
907```ts
908unionAll<TSource>(source): QueryBuilder<ContextFromUnionSource<TSource>>;
909```
910​
911Defined in: [packages/db/src/query/builder/index.ts:275](https://github.com/TanStack/db/blob/main/packages/db/src/query/builder/index.ts#L275)
912​
913Union multiple independent source streams in one query.
914​
915##### Type Parameters
916​
917###### TSource
918​
919`TSource` *extends* [`Source`](../type-aliases/Source.md)
920​
921##### Parameters
922​
923###### source
924​
925`TSource`
926​
927An object with one or more aliases mapped to collections or subqueries
928​
929##### Returns
930​
931[`QueryBuilder`](../type-aliases/QueryBuilder.md)\<[`ContextFromUnionSource`](../type-aliases/ContextFromUnionSource.md)\<`TSource`\>\>
932​
933A QueryBuilder with the unioned sources available
934​
935##### Example
936​
937```ts
938query
939 .unionAll({ message: messagesCollection, toolCall: toolCallsCollection })
940 .orderBy(({ message, toolCall }) =>
941 coalesce(message.timestamp, toolCall.timestamp)
942 )
943```
944​
945#### Call Signature
946​
947```ts
948unionAll<TBranches>(...branches): QueryBuilder<ContextFromUnionBranches<TBranches>>;
949```
950​
951Defined in: [packages/db/src/query/builder/index.ts:278](https://github.com/TanStack/db/blob/main/packages/db/src/query/builder/index.ts#L278)
952​
953Union multiple independent source streams in one query.
954​
955##### Type Parameters
956​
957###### TBranches
958​
959`TBranches` *extends* readonly \[[`QueryBuilder`](../type-aliases/QueryBuilder.md)\<`any`\>, [`QueryBuilder`](../type-aliases/QueryBuilder.md)\<`any`\>\]
960​
961##### Parameters
962​
963###### branches
964​
965...`TBranches`
966​
967##### Returns
968​
969[`QueryBuilder`](../type-aliases/QueryBuilder.md)\<[`ContextFromUnionBranches`](../type-aliases/ContextFromUnionBranches.md)\<`TBranches`\>\>
970​
971A QueryBuilder with the unioned sources available
972​
973##### Example
974​
975```ts
976query
977 .unionAll({ message: messagesCollection, toolCall: toolCallsCollection })
978 .orderBy(({ message, toolCall }) =>
979 coalesce(message.timestamp, toolCall.timestamp)
980 )
981```
982​
983***
984​
985### where()
986​
987```ts
988where(callback): QueryBuilder<TContext>;
989```
990​
991Defined in: [packages/db/src/query/builder/index.ts:523](https://github.com/TanStack/db/blob/main/packages/db/src/query/builder/index.ts#L523)
992​
993Filter rows based on a condition
994​
995#### Parameters
996​
997##### callback
998​
999[`WhereCallback`](../type-aliases/WhereCallback.md)\<`TContext`\>
1000​
1001A function that receives table references and returns an expression
1002​
1003#### Returns
1004​
1005[`QueryBuilder`](../type-aliases/QueryBuilder.md)\<`TContext`\>
1006​
1007A QueryBuilder with the where condition applied
1008​
1009#### Example
1010​
1011```ts
1012// Simple condition
1013query
1014 .from({ users: usersCollection })
1015 .where(({users}) => gt(users.age, 18))
1016​
1017// Multiple conditions
1018query
1019 .from({ users: usersCollection })
1020 .where(({users}) => and(
1021 gt(users.age, 18),
1022 eq(users.active, true)
1023 ))
1024​
1025// Multiple where calls are ANDed together
1026query
1027 .from({ users: usersCollection })
1028 .where(({users}) => gt(users.age, 18))
1029 .where(({users}) => eq(users.active, true))
1030```