Getting Started
Database Drivers
Schema Integrations
Seed Generators
Utilities and Testing
The following files were used as context for generating this wiki page:
The as to StringChunk flow is a core mechanism in Drizzle ORM that enables the conversion of a Query Builder instance into a reusable subquery. When you define a query and append .as('alias') to it, Drizzle prepares the query's SQL structure to be embedded as a derived table or subquery within a larger statement.
This process transforms high-level query builder configurations into an internal SQL representation, ensuring that when the subquery is eventually used in a parent query, it is correctly wrapped and aliased to maintain query integrity.
asThe execution begins at the as() method within MySqlSelectQueryBuilderBase. This method takes the current query configuration, computes the set of used tables (for dependency tracking), and wraps the entire query in a Subquery object. It also applies a SelectionProxyHandler to ensure that column references within the subquery maintain the correct alias context.
Sources: drizzle-orm/src/mysql-core/query-builders/select.ts:1041-1052
getSQLTo build the subquery's internal SQL, the system calls getSQL(). This method delegates the heavy lifting to the MySqlDialect, which is responsible for translating the query builder's config object (containing joins, wheres, etc.) into a valid SQL string structure.
Sources: drizzle-orm/src/mysql-core/query-builders/select.ts:1032-1034
buildSelectQueryThe dialect's buildSelectQuery receives the query configuration. It orchestrates the assembly of various components, including the SELECT clause, JOIN clauses, and finally, any Common Table Expressions (CTEs) or set operators.
Sources: drizzle-orm/src/mysql-core/dialect.ts:312-486
buildWithCTEWithin the query assembly, the dialect invokes buildWithCTE to process any defined Common Table Expressions. This ensures that if the query depends on external definitions, they are prepended correctly to the WITH clause of the resulting SQL object.
Sources: drizzle-orm/src/mysql-core/dialect.ts:112-124
sqlThe sql function is the factory that consumes the chunks produced by the builder. It takes the strings and query fragments (tables, columns, expressions) and assembles them into an SQL class instance, which stores an array of chunks representing the final query tree.
Sources: drizzle-orm/src/sql/sql.ts:485-495
StringChunkFinally, the StringChunk class acts as the leaf node in the SQL tree. It stores the raw string segments of the SQL statement. When the final SQL object is serialized (or passed to the driver), these chunks are joined to form the executable string.
Sources: drizzle-orm/src/sql/sql.ts:89-101
Note
The as() method is the entry point for creating subqueries. It internally calls getSQL() to ensure the generated SQL is current with any modifications made to the builder prior to the alias being assigned.
Tip
Always verify that your subquery has an alias using .as('name'), as this is required for the database engine to correctly reference the derived table.
Sources: drizzle-orm/src/mysql-core/query-builders/select.ts:1041-1052, drizzle-orm/src/mysql-core/dialect.ts:312-486, drizzle-orm/src/sql/sql.ts:89-101
Sources: drizzle-orm/src/mysql-core/query-builders/select.ts:1032-1052, drizzle-orm/src/mysql-core/dialect.ts:112-486, drizzle-orm/src/sql/sql.ts:89-495
mysql-core query builder, through the dialect-specific query assembly, into the low-level SQL structure representation.buildSelectQuery in the dialect layer is designed to throw descriptive errors.StringChunk is deferred until necessary (lazy evaluation), which is efficient for building complex, nested queries without immediate string concatenation overhead.