Interface RawBuilder<O>

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.

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 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)
Copy

The generated SQL (PostgreSQL):

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

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()
Copy

The generated SQL (PostgreSQL):

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

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<string>` returns an AliasableExpression<string>
    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)
Copy

The generated SQL (PostgreSQL):

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

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()
Copy

The generated SQL (PostgreSQL):

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

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)
Copy

Executes the raw query.

Examples

import { sql } from 'kysely'

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

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()
  }
}
Copy

Adds a plugin for this SQL snippet.