Skip to Content
Api ReferenceInterfacesRawBuilder

Last Updated: 3/10/2026

kysely

  • RawBuilder

Interface RawBuilder

An instance of this class can be used to create raw SQL snippets or queries.

You shouldn’t need to create RawBuilder instances directly. Instead you should use the sql template tag.

interface RawBuilder<O> {
    get expressionType(): undefined | T;
    get isRawBuilder(): true;
    $castTo<C>(): RawBuilder<C>;
    $notNull(): RawBuilder<Exclude<O, null>>;
    as<A extends string>(alias: A): AliasedRawBuilder<O, A>;
    as<A extends string>(alias: Expression<any>): AliasedRawBuilder<O, A>;
    compile(executorProvider: QueryExecutorProvider): CompiledQuery<O>;
    execute(executorProvider: QueryExecutorProvider): Promise<QueryResult<O>>;
    toOperationNode(): RawNode;
    withPlugin(plugin: KyselyPlugin): RawBuilder<O>;
}

Type Parameters

  • O

Hierarchy (View Summary)

Index

Accessors

expressionType isRawBuilder

Methods

$castTo $notNull as compile execute toOperationNode withPlugin

Accessors

expressionType

  • get expressionType(): undefined | T

    All expressions need to have this getter for complicated type-related reasons. Simply add this getter for your expression and always return undefined from it:

    Examples

    import { type  Expression, type  OperationNode, sql } from  'kysely' class  SomeExpression< T> implements  Expression< T> { get  expressionType(): T  |  undefined { return  undefined }  toOperationNode(): OperationNode { return  sql `some sql here`. toOperationNode() }}

    The getter is needed to make the expression assignable to another expression only if the types T are assignable. Without this property (or some other property that references T), you could assing Expression to Expression.

    Returns undefined | T

isRawBuilder

  • get isRawBuilder(): true

    Returns true

Methods

$castTo

  • $castTo<C>(): RawBuilder<C>

    Change the output type of the raw expression.

    This method call doesn’t change the SQL in any way. This methods simply returns a copy of this RawBuilder with a new output type.

    Type Parameters

    • C

    Returns RawBuilder<C>

$notNull

  • $notNull(): RawBuilder<Exclude<O, null>>

    Omit null from the expression’s type.

    This function can be useful in cases where you know an expression can’t be null, but Kysely is unable to infer it.

    This method call doesn’t change the SQL in any way. This methods simply returns a copy of this with a new output type.

    Returns RawBuilder<Exclude<O, null>>

as

  • as<A extends string>(alias: A): AliasedRawBuilder<O, A>

    Returns an aliased version of the SQL expression.

    In addition to slapping as "the_alias" to the end of the SQL, this method also provides strict typing:

    import { sql } from  'kysely' const  result = await  db . selectFrom('person') . select( sql< string>`concat(first_name, ' ', last_name)`. as('full_name') ) . executeTakeFirstOrThrow()// `full_name: string` field exists in the result type. console. log(result. full_name)

    The generated SQL (PostgreSQL):

    select concat(first_name, ' ', last_name) as "full_name" from "person"

    You can also pass in a raw SQL snippet but in that case you must provide the alias as the only type argument:

    import { sql } from  'kysely' const  values = sql<{ a: number, b: string }>`(values (1, 'foo'))`// The alias is `t(a, b)` which specifies the column names// in addition to the table name. We must tell kysely that// columns of the table can be referenced through `t`// by providing an explicit type argument. const  aliasedValues = values. as< 't'>(sql`t(a, b)`) await  db . insertInto('person') . columns(['first_name', 'last_name']) . expression( db. selectFrom(aliasedValues). select(['t.a', 't.b']) ) . execute()

    The generated SQL (PostgreSQL):

    insert into "person" ("first_name", "last_name") from (values (1, 'foo')) as t(a, b) select "t"."a", "t"."b"

    Type Parameters

    • A extends string

    Parameters

    • alias: A

    Returns AliasedRawBuilder<O, A>

  • as<A extends string>(alias: Expression<any>): AliasedRawBuilder<O, A>

    Returns an aliased version of the expression.

    Examples

    In addition to slapping as "the_alias" at the end of the expression, this method also provides strict typing:

    const  result = await  db . selectFrom('person') . select((eb) =>  // `eb.fn` returns an AliasableExpression  eb. fn< string>('concat', ['first_name', eb. val(' '), 'last_name']). as('full_name') ) . executeTakeFirstOrThrow()// `full_name: string` field exists in the result type. console. log(result. full_name)

    The generated SQL (PostgreSQL):

    select concat("first_name", $1, "last_name") as "full_name" from "person"

    You can also pass in a raw SQL snippet (or any expression) but in that case you must provide the alias as the only type argument:

    import { sql } from  'kysely' const  values = sql<{ a: number, b: string }>`(values (1, 'foo'))`// The alias is `t(a, b)` which specifies the column names// in addition to the table name. We must tell kysely that// columns of the table can be referenced through `t`// by providing an explicit type argument. const  aliasedValues = values. as< 't'>(sql`t(a, b)`) await  db . insertInto('person') . columns(['first_name', 'last_name']) . expression( db. selectFrom(aliasedValues). select(['t.a', 't.b']) ) . execute()

    The generated SQL (PostgreSQL):

    insert into "person" ("first_name", "last_name") from (values (1, 'foo')) as t(a, b) select "t"."a", "t"."b"

    Type Parameters

    • A extends string

    Parameters

    Returns AliasedRawBuilder<O, A>

compile

  • compile(executorProvider: QueryExecutorProvider): CompiledQuery<O>

    Compiles the builder to a CompiledQuery.

    Examples

    import { sql } from  'kysely' const  compiledQuery = sql`select * from ${sql. table('person')} `. compile(db) console. log(compiledQuery. sql)

    Parameters

    • executorProvider: QueryExecutorProvider

    Returns CompiledQuery<O>

execute

  • execute(executorProvider: QueryExecutorProvider): Promise<QueryResult<O>>

    Executes the raw query.

    Examples

    import { sql } from  'kysely' const  result = await  sql`select * from ${sql. table('person')} `. execute(db)

    Parameters

    • executorProvider: QueryExecutorProvider

    Returns Promise<QueryResult<O>>

toOperationNode

  • toOperationNode(): RawNode

    Creates the OperationNode that describes how to compile this expression into SQL.

    Examples

    If you are creating a custom expression, it’s often easiest to use the sql template tag to build the node:

    import { type  Expression, type  OperationNode, sql } from  'kysely' class  SomeExpression< T> implements  Expression< T> { get  expressionType(): T  | undefined { return  undefined }  toOperationNode(): OperationNode { return  sql `some sql here`. toOperationNode() }}

    Returns RawNode

withPlugin

  • withPlugin(plugin: KyselyPlugin): RawBuilder<O>

    Adds a plugin for this SQL snippet.

    Parameters

    Returns RawBuilder<O>

Settings

Member Visibility

On This Page

Accessors

expressionType

isRawBuilder

Methods

$castTo$notNullas

compile

execute

toOperationNode

withPlugin

CompiledQueryFunctionModule