---
title: "SQL Alias Formatting Process"
description: "The `as()` method in Drizzle ORM is a fundamental utility used to convert a query builder (such as a `select` statement) into a `Subquery` object, allowing the result of that query to be treated as..."
last_updated: "2026-07-02T09:35:18.672718+00:00"
canonical_url: "https://www.doc0.app/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/how-it-works/sql-alias-formatting-process"
---

<details>
<summary>Relevant source files</summary>

The following files were used as context for generating this wiki page:

- [drizzle-orm/src/gel-core/query-builders/select.ts](https://github.com/blade47/drizzle-orm/blob/main/drizzle-orm/src/gel-core/query-builders/select.ts)
- [drizzle-orm/src/gel-core/dialect.ts](https://github.com/blade47/drizzle-orm/blob/main/drizzle-orm/src/gel-core/dialect.ts)
- [drizzle-orm/src/sql/sql.ts](https://github.com/blade47/drizzle-orm/blob/main/drizzle-orm/src/sql/sql.ts)
</details>

The `as()` method in Drizzle ORM is a fundamental utility used to convert a query builder (such as a `select` statement) into a `Subquery` object, allowing the result of that query to be treated as a table alias for use in further joins or sub-select operations. 

When a user calls `.as('alias')` on a query builder, the system triggers a sequence that evaluates the current state of the query, compiles it into a structured SQL representation, and ultimately wraps the result in a proxy that manages column aliasing. This flow ensures that complex nested queries are correctly encapsulated and scoped within the final executed SQL.

### 1. `as` Method Invocation
The process starts in `GelSelectQueryBuilderBase.as(alias)`. This method gathers the tables currently used by the query and prepares to wrap the existing configuration. It acts as the orchestrator for turning the builder into a subquery.
Sources: [drizzle-orm/src/gel-core/query-builders/select.ts:987-998](https://github.com/blade47/drizzle-orm/blob/main/drizzle-orm/src/gel-core/query-builders/select.ts#L987-L998)

### 2. Retrieving Query State via `getSQL`
Inside `as()`, the builder calls `this.getSQL()` to convert its internal `config` object (containing `with`, `joins`, `where`, etc.) into an `SQL` class instance. This represents the raw structure of the statement being aliased.
Sources: [drizzle-orm/src/gel-core/query-builders/select.ts:978-980](https://github.com/blade47/drizzle-orm/blob/main/drizzle-orm/src/gel-core/query-builders/select.ts#L978-L980)

### 3. Dialect-Specific SQL Construction
`getSQL()` delegates the actual compilation to the `dialect.buildSelectQuery(config)` method. This is where Drizzle translates the JavaScript configuration object into an `SQL` instance by assembling parts like `with`, `select`, `from`, and `joins`.
Sources: [drizzle-orm/src/gel-core/dialect.ts:336-443](https://github.com/blade47/drizzle-orm/blob/main/drizzle-orm/src/gel-core/dialect.ts#L336-L443)

### 4. Building CTE Clauses
As part of the query construction, `buildSelectQuery` invokes `buildWithCTE(withList)`. This method iterates through any Common Table Expressions defined in the query, formatting them as `"alias" as (sql)` chunks to be prefixed to the main query.
Sources: [drizzle-orm/src/gel-core/dialect.ts:115-127](https://github.com/blade47/drizzle-orm/blob/main/drizzle-orm/src/gel-core/dialect.ts#L115-L127)

### 5. Finalizing as an SQL Object
The compilation process relies on the `sql` function, which accepts chunks (strings, identifiers, or other `SQL` instances) to produce the final `SQL` object that can be safely embedded into other queries.
Sources: [drizzle-orm/src/sql/sql.ts:485-495](https://github.com/blade47/drizzle-orm/blob/main/drizzle-orm/src/sql/sql.ts#L485-L495)

### 6. Component Encapsulation in `StringChunk`
During query generation, various parts of the SQL string are represented as `StringChunk` objects. This class encapsulates static strings, allowing them to be concatenated efficiently during the final serialization to the database dialect's syntax.
Sources: [drizzle-orm/src/sql/sql.ts:89-101](https://github.com/blade47/drizzle-orm/blob/main/drizzle-orm/src/sql/sql.ts#L89-L101)

### Sequence Diagram
```mermaid
sequenceDiagram
    participant B as GelSelectBuilder
    participant D as GelDialect
    participant S as SQL/SQL.ts
    
    B->>B: as(alias)
    B->>B: getSQL()
    B->>D: buildSelectQuery()
    D->>D: buildWithCTE()
    D->>S: sql(...)
    S->>S: new StringChunk()
    S-->>D: SQL object
    D-->>B: SQL object
    B-->>B: return Subquery(SQL)
```
Sources: [drizzle-orm/src/gel-core/query-builders/select.ts:987-998](https://github.com/blade47/drizzle-orm/blob/main/drizzle-orm/src/gel-core/query-builders/select.ts#L987-L998), [drizzle-orm/src/gel-core/dialect.ts:336-443](https://github.com/blade47/drizzle-orm/blob/main/drizzle-orm/src/gel-core/dialect.ts#L336-L443), [drizzle-orm/src/sql/sql.ts:485-495](https://github.com/blade47/drizzle-orm/blob/main/drizzle-orm/src/sql/sql.ts#L485-L495)

### Flowchart
```mermaid
flowchart TD
    A[Start As] --> B[Get Config]
    B --> C[Compile SQL]
    C --> D{Has CTEs?}
    D -- Yes --> E[Build CTEs]
    D -- No --> F[Build Query]
    E --> F
    F --> G[Wrap in StringChunk]
    G --> H[End Subquery]
```
Sources: [drizzle-orm/src/gel-core/query-builders/select.ts:987-998](https://github.com/blade47/drizzle-orm/blob/main/drizzle-orm/src/gel-core/query-builders/select.ts#L987-L998), [drizzle-orm/src/gel-core/dialect.ts:115-127](https://github.com/blade47/drizzle-orm/blob/main/drizzle-orm/src/gel-core/dialect.ts#L115-L127)

> [!NOTE]
> The `as` method returns a `Proxy`. This is critical because it allows the subquery to dynamically resolve column names when the subquery is referenced in an `ON` or `WHERE` clause of an outer query.

> [!IMPORTANT]
> The `StringChunk` class is only responsible for the literal segments of the SQL. Variables and identifiers are handled separately through `Param` and `Name` classes within the `SQL` instance.

### Key Observations
*   **Module Boundaries:** This flow begins in the query builder domain, transitions to the dialect (which handles DB-specific syntax), and finishes in the underlying `SQL` engine.
*   **Error Handling:** While `as` itself is straightforward, the subsequent query execution checks if referenced columns exist in the scope. If the subquery references an external table not included in the alias, the Dialect will throw a descriptive error during build-time.
*   **Performance:** The generation of the `SQL` object is lightweight. Because Drizzle constructs a tree of objects rather than concatenating strings immediately, query construction remains performant even for deeply nested subqueries.

## Sitemap

See the full [sitemap](https://www.doc0.app/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/llms.txt) for all pages in this wiki.