Basics

Raw Query

Use raw fragments when you need SQL expressions that are not covered by helpers yet. This page covers the full raw query surface from the base raw query builder.

raw (alias: r)

Build SQL fragments with template literals. Interpolations accept other statements (columns, subqueries, or other builders).

const query = q
  .select(q.raw`COUNT(*)`)
  .from(q.t("users"))
const query = q
  .select(q.r`NOW()`)
  .from(q.t("audit_logs"))
const query = q
  .select(
    q.r`DATE_TRUNC('day', ${q.c("events.created_at")})`,
  )
  .from(q.t("events"))
const query = q
  .select(
    q.c("users.id"),
    q.r`, LOWER(${q.c("users.email")})`,
  )
  .from(q.t("users"))
const query = q.raw`
  SELECT ${q.c("users.id")}, ${q.c("users.name")}
  FROM ${q.t("users")}
  WHERE ${q.c("users.status")} = ${q.v("active")}
`

literal (alias: l)

Push literal values directly into the query, or resolve statements when passed a builder.

const query = q
  .select(q.literal("active"))
  .from(q.t("users"))
const query = q
  .select(q.l("active"))
  .from(q.t("users"))

literalArray

Emit a sequence of literal values and statements as parameters.

const query = q
  .select(
    q.literalArray([
      "active",
      q.raw`NOW()`,
      q.v(42),
    ]),
  )
  .from(q.t("users"))

identifier (alias: i)

Emit identifiers (table/column names) with proper quoting rules.

const query = q
  .select(q.identifier("users.created_at"))
  .from(q.t("users"))
const query = q
  .select(q.i("users.created_at"))
  .from(q.t("users"))

identifierArray

Emit a sequence of identifiers and statements.

const query = q
  .select(
    q.identifierArray([
      "users.id",
      "users.email",
      q.raw`LOWER(${q.c("users.email")})`,
    ]),
  )
  .from(q.t("users"))

rawString (alias: rs)

Inject a string as-is into the SQL token stream. Use this only for trusted values that are already safe SQL.

const query = q
  .select(q.rawString("NOW()"))
  .from(q.t("audit_logs"))
const query = q
  .select(q.rs("NOW()"))
  .from(q.t("audit_logs"))
const query = q
  .select(q.rs("NULL::uuid"))
  .from(q.t("events"))
const query = q
  .select("*")
  .from(q.t("posts"))
  .limit(q.rs("ALL"))
  .offset(q.rs("10"))

v

Push a literal value or resolve a statement and emit its tokens.

const query = q
  .select(q.v("active"))
  .from(q.t("users"))
const query = q
  .select(q.v(q.raw`NOW()`))
  .from(q.t("events"))

percentCharacter

Emit a percent character token for safe LIKE expressions.

const query = q
  .select(
    q.r`LOWER(${q.c("users.email")}) LIKE ${q.percentCharacter()}`)
  .from(q.t("users"))

op

Emit operator tokens and values together. Operators are validated against the supported operator list.

const query = q
  .select(q.c("users.id"))
  .from(q.t("users"))
  .where(
    q.op(q.c("users.status"),"=", q.v("active")),
  )

Behavior Notes

The identifier alias has special handling for wildcards and NULL.

// if null is passed to the identifier helper, it emits a raw "NULL" token instead of a parameter.
const query = q
  .select(q.i("*"), q.i(null)) // emits "*" and "NULL" tokens, not parameters.
  .from(q.t("users"))