1. dialects
prorm
  • prorm documentation
  • Known test gaps
  • Architecture
  • Core concepts
  • Database types & coverage
  • Getting started
  • Going further
  • compliance
    • Compliance
    • The security toolkit: `prorm audit`
    • Checklists by regulation
    • Declaring personal data
    • Evidence bundles
    • Evidence
    • Frameworks: `@Security`
    • Jurisdictions
    • Platform policies
    • Protecting data
    • The regulation dataset
    • Residency and cross-border transfers
    • Retention & integrity
    • Status
    • Subject rights
  • decorators
    • prorm with decorators
    • Models with decorators
    • Querying a decorated model
    • Relations with decorators
  • diagrams
    • Diagram generators
    • Chen diagram
    • Class diagram
    • Dependency diagram
    • ER diagram
    • Flow diagram
    • From your models to a diagram
    • Gantt diagram
    • Index diagram
    • Migration diagram
    • Model diagram
    • Package diagram
    • Crow’s-foot diagram
    • Schema documentation
    • Sequence diagram
    • State diagram
    • Tree diagram
  • dialects
    • SQL dialects
    • AlloyDB Dialect
    • AlloyDB Omni Dialect
    • Amazon Athena Dialect
    • Aurora DSQL Dialect
    • Amazon Aurora MySQL Dialect
    • Amazon Aurora PostgreSQL Dialect
    • Azure Database for MySQL Dialect
    • Azure Database for PostgreSQL Dialect
    • Azure SQL Database Dialect
    • Azure SQL Managed Instance Dialect
    • Google BigQuery Dialect
    • Citus Dialect
    • ClickHouse dialect
    • Cloud Authentication (`cloud-auth`)
    • Cloud SQL for SQL Server Dialect
    • Cloud SQL for MySQL Dialect
    • Cloud SQL for PostgreSQL Dialect
    • CockroachDB Dialect
    • Azure Cosmos DB for PostgreSQL Dialect
    • CrateDB Dialect
    • Cloudflare D1 Dialect
    • Databricks dialect
    • IBM Db2 Dialect
    • Dolt Dialect
    • Apache Doris Dialect
    • Druid Dialect
    • DuckDB Dialect
    • Exasol dialect
    • Microsoft Fabric Data Warehouse Dialect
    • Firebird Dialect
    • Greenplum Dialect
    • SAP HANA Dialect
    • MySQL HeatWave Dialect
    • Azure Data Explorer (Kusto) Dialect — T-SQL
    • MariaDB Dialect
    • Materialize Dialect
    • MonetDB Dialect
    • MotherDuck Dialect
    • Microsoft SQL Server Dialect
    • MySQL Dialect
    • Neon Dialect
    • OceanBase Dialect
    • openGauss Dialect
    • Oracle Dialect
    • Oracle Autonomous Database Dialect
    • ParadeDB Dialect
    • PolarDB Dialect
    • PostgreSQL Dialect
    • Presto Dialect
    • QuestDB Dialect
    • Aurora RDS Data API Dialect (`rdsdata`)
    • Amazon RDS for Db2 Dialect
    • Amazon RDS for MariaDB Dialect
    • Amazon RDS for SQL Server Dialect
    • Amazon RDS for MySQL Dialect
    • Amazon RDS for Oracle Dialect
    • Amazon RDS for PostgreSQL Dialect
    • Amazon Redshift
    • Amazon Redshift Data API Dialect
    • RisingWave Dialect
    • rqlite Dialect
    • SingleStore Dialect
    • Snowflake Dialect
    • Google Cloud Spanner Dialect
    • Spanner (PostgreSQL interface) Dialect
    • SQLite Dialect
    • StarRocks Dialect
    • Supabase Dialect
    • Azure Synapse Analytics (dedicated SQL pool)
    • Teradata Dialect
    • TiDB Dialect
    • TimescaleDB Dialect
    • Trino Dialect
    • Turso / libSQL Dialect
    • Vertica dialect
    • Vitess Dialect
    • Yellowbrick Dialect
    • YugabyteDB Dialect
  • guides
    • Access rules and behaviour profiles
    • ArangoDB (AQL)
    • Associations
    • Audit levels and escalation
    • Audit logging
    • In the browser
    • Bulk operations
    • Caching
    • Capabilities, tiers and team roles
    • CLI
    • Cloudflare
    • Compliance & data protection
    • Connection Pooling & Performance
    • Security in the console
    • Couchbase: structured N1QL queries
    • Data types
    • Decorators
    • Eager loading
    • Enums and constants
    • Error handling & error types
    • Extensions
    • External fields
    • Foreign data wrappers
    • Graph databases
    • Hooks & lifecycle events
    • Indexes & constraints
    • InfluxDB: structured Flux pipelines
    • klock-errors
    • klock — the `.klock` file
    • Local databases (`prorm db up`)
    • Structured log search — Splunk, Graylog, Papertrail, Sumo Logic
    • Logging
    • Grafana Loki: structured LogQL queries
    • MCP server
    • Migrate — the data transfer subsystem
    • Migrations & Schema Sync
    • Models from an existing database
    • Defining models
    • Multiple databases
    • OrientDB, Neptune and TigerGraph
    • Passwords
    • Importing a Prisma schema
    • Structured PromQL and MetricsQL
    • Query firewall
    • QueryInterface
    • Query operators reference
    • Query optimization
    • Composing find options with `pipe()` and `Q`
    • Query safety: the fail-closed WHERE guard
    • Querying
    • Raw Queries & Query Building
    • Read replicas
    • Schema diffing & migration generation
    • Views, triggers & other schema objects
    • Scopes & default scopes
    • Seeders
    • SPARQL / RDF triplestores
    • SQL constants
    • SQL features
    • SQL function builders
    • SQLite advanced features
    • StoreKey — a prod-orm database as the storage
    • Streaming results
    • Terraform
    • Transactions & Isolation Levels
    • Type mapping: legacy and modern
    • TypeScript types
    • Database users, roles & privileges
    • Validation & constraints
    • Virtual & Computed Fields
    • Writing docs
  • javascript
    • prorm in JavaScript
    • Models in JavaScript
    • Querying in JavaScript
    • Relations in JavaScript
  • runbooks
    • Operational runbooks
    • Connection failures
    • Credential rotation
    • Failover
    • Incident checklist
    • Deploying klock v2
    • Migration rollback
  • running-databases
    • Running databases in Docker
    • Running prorm under Bun in Docker
    • Running Cassandra in Docker with prorm
    • Running ClickHouse in Docker with prorm
    • Running CockroachDB in Docker with prorm
    • Running prorm under Deno in Docker
    • Running Elasticsearch in Docker with prorm
    • Running MariaDB in Docker with prorm
    • Running MongoDB in Docker with prorm
  • prorm control plane
    • Introduction
    • Authentication
    • Errors
    • Getting started
      • Service
        • Is it up
        • This description
    • Account
      • Sign-up and verification
        • Create an account
        • Exchange credentials for a token
        • Verify with the emailed code
        • Verify by clicking the emailed link
        • Name the parent or guardian
        • What a consent link is about
        • Give consent for a child's account
        • Ask the parent or guardian again
        • Send a new code and link
      • Family
        • Everyone this account is responsible for
        • One child, in detail
        • Turn a limit on or off
      • Profile
        • Who am I
        • Change the account
        • Every address on the account
        • Add an address
        • Confirm an address with the code mailed to it
        • Mail a fresh code to an unconfirmed address
        • Make an address primary
        • Remove an address
        • What this caller may do
    • Security
      • Sessions
        • Everywhere this account is signed in
        • Sign out everywhere else
        • Sign one out
        • A token for the CLI on a named machine
        • A token for the customer console, from the staff one
        • Park a sign-in for the CLI to collect
        • The CLI collecting its sign-in
        • The team's members' live sessions
        • Sign a member's session out
        • Sign an account out everywhere
        • Everywhere the account is signed in
        • Sign an account's session out
      • Single sign-on
        • Begin a single sign-on
        • The provider's return
        • Link the signed-in account to a team's provider
        • Which team an address signs in to
        • The team's single sign-on, as a member sees it
        • Set the team's OpenID Connect provider up, or change it
        • Remove the provider
        • The team's domain claims and the DNS record each needs
        • Prove a claimed domain
      • MFA and passwords
        • Start enrolling a second factor
        • Prove the app has it
        • Remove the second factor
        • Ask for a reset link
        • Set a new password with the emailed token
      • Klock
        • Open a device-bound klock session
        • Check in, for the next grant
        • Step up the session asking
        • Rotate the device key
        • Freeze a session
        • Unfreeze a session
        • A guest grant
        • The revocation feed
        • The published keyset
        • What this control plane supports
      • Devices
        • Your devices, or a team's
        • Approve a new device's pairing code
        • One device
        • Rename a device
        • Revoke a device
        • Suspend a device
        • Reinstate a suspended device
        • Wipe a device
        • Ask a device to rotate its key
        • The team's members' devices
        • Revoke a member's device
        • An account's devices
        • Revoke an account's device
        • Wipe an account's device
        • The device fleet
      • Access rules and behaviour
        • The access rules that bear on you
        • Add an access rule
        • This request, as the rules see it
        • One access rule
        • Remove an access rule
        • The behaviour profiles that bear on you
        • Add or change a behaviour profile
        • The profile presets
        • Your behaviour findings
        • Acknowledge a finding
        • One behaviour profile
        • Remove a behaviour profile
        • The team's access rules
        • Add a team access rule
        • Remove a team access rule
        • The team's behaviour profiles
        • Add or change a team behaviour profile
        • Remove a team behaviour profile
        • What the team's profiles caught
        • Acknowledge a team finding
      • Recovery and lockdown
        • Ask for a recovery link
        • Recover access with the emailed code
        • Is the account locked down
        • Lock the account down
        • Release a lockdown
        • Lock a member down
        • Release a member's lockdown
      • MCP tokens
        • Make a delegated token for one MCP client
        • The account's delegated tokens
        • Revoke a delegated token
        • What a delegated token may do now
        • Run one MCP tool with a delegated token
        • Run a device-signed MCP tool call relayed by the MCP Worker
      • Kerberos
        • Give the team its own Kerberos realm
        • The team's realm
        • Remove the team's realm
    • Logging and monitoring
      • Audit log
        • What has been done to the account
        • What has happened to this account
        • The account's audit trail
      • Operations
        • Everything that has been asked of this database
        • One, with its steps
        • Stop it
        • Put a failed one back in the queue
        • Every operation, across all accounts
      • Metrics and events
        • Every measurement, for a graph
        • Who did what to it
    • Billing
      • Plans and pricing
        • What the plans allow
        • The rate card
        • What one database would cost
        • What this account is paying for, itemised
      • Subscriptions and invoices
        • What this month's invoice will say
        • What this account is on
        • What it has been charged
        • Start a Stripe Checkout session
        • Open the customer portal
        • Stripe's events
        • Buy more connection pools
      • Team billing
        • The team's billing account
        • What the team has been charged
        • What this month's invoice will say
        • The team's cards
        • Add a card, through a Stripe-hosted setup session
        • Make a card the team's default
        • Remove a card
        • Start the team paying
        • Open the Stripe portal on the team's customer
        • Change the team's plan
        • Who receives the team's bills
        • How the team pays for transfers
    • Support
      • Support chat
        • My conversations
        • Start a conversation
        • Every support conversation, open first
        • A ticket for the socket
        • One conversation, with who is in it and who is connected
        • Rename a group; open or close a support conversation
        • The lines, oldest first
        • Say something
        • Add somebody
        • Mark read
    • Administration
      • Users
        • Every account
        • One account, with everything hanging off it
        • Grant or revoke admin
        • Verify an account by hand
        • Lock or unlock sign-in
        • Allow or hold provisioning
        • Send the verification mail again
        • Set the plan by hand
      • Platform
        • Every database and store, across all accounts
        • The counts worth putting on a dashboard
      • Staff and permissions
        • What kind of admin the caller is, and which scopes they hold
        • The admin presets
        • Every admin, and the scopes each resolves to
        • Make an account an admin of a kind
        • Change an admin's kind, or a custom admin's scopes
        • Revoke admin
      • Team administration
        • Every team, with its owner and size
        • One team in full — members with their accounts, and projects
        • Hand the team to another member
        • Put an account in the team, active at once
        • Change a member's role
        • Remove a member
      • Assumed identities
        • Assume an identity — act as a customer account
        • The identities the caller holds open
        • End an assumed identity
      • Support inbox
        • The platform's addresses
        • Add a platform address
        • One address, with its counts
        • Change an address's label, routing, or whether it accepts mail
        • Remove an address that holds no mail
        • Make, adopt or repair the address's routing rule
        • Every admin's personal address, made where missing
        • File a raw message, as if it had arrived
        • The inbox
        • One message, whole
        • Mark a message
        • Hand a message to an admin, or take it back
        • Leave an internal note
        • Reply, from the address the message came to
        • What is waiting
    • Databases
      • Databases
        • Data stores
          • Every data store on the account
          • Provision a data store
          • Change a data store that is already running
          • One data store
          • Deprovision it
          • Report what it is using
          • How to reach a data store
        • Connections and credentials
          • The api keys on a database
          • Issue a key
          • Revoke a key
          • The engine users we created
          • Create a user inside the database
          • Give a user a new password
          • Drop a user
          • How the database is reached
          • Set how it is reached
          • Revoke every api key on it
          • How to connect to it
          • The ssh keys that open its bastion
          • Add a key, or have one made
          • The private half of a generated key, once
          • Revoke an ssh key
        • Schema and objects
          • The SQL objects we put in it
          • Create one, and apply it
          • What is in the database, as the engine reports it
          • One table
          • What it would run, without running it
          • Redefine an object in place
          • Drop it
          • The extensions installed in it
        • Migrations
          • A plan compiled to statements, recording nothing
          • The migrations recorded for it
          • Record one
          • Apply everything recorded and not yet run
          • Apply everything pending, oldest version first
        • Lifecycle
          • Grow or shrink it
          • Stop it accepting connections
          • Start it again
          • Move it to another region
        • Backups and replicas
          • Take a backup
          • The backups it has
          • Restore one into it
          • What has been restored into it, and from where
          • Its read copies
          • Add one
        • Policies
          • The catalog
          • One policy
          • What this database is held to
          • Switch a policy on, or change its knobs
          • Switch it off
          • Mark the policies reviewed
          • Evaluate the periodic policies now
          • Who is behind a credential
        • Passwordless
          • The database's passwordless sessions
          • Issue a passwordless session (v1)
          • Revoke a passwordless session
          • Bind a session to a device key
          • Issue a v2 session for a host to bind
          • Redeem an enrolment ticket on the host
          • Check a passwordless credential
          • Run one described query under a passwordless credential
        • Database roles
          • The database's roles
          • Define a role
          • One role
          • Change what a role permits
          • Delete a role, and revoke every key granted it
          • Grant a role, which mints a key
          • Who holds a role
          • The api keys bound to a role
        • Pools
          • A database's connection pools, and how busy each is
          • Open another pool
          • Rename a pool or change its size
          • Close a pool
        • Data plane
          • Run a query against a database
          • Several statements, in order, over one connection
          • Is this database answering
          • What the proxy itself is holding
        • Transfers
          • The strategies this account's tier may use
          • Price a transfer without creating it
          • The account's transfer jobs, newest first
          • Create a transfer job
          • One job, and whether its certificate holds
          • Cancel an unfinished job
          • Start a created job, confirming its price
          • Report a job's status (the runner, or the owner's side of a local run)
        • Every database on the account
        • Provision a database
        • Change a database that is already running
        • One database
        • Deprovision it
        • Read or write it
        • Report what it is using
        • The engines this API will provision
        • Where a managed database can be put
    • Teams
      • Teams
        • Members
          • Who is on it
          • Invite somebody
          • Accept an invitation
          • Change somebody's role
          • Remove somebody
        • Projects
          • The projects a team runs
          • Start one
          • Rename a project, or move its environment
          • Delete a project
          • One project, and what is in it
          • Put a database or store in it
          • What is in a project
          • Take one out
        • The teams this account is on
        • Start one
        • The twelve roles, and what each may do
        • Rename a team
        • Close a team
        • One team
        • Hand the team to somebody else
        • Leave a team
    • Schemas
      • Error
      • ValidationErrors
      • Token
      • PolicyCategory
      • PolicySeverity
      • PolicyAction
      • PolicyTrigger
      • PolicyParam
      • Policy
      • PolicyCatalog
      • PolicyAssignment
      • PolicyOutcome
      • PolicyFiring
      • CredentialTrace
      • Relation
      • Restrictions
      • ChildSummary
      • SignupRequest
      • SigninRequest
      • UpdateMeRequest
      • User
      • Address
      • GeoPoint
      • D1Region
      • Usage
      • UsageReport
      • Resource
      • Database
      • DataStore
      • NewDatabase
      • NewDataStore
      • QueryRequest
      • DatabasePrivilege
      • ApiKey
      • DbUser
      • Access
      • AccessRequest
      • DatabaseObject
      • NewDatabaseObject
      • NewMigration
      • SchemaOperation
      • Migration
      • Operation
      • Session
      • AdminPowers
      • Admin
      • AuditEntry
      • TeamRole
      • Conversation
      • ChatMessage
      • TeamSso
      • Team
      • TeamMember
      • SshKey
      • ConnectionInfo
      • InboxAddress
      • InboxMailbox
      • InboxMessageSummary
      • InboxMessage
      • InboxNote
      • Page
      • Quote
      • Plan
      • ApiError
      • CapabilityRefusal
      • KlockErrorCode
      • PageWindow
      • SessionView
      • KlockStepUpRequest
      • KlockOpenRequest
      • KlockOpenedSession
      • UpdateMeResult
      • CapabilitiesView
      • SessionLimits
      • Device
      • DeviceListed
      • DeviceTeamRef
      • DeviceCommand
      • DeviceAuditLine
      • DeviceActionRequest
      • StaffActionRequest
      • ManagedSession
      • SessionRevoked
      • AccessRule
      • AccessRuleRequest
      • BehaviourProfile
      • BehaviourProfileRequest
      • BehaviourProfileSaved
      • BehaviourFinding
      • BehaviourFindingAck
      • StepUpProof
      • Removed
      • MemberLockdownRequest
      • McpClient
      • McpDelegatedView
      • McpToolCall
      • McpForwardRequest
      • PasswordlessScope
      • RoleScope
      • PasswordlessSession
      • PasswordlessTlsMaterial
      • PasswordlessKerberosMaterial
      • ServiceDeviceKeys
      • ServiceSession
      • DatabaseRole
      • TransferEndpoint
      • TransferJobRequest
      • TransferQuote
      • TransferStrategy
      • TransferJob
      • TransferJobAccess
      • Pool
      • PoolAllowance
      • BillingSubscription
      • Invoice
      • BillingContact
      • PaymentMethod
      • UpcomingCharges
      • TeamBilling
      • TeamKerberosRealm
      • TeamSsoDomain
      • TeamSsoResponse
      • StoreConnection
      • BatchFailure
      • ProxyStatus
  1. dialects

Druid Dialect

Reference for the druid SQL dialect (Apache Druid).
Source: druid
Tests: druid

Overview#

Apache Druid is a real-time analytics database,
queried with Druid SQL (an ANSI dialect planned by Apache Calcite) over HTTP.
It is read-mostly. It has no row-level INSERT ... VALUES, UPDATE or
DELETE, no transactions and no CREATE TABLE. A datasource is created by
ingesting data into it, and SQL ingestion runs as a batch task on the
multi-stage query (MSQ) engine.
PropertyValue
Dialect namedruid
ExtendsSQLiteDialect (sqlite)
Drivernone — global fetch
Cloud SDKnone
Default port8888 (the Router)
Local runtimeself-hosted; no image in this repo
DruidDialect extends SQLiteDialect. SQLite's builders emit
double-quoted identifiers, LIKE, LIMIT n OFFSET m and ? placeholders.
Druid SQL reads all of these as they are, and ? is exactly Druid's
dynamic-parameter syntax, so the { sql, values } that buildSelectQuery()
returns goes straight onto the wire. (PostgreSQL's builders emit $n, ILIKE
and = ANY(...), which Druid does not accept.) RqliteDialect has the same
structure: SQLite's builders with a fetch transport.
export class DruidDialect extends SQLiteDialect {
  // name === 'druid'; library === 'fetch'
}
Relation to DruidStore. src/nosql/druid already has a DruidStore. It
is a thin NoSqlStore for raw SQL, native JSON queries and native
index_parallel tasks. DruidDialect is the SQL Dialect that Prorm builds
for dialect: 'druid', and it adds the ORM's query builders, typed parameters,
cancellation and MSQ ingestion. Both classes default to the Router on :8888,
use fetch, accept extra headers and raise DatabaseError.

Quick start#

Install#

$ npm install ts-prorm-orm
$ pnpm add ts-prorm-orm
$ yarn add ts-prorm-orm
$ bun add ts-prorm-orm
No driver package: the dialect talks to the service over fetch.

Connect#

import { Prorm } from 'ts-prorm-orm';

export const db = new Prorm({
  dialect: 'druid',
  host: 'druid-router.internal', // port defaults to 8888 (the Router)
});
import { Prorm } from 'ts-prorm-orm';

export const db = new Prorm({
  dialect: 'druid',
  url: 'druid://druid-router.internal:8888',
});
A URL is folded into host, port, database, username and password before the dialect is built; any of those passed alongside it wins.

Define a model#

import { DataTypes } from 'ts-prorm-orm';

const User = db.define('User', {
  id: { type: DataTypes.INTEGER(), primaryKey: true, autoIncrement: true },
  email: { type: DataTypes.STRING(255), allowNull: false, unique: true },
  name: { type: DataTypes.STRING(100) },
});

await db.sync(); // CREATE TABLE — see Generated SQL below
[!WARNING] db.sync() cannot create this table
CREATE TABLE is not supported on druid. Druid has no CREATE statements. A datasource is created by ingesting into it (buildInsertIngestion + submitIngestion).

Query#

import { Op } from 'ts-prorm-orm';

const page = await User.findAll({
  where: { name: { [Op.like]: 'A%' } },
  order: [['id', 'ASC']],
  limit: 20,
  offset: 40,
});

Generated SQL#

Each block is the statement the model call above it hands the dialect's query(), captured with the driver stubbed out. The model layer inlines the values.

Insert, update and delete#

[!WARNING] No row-level insert
INSERT ... VALUES is not supported on druid. Druid ingests in batches: buildInlineExtern() + buildInsertIngestion(), then submitIngestion()
[!WARNING] No row-level update
UPDATE is not supported on druid. Druid has no UPDATE. Rewrite the affected time range with REPLACE INTO ... OVERWRITE (buildReplaceIngestion) selecting from the datasource itself.
[!WARNING] No row-level delete
DELETE is not supported on druid. Druid has no row DELETE. Reindex without the rows: REPLACE INTO ... OVERWRITE with a SELECT that filters them out (buildReplaceIngestion).

Upsert#

[!WARNING] No upsert
Upsert is not supported on druid. Rewrite the time range with buildReplaceIngestion()

Pagination#

await User.findAll({
  where: { name: { [Op.like]: 'A%' } },
  order: [['id', 'ASC']],
  limit: 20,
  offset: 40,
});

Transaction#

[!CAUTION] No transactions
Transactions is not supported on druid. Each query and each ingestion task stands alone
Type mapping for the portable descriptors: STRING → VARCHAR, auto-increment INTEGER → INTEGER, BOOLEAN → BOOLEAN, DATE → TIMESTAMP, UUID → VARCHAR, JSON → COMPLEX<json>. The type comparison lines the major engines up side by side.

Connection: the Druid SQL API#

There is no driver. fetch is global from Node 18.
import { Prorm } from 'ts-prorm-orm';

const orm = new Prorm({ dialect: 'druid', host: 'druid-router.internal', logging: false });
// or directly:
const d = new Prorm({
  dialect: 'druid',
  host: 'druid-router.internal', // port defaults to 8888 (the Router)
  username: 'analyst', // HTTP Basic (basic-security extension)
  password: process.env.DRUID_PASSWORD,
  dialectOptions: {
    protocol: 'https', // default 'http'
    context: { sqlTimeZone: 'UTC' }, // query context on every request
  },
});
await d.connect(); // probes GET /status/health
OptionDefaultEffect
url—Full base URL; takes precedence over protocol/host/port
host, port, protocollocalhost, 8888, 'http'Router (or Broker) address
username, password—Authorization: Basic ...
headers—Extra headers on every request (overrides Basic, same option as DruidStore)
context—Query context merged into every query and ingestion
queryTimeoutMs300000Client-side abort + cluster-side cancel, and the timeout context value
fetchglobal fetchInjectable for tests and proxies
CallEndpoint
query(sql, { replacements })POST /druid/v2/sql
cancel(sqlQueryId)DELETE /druid/v2/sql/{sqlQueryId}
connect() / ping()GET /status/health (expects true)
getDatabaseVersion()GET /status → version
submitIngestion(stmt)POST /druid/v2/sql/task → { taskId, state }
getTaskStatus(id) / waitForTask(id)GET /druid/indexer/v1/task/{id}/status
cancelTask(id)POST /druid/indexer/v1/task/{id}/shutdown
markDatasourceUnused(name)DELETE /druid/indexer/v1/datasources/{name} (Overlord, via the Router)
Each query is sent as
{ query, parameters, context, resultFormat: 'array', header: true, typesHeader: true, sqlTypesHeader: true }.
The three header rows give the column names, the Druid types and the SQL types.
Rows come back as objects keyed by column name. fields[].type holds the SQL
type, and TIMESTAMP/DATE columns are returned as Date.
Cancellation. Every query has a sqlQueryId in its context. You can pass
your own; otherwise prorm-<uuid> is generated. When queryTimeoutMs passes,
the request is aborted, DELETE /druid/v2/sql/{sqlQueryId} stops the query on
the cluster, and a DruidError is thrown.
Errors. Druid returns JSON bodies with error, errorMessage,
errorClass, errorCode, category, persona and host. These surface as a
DruidError (a DatabaseError) that carries those fields and the HTTP
status. A transport failure has status 0.

Values: typed dynamic parameters#

Every value is sent as a { type, value } parameter and is never spliced into
the SQL. Druid needs a type for every parameter, so the dialect infers one
(toDruidParameter):
JS valueParameter
stringVARCHAR
null / undefinedVARCHAR null
booleanBOOLEAN
safe integer, safe bigintBIGINT
other finite numberDOUBLE
DateTIMESTAMP, 'yyyy-MM-dd HH:mm:ss.SSS' UTC
array of scalarsARRAY (e.g. SCALAR_IN_ARRAY(col, ?), ARRAY_CONTAINS)
plain objectVARCHAR JSON (wrap as PARSE_JSON(?))
new DruidTypedValue('FLOAT', 1.5)exactly as given
NaN/Infinity, unsafe bigint, Buffer, Literal, nested arraysrefused
Named :name replacements are rewritten to ? outside string literals, and
their values are appended in order of appearance, because Druid parameters are
positional only.

What differs from SQLite#

DruidDialect extends SQLiteDialect (sqlite) and
overrides 158 of its methods (Object.getOwnPropertyNames(DruidDialect.prototype),
computed by the scratch test); everything else is inherited unchanged.
AreaOverridden
Connection and executioncommitTransaction, connect, disconnect, getConnection, isConnected, ping, query, queryStream, rollbackTransaction, startTransaction
DML buildersbuildDeleteQuery, buildIncrementQuery, buildInlineExtern, buildInsertIngestion, buildInsertQuery, buildJsonContains, buildJsonExtract, buildJsonGroupArray, buildJsonGroupObject, buildJsonHasKey, buildJsonPatch, buildJsonPathQuery, buildJsonTable, buildLimitOffset, buildUpdateQuery, buildUpsertQuery, bulkInsert, escape
TypesgetDataTypeSql
DDL and schemaaddColumn, addConstraint, addForeignKey, addIndex, addPartition, analyze, attachDatabase, attachPartition, changeColumn, changeOwner, createComputedColumn, createConstraint, createDatabaseSQL, createExpressionIndex, createExtension, createForeignDataWrapper, createForeignServer, createForeignTable, createFulltextIndex, createIdentityColumn, createIndex, createMaterializedView, createPartialIndex, createPartition, createPartitionedTable, createPolicy, createProcedure, createRole, createSavepointSQL, createSchema, createSecurityPolicy, createSequence, createSpatialIndex, createStoredProcedure, createTable, createTrigger, createUser, createView, detachDatabase, detachPartition, disableRLS, dropConstraint, dropDatabaseSQL, dropExtension, dropForeignDataWrapper, dropForeignServer, dropIndex, dropMaterializedView, dropPartition, dropPolicy, dropProcedure, dropRole, dropSchema, dropSecurityPolicy, dropSequence, dropStoredProcedure, dropTable, dropTrigger, dropUser, dropView, enableRLS, enableRowLevelSecurity, refreshMaterializedView, removeColumn, removeConstraint, removeIndex, renameColumn, renameTable, vacuum
IntrospectionassertQueryable, cancel, cancelTask, describeTable, getCreateTable, getDatabaseInfo, getDatabaseVersion, getExtensions, getMariaDBVersionInfo, getTableStatus, getTaskStatus, hasExtension, hasMaterializedView, hasPartition, hasPolicy, hasSequence, hasStoredProcedure, hasTrigger, listPartitions, listRoles, listSchemas, listSequences, listUsers, showAllSchemas, showConstraints, showIndexes, showMaterializedViews, showTables, showViews
OtherbuildExtern, buildParameters, buildReplaceIngestion, buildRequestHeaders, bulkDelete, bulkUpdate, commentColumn, commentTable, executeStoredProcedure, fullTextSearch, grant, ingestionParts, markDatasourceUnused, nextSequenceValue, refuse, releaseSavepointSQL, renderExtract, revoke, rollbackToSavepointSQL, send, shapeResult, stAsText, stContains, stDWithin, stDistance, stGeomFromText, stIntersects, stWithin, submitIngestion, timestampLiteral, waitForTask

SQL differences from SQLite#

SQLite dialectDruid dialect
Offset without limitLIMIT -1 OFFSET mOFFSET m
Boolean / date literal1, '2024-...'TRUE, TIMESTAMP '2024-01-01 00:00:00.000'
JSON extractjson_extract(...)JSON_VALUE(col, '$.p' RETURNING VARCHAR) / JSON_QUERY
TypesSQLite affinitiesVARCHAR, BIGINT, DOUBLE, FLOAT, BOOLEAN, TIMESTAMP, DATE, COMPLEX<json>; TIME/BLOB/GEOMETRY refused
Metadatasqlite_master, PRAGMAINFORMATION_SCHEMA.TABLES / COLUMNS / SCHEMATA (schema druid)
__time is the primary timestamp column. TIME_FLOOR, TIME_PARSE and the
other time functions are ordinary Druid SQL that you write in raw SQL or in
Literals. $iLike compiles to LIKE, as it does on SQLite, and Druid's
LIKE is case-sensitive because Druid has no ILIKE. For
case-insensitive matching, use LOWER(col) LIKE ... or
ICONTAINS_STRING(col, ?).

Writes: SQL-based ingestion#

const src = d.buildInlineExtern(
  [{ ts: '2024-01-01T00:00:00Z', page: 'Main', added: 3 }],
  [
    { name: 'ts', type: 'string' },
    { name: 'page', type: 'string' },
    { name: 'added', type: 'long' },
  ],
);
const stmt = d.buildInsertIngestion({
  table: 'wikipedia',
  select: `SELECT TIME_PARSE("ts") AS __time, "page", "added" FROM ${src}`,
  partitionedBy: 'DAY',
  clusteredBy: ['page'],
});
const { taskId } = await d.submitIngestion(stmt);
await d.waitForTask(taskId); // throws with Druid's errorMsg on FAILED
buildExtern({ inputSource, inputFormat, signature }) builds
TABLE(EXTERN('<json>', '<json>', '<json>')) for any input source and format.
Signature types must be Druid native types (string, long, float,
double, ARRAY<...>, COMPLEX<...>).
buildInlineExtern(rows, signature) builds the inline input source with
newline-delimited JSON. Use it for small loads.
buildInsertIngestion({ table, select, values?, partitionedBy, clusteredBy? })
builds INSERT INTO "t" <select> PARTITIONED BY <g> [CLUSTERED BY ...].
select can be SQL text or SelectOptions.
buildReplaceIngestion({ ..., overwrite }) builds REPLACE INTO "t" OVERWRITE ALL, OVERWRITE WHERE __time >= TIMESTAMP '..' AND __time < TIMESTAMP '..'
(from { from, to }), or a raw { where } that must be on __time. Druid
"updates" and "deletes" by reindexing a time range from the datasource itself.
partitionedBy is validated against the granularities Druid documents:
HOUR, DAY, MONTH, YEAR, ALL, ALL TIME, the periods PT1S, PT1M,
PT5M, PT10M, PT15M, PT30M, PT1H, PT6H, P1D, P1W, P1M, P3M
and P1Y, TIME_FLOOR(__time, '<period>'), and FLOOR(__time TO <unit>).
Anything else is refused before a task is queued.
submitIngestion() accepts only INSERT/REPLACE. query() refuses both
and points to submitIngestion(), because /druid/v2/sql does not run
ingestion.

Refused, by name#

Every refusal throws (or rejects with) UnsupportedSchemaObjectError, with the
message "<X> is not supported on druid. <what to do instead>". query()
checks the leading keyword before sending a request. It skips comments and
leading SET ...; statements.
Call / statementInstead
UPDATE, buildUpdateQuery, buildIncrementQuery, bulkUpdatebuildReplaceIngestion over the time range
DELETE, buildDeleteQuery, bulkDelete, TRUNCATEREPLACE ... OVERWRITE with a filtering SELECT
buildInsertQuery, bulkInsert, buildUpsertQuery, MERGEbuildInlineExtern + buildInsertIngestion / buildReplaceIngestion
INSERT/REPLACE through query()submitIngestion()
CREATE ..., createTable, createPartitionedTable, createSchemaingest into the datasource
DROP ..., dropTablemarkDatasourceUnused() (explicit soft delete), then a kill task
ALTER, addColumn, removeColumn, changeColumn, renameColumn, renameTablereingest / REPLACE
transactions, savepoints (BEGIN, COMMIT, ROLLBACK, SAVEPOINT)none
indexes (all kinds), constraints, foreign keysnone (Druid builds its own bitmap indexes)
sequences, triggers, views, materialized views, proceduresnone
partitions APIPARTITIONED BY at ingestion
RLS, policies, users, roles, GRANT/REVOKEbasic-security extension API
extensions, FDW / foreign tables, ATTACHserver config / EXTERN
vacuum, analyze, fullTextSearch, SQLite JSON helpers, ST_* helpers, .advancednone
Read-only metadata methods for objects that cannot exist return an empty
answer instead of throwing: showIndexes, showConstraints and
showMaterializedViews return [], and hasSequence, hasTrigger and
similar return false.

Caveats / not-yet-verified#

The client is tested against a mocked fetch (tests/dialects/druid.test.ts).
It has not been run against a live cluster in this suite.
BOOLEAN parameters are sent as BOOLEAN, but Druid stores booleans as
LONG. Comparing a stored 0/1 column to a boolean parameter may need
CAST or a number.
markDatasourceUnused uses the Overlord endpoint from the current docs.
Older clusters exposed the deprecated Coordinator path
/druid/coordinator/v1/datasources/{name} instead.
queryStream uses the shared LIMIT/OFFSET pager, which re-runs the query
for each page. Druid documents that large OFFSETs still generate the
skipped rows.
waitForTask giving up does not stop the task. Use cancelTask() for that.

Capabilities#

Computed from the code — capabilitiesOf() (src/transaction-support.ts),
whereSupportOf() (src/query-builders/expression-render.ts),
sqlObjectCapabilitiesOf() (src/sql-objects/capabilities.ts) and the
builders — by the scratch test described in the
capability matrix.
Capabilitydruid
Transactions atomicno — each statement is its own request; requireAtomic refuses it
Savepointsno — a nested transaction() throws
Isolationup to SERIALIZABLE
Transaction modesread-only no; deferrable no; constraint deferral no
RETURNINGrefused — INSERT ... VALUES is not supported on druid. Druid ingests in batches: buildInlineExtern() + buildInsertIngestion(), then submitIngestion()
Upsertrefused — Upsert is not supported on druid. Rewrite the time range with buildReplaceIngestion()
JSON columnCOMPLEX<json> (JSONB → COMPLEX<json>)
Vector columnVARCHAR
Array columnVARCHAR
WHERE builder32 operator keys; $and/$or/$not; $exists: yes; $in subquery: yes; expression operands: yes
SQL objectsfamily unknown: triggers no; procedures no; functions no; materialized views no; sequences no; enums check; RLS no
StreamingqueryStream() present; LISTEN absent; createExtension() present

Related reading#

All dialects
SQLite dialect — the inherited builders
Druid SQL API — request body, parameters, cancel, error shape
Druid SQL — SELECT syntax, LIMIT/OFFSET, identifiers, dynamic parameters
SQL data types
SQL operators — LIKE, no ILIKE
Scalar functions — TIME_FLOOR, TIME_PARSE
SQL query context — sqlQueryId, sqlTimeZone
Query context reference — timeout
SQL-based ingestion reference — EXTERN, INSERT, REPLACE, PARTITIONED BY, CLUSTERED BY
SQL-based ingestion API — /druid/v2/sql/task, task status
Service status API — /status/health, /status
Data management API — marking segments unused
Data updates and deletion
Modified at 2026-10-04 00:40:16
Previous
Apache Doris Dialect
Next
DuckDB Dialect
Built with