squirreling 0.16.13 → 0.16.15

package/README.md

@@ -147,7 +147,7 @@ Squirreling mostly follows the SQL standard. The following features are supporte
 - `GROUP BY` and `HAVING` clauses, including `GROUP BY ALL`
 - Set operations: `UNION`, `UNION ALL`, `INTERSECT`, `INTERSECT ALL`, `EXCEPT`, `EXCEPT ALL`
 - `SHOW TABLES` to list the available tables
-- Expressions: `CASE`, `CAST`, `TRY_CAST`, `BETWEEN`, `IN`, `LIKE`, `IS NULL`, `IS NOT NULL`, string concatenation `||`
+- Expressions: `CASE`, `CAST`, `TRY_CAST`, `BETWEEN`, `IN`, `LIKE`, `IS [NOT] NULL`, `IS [NOT] TRUE`, `IS [NOT] FALSE`, string concatenation `||`
 - Subscript access: zero-based array indexing `col[0]`, struct field access `col['field']`, and chains like `col[0].field`
 
 ### Quoting
@@ -158,13 +158,13 @@ Squirreling mostly follows the SQL standard. The following features are supporte
 
 ### Functions
 
-- Aggregate: `COUNT`, `COUNTIF`, `SUM`, `AVG`, `MIN`, `MAX`, `MIN_BY`, `MAX_BY`, `ANY_VALUE`, `MEDIAN`, `PERCENTILE_CONT`, `APPROX_QUANTILE`, `STDDEV_POP`, `STDDEV_SAMP`, `ARRAY_AGG`, `JSON_ARRAYAGG`, `STRING_AGG`
+- Aggregate: `COUNT`, `COUNTIF`, `SUM`, `AVG`, `MIN`, `MAX`, `MIN_BY`, `MAX_BY`, `ANY_VALUE`, `MEDIAN`, `PERCENTILE_CONT`, `APPROX_QUANTILE`, `STDDEV_POP`, `STDDEV_SAMP`, `ARRAY_AGG`, `JSON_ARRAYAGG`, `STRING_AGG`, `GROUP_CONCAT`
 - Window: `ROW_NUMBER`, `LAG`, `LEAD`
-- String: `CONCAT`, `SUBSTRING`, `REPLACE`, `LENGTH`, `OCTET_LENGTH`, `UPPER`, `LOWER`, `TRIM`, `LEFT`, `RIGHT`, `INSTR`, `POSITION`, `STRPOS`, `SPLIT_PART`, `STRING_SPLIT`
+- String: `CONCAT`, `SUBSTRING`, `REPLACE`, `LENGTH`, `OCTET_LENGTH`, `UPPER`, `LOWER`, `TRIM`, `LEFT`, `RIGHT`, `INSTR`, `POSITION`, `STRPOS`, `SPLIT_PART`, `STRING_SPLIT`, `CHR`
 - Math: `ABS`, `SIGN`, `CEIL`, `FLOOR`, `ROUND`, `MOD`, `RAND`, `RANDOM`, `LN`, `LOG10`, `EXP`, `POWER`, `SQRT`
 - Trig: `SIN`, `COS`, `TAN`, `COT`, `ASIN`, `ACOS`, `ATAN`, `ATAN2`, `DEGREES`, `RADIANS`, `PI`
-- Date: `CURRENT_DATE`, `CURRENT_TIME`, `CURRENT_TIMESTAMP`, `DATE_DIFF`, `DATEDIFF`, `DATE_PART`, `DATE_TRUNC`, `EPOCH`, `EXTRACT`, `INTERVAL`
-- Json: `JSON_VALUE`, `JSON_QUERY`, `JSON_EXTRACT`, `JSON_EXTRACT_STRING`, `JSON_OBJECT`, `JSON_ARRAY_LENGTH`, `JSON_VALID`, `JSON_TYPE`, `JSON_KEYS`
+- Date: `CURRENT_DATE`, `CURRENT_TIME`, `CURRENT_TIMESTAMP`, `NOW`, `DATE_DIFF`, `DATEDIFF`, `DATE_PART`, `DATE_TRUNC`, `EPOCH`, `EXTRACT`, `INTERVAL`
+- Json: `JSON_VALUE`, `JSON_QUERY`, `JSON_EXTRACT`, `JSON_EXTRACT_STRING`, `JSON_EXTRACT_SCALAR`, `JSON_OBJECT`, `JSON_ARRAY_LENGTH`, `JSON_VALID`, `JSON_TYPE`, `JSON_KEYS`
 - Array: `ARRAY_LENGTH`, `ARRAY_POSITION`, `ARRAY_CONTAINS`, `ARRAY_SORT`, `ARRAY_APPEND`, `ARRAY_CONCAT`, `LEN`, `CARDINALITY`, `SIZE`
 - Table functions: `UNNEST`, `EXPLODE`, `JSON_EACH`
 - Regex: `REGEXP_SUBSTR`, `REGEXP_EXTRACT`, `REGEXP_REPLACE`, `REGEXP_MATCHES`, `REGEXP_LIKE`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "squirreling",
-  "version": "0.16.13",
+  "version": "0.16.15",
   "description": "Squirreling Async SQL Engine",
   "author": "Hyperparam",
   "homepage": "https://hyperparam.app",
@@ -40,10 +40,10 @@
   },
   "devDependencies": {
     "@eslint/js": "10.0.1",
-    "@types/node": "26.6.5",
+    "@types/node": "26.6.6",
     "@vitest/coverage-v8": "5.0.5",
     "eslint": "10.13.0",
-    "eslint-plugin-jsdoc": "65.4.0",
+    "eslint-plugin-jsdoc": "65.4.2",
     "globals": "17.13.0",
     "typescript": "7.0.2",
     "vitest": "5.0.5"

package/src/ast.d.ts

@@ -92,7 +92,7 @@ export interface IdentifierNode extends AstBase {
 
 export interface UnaryNode extends AstBase {
   type: 'unary'
-  op: 'NOT' | 'IS NULL' | 'IS NOT NULL' | '-'
+  op: 'NOT' | 'IS NULL' | 'IS NOT NULL' | 'IS TRUE' | 'IS NOT TRUE' | 'IS FALSE' | 'IS NOT FALSE' | '-'
   argument: ExprNode
 }
 

package/src/execute/accumulator.js

@@ -7,13 +7,15 @@ import { keyify } from './utils.js'
 /**
  * Incremental state for one streamable aggregate. Shared by the streaming
  * aggregate executor and the scanColumn fast path so COUNT/COUNTIF/SUM/AVG/
- * MIN/MAX fold semantics live in one place.
+ * MIN/MAX/MIN_BY/MAX_BY fold semantics live in one place.
  *
  * @typedef {{
  *   count: number,
  *   sum: number,
  *   min: SqlPrimitive,
  *   max: SqlPrimitive,
+ *   best?: SqlPrimitive,
+ *   bestKey?: SqlPrimitive,
  *   seen: Set<unknown> | null,
  * }} Accumulator
  */
@@ -41,8 +43,9 @@ export function newAccumulator(funcName, distinct) {
  * @param {string} funcName
  * @param {Accumulator} acc
  * @param {SqlPrimitive} value
+ * @param {SqlPrimitive} [key] - comparison key for MIN_BY/MAX_BY
  */
-export function updateAccumulator(funcName, acc, value) {
+export function updateAccumulator(funcName, acc, value, key) {
   switch (funcName) {
   case 'COUNT':
     if (value == null) break
@@ -58,6 +61,19 @@ export function updateAccumulator(funcName, acc, value) {
   case 'MAX':
     if (value != null && (acc.max === null || value > acc.max)) acc.max = value
     break
+  case 'MIN_BY':
+  case 'ARG_MIN':
+  case 'MAX_BY':
+  case 'ARG_MAX': {
+    if (value == null || key == null) break
+    const isMin = funcName === 'MIN_BY' || funcName === 'ARG_MIN'
+    // Match buffered aggregation: ignore null pairs and keep the first tie.
+    if (acc.bestKey == null || (isMin ? key < acc.bestKey : key > acc.bestKey)) {
+      acc.best = value
+      acc.bestKey = key
+    }
+    break
+  }
   default: { // SUM, AVG
     if (value == null) break
     const num = Number(value)
@@ -84,6 +100,10 @@ export function finalizeAccumulator(funcName, acc) {
   case 'AVG': return acc.count === 0 ? null : acc.sum / acc.count
   case 'MIN': return acc.min
   case 'MAX': return acc.max
+  case 'MIN_BY':
+  case 'ARG_MIN':
+  case 'MAX_BY':
+  case 'ARG_MAX': return acc.best ?? null
   default: return null
   }
 }

package/src/execute/aggregates.js

@@ -193,6 +193,18 @@ export function executeHashAggregate(plan, context) {
  * @returns {QueryResults}
  */
 export function executeScalarAggregate(plan, context) {
+  if (context.deferScans && plan.child.type === 'Scan') {
+    const child = executeScan(plan.child, context)
+    return {
+      columns: selectColumnNames(plan.columns, child.columns),
+      numRows: plan.having ? undefined : 1,
+      maxRows: 1,
+      async *rows() {
+        context.signal?.throwIfAborted()
+        yield* executeScalarAggregate(plan, { ...context, deferScans: false }).rows()
+      },
+    }
+  }
   // Fast path: use scanColumn when available
   const columnScan = tryColumnScanAggregate(plan, context)
   if (columnScan?.rows) {

package/src/execute/dynamicFilter.js

@@ -0,0 +1,131 @@
+/**
+ * @import { ExprNode, SqlPrimitive } from '../types.js'
+ * @import { QueryPlan } from '../plan/types.js'
+ */
+
+// Bound filter memory and match the session-index pruning limit.
+const MAX_DYNAMIC_FILTER_KEYS = 256
+
+/**
+ * Bounded, per-column key sets. Once a column exceeds the cap, release it and
+ * stop collecting that column. Unsupported values disable that column too.
+ *
+ * @param {number} count
+ * @param {boolean} [hash] - preserve the hash join's serialized key equivalences
+ * @returns {{ add(values: SqlPrimitive[]): void, apply(plan: QueryPlan, keys: ExprNode[]): QueryPlan }}
+ */
+export function dynamicFilter(count, hash = false) {
+  /** @type {(Set<SqlPrimitive> | undefined)[]} */
+  const sets = Array.from({ length: count }, () => new Set())
+  let active = true
+  return {
+    /**
+     * @param {SqlPrimitive[]} values
+     * @returns {void}
+     */
+    add(values) {
+      if (!active) return
+      // Hash tuple serialization uses delimiters and serializes objects. Do
+      // not prune when those encodings can collide across column boundaries.
+      if (hash && values.some(value => typeof value === 'object' && value !== null ||
+          typeof value === 'string' && (value.includes('|') || ['[', '{', '"'].includes(value[0]) || value === 'null'))) {
+        sets.fill(undefined)
+        active = false
+        return
+      }
+      for (let i = 0; i < sets.length; i++) {
+        const set = sets[i]
+        const value = values[i]
+        if (!set || value == null) continue
+        if (!['string', 'number', 'bigint', 'boolean'].includes(typeof value) ||
+            typeof value === 'number' && !Number.isFinite(value)) {
+          sets[i] = undefined
+          continue
+        }
+        set.add(value)
+        if (hash && count > 1) {
+          if (typeof value === 'boolean') set.add(String(value))
+          if (value === 'true' || value === 'false') set.add(value === 'true')
+        }
+        if (set.size > MAX_DYNAMIC_FILTER_KEYS) sets[i] = undefined
+      }
+      active = sets.some(Boolean)
+    },
+    /**
+     * @param {QueryPlan} plan
+     * @param {ExprNode[]} keys
+     * @returns {QueryPlan}
+     */
+    apply(plan, keys) {
+      for (let i = 0; i < keys.length; i++) {
+        const set = sets[i]
+        if (set?.size) plan = pushFilter(plan, keys[i], [...set])
+      }
+      return plan
+    },
+  }
+}
+
+/**
+ * Only traverse operators that preserve the meaning of a physical column.
+ * Limits, aggregates, windows and projections are deliberate barriers.
+ *
+ * @param {QueryPlan} plan
+ * @param {ExprNode} key
+ * @param {SqlPrimitive[]} values
+ * @returns {QueryPlan}
+ */
+function pushFilter(plan, key, values) {
+  if (key?.type !== 'identifier') return plan
+  if (plan.type === 'Scan') {
+    if (key.prefix && key.prefix !== (plan.alias ?? plan.table) ||
+        plan.hints.limit !== undefined || plan.hints.offset || plan.topK) return plan
+    const position = { positionStart: key.positionStart, positionEnd: key.positionEnd }
+    /** @type {ExprNode} */
+    const filter = {
+      type: 'in valuelist', expr: key, ...position,
+      values: values.map(value => ({ type: 'literal', value, ...position })),
+    }
+    /** @type {ExprNode} */
+    const where = plan.hints.where
+      ? { type: 'binary', op: 'AND', left: plan.hints.where, right: filter, ...position }
+      : filter
+    return { ...plan, hints: { ...plan.hints, where } }
+  }
+  if (plan.type === 'Filter' || plan.type === 'Sort' && !plan.topK || plan.type === 'Distinct') {
+    return { ...plan, child: pushFilter(plan.child, key, values) }
+  }
+  if (plan.type === 'HashJoin' && key.prefix) {
+    // Restrict only preserved inputs of outer joins; restricting an optional
+    // input could turn a formerly matched row into a new null-extended row.
+    const left = plan.joinType === 'INNER' || plan.joinType === 'LEFT'
+      ? pushFilter(plan.left, key, values) : plan.left
+    const right = plan.joinType === 'INNER' || plan.joinType === 'RIGHT'
+      ? pushFilter(plan.right, key, values) : plan.right
+    return { ...plan, left, right }
+  }
+  return plan
+}
+
+/**
+ * Selectivity heuristic when exact filtered cardinalities are unavailable.
+ * Count conjuncts so a date plus a LIKE wins over a lone part-type predicate.
+ *
+ * @param {QueryPlan} plan
+ * @returns {number}
+ */
+export function filterScore(plan) {
+  if (plan.type === 'Scan') return conjuncts(plan.hints.where)
+  if (plan.type === 'Filter') return conjuncts(plan.condition) + filterScore(plan.child)
+  if (plan.type === 'HashJoin' && plan.joinType === 'INNER') return Math.max(filterScore(plan.left), filterScore(plan.right))
+  return 0
+}
+
+/**
+ * @param {ExprNode} expr
+ * @returns {number}
+ */
+function conjuncts(expr) {
+  return !expr ? 0 : expr.type === 'binary' && expr.op === 'AND'
+    ? conjuncts(expr.left) + conjuncts(expr.right) : 1
+}

package/src/execute/execute.js

@@ -1,5 +1,5 @@
 import { selectedRowCount } from '../backend/batch.js'
-import { batchesToRows } from '../backend/batchAdapters.js'
+import { batchesToRows, rowsToBatches } from '../backend/batchAdapters.js'
 import { dataSourceColumns, memorySource } from '../backend/dataSource.js'
 import { derivedAlias } from '../expression/alias.js'
 import { compileBatchExpression } from '../expression/batch.js'
@@ -98,6 +98,9 @@ export function executeStatement({ query, context, outerScope }) {
  * @returns {QueryResults}
  */
 export function executePlan({ plan, context }) {
+  if (context.currentTimestamp === undefined) {
+    context = { ...context, currentTimestamp: new Date().toISOString() }
+  }
   if (plan.type === 'Scan') {
     return executeScan(plan, context)
   } else if (plan.type === 'SingleRow') {
@@ -318,6 +321,37 @@ export function executeScan(plan, context, existingColumnResult) {
   const { tables, signal } = context
   const table = validateTable({ ...plan, tables })
   validateScan({ ...plan, tables })
+  if (context.deferScans && !existingColumnResult) {
+    const size = computeScanRows(table.numRows, plan.hints.limit, plan.hints.offset)
+    const columns = plan.hints.columns ?? dataSourceColumns(table)
+    /** @type {QueryResults} */
+    const deferred = {
+      columns,
+      numRows: plan.hints.where ? undefined : size,
+      maxRows: size,
+      async *rows() {
+        context.signal?.throwIfAborted()
+        yield* executeScan(plan, { ...context, deferScans: false }).rows()
+      },
+    }
+    // Preserve native batch execution above a deferred input. Legacy fallback
+    // remains at the source boundary if a source declines its column path.
+    if (table.prepareScan && table.schema || table.scanColumn && plan.hints.columns?.length === 1) {
+      deferred.batches = async function* deferredBatches() {
+        context.signal?.throwIfAborted()
+        const result = executeScan(plan, { ...context, deferScans: false })
+        if (result.batches) {
+          // Prepared sources may return extra fields or a different order.
+          // Align vectors with the metadata exposed before opening the scan.
+          const indexes = columns.map(column => result.columns.indexOf(column))
+          for await (const batch of result.batches()) {
+            yield { ...batch, columns: indexes.map(index => batch.columns[index]) }
+          }
+        } else yield* rowsToBatches(result.rows(), columns, { signal })
+      }
+    }
+    return deferred
+  }
   const { where, residual } = scanFilter(plan, dataSourceColumns(table))
   const hints = { ...plan.hints, where }
   if (residual) {

package/src/execute/join.js

@@ -1,6 +1,7 @@
 import { evaluateExpr } from '../expression/evaluate.js'
 import { keyify, maxBounds } from './utils.js'
 import { executePlan } from './execute.js'
+import { dynamicFilter, filterScore } from './dynamicFilter.js'
 import { yieldToEventLoop } from './yield.js'
 
 /**
@@ -222,14 +223,18 @@ export function executePositionalJoin(plan, context) {
  * @returns {QueryResults}
  */
 export function executeHashJoin(plan, context) {
-  const left = executePlan({ plan: plan.left, context })
-  const right = executePlan({ plan: plan.right, context })
-  // Build the hash table on the smaller side when both sizes are known,
-  // so joining a small table against a large one buffers the small one.
+  const left = executePlan({ plan: plan.left, context: { ...context, deferScans: true } })
+  const right = executePlan({ plan: plan.right, context: { ...context, deferScans: true } })
+  // Prefer exact sizes, then predicate selectivity, then upper bounds.
+  // A filtered scan's table size is only an upper bound, not its cardinality.
   // Swapping reorders output rows, which SQL leaves unspecified.
   const leftSize = left.numRows ?? left.maxRows
   const rightSize = right.numRows ?? right.maxRows
-  const swap = leftSize !== undefined && rightSize !== undefined && leftSize < rightSize
+  const swap = left.numRows !== undefined && right.numRows !== undefined
+    ? leftSize < rightSize
+    : filterScore(plan.left) !== filterScore(plan.right)
+      ? filterScore(plan.left) > filterScore(plan.right)
+      : leftSize !== undefined && rightSize !== undefined && leftSize < rightSize
   return {
     columns: mergeColumnNames(left.columns, right.columns, plan.leftAlias, plan.rightAlias),
     async *rows() {
@@ -237,7 +242,7 @@ export function executeHashJoin(plan, context) {
       const rightTable = plan.rightAlias
       const { residual } = plan
       const build = swap ? left : right
-      const probe = swap ? right : left
+      let probe = swap ? right : left
       const buildKeys = swap ? plan.leftKeys : plan.rightKeys
       const probeKeys = swap ? plan.rightKeys : plan.leftKeys
       // Which sides must also emit their unmatched rows
@@ -260,6 +265,7 @@ export function executeHashJoin(plan, context) {
       // otherwise rows with NULL join keys are released immediately.
       /** @type {Map<string | number | bigint | boolean, AsyncRow[]>} */
       const hashMap = new Map()
+      const filters = dynamicFilter(buildKeys.length, true)
       /** @type {AsyncRow[] | undefined} */
       const buildRows = buildOuter ? [] : undefined
       /** @type {string[]} */
@@ -281,6 +287,7 @@ export function executeHashJoin(plan, context) {
         // SQL semantics: NULL never equals anything, so a row with any NULL
         // join key is excluded from the hash table.
         if (keyValues.some(v => v == null)) continue
+        if (!probeOuter) filters.add(keyValues)
         const key = keyify(...keyValues)
         let bucket = hashMap.get(key)
         if (!bucket) {
@@ -295,8 +302,14 @@ export function executeHashJoin(plan, context) {
       /** @type {Set<AsyncRow> | undefined} */
       const matchedBuildRows = buildOuter ? new Set() : undefined
 
+      if (!probeOuter && !hashMap.size && !buildOuter) return
+      if (!probeOuter && hashMap.size) {
+        const filtered = filters.apply(swap ? plan.right : plan.left, probeKeys)
+        probe = executePlan({ plan: filtered, context: { ...context, deferScans: true } })
+      }
+
       // Probe phase: stream the other side
-      for await (const probeRow of probe.rows()) {
+      for await (const probeRow of !probeOuter && !hashMap.size ? [] : probe.rows()) {
         context.signal?.throwIfAborted()
 
         if (!probeCols) {

package/src/execute/semiJoin.js

@@ -1,5 +1,6 @@
 import { evaluateExpr } from '../expression/evaluate.js'
 import { executePlan } from './execute.js'
+import { dynamicFilter } from './dynamicFilter.js'
 import { sqlEquals } from './utils.js'
 import { yieldToEventLoop } from './yield.js'
 
@@ -19,7 +20,7 @@ import { yieldToEventLoop } from './yield.js'
  */
 export function executeSemiJoin(plan, context) {
   if (plan.keys) return executeExistsJoin(plan, context)
-  const left = executePlan({ plan: plan.left, context })
+  const left = executePlan({ plan: plan.left, context: { ...context, deferScans: true } })
   return {
     columns: left.columns,
     maxRows: left.maxRows,
@@ -28,29 +29,30 @@ export function executeSemiJoin(plan, context) {
       const values = new Map()
       let hasNull = false
       let count = 0
-      let built = false
       let rowIndex = 0
-      for await (const row of left.rows()) {
+      const filters = dynamicFilter(1)
+      for await (const inner of executePlan({ plan: plan.right, context }).rows()) {
+        context.signal?.throwIfAborted()
+        if (++count % 4000 === 0) await yieldToEventLoop()
+        const value = await inner.cells[inner.columns[0]]()
+        if (value == null) hasNull = true
+        else {
+          const type = typeof value
+          let group = values.get(type)
+          if (!group) values.set(type, group = new Set())
+          group.add(value)
+          if (!plan.not) filters.add([value])
+        }
+      }
+      if (!plan.not && !values.size || plan.not && hasNull) return
+      const probe = executePlan({
+        plan: plan.not ? plan.left : filters.apply(plan.left, [plan.expr]),
+        context: { ...context, deferScans: true },
+      })
+      for await (const row of probe.rows()) {
         context.signal?.throwIfAborted()
         if (++rowIndex % 4000 === 0) await yieldToEventLoop()
         const value = await evaluateExpr({ node: plan.expr, row, rowIndex, context })
-        if (!built) {
-          for await (const inner of executePlan({ plan: plan.right, context }).rows()) {
-            if (++count % 4000 === 0) {
-              await yieldToEventLoop()
-              context.signal?.throwIfAborted()
-            }
-            const value = await inner.cells[inner.columns[0]]()
-            if (value == null) hasNull = true
-            else {
-              const type = typeof value
-              let group = values.get(type)
-              if (!group) values.set(type, group = new Set())
-              group.add(value)
-            }
-          }
-          built = true
-        }
         const matched = count === 0 ? false : value == null ? null : contains(values, value) ? true : hasNull ? null : false
         if (matched !== null && matched !== plan.not) yield row
       }
@@ -87,36 +89,39 @@ function contains(values, value) {
  * @returns {QueryResults}
  */
 function executeExistsJoin(plan, context) {
-  const left = executePlan({ plan: plan.left, context })
+  const left = executePlan({ plan: plan.left, context: { ...context, deferScans: true } })
   return {
     columns: left.columns,
     maxRows: left.maxRows,
     async *rows() {
       /** @type {KeyTrie} */
       const root = { groups: new Map() }
-      let built = false
       let count = 0
-      for await (const row of left.rows()) {
+      const filters = dynamicFilter(plan.keys?.length ?? 0)
+      for await (const inner of executePlan({ plan: plan.right, context }).rows()) {
         context.signal?.throwIfAborted()
         if (++count % 4000 === 0) await yieldToEventLoop()
-        if (!built) {
-          for await (const inner of executePlan({ plan: plan.right, context }).rows()) {
-            context.signal?.throwIfAborted()
-            if (++count % 4000 === 0) await yieldToEventLoop()
-            const values = await Promise.all(inner.columns.map(col => inner.cells[col]()))
-            if (values.some(value => value == null)) continue
-            let node = root
-            for (const value of values) {
-              const type = typeof value
-              let group = node.groups.get(type)
-              if (!group) node.groups.set(type, group = new Map())
-              let child = group.get(value)
-              if (!child) group.set(value, child = { groups: new Map() })
-              node = child
-            }
-          }
-          built = true
+        const values = await Promise.all(inner.columns.map(col => inner.cells[col]()))
+        if (values.some(value => value == null)) continue
+        if (!plan.not) filters.add(values)
+        let node = root
+        for (const value of values) {
+          const type = typeof value
+          let group = node.groups.get(type)
+          if (!group) node.groups.set(type, group = new Map())
+          let child = group.get(value)
+          if (!child) group.set(value, child = { groups: new Map() })
+          node = child
         }
+      }
+      if (!plan.not && !root.groups.size) return
+      const probe = executePlan({
+        plan: plan.not ? plan.left : filters.apply(plan.left, plan.keys ?? []),
+        context: { ...context, deferScans: true },
+      })
+      for await (const row of probe.rows()) {
+        context.signal?.throwIfAborted()
+        if (++count % 4000 === 0) await yieldToEventLoop()
         const values = await Promise.all((plan.keys ?? []).map(node => evaluateExpr({ node, row, context })))
         const matched = !values.some(value => value == null) && matchesKeys(root, values, 0)
         if (matched !== plan.not) yield row

package/src/execute/streamingAggregate.js

@@ -24,7 +24,7 @@ const CHUNK_SIZE = 4000
 // Aggregate functions whose state can be accumulated one row at a time with
 // bounded memory. Aggregates outside this set (MEDIAN, ARRAY_AGG, STDDEV, ...)
 // need the full value set, so their queries buffer rows instead.
-const STREAMABLE_FUNCS = new Set(['COUNT', 'COUNTIF', 'SUM', 'AVG', 'MIN', 'MAX'])
+const STREAMABLE_FUNCS = new Set(['COUNT', 'COUNTIF', 'SUM', 'AVG', 'MIN', 'MAX', 'MIN_BY', 'MAX_BY', 'ARG_MIN', 'ARG_MAX'])
 
 /**
  * Specs are keyed by aggregate node identity, so two aggregates that differ
@@ -178,6 +178,7 @@ export function planStreamingAggregates({ columns, having, orderBy, groupBy }, c
       }
       if (!STREAMABLE_FUNCS.has(funcName)) return false
       const star = node.args[0]?.type === 'star'
+      if (star && node.args.length > 1) return false
       if (lazy && !(star && !node.filter)) return false
       if (!star && !node.args.every(arg => isScalarExpr(arg))) return false
       if (node.filter && !isScalarExpr(node.filter)) return false
@@ -401,7 +402,7 @@ function accumulateChunk({ chunk, groupBy, specs, groups, needsRow, context }) {
     rows: chunk,
     signal: context.signal,
     // One flat tuple per row: group key values, then per spec its FILTER
-    // result and its argument. The argument is only evaluated for rows that
+    // result and its arguments. Arguments are only evaluated for rows that
     // pass the FILTER, matching the buffered path.
     evaluate(row) {
       const pending = groupBy.map(expr => evaluateExpr({ node: expr, row, context }))
@@ -410,10 +411,14 @@ function accumulateChunk({ chunk, groupBy, specs, groups, needsRow, context }) {
           const passes = evaluateExpr({ node: node.filter, row, context })
           pending.push(passes)
           if (!star) {
-            pending.push(passes.then(pass => pass ? evaluateExpr({ node: node.args[0], row, context }) : null))
+            for (const argument of node.args) {
+              pending.push(passes.then(pass => pass ? evaluateExpr({ node: argument, row, context }) : null))
+            }
           }
         } else if (!star) {
-          pending.push(evaluateExpr({ node: node.args[0], row, context }))
+          for (const argument of node.args) {
+            pending.push(evaluateExpr({ node: argument, row, context }))
+          }
         }
       }
       return Promise.all(pending)
@@ -431,11 +436,12 @@ function accumulateChunk({ chunk, groupBy, specs, groups, needsRow, context }) {
         const spec = specs[s]
         const passes = spec.node.filter ? values[slot++] : true
         const arg = spec.star ? null : values[slot++]
+        const comparison = spec.node.args.length > 1 ? values[slot++] : undefined
         if (!passes) continue
         if (spec.star && spec.funcName === 'COUNT') {
           group.accumulators[s].count++
         } else {
-          updateAccumulator(spec.funcName, group.accumulators[s], arg)
+          updateAccumulator(spec.funcName, group.accumulators[s], arg, comparison)
         }
       }
     },
@@ -470,16 +476,18 @@ function compileBatchAggregateInputs(groupBy, specs, columns, context) {
   for (const spec of specs) {
     if (spec.node.filter && !spec.star) return undefined
     if (spec.node.filter && referencesRowScope(spec.node.filter, columns, context)) return undefined
-    if (!spec.star && referencesRowScope(spec.node.args[0], columns, context)) return undefined
+    if (!spec.star && spec.node.args.some(argument => referencesRowScope(argument, columns, context))) return undefined
     const filter = spec.node.filter
       ? compileBatchExpression(spec.node.filter, columns)
       : undefined
     const argument = spec.star
       ? undefined
       : compileBatchExpression(spec.node.args[0], columns)
-    if (spec.node.filter && !filter || !spec.star && !argument) return undefined
+    const comparison = spec.node.args[1] && compileBatchExpression(spec.node.args[1], columns)
+    if (spec.node.filter && !filter || !spec.star && !argument || spec.node.args[1] && !comparison) return undefined
     filters.push(filter)
     args.push(argument)
+    if (spec.node.args[1]) args.push(comparison)
   }
   return {
     keys,
@@ -563,15 +571,18 @@ async function accumulateBatch({ batch, inputs, specs, groups, context, rowOffse
       }
       groups.set(key, group)
     }
+    let argumentIndex = 0
     for (let specIndex = 0; specIndex < specs.length; specIndex++) {
+      const spec = specs[specIndex]
+      const argument = args[argumentIndex++]
+      const comparison = spec.node.args[1] ? args[argumentIndex++] : undefined
       const filter = filters[specIndex]
       if (filter && !valueAt(filter, rowIndex)) continue
-      const spec = specs[specIndex]
       if (spec.star && spec.funcName === 'COUNT') {
         group.accumulators[specIndex].count++
       } else {
-        const argument = args[specIndex]
-        updateAccumulator(spec.funcName, group.accumulators[specIndex], argument ? valueAt(argument, rowIndex) : null)
+        updateAccumulator(spec.funcName, group.accumulators[specIndex],
+          argument ? valueAt(argument, rowIndex) : null, comparison ? valueAt(comparison, rowIndex) : undefined)
       }
     }
   }

package/src/expression/batch.js

@@ -5,7 +5,7 @@ import { isStringFunc } from '../validation/functions.js'
 import { ColumnNotFoundError } from '../validation/tables.js'
 import { applyBinaryOp } from './binary.js'
 import { evaluateRegexpLike } from './regexp.js'
-import { applyCast, evaluateJsonExtract } from './scalar.js'
+import { applyCast, applyUnaryOp, evaluateJsonExtract } from './scalar.js'
 import { evaluateStringFunc } from './strings.js'
 
 /**
@@ -52,10 +52,7 @@ function compileEvaluator(node, columns) {
         const vector = await argument.evaluate(context)
         return evaluateValues(context, function unaryValue(rowIndex) {
           const value = valueAt(vector, rowIndex)
-          if (node.op === '-') return value == null ? null : -value
-          if (node.op === 'NOT') return value == null ? null : !value
-          if (node.op === 'IS NULL') return value == null
-          return value != null
+          return applyUnaryOp(node.op, value)
         })
       },
     }
@@ -184,10 +181,7 @@ function compileValueKernel(node, state) {
     if (!argument) return undefined
     return function unaryValue(vectors, rowIndex, streamRowIndex) {
       const value = argument(vectors, rowIndex, streamRowIndex)
-      if (node.op === '-') return value == null ? null : -value
-      if (node.op === 'NOT') return value == null ? null : !value
-      if (node.op === 'IS NULL') return value == null
-      return value != null
+      return applyUnaryOp(node.op, value)
     }
   }
 
@@ -278,7 +272,7 @@ function compileFunctionKernel(node, state) {
       return sqlEquals(first, second) ? null : first
     }
   }
-  if (funcName === 'JSON_VALUE' || funcName === 'JSON_QUERY' || funcName === 'JSON_EXTRACT' || funcName === 'JSON_EXTRACT_STRING') {
+  if (funcName === 'JSON_VALUE' || funcName === 'JSON_QUERY' || funcName === 'JSON_EXTRACT' || funcName === 'JSON_EXTRACT_STRING' || funcName === 'JSON_EXTRACT_SCALAR') {
     return function jsonValue(vectors, rowIndex, streamRowIndex) {
       const args = arguments_.map(function argumentValue(argument) {
         return argument(vectors, rowIndex, streamRowIndex)
@@ -327,7 +321,7 @@ function compileFunctionEvaluator(node, columns) {
     }
   }
   if (funcName !== 'NULLIF' && funcName !== 'JSON_VALUE' && funcName !== 'JSON_QUERY' &&
-    funcName !== 'JSON_EXTRACT' && funcName !== 'JSON_EXTRACT_STRING' && funcName !== 'REGEXP_LIKE' &&
+    funcName !== 'JSON_EXTRACT' && funcName !== 'JSON_EXTRACT_STRING' && funcName !== 'JSON_EXTRACT_SCALAR' && funcName !== 'REGEXP_LIKE' &&
     !isStringFunc(funcName)) return undefined
   const regexpCache = funcName === 'REGEXP_LIKE' && node.args[1]?.type === 'literal' ? {} : undefined
   return {
@@ -338,7 +332,7 @@ function compileFunctionEvaluator(node, columns) {
       return evaluateValues(context, function functionValue(rowIndex, streamRowIndex) {
         const args = vectors.map(function argumentValue(vector) { return valueAt(vector, rowIndex) })
         if (funcName === 'NULLIF') return sqlEquals(args[0], args[1]) ? null : args[0]
-        if (funcName === 'JSON_VALUE' || funcName === 'JSON_QUERY' || funcName === 'JSON_EXTRACT' || funcName === 'JSON_EXTRACT_STRING') {
+        if (funcName === 'JSON_VALUE' || funcName === 'JSON_QUERY' || funcName === 'JSON_EXTRACT' || funcName === 'JSON_EXTRACT_STRING' || funcName === 'JSON_EXTRACT_SCALAR') {
           return evaluateJsonExtract({ funcName, node, args, rowIndex: streamRowIndex + 1 })
         }
         if (funcName === 'REGEXP_LIKE') {

package/src/expression/evaluate.js

@@ -10,7 +10,7 @@ import { applyBinaryOp } from './binary.js'
 import { applyIntervalToDate, dateDiff, dateTrunc, extractField } from './date.js'
 import { evaluateMathFunc } from './math.js'
 import { evaluateRegexpFunc } from './regexp.js'
-import { applyCast, evaluateJsonExtract } from './scalar.js'
+import { applyCast, applyUnaryOp, evaluateJsonExtract } from './scalar.js'
 import { evaluateSpatialFunc } from '../spatial/spatial.js'
 import { evaluateStringFunc } from './strings.js'
 
@@ -171,15 +171,7 @@ export async function evaluateExpr({ node, row, rowIndex, rows, context }) {
   // Unary operators
   if (node.type === 'unary') {
     const val = await evaluateExpr({ node: node.argument, row, rowIndex, rows, context })
-    if (node.op === '-') {
-      if (val == null) return null
-      return -val
-    }
-    // NOT UNKNOWN is UNKNOWN: JS ! would flip null to true and return rows
-    // SQL excludes, e.g. WHERE NOT (nullable < 300)
-    if (node.op === 'NOT') return val == null ? null : !val
-    if (node.op === 'IS NULL') return val == null
-    if (node.op === 'IS NOT NULL') return val != null
+    return applyUnaryOp(node.op, val)
   }
 
   // Binary operators
@@ -411,9 +403,12 @@ export async function evaluateExpr({ node, row, rowIndex, rows, context }) {
         }
       }
 
-      if (funcName === 'STRING_AGG') {
+      if (funcName === 'STRING_AGG' || funcName === 'GROUP_CONCAT') {
         const separatorNode = node.args[1]
-        const separator = String(await evaluateExpr({ node: separatorNode, row: filteredRows[0] ?? { columns: [], cells: {} }, context }))
+        const separatorValue = separatorNode
+          ? await evaluateExpr({ node: separatorNode, row: filteredRows[0] ?? { columns: [], cells: {} }, context })
+          : ','
+        const separator = funcName === 'GROUP_CONCAT' && separatorValue == null ? '' : String(separatorValue)
         /** @type {string[]} */
         const values = []
         const allValues = await evaluateAll(argNode, filteredRows, context)
@@ -506,15 +501,15 @@ export async function evaluateExpr({ node, row, rowIndex, rows, context }) {
     }
 
     if (funcName === 'CURRENT_DATE') {
-      return new Date().toISOString().split('T')[0]
+      return (context.currentTimestamp ?? new Date().toISOString()).split('T')[0]
     }
 
     if (funcName === 'CURRENT_TIME') {
-      return new Date().toISOString().split('T')[1].replace('Z', '')
+      return (context.currentTimestamp ?? new Date().toISOString()).split('T')[1].replace('Z', '')
     }
 
-    if (funcName === 'CURRENT_TIMESTAMP') {
-      return new Date().toISOString()
+    if (funcName === 'CURRENT_TIMESTAMP' || funcName === 'NOW') {
+      return context.currentTimestamp ?? new Date().toISOString()
     }
 
     if (funcName === 'JSON_OBJECT') {
@@ -676,7 +671,7 @@ export async function evaluateExpr({ node, row, rowIndex, rows, context }) {
       })
     }
 
-    if (funcName === 'JSON_VALUE' || funcName === 'JSON_QUERY' || funcName === 'JSON_EXTRACT' || funcName === 'JSON_EXTRACT_STRING') {
+    if (funcName === 'JSON_VALUE' || funcName === 'JSON_QUERY' || funcName === 'JSON_EXTRACT' || funcName === 'JSON_EXTRACT_STRING' || funcName === 'JSON_EXTRACT_SCALAR') {
       return evaluateJsonExtract({ funcName, node, args, rowIndex })
     }
 

package/src/expression/scalar.js

@@ -3,7 +3,7 @@ import { ArgValueError, ExecutionError } from '../validation/executionErrors.js'
 import { toDate } from './date.js'
 
 /**
- * @import { CastNode, FunctionNode, SqlPrimitive } from '../types.js'
+ * @import { CastNode, FunctionNode, SqlPrimitive, UnaryNode } from '../types.js'
  */
 
 /**
@@ -72,7 +72,7 @@ export function evaluateJsonExtract({ funcName, node, args, rowIndex }) {
       })
     }
   }
-  if (typeof json !== 'object' || json instanceof Date) {
+  if (funcName !== 'JSON_EXTRACT_SCALAR' && typeof json !== 'object' || json instanceof Date) {
     throw new ArgValueError({
       ...node,
       message: `first argument must be JSON string or object, got ${typeof json}`,
@@ -98,8 +98,28 @@ export function evaluateJsonExtract({ funcName, node, args, rowIndex }) {
   }
 
   if (current == null) return null
+  if (funcName === 'JSON_EXTRACT_SCALAR') {
+    return typeof current === 'object' ? null : String(current)
+  }
   if (funcName === 'JSON_EXTRACT_STRING') {
     return typeof current === 'object' ? JSON.stringify(current) : String(current)
   }
   return current
 }
+
+/**
+ * Applies unary predicates identically in row and batch execution.
+ * @param {UnaryNode['op']} op
+ * @param {SqlPrimitive} value
+ * @returns {SqlPrimitive}
+ */
+export function applyUnaryOp(op, value) {
+  if (op === '-') return value == null ? null : -value
+  if (op === 'NOT') return value == null ? null : !value
+  if (op === 'IS NULL') return value == null
+  if (op === 'IS NOT NULL') return value != null
+  if (op === 'IS TRUE') return value === true
+  if (op === 'IS NOT TRUE') return value !== true
+  if (op === 'IS FALSE') return value === false
+  return value !== false
+}

package/src/expression/strings.js

@@ -35,6 +35,17 @@ export function evaluateStringFunc({ funcName, node, args, rowIndex }) {
   const [val] = args
   if (val == null) return null
 
+  if (funcName === 'CHR') {
+    const codePoint = typeof val === 'number' || typeof val === 'bigint' ? Number(val) : NaN
+    if (!Number.isInteger(codePoint) || codePoint < 0 || codePoint > 0x10ffff ||
+        codePoint >= 0xd800 && codePoint <= 0xdfff) {
+      throw new ArgValueError({
+        ...node, message: 'expected a Unicode scalar value (0..0x10ffff, excluding surrogates)', rowIndex,
+      })
+    }
+    return String.fromCodePoint(codePoint)
+  }
+
   if (funcName === 'LENGTH') {
     if (typeof val === 'string' || Array.isArray(val)) return val.length
     throw new ArgValueError({

package/src/internalTypes.d.ts

@@ -23,6 +23,7 @@ export interface CompileState {
 export interface BatchAggregateInputs {
   keys: CompiledBatchExpression[]
   filters: (CompiledBatchExpression | undefined)[]
+  // One value slot per aggregate, followed by its key for MIN_BY/MAX_BY.
   args: (CompiledBatchExpression | undefined)[]
 }
 

package/src/parse/expression.js

@@ -5,7 +5,7 @@ import { parseStatement } from './parse.js'
 import { consume, current, expect, match } from './state.js'
 
 /**
- * @import { ExprNode, ParserState } from '../types.js'
+ * @import { ExprNode, ParserState, UnaryNode } from '../types.js'
  */
 
 // Precedence (lowest to highest):
@@ -91,10 +91,18 @@ function parseComparison(state) {
   const left = parseConcat(state)
   const { positionStart } = left
 
-  // IS [NOT] NULL
+  // IS [NOT] NULL/TRUE/FALSE
   if (match(state, 'keyword', 'IS')) {
-    const op = match(state, 'keyword', 'NOT') ? 'IS NOT NULL' : 'IS NULL'
-    expect(state, 'keyword', 'NULL')
+    const not = match(state, 'keyword', 'NOT')
+    const target = current(state)
+    if (target.type !== 'keyword' || !['NULL', 'TRUE', 'FALSE'].includes(target.value)) {
+      throw new SyntaxError({ expected: 'NULL, TRUE, or FALSE', after: not ? 'NOT' : 'IS', ...target })
+    }
+    consume(state)
+    /** @type {UnaryNode['op']} */
+    const op = target.value === 'TRUE' ? not ? 'IS NOT TRUE' : 'IS TRUE'
+      : target.value === 'FALSE' ? not ? 'IS NOT FALSE' : 'IS FALSE'
+        : not ? 'IS NOT NULL' : 'IS NULL'
     return {
       type: 'unary',
       op,

package/src/types.d.ts

@@ -212,6 +212,10 @@ export interface ExecuteContext {
   // CTE references in subqueries re-planned during execution
   ctePlans?: Map<string, QueryPlan>
   cteColumns?: Map<string, string[]>
+  // UTC timestamp shared by current-time functions throughout one execution.
+  currentTimestamp?: string
+  // Delay opening join input scans until their rows are consumed.
+  deferScans?: boolean
 }
 
 // AsyncRow represents a row with async cell values
@@ -312,7 +316,7 @@ export interface UserDefinedFunction {
   arguments: FunctionSignature
 }
 
-export type AggregateFunc = 'COUNT' | 'COUNTIF' | 'SUM' | 'AVG' | 'MIN' | 'MAX' | 'MIN_BY' | 'ARG_MIN' | 'MAX_BY' | 'ARG_MAX' | 'ANY_VALUE' | 'ARRAY_AGG' | 'LIST' | 'JSON_ARRAYAGG' | 'STDDEV_SAMP' | 'STDDEV_POP' | 'MEDIAN' | 'PERCENTILE_CONT' | 'APPROX_QUANTILE' | 'STRING_AGG'
+export type AggregateFunc = 'COUNT' | 'COUNTIF' | 'SUM' | 'AVG' | 'MIN' | 'MAX' | 'MIN_BY' | 'ARG_MIN' | 'MAX_BY' | 'ARG_MAX' | 'ANY_VALUE' | 'ARRAY_AGG' | 'LIST' | 'JSON_ARRAYAGG' | 'STDDEV_SAMP' | 'STDDEV_POP' | 'MEDIAN' | 'PERCENTILE_CONT' | 'APPROX_QUANTILE' | 'STRING_AGG' | 'GROUP_CONCAT'
 
 export type RegExpFunction = 'REGEXP_SUBSTR' | 'REGEXP_EXTRACT' | 'REGEXP_REPLACE' | 'REGEXP_MATCHES' | 'REGEXP_LIKE'
 
@@ -345,6 +349,7 @@ export type MathFunc =
   | 'RANDOM'
 
 export type StringFunc =
+  | 'CHR'
   | 'UPPER'
   | 'LOWER'
   | 'CONCAT'

package/src/validation/functions.js

@@ -11,7 +11,7 @@ export const niladicFuncs = ['CURRENT_DATE', 'CURRENT_TIME', 'CURRENT_TIMESTAMP'
  * @returns {name is AggregateFunc}
  */
 export function isAggregateFunc(name) {
-  return ['COUNT', 'COUNTIF', 'SUM', 'AVG', 'MIN', 'MAX', 'MIN_BY', 'ARG_MIN', 'MAX_BY', 'ARG_MAX', 'ANY_VALUE', 'ARRAY_AGG', 'LIST', 'JSON_ARRAYAGG', 'STDDEV_SAMP', 'STDDEV_POP', 'MEDIAN', 'PERCENTILE_CONT', 'APPROX_QUANTILE', 'STRING_AGG'].includes(name)
+  return ['COUNT', 'COUNTIF', 'SUM', 'AVG', 'MIN', 'MAX', 'MIN_BY', 'ARG_MIN', 'MAX_BY', 'ARG_MAX', 'ANY_VALUE', 'ARRAY_AGG', 'LIST', 'JSON_ARRAYAGG', 'STDDEV_SAMP', 'STDDEV_POP', 'MEDIAN', 'PERCENTILE_CONT', 'APPROX_QUANTILE', 'STRING_AGG', 'GROUP_CONCAT'].includes(name)
 }
 
 /**
@@ -96,7 +96,7 @@ export function isCastType(name) {
 export function isStringFunc(name) {
   return [
     'UPPER', 'LOWER', 'CONCAT', 'LENGTH', 'OCTET_LENGTH', 'SUBSTRING', 'SUBSTR', 'TRIM',
-    'REPLACE', 'LEFT', 'RIGHT', 'INSTR', 'POSITION', 'STRPOS', 'SPLIT_PART', 'STRING_SPLIT',
+    'REPLACE', 'LEFT', 'RIGHT', 'INSTR', 'POSITION', 'STRPOS', 'SPLIT_PART', 'STRING_SPLIT', 'CHR',
   ].includes(name)
 }
 
@@ -114,6 +114,7 @@ export function isBinaryOp(op) {
  */
 export const FUNCTION_SIGNATURES = {
   // String functions
+  CHR: { min: 1, max: 1, signature: 'code_point' },
   UPPER: { min: 1, max: 1, signature: 'string' },
   LOWER: { min: 1, max: 1, signature: 'string' },
   LENGTH: { min: 1, max: 1, signature: 'string' },
@@ -137,6 +138,7 @@ export const FUNCTION_SIGNATURES = {
   REGEXP_LIKE: { min: 2, max: 2, signature: 'string, pattern' },
 
   // Date/time functions
+  NOW: { min: 0, max: 0, signature: '' },
   RANDOM: { min: 0, max: 0, signature: '' },
   RAND: { min: 0, max: 0, signature: '' },
   CURRENT_DATE: { min: 0, max: 0, signature: '' },
@@ -176,6 +178,7 @@ export const FUNCTION_SIGNATURES = {
   PI: { min: 0, max: 0, signature: '' },
 
   // JSON functions
+  JSON_EXTRACT_SCALAR: { min: 2, max: 2, signature: 'expression, path' },
   JSON_VALUE: { min: 2, max: 2, signature: 'expression, path' },
   JSON_QUERY: { min: 2, max: 2, signature: 'expression, path' },
   JSON_EXTRACT: { min: 2, max: 2, signature: 'expression, path' },
@@ -217,6 +220,7 @@ export const FUNCTION_SIGNATURES = {
   LEAST: { min: 1, signature: 'value1[, value2, ...]' },
 
   // Aggregate functions
+  GROUP_CONCAT: { min: 1, max: 2, signature: 'expression[, separator]' },
   COUNT: { min: 1, max: 1, signature: 'expression' },
   COUNTIF: { min: 1, max: 1, signature: 'condition' },
   SUM: { min: 1, max: 1, signature: 'expression' },