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

BaseQueryBuilder.md

1,056 lines26.0 KB

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