Skip to content
Source
Sign inSign up
TanStack/db
Open History to see the last commit

BaseQueryBuilder.md

1,018 lines24.5 KB

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