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