@pythia-software/query-table-duckdb 0.0.0-stage → 0.7.0

package/dist/index.js

@@ -0,0 +1,1028 @@
+// src/sql.ts
+import {
+  coerceValue,
+  compileFormula,
+  compileMetric,
+  isFilterable,
+  isSortable,
+  isSelectable,
+  opsForField
+} from "@pythia-software/query-table-core";
+function quoteIdentifier(value) {
+  if (!value || value.includes("\0")) throw Error("Invalid DuckDB identifier.");
+  return `"${value.replace(/"/g, '""')}"`;
+}
+function quoteRelation(value) {
+  return value.split(".").map(quoteIdentifier).join(".");
+}
+var aggregates = /* @__PURE__ */ new Set([
+  "COUNT",
+  "COUNT_DISTINCT",
+  "SUM",
+  "AVG",
+  "MIN",
+  "MAX",
+  "MEDIAN"
+]);
+var safeNumber = (value) => `(CASE WHEN ${value} IS NULL OR (isfinite(${value}) AND abs(${value}) <= 9007199254740991) THEN ${value} ELSE error('Query Table numeric precision exceeded') END)`;
+var SQLBuilder = class {
+  constructor(schema, now = Date.now(), bindings = {}) {
+    this.schema = schema;
+    this.now = now;
+    this.bindings = bindings;
+    this.args = [];
+  }
+  bind(value) {
+    this.args.push(value);
+    return `$${this.args.length}`;
+  }
+  statement(sql) {
+    if (sql.length > 262144 || this.args.length > 1e4)
+      throw Error("DuckDB statement budget exceeded.");
+    return { sql, args: [...this.args] };
+  }
+  definition(name) {
+    const field = this.schema.fields.find((field2) => field2.name === name);
+    if (!field || field.source.kind !== "backend")
+      throw Error(`Unavailable DuckDB field: ${name}.`);
+    return field;
+  }
+  field(name, normalize = true) {
+    const field = this.definition(name), value = (Object.prototype.hasOwnProperty.call(this.bindings, name) ? this.bindings[name] : void 0) ?? quoteIdentifier(
+      field.source.kind === "backend" ? field.source.path ?? name : name
+    );
+    if (!normalize) return value;
+    if (field.type === "text" || field.type === "enum")
+      return `NULLIF(CAST(${value} AS VARCHAR), '')`;
+    if (field.type === "datetime") return `CAST(${value} AS TIMESTAMPTZ)`;
+    return value;
+  }
+  where(terms) {
+    if (terms.length > 100)
+      throw Error("At most 100 filter terms are allowed.");
+    let count = 0;
+    return terms.length ? terms.map((term) => {
+      const clauses = "any" in term ? term.any : [term];
+      if (!clauses.length || (count += clauses.length) > 100)
+        throw Error("Invalid filter predicate budget.");
+      return `(${clauses.map((clause) => {
+        const field = this.definition(clause.field), raw = this.field(field.name), op = clause.op;
+        if (!isFilterable(field) || !opsForField(field).includes(op))
+          throw Error(`Unsupported filter on ${field.name}: ${op}.`);
+        const value = field.type === "textarray" ? `CASE WHEN len(${raw}) > 0 THEN ${raw} END` : raw;
+        let sql;
+        if (op === "is_null" || op === "is_not_null")
+          sql = `${value} IS ${op === "is_null" ? "" : "NOT "}NULL`;
+        else {
+          const typed = coerceValue(field.type, clause.value, this.now);
+          if (typeof typed === "number" && !Number.isFinite(typed))
+            throw Error("Filter operands must be finite.");
+          const param = this.bind(
+            field.type === "datetime" ? new Date(typed).toISOString() : typed
+          );
+          const rhs = field.type === "datetime" ? `CAST(${param} AS TIMESTAMPTZ)` : param;
+          if (["=", "!=", ">", ">=", "<", "<="].includes(op))
+            sql = `${value} ${op} ${rhs}`;
+          else if (["contains", "starts_with", "ends_with"].includes(op))
+            sql = `${op}(lower(${value}), lower(${param}))`;
+          else if (op === "includes")
+            sql = field.filter?.arrayCaseSensitive ? `list_contains(${value}, ${param})` : `list_contains(list_transform(${value}, x -> lower(x)), lower(${param}))`;
+          else if (op.startsWith("length_"))
+            sql = `length(${value}) ${op === "length_gt" ? ">" : op === "length_lt" ? "<" : "="} CAST(${param} AS DOUBLE)`;
+          else if (op === "matches_regex" || op === "not_matches_regex") {
+            if (clause.value.length > 2e3)
+              throw Error("Regex exceeds 2,000 characters.");
+            sql = `${op === "not_matches_regex" ? "NOT " : ""}regexp_matches(${value}, ${param})`;
+          } else throw Error(`Unsupported DuckDB operator: ${op}.`);
+        }
+        return clause.negated ? `NOT (${sql})` : sql;
+      }).join(" OR ")})`;
+    }).join(" AND ") : "TRUE";
+  }
+  order(terms, identity = true) {
+    if (terms.length > 20) throw Error("At most 20 sort fields are allowed.");
+    const output = terms.map((term) => {
+      const field = this.definition(term.field);
+      if (!isSortable(field) && field.name !== this.schema.idField)
+        throw Error(`Field ${field.name} is not sortable.`);
+      if (!["asc", "desc"].includes(term.dir) || term.nulls && !["first", "last"].includes(term.nulls))
+        throw Error("Invalid ordering.");
+      let value = this.field(field.name);
+      if (term.extract) {
+        if (field.type !== "text" || term.extract.regex.length > 2e3)
+          throw Error("Invalid regex extraction.");
+        const pattern = this.bind(term.extract.regex);
+        const capture = /(^|[^\\])\((?!\?)/.test(term.extract.regex) ? 1 : 0;
+        value = `CASE WHEN regexp_matches(${value}, ${pattern}) THEN regexp_extract(${value}, ${pattern}, ${capture}) END`;
+      }
+      return `${value} ${term.dir.toUpperCase()} NULLS ${(term.nulls ?? "last").toUpperCase()}`;
+    });
+    if (identity && !terms.some((term) => term.field === this.schema.idField))
+      output.push(`${this.field(this.schema.idField)} ASC NULLS LAST`);
+    return output.length ? `ORDER BY ${output.join(", ")}` : "";
+  }
+  expression(source, aggregate = false) {
+    const plan = aggregate ? compileMetric(source, this.schema) : compileFormula(source, this.schema.fields);
+    return { sql: this.node(plan.ast), plan };
+  }
+  node(node) {
+    const sql = this.nodeSQL(node);
+    if (sql.length > 131072)
+      throw Error("DuckDB expression SQL budget exceeded.");
+    return sql;
+  }
+  nodeSQL(node) {
+    if (node.kind === "literal")
+      return node.value === null ? "NULL" : this.bind(node.value);
+    if (node.kind === "field") return this.field(node.name, false);
+    const name = node.name, vs = node.args.map((arg) => this.node(arg)), a = vs[0], b = vs[1], c = vs[2];
+    if (aggregates.has(name)) {
+      if (name === "COUNT") return `CAST(COUNT(${a ?? "*"}) AS DOUBLE)`;
+      if (name === "COUNT_DISTINCT")
+        return `CAST(COUNT(DISTINCT ${a}) AS DOUBLE)`;
+      const sql = `${name}(${a})`;
+      return ["SUM", "AVG", "MEDIAN"].includes(name) ? safeNumber(
+        `CAST(${name === "SUM" ? `COALESCE(${sql}, 0)` : sql} AS DOUBLE)`
+      ) : sql;
+    }
+    if (name.startsWith("op:")) {
+      const op = name.slice(3);
+      if (op === "IN") return `(${a} IN (${vs.slice(1).join(", ")}))`;
+      if (op === "BETWEEN") return `(${a} BETWEEN ${b} AND ${c})`;
+      if (["/", "%"].includes(op))
+        return safeNumber(
+          `(CASE WHEN ${b} = 0 THEN error('Division by zero') ELSE ${a} ${op} ${b} END)`
+        );
+      return ["+", "-", "*"].includes(op) ? safeNumber(`(${a} ${op} ${b})`) : `(${a} ${op} ${b})`;
+    }
+    if (name.startsWith("unary:")) return `(${name.slice(6)} ${a})`;
+    if (name === "IF") return `CASE WHEN ${a} THEN ${b} ELSE ${c} END`;
+    if (name === "IFS")
+      return `CASE ${vs.slice(0, -1).filter((_, i) => i % 2 === 0).map((v, i) => `WHEN ${v} THEN ${vs[2 * i + 1]}`).join(" ")} ELSE ${vs[vs.length - 1]} END`;
+    if (name === "SWITCH")
+      return `CASE ${vs.slice(1, -1).filter((_, i) => i % 2 === 0).map(
+        (v, i) => `WHEN ${a} IS NOT DISTINCT FROM ${v} THEN ${vs[2 * i + 2]}`
+      ).join(" ")} ELSE ${vs[vs.length - 1]} END`;
+    if (name === "IS_NULL") return `(${a} IS NULL)`;
+    if (name === "IS_EMPTY") {
+      const input = node.args[0];
+      const array = input.kind === "field" && input.valueType === "textarray" || input.kind === "call" && ["SPLIT", "ARRAY_UNIQUE", "ARRAY_SORT"].includes(input.name);
+      return `(${a} IS NULL OR len(${array ? a : `CAST(${a} AS VARCHAR)`}) = 0)`;
+    }
+    if (name === "COALESCE" || name === "NULLIF")
+      return `${name}(${vs.join(", ")})`;
+    if (name === "IFERROR")
+      throw Error("IFERROR is not available in the qt-duckdb-v1 SQL profile.");
+    if (name === "ROUND") {
+      const scale = `power(10, ${b ?? "0"})`;
+      return safeNumber(`(floor(${a} * ${scale} + 0.5) / ${scale})`);
+    }
+    if (name === "CLAMP")
+      return `CASE WHEN ${a} IS NULL OR ${b} IS NULL OR ${c} IS NULL THEN NULL ELSE greatest(${b}, least(${c}, ${a})) END`;
+    if (name === "LEAST" || name === "GREATEST" || name === "CONCAT")
+      return `CASE WHEN ${vs.map((v) => `${v} IS NULL`).join(" OR ")} THEN NULL ELSE ${name}(${vs.join(", ")}) END`;
+    if (name === "CONCAT_WS")
+      return `CASE WHEN ${a} IS NULL THEN NULL ELSE concat_ws(${vs.join(", ")}) END`;
+    if (["CONTAINS", "STARTS_WITH", "ENDS_WITH"].includes(name))
+      return `${name.toLowerCase()}(CASE WHEN ${c ?? "FALSE"} THEN lower(${a}) ELSE ${a} END, CASE WHEN ${c ?? "FALSE"} THEN lower(${b}) ELSE ${b} END)`;
+    if (name === "TO_NUMBER") return safeNumber(`CAST(${a} AS DOUBLE)`);
+    if (name === "TO_TEXT") return `CAST(${a} AS VARCHAR)`;
+    if (name === "TO_BOOLEAN") return `CAST(${a} AS BOOLEAN)`;
+    if (name === "TO_DATETIME") return `CAST(${a} AS TIMESTAMPTZ)`;
+    if (name === "SPLIT") return `string_split(${a}, ${b})`;
+    if (name === "JOIN") return `array_to_string(${a}, ${b})`;
+    if (name === "ARRAY_LENGTH") return `len(${a})`;
+    if (name === "ARRAY_CONTAINS") return `list_contains(${a}, ${b})`;
+    if (name === "ARRAY_GET")
+      return `CASE WHEN ${b} < 0 THEN error('Array index must be nonnegative') ELSE list_extract(${a}, CAST(${b} + 1 AS BIGINT)) END`;
+    if (name === "ARRAY_SORT") return `list_sort(${a})`;
+    if (name === "ARRAY_UNIQUE")
+      return `list_filter(${a}, (x, i) -> list_position(${a}, x) = i)`;
+    if (name === "WEEKDAY")
+      return `extract(isodow FROM CAST(${a} AS TIMESTAMPTZ))`;
+    if (["YEAR", "MONTH", "DAY", "HOUR"].includes(name))
+      return `extract(${name.toLowerCase()} FROM CAST(${a} AS TIMESTAMPTZ))`;
+    if (name === "DATE_TRUNC")
+      return `date_trunc(${a}, CAST(${b} AS TIMESTAMPTZ))`;
+    if (name === "DATE_DIFF" || name === "DATE_ADD" || name === "FORMAT_DATE" || name.startsWith("REGEX_"))
+      throw Error(`${name} is not available in the qt-duckdb-v1 SQL profile.`);
+    if (["LEFT", "RIGHT", "SUBSTRING", "LPAD", "RPAD", "SPLIT_PART"].includes(
+      name
+    )) {
+      const args = [...vs];
+      const indices = name === "SUBSTRING" ? [1, 2] : name === "SPLIT_PART" ? [2] : [1];
+      for (const index of indices)
+        if (args[index] !== void 0)
+          args[index] = `CAST(${args[index]} AS BIGINT)`;
+      return `${name}(${args.join(", ")})`;
+    }
+    if ([
+      "LENGTH",
+      "LOWER",
+      "UPPER",
+      "TRIM",
+      "LTRIM",
+      "RTRIM",
+      "REPLACE",
+      "ABS",
+      "FLOOR",
+      "CEIL",
+      "TRUNC",
+      "POWER",
+      "SQRT"
+    ].includes(name))
+      return `${name}(${vs.join(", ")})`;
+    throw Error(`Unsupported DuckDB function: ${name}.`);
+  }
+};
+function compileDuckDBRows(query, schema, relation, now = Date.now()) {
+  const sql = new SQLBuilder(schema, now);
+  if (!Number.isSafeInteger(query.limit) || query.limit < 1 || query.limit > 1e4 || !Number.isSafeInteger(query.offset) || query.offset < 0)
+    throw Error("Invalid result window.");
+  const select = [.../* @__PURE__ */ new Set([schema.idField, ...query.select])].map((name) => {
+    const field = sql.definition(name);
+    if (!isSelectable(field) && name !== schema.idField)
+      throw Error(`Field ${name} is not selectable.`);
+    return `${sql.field(name, false)} AS ${quoteIdentifier(name)}`;
+  });
+  const where = sql.where(query.where), order = sql.order(query.orderBy);
+  return sql.statement(
+    `SELECT ${select.join(", ")} FROM ${quoteRelation(relation)} WHERE ${where} ${order} LIMIT ${sql.bind(query.limit)} OFFSET ${sql.bind(query.offset)}`
+  );
+}
+
+// src/backend.ts
+import {
+  compileFormula as compileFormula2,
+  createGroupingModel,
+  GROUP_ID_FIELD,
+  metricExpression,
+  validateMetric,
+  isSelectable as isSelectable2,
+  isFilterable as isFilterable2,
+  boxSummary,
+  histogramEdges,
+  histogramCounts,
+  compareMetricValues,
+  metricDateFloor,
+  metricDateTime,
+  metricDateNext,
+  metricDateRange
+} from "@pythia-software/query-table-core";
+var DUCKDB_PROFILE = "qt-duckdb-v1";
+function abort(signal) {
+  if (signal?.aborted)
+    throw new DOMException("DuckDB query cancelled.", "AbortError");
+}
+function normalizeDuckDBValue(value) {
+  if (typeof value === "bigint") {
+    const numeric = Number(value);
+    if (!Number.isSafeInteger(numeric))
+      throw Error("DuckDB integer exceeds JavaScript safe precision.");
+    return numeric;
+  }
+  if (value instanceof Date) return value.toISOString();
+  if (typeof value === "number" && (!Number.isFinite(value) || Math.abs(value) > Number.MAX_SAFE_INTEGER))
+    throw Error("DuckDB number exceeds finite safe precision.");
+  if (Array.isArray(value)) return value.map(normalizeDuckDBValue);
+  if (value && typeof value === "object") {
+    if ("toArray" in value && typeof value.toArray === "function")
+      return Array.from(value.toArray()).map(normalizeDuckDBValue);
+    if ("toJSON" in value && typeof value.toJSON === "function")
+      return normalizeDuckDBValue(value.toJSON());
+    return Object.fromEntries(
+      Object.entries(value).map(([key, item]) => [
+        key,
+        normalizeDuckDBValue(item)
+      ])
+    );
+  }
+  return value;
+}
+function positive(value, fallback, maximum) {
+  const out = value ?? fallback;
+  if (!Number.isSafeInteger(out) || out < 1 || out > maximum)
+    throw Error("Invalid DuckDB resource budget.");
+  return out;
+}
+var DuckDBBackend = class {
+  constructor(options) {
+    this.options = options;
+    this.queue = Promise.resolve();
+    this.sequence = 0;
+    this.computed = /* @__PURE__ */ new Map();
+    const fields = options.schema.fields.filter((field) => field.source.kind === "backend").map((field) => ({
+      ...field,
+      source: { ...field.source, kind: "backend", path: field.name }
+    }));
+    if (!fields.some((field) => field.name === options.schema.idField) || new Set(fields.map((field) => field.name)).size !== fields.length)
+      throw Error(
+        "DuckDB needs a unique field catalogue and a bound identity."
+      );
+    quoteRelation(options.relation);
+    this.schema = { ...options.schema, fields };
+    const definitions = new Map(
+      (options.computedColumns ?? []).map((column) => [
+        `@computed/${column.id}`,
+        column
+      ])
+    );
+    const visiting = /* @__PURE__ */ new Set();
+    const resolve = (name) => {
+      if (this.computed.has(name)) return this.computed.get(name);
+      const definition = definitions.get(name);
+      if (!definition) return void 0;
+      if (visiting.has(name)) throw Error("Computed definition cycle.");
+      visiting.add(name);
+      const plan = compileFormula2(
+        definition.expression.source,
+        fields,
+        resolve
+      );
+      new SQLBuilder(this.schema).node(plan.ast);
+      visiting.delete(name);
+      this.computed.set(name, plan);
+      return plan;
+    };
+    for (const name of definitions.keys()) {
+      const plan = resolve(name);
+      fields.push({
+        name,
+        label: definitions.get(name).label,
+        type: plan.type === "null" ? "text" : plan.type,
+        source: { kind: "backend", path: name },
+        filter: { enabled: true },
+        sort: { enabled: true },
+        aggregate: { measure: true, groupable: plan.type !== "textarray" }
+      });
+    }
+    this.execution = {
+      profile: DUCKDB_PROFILE,
+      planToken: `duckdb:${JSON.stringify([...definitions.values()].map((column) => [column.id, column.revision]))}`,
+      resolvedRevisions: Object.fromEntries(
+        [...definitions.values()].map((column) => [column.id, column.revision])
+      ),
+      fields: Object.fromEntries(
+        fields.filter((field) => definitions.has(field.name)).map((field) => [
+          field.name,
+          {
+            type: field.type,
+            select: true,
+            filter: true,
+            sort: true,
+            measure: true,
+            group: field.type !== "textarray"
+          }
+        ])
+      ),
+      ...options.snapshot !== void 0 ? { snapshot: options.snapshot } : {}
+    };
+    this.capabilities = {
+      version: 3,
+      profile: DUCKDB_PROFILE,
+      groupedRows: true,
+      calendarGrouping: true,
+      computedSourceFilters: definitions.size > 0,
+      regex: true,
+      regexSourceFilters: true,
+      regexAggregateExpressions: false,
+      maxRows: positive(options.maxRows, 1e4, 1e4),
+      maxGroups: positive(options.maxGroups, 1e4, 1e4),
+      maxPopulation: positive(options.maxPopulation, 25e4, 1e7)
+    };
+    this.maxSamples = positive(options.maxSamples, 1e5, 1e6);
+    this.maxStagingBytes = positive(
+      options.maxStagingBytes,
+      64 * 1024 * 1024,
+      1024 * 1024 * 1024
+    );
+  }
+  serial(work, signal) {
+    const next = this.queue.then(() => {
+      abort(signal);
+      return work();
+    });
+    this.queue = next.catch(() => {
+    });
+    return next;
+  }
+  /** Wait before closing an owned driver connection. */
+  async drain() {
+    await this.queue;
+  }
+  async run(statement, signal) {
+    abort(signal);
+    const cancel = () => {
+      void this.options.connection.interrupt?.();
+    };
+    signal?.addEventListener("abort", cancel, { once: true });
+    try {
+      const rows = await this.options.connection.query(
+        statement.sql,
+        statement.args
+      );
+      abort(signal);
+      return rows.map((row) => normalizeDuckDBValue(row));
+    } finally {
+      signal?.removeEventListener("abort", cancel);
+    }
+  }
+  sql(statement, args = [], signal) {
+    return this.run({ sql: statement, args }, signal);
+  }
+  window(query) {
+    if (!Number.isSafeInteger(query.limit) || query.limit < 1 || query.limit > this.capabilities.maxRows || !Number.isSafeInteger(query.offset) || query.offset < 0)
+      throw Error("Invalid DuckDB result window.");
+  }
+  builder(schema = this.schema, now = Date.now()) {
+    return new SQLBuilder(schema, now);
+  }
+  projectedSource(now) {
+    const bindings = Object.fromEntries(
+      this.schema.fields.filter((field) => !this.computed.has(field.name)).map((field) => [
+        field.name,
+        (this.options.bindings && Object.prototype.hasOwnProperty.call(
+          this.options.bindings,
+          field.name
+        ) ? this.options.bindings[field.name] : void 0) ?? quoteIdentifier(
+          (() => {
+            const original = this.options.schema.fields.find(
+              (item) => item.name === field.name
+            );
+            return original?.source.kind === "backend" ? original.source.path ?? field.name : field.name;
+          })()
+        )
+      ])
+    );
+    const builder = new SQLBuilder(this.schema, now, bindings);
+    const projections = this.schema.fields.map((field) => {
+      const plan = this.computed.get(field.name), raw = plan ? builder.node(plan.ast) : bindings[field.name];
+      return `${raw} AS ${quoteIdentifier(field.name)}`;
+    });
+    return builder.statement(
+      `SELECT ${projections.join(", ")} FROM ${quoteRelation(this.options.relation)} AS r`
+    );
+  }
+  async transaction(work, signal) {
+    return this.serial(async () => {
+      await this.sql("BEGIN TRANSACTION", [], signal);
+      const tables = [];
+      try {
+        const result = await work(tables);
+        for (const table of tables.reverse())
+          await this.sql(`DROP TABLE ${quoteIdentifier(table)}`, [], signal);
+        await this.sql("COMMIT", [], signal);
+        return result;
+      } catch (error) {
+        await this.sql("ROLLBACK").catch(() => {
+        });
+        abort(signal);
+        throw error;
+      }
+    }, signal);
+  }
+  temp(tables) {
+    const name = `qt_duckdb_${++this.sequence}`;
+    tables.push(name);
+    return name;
+  }
+  async stage(source, now, tables, signal) {
+    const projection = this.projectedSource(now), builder = this.builder(this.schema, now);
+    builder.args.push(...projection.args);
+    const where = builder.where(source.where), name = this.temp(tables);
+    const population = `(${projection.sql}) r WHERE ${where}`;
+    const [{ n, bytes }] = await this.run(
+      builder.statement(
+        `SELECT COUNT(*) AS n, COALESCE(SUM(octet_length(encode(CAST(to_json(r) AS VARCHAR)))),0) AS bytes FROM ${population}`
+      ),
+      signal
+    );
+    if (n > this.capabilities.maxPopulation || bytes > this.maxStagingBytes)
+      throw Error("DuckDB source population or staging byte budget exceeded.");
+    await this.run(
+      builder.statement(
+        `CREATE TEMP TABLE ${quoteIdentifier(name)} AS SELECT * FROM ${population}`
+      ),
+      signal
+    );
+    const [{ invalid }] = await this.sql(
+      `SELECT COUNT(*) - COUNT(DISTINCT ${quoteIdentifier(this.schema.idField)}) AS invalid FROM ${quoteIdentifier(name)}`,
+      [],
+      signal
+    );
+    if (invalid !== 0)
+      throw Error("DuckDB source identity must be unique and non-null.");
+    return { name, count: n };
+  }
+  async page(relation, schema, query, now, signal) {
+    this.window(query);
+    const builder = this.builder(schema, now), where = builder.where(query.where);
+    const [{ total }] = await this.run(
+      builder.statement(
+        `SELECT COUNT(*) AS total FROM ${quoteIdentifier(relation)} WHERE ${where}`
+      ),
+      signal
+    );
+    const order = builder.order(query.orderBy), names = [.../* @__PURE__ */ new Set([schema.idField, ...query.select])];
+    names.forEach((name) => {
+      if (!isSelectable2(builder.definition(name)) && name !== schema.idField)
+        throw Error(`Field ${name} is not selectable.`);
+    });
+    const rows = await this.run(
+      builder.statement(
+        `SELECT ${names.map(quoteIdentifier).join(", ")} FROM ${quoteIdentifier(relation)} WHERE ${where} ${order} LIMIT ${builder.bind(query.limit)} OFFSET ${builder.bind(query.offset)}`
+      ),
+      signal
+    );
+    return { rows: rows.map((row) => this.formatRow(row, schema)), total };
+  }
+  formatRow(row, schema) {
+    return Object.fromEntries(
+      Object.entries(row).map(([name, value]) => {
+        const field = schema.fields.find((field2) => field2.name === name);
+        if (value != null && field?.type === "datetime") {
+          const text = String(value);
+          const canonical = /^\d{4}-\d{2}-\d{2}[ T]\d{2}:\d{2}:\d{2}(?:\.\d+)?$/.test(text) ? `${text.replace(" ", "T")}Z` : text;
+          const date = typeof value === "number" ? new Date(value) : new Date(canonical);
+          if (!Number.isFinite(date.getTime()))
+            throw Error(`Invalid datetime returned for ${name}.`);
+          value = date.toISOString();
+        }
+        return [name, value];
+      })
+    );
+  }
+  validateRequest(request) {
+    if (request.version !== 3 || request.profile !== DUCKDB_PROFILE || request.diagnostics.length)
+      throw Error("Invalid DuckDB execution request or profile.");
+    if (!Number.isSafeInteger(request.now) || Math.abs(request.now) > 864e13)
+      throw Error("Invalid query clock.");
+    if ((request.planToken ?? "") !== (Object.keys(this.execution.fields).length ? this.execution.planToken : "") && request.planToken !== this.execution.planToken)
+      throw Error("DuckDB execution handshake changed.");
+    if ((request.snapshot ?? "") !== (this.options.snapshot ?? ""))
+      throw Error("DuckDB snapshot changed.");
+    for (const [key, revision] of Object.entries(request.expectedRevisions))
+      if (this.execution.resolvedRevisions[key] !== revision)
+        throw Error("Computed definitions changed; refresh the handshake.");
+    if (request.metrics.length > 20)
+      throw Error("At most 20 metrics are allowed.");
+    this.window(request.result);
+    const model = createGroupingModel(this.schema);
+    if (request.grouping) model.validate(request.grouping);
+    const resultSchema = request.grouping ? model.resultSchema(request.grouping.keys, request.grouping.summaries) : this.schema;
+    this.builder(this.schema, request.now).where(request.source.where);
+    const result = this.builder(resultSchema, request.now);
+    result.where(request.result.where);
+    result.order(request.result.orderBy);
+    request.result.select.forEach((name) => result.definition(name));
+  }
+  async execute(request, signal) {
+    this.validateRequest(request);
+    return this.transaction(async (tables) => {
+      const source = await this.stage(
+        request.source,
+        request.now,
+        tables,
+        signal
+      );
+      let relation = source.name, schema = this.schema;
+      if (request.grouping) {
+        const grouping = request.grouping, model = createGroupingModel(schema), builder = this.builder(schema, request.now);
+        const keys = grouping.keys.map((name) => builder.field(name, false)), names = grouping.keys.map(quoteIdentifier);
+        const representative = builder.order(
+          grouping.representative?.orderBy ?? [
+            { field: schema.idField, dir: "desc" }
+          ],
+          false
+        ).replace(/^ORDER BY /, "");
+        const tie = grouping.representative?.orderBy.some(
+          (term) => term.field === schema.idField
+        ) ? "" : `, ${builder.field(schema.idField)} DESC NULLS LAST`;
+        const summaries = grouping.summaries.map(
+          (summary) => `${summary.op === "row" ? `first(${builder.field(summary.field, false)} ORDER BY ${representative}${tie})` : builder.expression(model.summaryExpression(summary), true).sql} AS ${quoteIdentifier(summary.id)}`
+        );
+        relation = this.temp(tables);
+        const identity = `CAST(to_json(struct_pack(${keys.map((key, i) => `k${i} := ${key}`).join(", ")})) AS VARCHAR)`;
+        await this.run(
+          builder.statement(
+            `CREATE TEMP TABLE ${quoteIdentifier(relation)} AS SELECT ${identity} AS ${quoteIdentifier(GROUP_ID_FIELD)}, ${keys.map((key, i) => `${key} AS ${names[i]}`).join(", ")}${summaries.length ? `, ${summaries.join(", ")}` : ""} FROM ${quoteIdentifier(source.name)} GROUP BY ${keys.join(", ")}`
+          ),
+          signal
+        );
+        const [{ n }] = await this.sql(
+          `SELECT COUNT(*) AS n FROM ${quoteIdentifier(relation)}`,
+          [],
+          signal
+        );
+        if (n > this.capabilities.maxGroups)
+          throw Error("DuckDB grouped row budget exceeded.");
+        schema = model.resultSchema(grouping.keys, grouping.summaries);
+      }
+      const page = await this.page(
+        relation,
+        schema,
+        request.result,
+        request.now,
+        signal
+      );
+      const metrics = await this.metrics(
+        relation,
+        schema,
+        request.result,
+        request.metrics,
+        request.now,
+        tables,
+        signal
+      );
+      return {
+        version: 3,
+        now: request.now,
+        sourceTotal: source.count,
+        rows: request.rows ? page.rows : [],
+        total: page.total,
+        schema: {
+          name: schema.name,
+          idField: schema.idField,
+          fields: schema.fields.map((field) => ({
+            name: field.name,
+            type: field.type
+          }))
+        },
+        metrics,
+        execution: { ...this.execution, planToken: request.planToken ?? "" }
+      };
+    }, signal);
+  }
+  async metrics(relation, schema, query, clauses, now, tables, signal) {
+    const output = [];
+    for (const clause of clauses) {
+      abort(signal);
+      try {
+        output.push(
+          await this.metric(
+            relation,
+            schema,
+            query,
+            clause,
+            now,
+            tables,
+            signal
+          )
+        );
+      } catch (error) {
+        abort(signal);
+        output.push({
+          id: clause.id,
+          buckets: [],
+          error: error instanceof Error ? error.message : String(error)
+        });
+      }
+    }
+    return output;
+  }
+  async metric(relation, schema, query, clause, now, tables, signal) {
+    if (clause.distribution && !clause.display)
+      clause = { ...clause, display: { kind: clause.distribution.kind } };
+    const issues = validateMetric(clause, schema);
+    if (issues.length)
+      throw Error(issues.map((issue) => issue.message).join(" "));
+    const builder = this.builder(schema, now), where = builder.where(query.where);
+    const window = clause.scope === "shownRows" ? `${builder.order(query.orderBy)} LIMIT ${builder.bind(query.limit)} OFFSET ${builder.bind(query.offset)}` : "";
+    let population = `(SELECT * FROM ${quoteIdentifier(relation)} WHERE ${where} ${window})`;
+    let dateMapping;
+    if (clause.dateGrouping) {
+      const config = clause.dateGrouping, source = builder.field(config.field, false);
+      const dates = await this.run(
+        builder.statement(
+          `SELECT DISTINCT CAST(${source} AS VARCHAR) AS value FROM ${population} r WHERE ${source} IS NOT NULL`
+        ),
+        signal
+      );
+      dateMapping = this.temp(tables);
+      await this.sql(
+        `CREATE TEMP TABLE ${quoteIdentifier(dateMapping)} (value TIMESTAMPTZ, bucket TIMESTAMPTZ)`,
+        [],
+        signal
+      );
+      for (let i = 0; i < dates.length; i += 250) {
+        const args = [];
+        const values = dates.slice(i, i + 250).map((row) => {
+          const value = /^\d{4}-\d{2}-\d{2}$/.test(String(row.value)) ? String(row.value) : this.formatRow({ [config.field]: row.value }, schema)[config.field];
+          args.push(
+            value,
+            new Date(
+              metricDateFloor(
+                metricDateTime(value, config.timeZone),
+                config.interval,
+                config.timeZone
+              )
+            ).toISOString()
+          );
+          return `(CAST($${args.length - 1} AS TIMESTAMPTZ), CAST($${args.length} AS TIMESTAMPTZ))`;
+        });
+        if (values.length)
+          await this.sql(
+            `INSERT INTO ${quoteIdentifier(dateMapping)} VALUES ${values.join(", ")}`,
+            args,
+            signal
+          );
+      }
+      population = `(SELECT r.* EXCLUDE (${quoteIdentifier(config.field)}), m.bucket AS ${quoteIdentifier(config.field)} FROM ${population} r LEFT JOIN ${quoteIdentifier(dateMapping)} m ON CAST(r.${quoteIdentifier(config.field)} AS TIMESTAMPTZ) = m.value)`;
+    }
+    const keys = clause.groupBy.map((name) => builder.field(name, false)), groups = keys.length ? `GROUP BY ${keys.join(", ")}` : "";
+    const distribution = clause.distribution && ["box", "histogram"].includes(clause.display?.kind ?? "") ? clause.distribution : void 0;
+    const expression = distribution ? builder.expression(distribution.input).sql : builder.expression(metricExpression(clause), true).sql;
+    const projections = keys.map(
+      (key, index) => `${key} AS ${quoteIdentifier(`g${index}`)}`
+    );
+    projections.push(
+      "COUNT(*) AS count",
+      distribution ? `list(${expression}) FILTER (WHERE ${expression} IS NOT NULL) AS samples` : `${expression} AS value`
+    );
+    if (!distribution && clause.display?.kind === "scatter")
+      projections.push(
+        `${builder.expression(clause.expressionY ?? "COUNT()", true).sql} AS y`
+      );
+    const rows = await this.run(
+      builder.statement(
+        `SELECT ${projections.join(", ")} FROM ${population} r ${groups} LIMIT ${this.capabilities.maxGroups + 1}`
+      ),
+      signal
+    );
+    if (rows.length > this.capabilities.maxGroups)
+      throw Error("DuckDB metric group budget exceeded.");
+    if (distribution && rows.some(
+      (row) => row.samples?.length && row.samples.length > this.maxSamples
+    ))
+      throw Error("DuckDB exact sample budget exceeded.");
+    const edges = distribution?.kind === "histogram" ? histogramEdges(
+      rows.flatMap((row) => row.samples ?? []),
+      distribution.bins ?? 10
+    ) : [];
+    const buckets = rows.map((row) => {
+      const samples = row.samples ?? [];
+      return {
+        keys: clause.groupBy.map((name, index) => {
+          const value = row[`g${index}`] ?? null;
+          return schema.fields.find((field) => field.name === name)?.type === "datetime" && value !== null ? this.formatRow({ [name]: value }, schema)[name] : value;
+        }),
+        count: row.count,
+        value: distribution ? null : row.value,
+        ...row.y !== void 0 ? { y: row.y } : {},
+        ...distribution ? {
+          nullCount: row.count - samples.length,
+          distribution: distribution.kind === "box" ? {
+            kind: "box",
+            summary: boxSummary(samples, distribution.whiskers)
+          } : {
+            kind: "histogram",
+            n: samples.length,
+            edges,
+            counts: histogramCounts(samples, edges)
+          }
+        } : {}
+      };
+    });
+    if (clause.dateGrouping?.includeEmpty) {
+      const config = clause.dateGrouping, observed = buckets.filter((bucket) => bucket.keys[0] !== null).map((bucket) => metricDateTime(bucket.keys[0]));
+      const range = metricDateRange(
+        config,
+        {
+          ...query,
+          select: query.select.map((field) => ({ field }))
+        },
+        observed,
+        now,
+        (name) => name
+      );
+      const series = new Map(
+        buckets.filter((bucket) => bucket.keys[0] !== null).map((bucket) => [
+          JSON.stringify(bucket.keys.slice(1)),
+          bucket.keys.slice(1)
+        ])
+      );
+      if (keys.length === 1 && !series.size) series.set("[]", []);
+      const existing = new Set(
+        buckets.map((bucket) => JSON.stringify(bucket.keys))
+      );
+      if (range)
+        for (let time = range[0]; time <= range[1]; time = metricDateNext(time, config.interval, config.timeZone)) {
+          for (const tuple of series.values()) {
+            const values = [new Date(time).toISOString(), ...tuple];
+            if (!existing.has(JSON.stringify(values))) {
+              if (buckets.length >= this.capabilities.maxGroups)
+                throw Error("DuckDB calendar group budget exceeded.");
+              buckets.push({
+                keys: values,
+                count: 0,
+                value: !clause.expression && ["count", "count_distinct", "sum"].includes(clause.op) || /^(COUNT|COUNT_DISTINCT|SUM)\([^)]*\)$/.test(
+                  metricExpression(clause)
+                ) ? 0 : null
+              });
+            }
+          }
+        }
+    }
+    const sort = clause.sort ?? [
+      { key: "value", dir: "desc" }
+    ];
+    buckets.sort((a, b) => {
+      for (const term of sort) {
+        const value = (bucket) => term.key.startsWith("group") ? bucket.keys[Number(term.key.slice(5))] ?? null : term.key === "samples" ? bucket.distribution?.kind === "box" ? bucket.distribution.summary?.n ?? 0 : bucket.distribution?.n ?? 0 : bucket[term.key] ?? null;
+        const av = value(a), bv = value(b);
+        if (av === null || bv === null) {
+          if (av !== bv)
+            return (av === null ? 1 : -1) * (term.nulls === "first" ? -1 : 1);
+        } else {
+          const result = compareMetricValues(av, bv);
+          if (result) return result * (term.dir === "asc" ? 1 : -1);
+        }
+      }
+      return JSON.stringify(a.keys).localeCompare(JSON.stringify(b.keys));
+    });
+    const limit = clause.groupLimit ?? 1e4;
+    return {
+      id: clause.id,
+      buckets: buckets.slice(0, limit),
+      groupCount: buckets.length,
+      coverage: buckets.length > limit ? "partial" : "exact",
+      ...clause.scope ? { scope: clause.scope } : {}
+    };
+  }
+  transport() {
+    return {
+      queryCapabilities: this.capabilities,
+      metricCapabilities: {
+        version: 2,
+        expressions: true,
+        shownRows: true,
+        distributions: true,
+        computedFields: this.computed.size > 0,
+        profile: DUCKDB_PROFILE,
+        maxGroups: this.capabilities.maxGroups
+      },
+      fetchQueryV3: (request, signal) => this.execute(request, signal),
+      fetchRows: (query, signal) => this.transaction(async (tables) => {
+        this.window(query);
+        const source = await this.stage(query, Date.now(), tables, signal);
+        return this.page(
+          source.name,
+          this.schema,
+          { ...query, where: [] },
+          Date.now(),
+          signal
+        );
+      }, signal),
+      fetchMetrics: (query, signal) => {
+        if (query.diagnostics.length || query.profile && query.profile !== DUCKDB_PROFILE || query.metrics.length > 20)
+          return Promise.reject(Error("Invalid DuckDB metric request."));
+        return this.transaction(async (tables) => {
+          const now = Date.now(), server = { ...query, select: [] };
+          const source = await this.stage(server, now, tables, signal);
+          return {
+            metrics: await this.metrics(
+              source.name,
+              this.schema,
+              server,
+              query.metrics,
+              now,
+              tables,
+              signal
+            )
+          };
+        }, signal);
+      },
+      fetchAggregations: (query, signal) => this.transaction(async (tables) => {
+        if (query.diagnostics?.length || query.aggregations.length > 20)
+          throw Error("Invalid DuckDB aggregation request.");
+        const server = {
+          select: [],
+          where: query.where,
+          orderBy: [],
+          limit: 100,
+          offset: 0
+        }, now = Date.now();
+        const source = await this.stage(server, now, tables, signal);
+        return {
+          metrics: await this.metrics(
+            source.name,
+            this.schema,
+            { ...server, where: [] },
+            query.aggregations,
+            now,
+            tables,
+            signal
+          )
+        };
+      }, signal),
+      fetchDistinctValues: (query, signal) => this.serial(async () => {
+        const builder = this.builder(), field = builder.definition(query.field), limit = positive(query.limit, 50, 500);
+        if (!isFilterable2(field))
+          throw Error(`Field ${field.name} is not filterable.`);
+        if (query.search.length > 2e3)
+          throw Error("Distinct search exceeds its budget.");
+        const source = this.projectedSource(Date.now()), value = builder.field(query.field), array = field.type === "textarray";
+        builder.args.push(...source.args);
+        const param = builder.bind(query.search);
+        const rows = await this.run(
+          builder.statement(
+            `SELECT CAST(value AS VARCHAR) AS value, COUNT(*) AS n FROM (SELECT ${array ? `unnest(${value})` : value} AS value FROM (${source.sql}) r) v WHERE value IS NOT NULL AND contains(lower(CAST(value AS VARCHAR)), lower(${param})) GROUP BY value ORDER BY n DESC, value ASC LIMIT ${limit + 1}`
+          ),
+          signal
+        );
+        const [{ n }] = await this.sql(
+          `SELECT COUNT(*) AS n FROM (${source.sql}) r WHERE ${array ? `COALESCE(len(${value}),0) = 0` : `${value} IS NULL`}`,
+          source.args,
+          signal
+        );
+        return {
+          values: rows.slice(0, limit).map((row) => String(row.value)),
+          hasMore: rows.length > limit,
+          hasNull: n > 0
+        };
+      }, signal),
+      fetchRow: (identity, signal) => this.serial(async () => {
+        const source = this.projectedSource(Date.now());
+        const rows = await this.sql(
+          `SELECT * FROM (${source.sql}) r WHERE ${quoteIdentifier(this.schema.idField)} = $${source.args.length + 1} LIMIT 2`,
+          [...source.args, identity],
+          signal
+        );
+        if (rows.length > 1) throw Error("DuckDB identity must be unique.");
+        return rows[0] ? this.formatRow(rows[0], this.schema) : null;
+      }, signal),
+      fetchFieldStats: (fields, signal) => this.serial(async () => {
+        if (fields.length > 64)
+          throw Error("At most 64 field stats can be requested.");
+        const stats = {};
+        for (const name of fields) {
+          const builder = this.builder(), field = builder.definition(name), source = this.projectedSource(Date.now()), value = builder.field(name);
+          const rows = await this.sql(
+            field.type === "textarray" ? `SELECT COUNT(DISTINCT value) AS "distinct" FROM (SELECT unnest(${value}) AS value FROM (${source.sql}) r)` : `SELECT COUNT(DISTINCT ${value}) AS "distinct", MIN(${value}) AS min, MAX(${value}) AS max FROM (${source.sql}) r`,
+            source.args,
+            signal
+          );
+          const result = rows[0];
+          stats[name] = {
+            distinct: result.distinct,
+            ...typeof result.min === "number" || typeof result.min === "string" ? { min: result.min } : {},
+            ...typeof result.max === "number" || typeof result.max === "string" ? { max: result.max } : {}
+          };
+        }
+        return stats;
+      }, signal)
+    };
+  }
+};
+function createDuckDBTransport(options) {
+  return new DuckDBBackend(options).transport();
+}
+
+// src/wasm.ts
+function fromDuckDBWasmConnection(connection) {
+  return {
+    async query(sql, args) {
+      if (!args.length)
+        return (await connection.query(sql)).toArray().map((row) => row.toJSON());
+      const statement = await connection.prepare(sql);
+      try {
+        return (await statement.query(...args)).toArray().map((row) => row.toJSON());
+      } finally {
+        await statement.close();
+      }
+    }
+  };
+}
+
+// src/schema.ts
+import {
+  loadSchema
+} from "@pythia-software/query-table-core";
+function loadDuckDBSchema(document) {
+  const schema = loadSchema(document);
+  const raw = document;
+  const bindings = /* @__PURE__ */ Object.create(null);
+  for (const field of schema.fields) {
+    if (field.source.kind !== "backend") continue;
+    const binding = raw.fields.find((item) => item.name === field.name)?.bindings?.duckdb;
+    if (!binding || typeof binding.expr !== "string" || !binding.expr.trim() || binding.expr.includes("\0"))
+      throw Error(
+        `Field ${field.name} requires an explicit bindings.duckdb.expr.`
+      );
+    bindings[field.name] = binding.expr;
+  }
+  return { schema, bindings };
+}
+export {
+  DUCKDB_PROFILE,
+  DuckDBBackend,
+  SQLBuilder,
+  compileDuckDBRows,
+  createDuckDBTransport,
+  fromDuckDBWasmConnection,
+  loadDuckDBSchema,
+  normalizeDuckDBValue,
+  quoteIdentifier,
+  quoteRelation
+};
+//# sourceMappingURL=index.js.map