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

BaseQueryBuilder.md

1,041 lines25.6 KB

1---
2id: BaseQueryBuilder
3title: BaseQueryBuilder
4---
5​
6Defined in: [packages/db/src/query/builder/index.ts:137](https://github.com/TanStack/db/blob/main/packages/db/src/query/builder/index.ts#L137)
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:140](https://github.com/TanStack/db/blob/main/packages/db/src/query/builder/index.ts#L140)
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:941](https://github.com/TanStack/db/blob/main/packages/db/src/query/builder/index.ts#L941)
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:1038](https://github.com/TanStack/db/blob/main/packages/db/src/query/builder/index.ts#L1038)
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:874](https://github.com/TanStack/db/blob/main/packages/db/src/query/builder/index.ts#L874)
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:894](https://github.com/TanStack/db/blob/main/packages/db/src/query/builder/index.ts#L894)
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:257](https://github.com/TanStack/db/blob/main/packages/db/src/query/builder/index.ts#L257)
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:492](https://github.com/TanStack/db/blob/main/packages/db/src/query/builder/index.ts#L492)
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:796](https://github.com/TanStack/db/blob/main/packages/db/src/query/builder/index.ts#L796)
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:586](https://github.com/TanStack/db/blob/main/packages/db/src/query/builder/index.ts#L586)
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:466](https://github.com/TanStack/db/blob/main/packages/db/src/query/builder/index.ts#L466)
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:344](https://github.com/TanStack/db/blob/main/packages/db/src/query/builder/index.ts#L344)
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:414](https://github.com/TanStack/db/blob/main/packages/db/src/query/builder/index.ts#L414)
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:829](https://github.com/TanStack/db/blob/main/packages/db/src/query/builder/index.ts#L829)
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:853](https://github.com/TanStack/db/blob/main/packages/db/src/query/builder/index.ts#L853)
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:711](https://github.com/TanStack/db/blob/main/packages/db/src/query/builder/index.ts#L711)
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:440](https://github.com/TanStack/db/blob/main/packages/db/src/query/builder/index.ts#L440)
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:652](https://github.com/TanStack/db/blob/main/packages/db/src/query/builder/index.ts#L652)
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:657](https://github.com/TanStack/db/blob/main/packages/db/src/query/builder/index.ts#L657)
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:283](https://github.com/TanStack/db/blob/main/packages/db/src/query/builder/index.ts#L283)
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:286](https://github.com/TanStack/db/blob/main/packages/db/src/query/builder/index.ts#L286)
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:531](https://github.com/TanStack/db/blob/main/packages/db/src/query/builder/index.ts#L531)
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```