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