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