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