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