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

BaseQueryBuilder.md

946 lines23.1 KB

1---
2id: BaseQueryBuilder
3title: BaseQueryBuilder
4---
5​
6# Class: BaseQueryBuilder\<TContext\>
7​
8Defined in: [packages/db/src/query/builder/index.ts:63](https://github.com/TanStack/db/blob/main/packages/db/src/query/builder/index.ts#L63)
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:66](https://github.com/TanStack/db/blob/main/packages/db/src/query/builder/index.ts#L66)
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:770](https://github.com/TanStack/db/blob/main/packages/db/src/query/builder/index.ts#L770)
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:857](https://github.com/TanStack/db/blob/main/packages/db/src/query/builder/index.ts#L857)
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:709](https://github.com/TanStack/db/blob/main/packages/db/src/query/builder/index.ts#L709)
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:729](https://github.com/TanStack/db/blob/main/packages/db/src/query/builder/index.ts#L729)
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<{
248 baseSchema: SchemaFromSource<TSource>;
249 fromSourceName: keyof TSource & string;
250 hasJoins: false;
251 schema: SchemaFromSource<TSource>;
252}>;
253```
254​
255Defined in: [packages/db/src/query/builder/index.ts:145](https://github.com/TanStack/db/blob/main/packages/db/src/query/builder/index.ts#L145)
256​
257Specify the source table or subquery for the query
258​
259#### Type Parameters
260​
261##### TSource
262​
263`TSource` *extends* [`Source`](../type-aliases/Source.md)
264​
265#### Parameters
266​
267##### source
268​
269`TSource`
270​
271An object with a single key-value pair where the key is the table alias and the value is a Collection or subquery
272​
273#### Returns
274​
275[`QueryBuilder`](../type-aliases/QueryBuilder.md)\<\{
276 `baseSchema`: [`SchemaFromSource`](../type-aliases/SchemaFromSource.md)\<`TSource`\>;
277 `fromSourceName`: keyof `TSource` & `string`;
278 `hasJoins`: `false`;
279 `schema`: [`SchemaFromSource`](../type-aliases/SchemaFromSource.md)\<`TSource`\>;
280\}\>
281​
282A QueryBuilder with the specified source
283​
284#### Example
285​
286```ts
287// Query from a collection
288query.from({ users: usersCollection })
289​
290// Query from a subquery
291const activeUsers = query.from({ u: usersCollection }).where(({u}) => u.active)
292query.from({ activeUsers })
293```
294​
295***
296​
297### fullJoin()
298​
299```ts
300fullJoin<TSource>(source, onCallback): QueryBuilder<MergeContextWithJoinType<TContext, SchemaFromSource<TSource>, "full">>;
301```
302​
303Defined in: [packages/db/src/query/builder/index.ts:336](https://github.com/TanStack/db/blob/main/packages/db/src/query/builder/index.ts#L336)
304​
305Perform a FULL JOIN with another table or subquery
306​
307#### Type Parameters
308​
309##### TSource
310​
311`TSource` *extends* [`Source`](../type-aliases/Source.md)
312​
313#### Parameters
314​
315##### source
316​
317`TSource`
318​
319An object with a single key-value pair where the key is the table alias and the value is a Collection or subquery
320​
321##### onCallback
322​
323[`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\> ? \{ \[K in string \| number \| symbol\]: ResultValue\<TContext\>\[K\] \} : never \}\[K\] \}\>\>
324​
325A function that receives table references and returns the join condition
326​
327#### Returns
328​
329[`QueryBuilder`](../type-aliases/QueryBuilder.md)\<[`MergeContextWithJoinType`](../type-aliases/MergeContextWithJoinType.md)\<`TContext`, [`SchemaFromSource`](../type-aliases/SchemaFromSource.md)\<`TSource`\>, `"full"`\>\>
330​
331A QueryBuilder with the full joined table available
332​
333#### Example
334​
335```ts
336// Full join users with posts
337query
338 .from({ users: usersCollection })
339 .fullJoin({ posts: postsCollection }, ({users, posts}) => eq(users.id, posts.userId))
340```
341​
342***
343​
344### groupBy()
345​
346```ts
347groupBy(callback): QueryBuilder<TContext>;
348```
349​
350Defined in: [packages/db/src/query/builder/index.ts:631](https://github.com/TanStack/db/blob/main/packages/db/src/query/builder/index.ts#L631)
351​
352Group rows by one or more columns for aggregation
353​
354#### Parameters
355​
356##### callback
357​
358[`GroupByCallback`](../type-aliases/GroupByCallback.md)\<`TContext`\>
359​
360A function that receives table references and returns the field(s) to group by
361​
362#### Returns
363​
364[`QueryBuilder`](../type-aliases/QueryBuilder.md)\<`TContext`\>
365​
366A QueryBuilder with grouping applied (enables aggregate functions in SELECT and HAVING)
367​
368#### Example
369​
370```ts
371// Group by a single column
372query
373 .from({ posts: postsCollection })
374 .groupBy(({posts}) => posts.userId)
375 .select(({posts, count}) => ({
376 userId: posts.userId,
377 postCount: count()
378 }))
379​
380// Group by multiple columns
381query
382 .from({ sales: salesCollection })
383 .groupBy(({sales}) => [sales.region, sales.category])
384 .select(({sales, sum}) => ({
385 region: sales.region,
386 category: sales.category,
387 totalSales: sum(sales.amount)
388 }))
389```
390​
391***
392​
393### having()
394​
395```ts
396having(callback): QueryBuilder<TContext>;
397```
398​
399Defined in: [packages/db/src/query/builder/index.ts:430](https://github.com/TanStack/db/blob/main/packages/db/src/query/builder/index.ts#L430)
400​
401Filter grouped rows based on aggregate conditions
402​
403#### Parameters
404​
405##### callback
406​
407[`WhereCallback`](../type-aliases/WhereCallback.md)\<`TContext`\>
408​
409A function that receives table references and returns an expression
410​
411#### Returns
412​
413[`QueryBuilder`](../type-aliases/QueryBuilder.md)\<`TContext`\>
414​
415A QueryBuilder with the having condition applied
416​
417#### Example
418​
419```ts
420// Filter groups by count
421query
422 .from({ posts: postsCollection })
423 .groupBy(({posts}) => posts.userId)
424 .having(({posts}) => gt(count(posts.id), 5))
425​
426// Filter by average
427query
428 .from({ orders: ordersCollection })
429 .groupBy(({orders}) => orders.customerId)
430 .having(({orders}) => gt(avg(orders.total), 100))
431​
432// Multiple having calls are ANDed together
433query
434 .from({ orders: ordersCollection })
435 .groupBy(({orders}) => orders.customerId)
436 .having(({orders}) => gt(count(orders.id), 5))
437 .having(({orders}) => gt(avg(orders.total), 100))
438```
439​
440***
441​
442### innerJoin()
443​
444```ts
445innerJoin<TSource>(source, onCallback): QueryBuilder<MergeContextWithJoinType<TContext, SchemaFromSource<TSource>, "inner">>;
446```
447​
448Defined in: [packages/db/src/query/builder/index.ts:310](https://github.com/TanStack/db/blob/main/packages/db/src/query/builder/index.ts#L310)
449​
450Perform an INNER JOIN with another table or subquery
451​
452#### Type Parameters
453​
454##### TSource
455​
456`TSource` *extends* [`Source`](../type-aliases/Source.md)
457​
458#### Parameters
459​
460##### source
461​
462`TSource`
463​
464An object with a single key-value pair where the key is the table alias and the value is a Collection or subquery
465​
466##### onCallback
467​
468[`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\> ? \{ \[K in string \| number \| symbol\]: ResultValue\<TContext\>\[K\] \} : never \}\[K\] \}\>\>
469​
470A function that receives table references and returns the join condition
471​
472#### Returns
473​
474[`QueryBuilder`](../type-aliases/QueryBuilder.md)\<[`MergeContextWithJoinType`](../type-aliases/MergeContextWithJoinType.md)\<`TContext`, [`SchemaFromSource`](../type-aliases/SchemaFromSource.md)\<`TSource`\>, `"inner"`\>\>
475​
476A QueryBuilder with the inner joined table available
477​
478#### Example
479​
480```ts
481// Inner join users with posts
482query
483 .from({ users: usersCollection })
484 .innerJoin({ posts: postsCollection }, ({users, posts}) => eq(users.id, posts.userId))
485```
486​
487***
488​
489### join()
490​
491```ts
492join<TSource, TJoinType>(
493 source,
494 onCallback,
495type): QueryBuilder<MergeContextWithJoinType<TContext, SchemaFromSource<TSource>, TJoinType>>;
496```
497​
498Defined in: [packages/db/src/query/builder/index.ts:188](https://github.com/TanStack/db/blob/main/packages/db/src/query/builder/index.ts#L188)
499​
500Join another table or subquery to the current query
501​
502#### Type Parameters
503​
504##### TSource
505​
506`TSource` *extends* [`Source`](../type-aliases/Source.md)
507​
508##### TJoinType
509​
510`TJoinType` *extends* `"inner"` \| `"left"` \| `"right"` \| `"full"` = `"left"`
511​
512#### Parameters
513​
514##### source
515​
516`TSource`
517​
518An object with a single key-value pair where the key is the table alias and the value is a Collection or subquery
519​
520##### onCallback
521​
522[`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\> ? \{ \[K in string \| number \| symbol\]: ResultValue\<TContext\>\[K\] \} : never \}\[K\] \}\>\>
523​
524A function that receives table references and returns the join condition
525​
526##### type
527​
528`TJoinType` = `...`
529​
530The type of join: 'inner', 'left', 'right', or 'full' (defaults to 'left')
531​
532#### Returns
533​
534[`QueryBuilder`](../type-aliases/QueryBuilder.md)\<[`MergeContextWithJoinType`](../type-aliases/MergeContextWithJoinType.md)\<`TContext`, [`SchemaFromSource`](../type-aliases/SchemaFromSource.md)\<`TSource`\>, `TJoinType`\>\>
535​
536A QueryBuilder with the joined table available
537​
538#### Example
539​
540```ts
541// Left join users with posts
542query
543 .from({ users: usersCollection })
544 .join({ posts: postsCollection }, ({users, posts}) => eq(users.id, posts.userId))
545​
546// Inner join with explicit type
547query
548 .from({ u: usersCollection })
549 .join({ p: postsCollection }, ({u, p}) => eq(u.id, p.userId), 'inner')
550```
551​
552// Join with a subquery
553const activeUsers = query.from({ u: usersCollection }).where(({u}) => u.active)
554query
555 .from({ activeUsers })
556 .join({ p: postsCollection }, ({u, p}) => eq(u.id, p.userId))
557​
558***
559​
560### leftJoin()
561​
562```ts
563leftJoin<TSource>(source, onCallback): QueryBuilder<MergeContextWithJoinType<TContext, SchemaFromSource<TSource>, "left">>;
564```
565​
566Defined in: [packages/db/src/query/builder/index.ts:258](https://github.com/TanStack/db/blob/main/packages/db/src/query/builder/index.ts#L258)
567​
568Perform a LEFT JOIN with another table or subquery
569​
570#### Type Parameters
571​
572##### TSource
573​
574`TSource` *extends* [`Source`](../type-aliases/Source.md)
575​
576#### Parameters
577​
578##### source
579​
580`TSource`
581​
582An object with a single key-value pair where the key is the table alias and the value is a Collection or subquery
583​
584##### onCallback
585​
586[`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\> ? \{ \[K in string \| number \| symbol\]: ResultValue\<TContext\>\[K\] \} : never \}\[K\] \}\>\>
587​
588A function that receives table references and returns the join condition
589​
590#### Returns
591​
592[`QueryBuilder`](../type-aliases/QueryBuilder.md)\<[`MergeContextWithJoinType`](../type-aliases/MergeContextWithJoinType.md)\<`TContext`, [`SchemaFromSource`](../type-aliases/SchemaFromSource.md)\<`TSource`\>, `"left"`\>\>
593​
594A QueryBuilder with the left joined table available
595​
596#### Example
597​
598```ts
599// Left join users with posts
600query
601 .from({ users: usersCollection })
602 .leftJoin({ posts: postsCollection }, ({users, posts}) => eq(users.id, posts.userId))
603```
604​
605***
606​
607### limit()
608​
609```ts
610limit(count): QueryBuilder<TContext>;
611```
612​
613Defined in: [packages/db/src/query/builder/index.ts:664](https://github.com/TanStack/db/blob/main/packages/db/src/query/builder/index.ts#L664)
614​
615Limit the number of rows returned by the query
616`orderBy` is required for `limit`
617​
618#### Parameters
619​
620##### count
621​
622`number`
623​
624Maximum number of rows to return
625​
626#### Returns
627​
628[`QueryBuilder`](../type-aliases/QueryBuilder.md)\<`TContext`\>
629​
630A QueryBuilder with the limit applied
631​
632#### Example
633​
634```ts
635// Get top 5 posts by likes
636query
637 .from({ posts: postsCollection })
638 .orderBy(({posts}) => posts.likes, 'desc')
639 .limit(5)
640```
641​
642***
643​
644### offset()
645​
646```ts
647offset(count): QueryBuilder<TContext>;
648```
649​
650Defined in: [packages/db/src/query/builder/index.ts:688](https://github.com/TanStack/db/blob/main/packages/db/src/query/builder/index.ts#L688)
651​
652Skip a number of rows before returning results
653`orderBy` is required for `offset`
654​
655#### Parameters
656​
657##### count
658​
659`number`
660​
661Number of rows to skip
662​
663#### Returns
664​
665[`QueryBuilder`](../type-aliases/QueryBuilder.md)\<`TContext`\>
666​
667A QueryBuilder with the offset applied
668​
669#### Example
670​
671```ts
672// Get second page of results
673query
674 .from({ posts: postsCollection })
675 .orderBy(({posts}) => posts.createdAt, 'desc')
676 .offset(page * pageSize)
677 .limit(pageSize)
678```
679​
680***
681​
682### orderBy()
683​
684```ts
685orderBy(callback, options): QueryBuilder<TContext>;
686```
687​
688Defined in: [packages/db/src/query/builder/index.ts:555](https://github.com/TanStack/db/blob/main/packages/db/src/query/builder/index.ts#L555)
689​
690Sort the query results by one or more columns
691​
692#### Parameters
693​
694##### callback
695​
696[`OrderByCallback`](../type-aliases/OrderByCallback.md)\<`TContext`\>
697​
698A function that receives table references and returns the field to sort by
699​
700##### options
701​
702[`OrderByDirection`](../@tanstack/namespaces/IR/type-aliases/OrderByDirection.md) | `OrderByOptions`
703​
704#### Returns
705​
706[`QueryBuilder`](../type-aliases/QueryBuilder.md)\<`TContext`\>
707​
708A QueryBuilder with the ordering applied
709​
710#### Example
711​
712```ts
713// Sort by a single column
714query
715 .from({ users: usersCollection })
716 .orderBy(({users}) => users.name)
717​
718// Sort descending
719query
720 .from({ users: usersCollection })
721 .orderBy(({users}) => users.createdAt, 'desc')
722​
723// Multiple sorts (chain orderBy calls)
724query
725 .from({ users: usersCollection })
726 .orderBy(({users}) => users.lastName)
727 .orderBy(({users}) => users.firstName)
728```
729​
730***
731​
732### rightJoin()
733​
734```ts
735rightJoin<TSource>(source, onCallback): QueryBuilder<MergeContextWithJoinType<TContext, SchemaFromSource<TSource>, "right">>;
736```
737​
738Defined in: [packages/db/src/query/builder/index.ts:284](https://github.com/TanStack/db/blob/main/packages/db/src/query/builder/index.ts#L284)
739​
740Perform a RIGHT JOIN with another table or subquery
741​
742#### Type Parameters
743​
744##### TSource
745​
746`TSource` *extends* [`Source`](../type-aliases/Source.md)
747​
748#### Parameters
749​
750##### source
751​
752`TSource`
753​
754An object with a single key-value pair where the key is the table alias and the value is a Collection or subquery
755​
756##### onCallback
757​
758[`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\> ? \{ \[K in string \| number \| symbol\]: ResultValue\<TContext\>\[K\] \} : never \}\[K\] \}\>\>
759​
760A function that receives table references and returns the join condition
761​
762#### Returns
763​
764[`QueryBuilder`](../type-aliases/QueryBuilder.md)\<[`MergeContextWithJoinType`](../type-aliases/MergeContextWithJoinType.md)\<`TContext`, [`SchemaFromSource`](../type-aliases/SchemaFromSource.md)\<`TSource`\>, `"right"`\>\>
765​
766A QueryBuilder with the right joined table available
767​
768#### Example
769​
770```ts
771// Right join users with posts
772query
773 .from({ users: usersCollection })
774 .rightJoin({ posts: postsCollection }, ({users, posts}) => eq(users.id, posts.userId))
775```
776​
777***
778​
779### select()
780​
781#### Call Signature
782​
783```ts
784select<TSelectObject>(callback): QueryBuilder<WithResult<TContext, ResultTypeFromSelect<TSelectObject>>>;
785```
786​
787Defined in: [packages/db/src/query/builder/index.ts:496](https://github.com/TanStack/db/blob/main/packages/db/src/query/builder/index.ts#L496)
788​
789Select specific columns or computed values from the query
790​
791##### Type Parameters
792​
793###### TSelectObject
794​
795`TSelectObject` *extends* `SelectShape`
796​
797##### Parameters
798​
799###### callback
800​
801(`refs`) => `NonScalarSelectObject`\<`TSelectObject`\>
802​
803A function that receives table references and returns an object with selected fields or expressions
804​
805##### Returns
806​
807[`QueryBuilder`](../type-aliases/QueryBuilder.md)\<[`WithResult`](../type-aliases/WithResult.md)\<`TContext`, [`ResultTypeFromSelect`](../type-aliases/ResultTypeFromSelect.md)\<`TSelectObject`\>\>\>
808​
809A QueryBuilder that returns only the selected fields
810​
811##### Example
812​
813```ts
814// Select specific columns
815query
816 .from({ users: usersCollection })
817 .select(({users}) => ({
818 name: users.name,
819 email: users.email
820 }))
821​
822// Select with computed values
823query
824 .from({ users: usersCollection })
825 .select(({users}) => ({
826 fullName: concat(users.firstName, ' ', users.lastName),
827 ageInMonths: mul(users.age, 12)
828 }))
829​
830// Select with aggregates (requires GROUP BY)
831query
832 .from({ posts: postsCollection })
833 .groupBy(({posts}) => posts.userId)
834 .select(({posts, count}) => ({
835 userId: posts.userId,
836 postCount: count(posts.id)
837 }))
838```
839​
840#### Call Signature
841​
842```ts
843select<TSelectValue>(callback): QueryBuilder<WithResult<TContext, ResultTypeFromSelectValue<TSelectValue>>>;
844```
845​
846Defined in: [packages/db/src/query/builder/index.ts:501](https://github.com/TanStack/db/blob/main/packages/db/src/query/builder/index.ts#L501)
847​
848Select specific columns or computed values from the query
849​
850##### Type Parameters
851​
852###### TSelectValue
853​
854`TSelectValue` *extends* `ScalarSelectValue`
855​
856##### Parameters
857​
858###### callback
859​
860(`refs`) => `TSelectValue`
861​
862A function that receives table references and returns an object with selected fields or expressions
863​
864##### Returns
865​
866[`QueryBuilder`](../type-aliases/QueryBuilder.md)\<[`WithResult`](../type-aliases/WithResult.md)\<`TContext`, `ResultTypeFromSelectValue`\<`TSelectValue`\>\>\>
867​
868A QueryBuilder that returns only the selected fields
869​
870##### Example
871​
872```ts
873// Select specific columns
874query
875 .from({ users: usersCollection })
876 .select(({users}) => ({
877 name: users.name,
878 email: users.email
879 }))
880​
881// Select with computed values
882query
883 .from({ users: usersCollection })
884 .select(({users}) => ({
885 fullName: concat(users.firstName, ' ', users.lastName),
886 ageInMonths: mul(users.age, 12)
887 }))
888​
889// Select with aggregates (requires GROUP BY)
890query
891 .from({ posts: postsCollection })
892 .groupBy(({posts}) => posts.userId)
893 .select(({posts, count}) => ({
894 userId: posts.userId,
895 postCount: count(posts.id)
896 }))
897```
898​
899***
900​
901### where()
902​
903```ts
904where(callback): QueryBuilder<TContext>;
905```
906​
907Defined in: [packages/db/src/query/builder/index.ts:375](https://github.com/TanStack/db/blob/main/packages/db/src/query/builder/index.ts#L375)
908​
909Filter rows based on a condition
910​
911#### Parameters
912​
913##### callback
914​
915[`WhereCallback`](../type-aliases/WhereCallback.md)\<`TContext`\>
916​
917A function that receives table references and returns an expression
918​
919#### Returns
920​
921[`QueryBuilder`](../type-aliases/QueryBuilder.md)\<`TContext`\>
922​
923A QueryBuilder with the where condition applied
924​
925#### Example
926​
927```ts
928// Simple condition
929query
930 .from({ users: usersCollection })
931 .where(({users}) => gt(users.age, 18))
932​
933// Multiple conditions
934query
935 .from({ users: usersCollection })
936 .where(({users}) => and(
937 gt(users.age, 18),
938 eq(users.active, true)
939 ))
940​
941// Multiple where calls are ANDed together
942query
943 .from({ users: usersCollection })
944 .where(({users}) => gt(users.age, 18))
945 .where(({users}) => eq(users.active, true))
946```