Select
Builds a SELECT query. Extends Query directly and mixes in Node's
EventEmitter. See the Select Statement
guide for a full walkthrough.
Constructor
Select(...column: (string | string[] | SqlElement)[]): Select
new Select(...column: (string | string[] | SqlElement)[]): Select
Dual-callable — invoking it as a plain function returns a new instance, same as new. Any
columns passed are forwarded to .addColumn().
import { Select } from '@sqb/builder';
Select('id', 'given_name family_name');
new Select('id', 'given_name family_name'); // identical result
Properties
| Key | Type | Readonly | Description |
|---|---|---|---|
_type | SerializationType.SELECT_QUERY | Yes | Discriminates this node during serialization. |
_tables | SqlElement[] | undefined | No | Tables set by .from(). |
_columns | SqlElement[] | undefined | No | Columns added by the constructor / .addColumn(). |
_joins | Join[] | undefined | No | Joins added by .join(). |
_where | LogicalOperator | undefined | No | The implicit top-level And built by .where(). |
_groupBy | (GroupColumn | SqlElement)[] | undefined | No | Columns added by .groupBy(). |
_orderBy | (OrderColumn | SqlElement)[] | undefined | No | Columns added by .orderBy(). |
_limit | number | undefined | No | Set by .limit(). |
_offset | number | undefined | No | Set by .offset(). |
_alias | string | undefined | No | Set by .as(); required when this Select is used as a sub-query in columns/from/join. |
_distinct | boolean | undefined | No | Set by .distinct(). |
Plus everything inherited from Query (_comment, _params, EventEmitter).
Methods
addColumn()
addColumn(...column: (string | string[] | SqlElement)[]): this
Adds columns. Strings are tokenized on top-level commas (respecting brackets/quotes) and turned
into Field instances; arrays are flattened; falsy arguments are skipped.
Select().addColumn('id', 'given_name family_name');
Select().addColumn(['id', 'name']); // same as addColumn('id', 'name')
Select().addColumn('id, given_name family_name, gender'); // one string, comma-split into 3 columns
from()
from(...table: (string | TableName | Raw | Select | Union)[]): this
Sets the FROM clause. Replaces any previously set tables (unlike .join(), which appends).
String arguments become TableName instances. A sub-Select/Union must
carry an alias (.as()) or .generate() throws "Alias required for sub-select in \"from\"".
Select().from('customers');
Select().from('schema1.customers c', Raw('LATERAL func()'));
join()
join(...join: Join[]): this
Appends join clauses (each call adds to the existing list). Throws a TypeError
("Join statement required") if any argument is not a Join instance. See
Joins and the Join class.
where()
where(...condition: (SqlElement | object)[]): this
Accumulates conditions into an implicit top-level And (creating it on first use). Accepts
operator instances, Raw fragments, or object-literal shorthand — see
Operators and Conditions.
Select().from('customers').where(Eq('active', true)).where(Eq('country', 'US'));
// where active = true and country = 'US'
groupBy()
groupBy(...field: (string | SqlElement)[]): this
Adds GROUP BY columns; strings become GroupColumn instances.
orderBy()
orderBy(...field: (string | SqlElement)[]): this
Adds ORDER BY columns; strings become OrderColumn instances (supporting a
leading +/- or a trailing asc/desc/ascending/descending).
Select().from('customers').orderBy('-created_at', 'name asc');
// order by created_at desc, name
as()
as(alias: string): this
Sets the alias used when this Select is embedded as a sub-query in a column, a from(), or a
join's table.
limit()
limit(limit: number): this
Sets the row limit (coerced to an integer). Rendered SQL depends on the target dialect — see Generating SQL per dialect.
offset()
offset(offset: number): this
Sets the row offset (coerced to an integer).
distinct()
distinct(): this
Enables SELECT DISTINCT.
onFetch() / onceFetch()
onFetch(listener: (...args: any[]) => void): this
onceFetch(listener: (...args: any[]) => void): this
Registers a listener for the 'fetch' event (.on('fetch', listener) /
.once('fetch', listener)). @sqb/builder never emits this event itself — it's a hook point used
by @sqb/connect when streaming query results.
generate(), values(), comment()
Inherited from Query.