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

BaseQueryBuilder.md

1,027 lines25.3 KB

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```