squirreling 0.12.1 → 0.12.3

package/README.md

@@ -140,7 +140,7 @@ Squirreling mostly follows the SQL standard. The following features are supporte
 
 - `SELECT` statements with `DISTINCT`, `WHERE`, `ORDER BY`, `LIMIT`, `OFFSET`
 - `WITH` clause for Common Table Expressions (CTEs)
-- Subqueries in `SELECT`, `FROM`, and `WHERE` clauses
+- Subqueries in `SELECT`, `FROM`, `WHERE`, and correlated subqueries
 - `JOIN` operations: `INNER JOIN`, `LEFT JOIN`, `RIGHT JOIN`, `FULL JOIN`, `CROSS JOIN`, `POSITIONAL JOIN`
 - `GROUP BY` and `HAVING` clauses
 - Set operations: `UNION`, `UNION ALL`, `INTERSECT`, `INTERSECT ALL`, `EXCEPT`, `EXCEPT ALL`
@@ -154,14 +154,14 @@ Squirreling mostly follows the SQL standard. The following features are supporte
 
 ### Functions
 
-- Aggregate: `COUNT`, `SUM`, `AVG`, `MIN`, `MAX`, `MEDIAN`, `PERCENTILE_CONT`, `APPROX_QUANTILE`, `STDDEV_POP`, `STDDEV_SAMP`, `JSON_ARRAYAGG`
+- Aggregate: `COUNT`, `SUM`, `AVG`, `MIN`, `MAX`, `MEDIAN`, `PERCENTILE_CONT`, `APPROX_QUANTILE`, `STDDEV_POP`, `STDDEV_SAMP`, `JSON_ARRAYAGG`, `STRING_AGG`
 - String: `CONCAT`, `SUBSTRING`, `REPLACE`, `LENGTH`, `UPPER`, `LOWER`, `TRIM`, `LEFT`, `RIGHT`, `INSTR`, `POSITION`, `STRPOS`
 - 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_PART`, `DATE_TRUNC`, `EXTRACT`, `INTERVAL`
-- Json: `JSON_VALUE`, `JSON_QUERY`, `JSON_EXTRACT`, `JSON_OBJECT`
+- Json: `JSON_VALUE`, `JSON_QUERY`, `JSON_EXTRACT`, `JSON_OBJECT`, `JSON_ARRAY_LENGTH`
 - Array: `ARRAY_LENGTH`, `ARRAY_POSITION`, `ARRAY_SORT`, `CARDINALITY`
-- Regex: `REGEXP_SUBSTR`, `REGEXP_EXTRACT`, `REGEXP_REPLACE`
+- Regex: `REGEXP_SUBSTR`, `REGEXP_EXTRACT`, `REGEXP_REPLACE`, `REGEXP_MATCHES`
 - Spatial: `ST_GeomFromText`, `ST_MakeEnvelope`, `ST_AsText`, `ST_Intersects`, `ST_Contains`, `ST_ContainsProperly`, `ST_Within`, `ST_Overlaps`, `ST_Touches`, `ST_Equals`, `ST_Crosses`, `ST_Covers`, `ST_CoveredBy`, `ST_DWithin`
-- Conditional: `COALESCE`, `NULLIF`
+- Conditional: `COALESCE`, `NULLIF`, `GREATEST`, `LEAST`
 - User-defined functions (UDFs)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "squirreling",
-  "version": "0.12.1",
+  "version": "0.12.3",
   "description": "Squirreling Async SQL Engine",
   "author": "Hyperparam",
   "homepage": "https://hyperparam.app",
@@ -39,11 +39,11 @@
     "test": "vitest run"
   },
   "devDependencies": {
-    "@types/node": "25.5.2",
-    "@vitest/coverage-v8": "4.1.3",
+    "@types/node": "25.6.0",
+    "@vitest/coverage-v8": "4.1.4",
     "eslint": "9.39.2",
     "eslint-plugin-jsdoc": "62.9.0",
     "typescript": "6.0.2",
-    "vitest": "4.1.3"
+    "vitest": "4.1.4"
   }
 }

package/src/backend/dataSource.js

@@ -15,7 +15,7 @@ export function asyncRow(obj, columns) {
   for (const key of columns) {
     cells[key] = () => Promise.resolve(obj[key])
   }
-  return { columns, cells }
+  return { columns, cells, resolved: obj }
 }
 
 /**
@@ -34,13 +34,14 @@ export function memorySource({ data, columns }) {
     }
     const firstColumns = Object.keys(data[0])
     // Check first 1000 rows for consistent columns
+    const firstColSet = new Set(firstColumns)
     for (let i = 1; i < data.length && i < 1000; i++) {
       const rowColumns = Object.keys(data[i])
       const missing = firstColumns.find(col => !rowColumns.includes(col))
       if (missing) {
         throw new Error(`Inconsistent data, column "${missing}" not found in row ${i}`)
       }
-      const extra = rowColumns.find(col => !firstColumns.includes(col))
+      const extra = rowColumns.find(col => !firstColSet.has(col))
       if (extra) {
         throw new Error(`Inconsistent data, unexpected column "${extra}" found in row ${i}`)
       }
@@ -54,11 +55,12 @@ export function memorySource({ data, columns }) {
       // Only apply offset and limit if no where clause
       const start = !where ? offset ?? 0 : 0
       const end = !where && limit !== undefined ? start + limit : data.length
+      const rowColumns = scanColumns ?? columns
       return {
         async *rows() {
           for (let i = start; i < end && i < data.length; i++) {
             if (signal?.aborted) break
-            yield asyncRow(data[i], scanColumns ?? columns)
+            yield asyncRow(data[i], rowColumns)
           }
         },
         appliedWhere: false,

package/src/execute/aggregates.js

@@ -62,7 +62,7 @@ export function executeHashAggregate(plan, context) {
   return {
     columns: selectColumnNames(plan.columns, child.columns),
     maxRows: child.maxRows,
-    async *rows () {
+    async *rows() {
       // Collect all rows
       /** @type {AsyncRow[]} */
       const allRows = []
@@ -136,7 +136,7 @@ export function executeScalarAggregate(plan, context) {
     columns: selectColumnNames(plan.columns, child.columns),
     numRows: plan.having ? undefined : 1,
     maxRows: 1,
-    async *rows () {
+    async *rows() {
       // Collect all rows into single group
       /** @type {AsyncRow[]} */
       const group = []

package/src/execute/execute.js

@@ -2,7 +2,8 @@ import { memorySource } from '../backend/dataSource.js'
 import { derivedAlias } from '../expression/alias.js'
 import { evaluateExpr } from '../expression/evaluate.js'
 import { parseSql } from '../parse/parse.js'
-import { planSql } from '../plan/plan.js'
+import { planSql, planStatement } from '../plan/plan.js'
+import { fromAlias } from '../plan/columns.js'
 import { validateScan, validateTable } from '../validation/tables.js'
 import { executeHashAggregate, executeScalarAggregate } from './aggregates.js'
 import { executeHashJoin, executeNestedLoopJoin, executePositionalJoin } from './join.js'
@@ -10,7 +11,7 @@ import { executeSort } from './sort.js'
 import { addBounds, minBounds, stableRowKey } from './utils.js'
 
 /**
- * @import { AsyncCells, AsyncDataSource, AsyncRow, ExecuteContext, ExecuteSqlOptions, ExprNode, QueryResults, SelectColumn, Statement } from '../types.js'
+ * @import { AsyncCells, AsyncDataSource, AsyncRow, DerivedColumn, ExecuteContext, ExecuteSqlOptions, ExprNode, IdentifierNode, QueryResults, SelectColumn, SqlPrimitive, Statement } from '../types.js'
  * @import { CountNode, DistinctNode, FilterNode, LimitNode, ProjectNode, QueryPlan, ScanNode, SetOperationNode } from '../plan/types.js'
  */
 
@@ -34,7 +35,8 @@ export function executeSql({ tables, query, functions, signal }) {
     }
   }
 
-  const context = { tables: normalizedTables, functions, signal }
+  const scope = statementScope(parsed)
+  const context = { tables: normalizedTables, functions, signal, scope }
   const plan = planSql({ query: parsed, functions, tables: normalizedTables })
   return executePlan({ plan, context })
 }
@@ -45,11 +47,26 @@ export function executeSql({ tables, query, functions, signal }) {
  * @param {Object} options
  * @param {Statement} options.query
  * @param {ExecuteContext} options.context
+ * @param {string[]} [options.outerScope] - outer query aliases for correlated subqueries
  * @returns {QueryResults}
  */
-export function executeStatement({ query, context }) {
-  const plan = planSql({ query, functions: context.functions, tables: context.tables })
-  return executePlan({ plan, context })
+export function executeStatement({ query, context, outerScope }) {
+  const plan = planStatement({ stmt: query, tables: context.tables, outerScope })
+  // Compute this query's scope (FROM alias + JOIN aliases) for nested correlated subqueries
+  const scope = statementScope(query)
+  return executePlan({ plan, context: scope ? { ...context, scope } : context })
+}
+
+/**
+ * Extracts the table aliases from a statement's FROM and JOIN clauses.
+ *
+ * @param {Statement} stmt
+ * @returns {string[] | undefined}
+ */
+function statementScope(stmt) {
+  if (stmt.type === 'with') return statementScope(stmt.query)
+  if (stmt.type === 'compound') return undefined
+  return [fromAlias(stmt.from), ...stmt.joins.map(j => j.alias ?? j.table)]
 }
 
 /**
@@ -88,7 +105,7 @@ export function executePlan({ plan, context }) {
   } else if (plan.type === 'SetOperation') {
     return executeSetOperation(plan, context)
   }
-  return { columns: [], async *rows () {} }
+  return { columns: [], async *rows() {} }
 }
 
 /**
@@ -142,7 +159,7 @@ function executeScan(plan, context) {
       columns: [column],
       numRows: scanRows,
       maxRows: scanRows,
-      async *rows () {
+      async *rows() {
         const columns = [column]
         for await (const chunk of chunks) {
           if (signal?.aborted) return
@@ -172,7 +189,7 @@ function executeScan(plan, context) {
     columns: plan.hints.columns ?? table.columns,
     numRows: !plan.hints.where ? scanRows : undefined,
     maxRows: scanRows,
-    async *rows () {
+    async *rows() {
       let result = scanResult.rows()
 
       // Apply WHERE if data source did not
@@ -205,7 +222,7 @@ function executeCount(plan, context) {
     columns: plan.columns.map(col => col.alias ?? derivedAlias(col.expr)),
     numRows: 1,
     maxRows: 1,
-    async *rows () {
+    async *rows() {
       // Use source numRows if available
       let count = table.numRows
       if (count === undefined) {
@@ -344,37 +361,86 @@ function executeFilter(plan, context) {
  */
 function executeProject(plan, context) {
   const child = executePlan({ plan: plan.child, context })
+
+  // Pre-compute column names for derived columns (avoids per-row derivedAlias calls)
+  const hasStar = plan.columns.some(col => col.type === 'star')
+
+  /** @type {string[] | undefined} */
+  let staticColumns
+  /** @type {{ alias: string, sourceName: string }[] | undefined} */
+  let identifierMap
+  if (!hasStar) {
+    const derived = /** @type {DerivedColumn[]} */ (plan.columns)
+    staticColumns = derived.map(col => col.alias ?? derivedAlias(col.expr))
+    const allIdentifiers = derived.every(col =>
+      col.expr.type === 'identifier' && !col.expr.prefix
+    )
+    if (allIdentifiers) {
+      identifierMap = derived.map((col, i) => ({
+        alias: staticColumns[i],
+        sourceName: /** @type {IdentifierNode} */ (col.expr).name,
+      }))
+    }
+  }
+
   return {
     columns: selectColumnNames(plan.columns, child.columns),
     numRows: child.numRows,
     maxRows: child.maxRows,
-    async *rows () {
+    async *rows() {
       let rowIndex = 0
+      let identifierMapValidated = false
 
       for await (const row of child.rows()) {
         if (context.signal?.aborted) return
         rowIndex++
+
+        // Validate identifier fast path on first row (may fail for JOINs with prefixed columns)
+        if (identifierMap && !identifierMapValidated) {
+          identifierMapValidated = true
+          if (!identifierMap.every(m => m.sourceName in row.cells)) {
+            identifierMap = undefined
+          }
+        }
+
+        // Fast path: all columns are simple identifier references
+        if (identifierMap) {
+          /** @type {AsyncCells} */
+          const cells = {}
+          const source = row.resolved
+          /** @type {Record<string, SqlPrimitive> | undefined} */
+          const resolved = source ? {} : undefined
+          for (const { alias, sourceName } of identifierMap) {
+            cells[alias] = row.cells[sourceName]
+            if (resolved && source) resolved[alias] = source[sourceName]
+          }
+          yield resolved
+            ? { columns: staticColumns, cells, resolved }
+            : { columns: staticColumns, cells }
+          continue
+        }
+
         const currentRowIndex = rowIndex
 
         /** @type {string[]} */
-        const columns = []
+        const columns = staticColumns ?? []
         /** @type {AsyncCells} */
         const cells = {}
 
-        for (const col of plan.columns) {
+        for (let i = 0; i < plan.columns.length; i++) {
+          const col = plan.columns[i]
           if (col.type === 'star') {
             const prefix = col.table ? `${col.table}.` : undefined
             for (const key of row.columns) {
               if (prefix && !key.startsWith(prefix)) continue
-              // Strip table prefix for output column names
               const dotIndex = key.indexOf('.')
               const outputKey = prefix ? key.substring(prefix.length) : dotIndex >= 0 ? key.substring(dotIndex + 1) : key
               columns.push(outputKey)
               cells[outputKey] = row.cells[key]
             }
           } else {
-            const alias = col.alias ?? derivedAlias(col.expr)
-            columns.push(alias)
+            const alias = staticColumns ? staticColumns[i] : (col.alias ?? derivedAlias(col.expr))
+            if (!staticColumns) columns.push(alias)
             cells[alias] = () => evaluateExpr({
               node: col.expr,
               row,
@@ -402,7 +468,7 @@ function executeDistinct(plan, context) {
   return {
     columns: child.columns,
     maxRows: child.maxRows,
-    async *rows () {
+    async *rows() {
       const { signal } = context
       const MAX_CHUNK = 256
 
@@ -478,7 +544,7 @@ function executeSetOperation(plan, context) {
         columns: left.columns,
         numRows: addBounds(left.numRows, right.numRows),
         maxRows: addBounds(left.maxRows, right.maxRows),
-        async *rows () {
+        async *rows() {
           // UNION ALL: yield all rows from both sides
           yield* left.rows()
           yield* right.rows()
@@ -490,7 +556,7 @@ function executeSetOperation(plan, context) {
       return {
         columns: left.columns,
         maxRows: addBounds(left.maxRows, right.maxRows),
-        async *rows () {
+        async *rows() {
           // UNION: yield deduplicated rows from both sides
           const seen = new Set()
           for await (const row of left.rows()) {
@@ -518,7 +584,7 @@ function executeSetOperation(plan, context) {
     return {
       columns: left.columns,
       maxRows: minBounds(left.maxRows, right.maxRows),
-      async *rows () {
+      async *rows() {
         // Materialize right side keys
         /** @type {Map<any, number>} */
         const rightKeys = new Map()
@@ -560,7 +626,7 @@ function executeSetOperation(plan, context) {
     return {
       columns: left.columns,
       maxRows: left.maxRows,
-      async *rows () {
+      async *rows() {
         // Materialize right side keys
         /** @type {Map<any, number>} */
         const rightKeys = new Map()

package/src/execute/join.js

@@ -19,7 +19,7 @@ export function executeNestedLoopJoin(plan, context) {
   const right = executePlan({ plan: plan.right, context })
   return {
     columns: mergeColumnNames(left.columns, right.columns, plan.leftAlias, plan.rightAlias),
-    async *rows () {
+    async *rows() {
       const leftTable = plan.leftAlias
       const rightTable = plan.rightAlias
 
@@ -97,7 +97,7 @@ export function executePositionalJoin(plan, context) {
     columns: mergeColumnNames(left.columns, right.columns, plan.leftAlias, plan.rightAlias),
     numRows,
     maxRows: maxBounds(left.maxRows, right.maxRows),
-    async *rows () {
+    async *rows() {
       const { signal } = context
       const leftTable = plan.leftAlias
       const rightTable = plan.rightAlias
@@ -143,7 +143,7 @@ export function executeHashJoin(plan, context) {
   const right = executePlan({ plan: plan.right, context })
   return {
     columns: mergeColumnNames(left.columns, right.columns, plan.leftAlias, plan.rightAlias),
-    async *rows () {
+    async *rows() {
       const leftTable = plan.leftAlias
       const rightTable = plan.rightAlias
 

package/src/execute/sort.js

@@ -20,7 +20,7 @@ export function executeSort(plan, context) {
     columns: child.columns,
     numRows: child.numRows,
     maxRows: child.maxRows,
-    async *rows () {
+    async *rows() {
       // Buffer all rows
       /** @type {AsyncRow[]} */
       const rows = []

package/src/execute/utils.js

@@ -2,6 +2,8 @@
  * @import { AsyncRow, OrderByItem, QueryResults, SqlPrimitive } from '../types.js'
  */
 
+const primitiveTypes = new Set(['number', 'bigint', 'boolean', 'string'])
+
 /**
  * Compares two values for a single ORDER BY term, handling nulls and direction
  *
@@ -24,10 +26,9 @@ export function compareForTerm(a, b, term) {
   // Compare non-null values
   if (a == b) return 0
 
-  const primitives = ['number', 'bigint', 'boolean', 'string']
   let cmp
-  if (primitives.includes(typeof a) && primitives.includes(typeof b)) {
-    cmp = a < b ? -1 : a > b ? 1 : 0
+  if (primitiveTypes.has(typeof a) && primitiveTypes.has(typeof b)) {
+    cmp = a < b ? -1 : 1
   } else {
     const aa = String(a)
     const bb = String(b)
@@ -51,6 +52,29 @@ export async function collect(results) {
   for await (const asyncRow of results.rows()) {
     rows.push(asyncRow)
   }
+
+  // Fast path: if all rows have pre-materialized data, skip Promise overhead
+  let allMaterialized = rows.length > 0
+  for (let i = 0; i < rows.length; i++) {
+    if (!rows[i].resolved) {
+      allMaterialized = false
+      break
+    }
+  }
+  if (allMaterialized) {
+    const result = new Array(rows.length)
+    for (let i = 0; i < rows.length; i++) {
+      const row = rows[i]
+      /** @type {Record<string, SqlPrimitive>} */
+      const item = {}
+      for (const col of row.columns) {
+        item[col] = row.resolved[col]
+      }
+      result[i] = item
+    }
+    return result
+  }
+
   return Promise.all(rows.map(async asyncRow => {
     const values = await Promise.all(asyncRow.columns.map(k => asyncRow.cells[k]()))
     /** @type {Record<string, SqlPrimitive>} */

package/src/expression/evaluate.js

@@ -39,6 +39,10 @@ export async function evaluateExpr({ node, row, rowIndex, rows, context }) {
       if (qualified in row.cells) {
         return row.cells[qualified]()
       }
+      // Check outer row for correlated subquery references
+      if (context.outerRow && context.outerAliases?.has(node.prefix) && node.name in context.outerRow.cells) {
+        return context.outerRow.cells[node.name]()
+      }
       // Fall back to just the column part
       if (node.name in row.cells) {
         return row.cells[node.name]()
@@ -66,7 +70,11 @@ export async function evaluateExpr({ node, row, rowIndex, rows, context }) {
 
   // Scalar subquery - returns a single value
   if (node.type === 'subquery') {
-    const gen = executeStatement({ query: node.subquery, context }).rows()
+    const outerScope = context.scope
+    const subContext = outerScope
+      ? { ...context, outerRow: row, outerAliases: new Set(outerScope) }
+      : context
+    const gen = executeStatement({ query: node.subquery, context: subContext, outerScope }).rows()
     const { value } = await gen.next()
     gen.return(undefined)
     if (!value) return null
@@ -272,6 +280,32 @@ export async function evaluateExpr({ node, row, rowIndex, rows, context }) {
           ))
         }
       }
+
+      if (funcName === 'STRING_AGG') {
+        const separatorNode = node.args[1]
+        const separator = String(await evaluateExpr({ node: separatorNode, row: filteredRows[0] ?? { columns: [], cells: {} }, context }))
+        /** @type {string[]} */
+        const values = []
+        if (node.distinct) {
+          const seen = new Set()
+          for (const row of filteredRows) {
+            const v = await evaluateExpr({ node: argNode, row, context })
+            if (v == null) continue
+            const str = String(v)
+            const key = keyify(str)
+            if (!seen.has(key)) {
+              seen.add(key)
+              values.push(str)
+            }
+          }
+        } else {
+          for (const row of filteredRows) {
+            const v = await evaluateExpr({ node: argNode, row, context })
+            if (v != null) values.push(String(v))
+          }
+        }
+        return values.length === 0 ? null : values.join(separator)
+      }
     }
 
     /** @type {SqlPrimitive[]} */
@@ -311,6 +345,20 @@ export async function evaluateExpr({ node, row, rowIndex, rows, context }) {
       return val1 == await val2 ? null : val1
     }
 
+    if (funcName === 'GREATEST' || funcName === 'LEAST') {
+      // Skip nulls; return null if all inputs are null
+      const isGreatest = funcName === 'GREATEST'
+      /** @type {SqlPrimitive} */
+      let best = null
+      for (const arg of args) {
+        if (arg == null) continue
+        if (best == null || (isGreatest ? arg > best : arg < best)) {
+          best = arg
+        }
+      }
+      return best
+    }
+
     if (funcName === 'DATE_TRUNC') {
       return dateTrunc(args[0], args[1])
     }
@@ -357,6 +405,25 @@ export async function evaluateExpr({ node, row, rowIndex, rows, context }) {
       return result
     }
 
+    if (funcName === 'JSON_ARRAY_LENGTH') {
+      let arr = args[0]
+      if (arr == null) return null
+      if (typeof arr === 'string') {
+        try {
+          arr = JSON.parse(arr)
+        } catch {
+          throw new ArgValueError({
+            ...node,
+            message: 'invalid JSON string',
+            hint: 'Argument must be valid JSON.',
+            rowIndex,
+          })
+        }
+      }
+      if (!Array.isArray(arr)) return null
+      return arr.length
+    }
+
     if (funcName === 'ARRAY_LENGTH' || funcName === 'CARDINALITY') {
       const arr = args[0]
       if (!Array.isArray(arr)) return null

package/src/expression/regexp.js

@@ -78,6 +78,27 @@ export function evaluateRegexpFunc({ funcName, node, args, rowIndex }) {
     return null
   }
 
+  if (funcName === 'REGEXP_MATCHES') {
+    const str = args[0]
+    const pattern = args[1]
+    if (str == null || pattern == null) return null
+    const strVal = String(str)
+    const patternStr = String(pattern)
+
+    let regex
+    try {
+      regex = new RegExp(patternStr)
+    } catch (/** @type {any} */ error) {
+      throw new ArgValueError({
+        ...node,
+        message: `invalid regex pattern: ${error.message}`,
+        rowIndex,
+      })
+    }
+
+    return regex.test(strVal)
+  }
+
   if (funcName === 'REGEXP_REPLACE') {
     const str = args[0]
     const pattern = args[1]

package/src/parse/functions.js

@@ -104,6 +104,16 @@ export function parseFunctionCall(state, positionStart) {
     expect(state, 'paren', ')')
   }
 
+  // Check for OVER clause (window functions not supported)
+  const overTok = current(state)
+  if (overTok.type === 'identifier' && overTok.value.toUpperCase() === 'OVER') {
+    throw new ParseError({
+      message: `Window functions are not supported: ${funcName}(...) OVER (...)`,
+      positionStart,
+      positionEnd: overTok.positionEnd,
+    })
+  }
+
   return {
     type: 'function',
     funcName,

package/src/plan/columns.js

@@ -163,7 +163,54 @@ function collectColumnsFromExpr(expr, columns, aliases) {
       collectColumnsFromExpr(expr.elseResult, columns, aliases)
     }
   }
-  // No columns: count(*), literal, interval, exists, not exists, subquery
+  // Subqueries: collect prefixed identifiers for correlated column detection.
+  // Only prefixed identifiers are collected because correlated outer references
+  // are always qualified (e.g. users.id, a.session_id). Unprefixed identifiers
+  // from the inner query would incorrectly be attributed to the outer table.
+  if (expr.type === 'subquery' || expr.type === 'in' || expr.type === 'exists' || expr.type === 'not exists') {
+    if (expr.type === 'in') {
+      collectColumnsFromExpr(expr.expr, columns, aliases)
+    }
+    const sub = expr.subquery
+    if (sub) {
+      /** @type {IdentifierNode[]} */
+      const inner = []
+      collectColumnsFromStatement(sub, inner)
+      for (const id of inner) {
+        if (id.prefix) columns.push(id)
+      }
+    }
+  }
+  // No columns: count(*), literal, interval
+}
+
+/**
+ * Collects identifiers from a subquery statement for correlated column detection.
+ *
+ * @param {Statement} stmt
+ * @param {IdentifierNode[]} columns
+ */
+function collectColumnsFromStatement(stmt, columns) {
+  if (stmt.type === 'compound') {
+    collectColumnsFromStatement(stmt.left, columns)
+    collectColumnsFromStatement(stmt.right, columns)
+    return
+  }
+  if (stmt.type === 'with') {
+    collectColumnsFromStatement(stmt.query, columns)
+    return
+  }
+  for (const col of stmt.columns) {
+    if (col.type === 'derived') collectColumnsFromExpr(col.expr, columns)
+  }
+  collectColumnsFromExpr(stmt.where, columns)
+  if (stmt.from?.type === 'subquery') {
+    collectColumnsFromStatement(stmt.from.query, columns)
+  }
+  for (const join of stmt.joins) collectColumnsFromExpr(join.on, columns)
+  for (const expr of stmt.groupBy) collectColumnsFromExpr(expr, columns)
+  collectColumnsFromExpr(stmt.having, columns)
+  for (const item of stmt.orderBy) collectColumnsFromExpr(item.expr, columns)
 }
 
 /**

package/src/plan/plan.js

@@ -32,9 +32,10 @@ export function planSql({ query, functions, tables }) {
  * @param {Map<string, string[]>} [options.cteColumns]
  * @param {Record<string, AsyncDataSource>} [options.tables]
  * @param {IdentifierNode[]} [options.parentColumns] - columns needed by the parent query (for subquery pushdown)
+ * @param {string[]} [options.outerScope] - aliases from an outer query (for correlated subqueries)
  * @returns {QueryPlan}
  */
-function planStatement({ stmt, ctePlans, cteColumns, tables, parentColumns }) {
+export function planStatement({ stmt, ctePlans, cteColumns, tables, parentColumns, outerScope }) {
   if (stmt.type === 'with') {
     // Build CTE plans in order (each CTE can reference preceding CTEs)
     ctePlans ??= new Map()
@@ -44,12 +45,12 @@ function planStatement({ stmt, ctePlans, cteColumns, tables, parentColumns }) {
       ctePlans.set(cte.name.toLowerCase(), ctePlan)
       cteColumns.set(cte.name.toLowerCase(), inferStatementColumns({ stmt: cte.query, cteColumns, tables }))
     }
-    return planStatement({ stmt: stmt.query, ctePlans, cteColumns, tables, parentColumns })
+    return planStatement({ stmt: stmt.query, ctePlans, cteColumns, tables, parentColumns, outerScope })
   }
   if (stmt.type === 'compound') {
     return planSetOperation({ compound: stmt, ctePlans, cteColumns, tables })
   }
-  return planSelect({ select: stmt, ctePlans, cteColumns, tables, parentColumns })
+  return planSelect({ select: stmt, ctePlans, cteColumns, tables, parentColumns, outerScope })
 }
 
 /**
@@ -100,9 +101,10 @@ function planSetOperation({ compound, ctePlans, cteColumns, tables }) {
  * @param {Map<string, string[]>} [options.cteColumns]
  * @param {Record<string, AsyncDataSource>} [options.tables]
  * @param {IdentifierNode[]} [options.parentColumns] - columns needed by the parent query (for subquery pushdown)
+ * @param {string[]} [options.outerScope] - aliases from an outer query (for correlated subqueries)
  * @returns {QueryPlan}
  */
-function planSelect({ select, ctePlans, cteColumns, tables, parentColumns }) {
+function planSelect({ select, ctePlans, cteColumns, tables, parentColumns, outerScope }) {
   // Check for aggregation
   const hasAggregate = select.columns.some(col =>
     col.type === 'derived' && findAggregate(col.expr)
@@ -114,7 +116,8 @@ function planSelect({ select, ctePlans, cteColumns, tables, parentColumns }) {
   const sourceAlias = fromAlias(select.from)
 
   // Resolve aliases (and validate qualified references)
-  const scopeTables = Object.fromEntries([sourceAlias, ...select.joins.map(j => j.alias ?? j.table)].map(a => [a, true]))
+  // Include outerScope aliases so correlated references pass validation
+  const scopeTables = Object.fromEntries([sourceAlias, ...select.joins.map(j => j.alias ?? j.table), ...outerScope ?? []].map(a => [a, true]))
   /** @type {Map<string, ExprNode>} */
   const aliases = new Map()
   const columns = select.columns.map(col => {
@@ -153,6 +156,11 @@ function planSelect({ select, ctePlans, cteColumns, tables, parentColumns }) {
   const hints = {}
   const perTableColumns = extractColumns({ select, parentColumns })
   hints.columns = perTableColumns.get(sourceAlias)
+  // Empty columns array means no columns were referenced, but a FROM subquery
+  // still needs its own columns (e.g. for DISTINCT). Treat empty as unrestricted.
+  if (hints.columns?.length === 0 && select.from.type === 'subquery') {
+    hints.columns = undefined
+  }
   if (!select.joins.length) {
     hints.where = select.where
     if (!needsBuffering && !select.distinct) {
@@ -163,7 +171,7 @@ function planSelect({ select, ctePlans, cteColumns, tables, parentColumns }) {
 
   // Start with the data source (FROM clause)
   /** @type {QueryPlan} */
-  let plan = planFrom({ select, ctePlans, cteColumns, hints, tables })
+  let plan = planFrom({ select, ctePlans, cteColumns, hints, tables, outerScope })
 
   // Add JOINs
   if (select.joins.length) {
@@ -255,9 +263,10 @@ function planSelect({ select, ctePlans, cteColumns, tables, parentColumns }) {
  * @param {Map<string, string[]>} [options.cteColumns]
  * @param {ScanOptions} options.hints
  * @param {Record<string, AsyncDataSource>} [options.tables]
+ * @param {string[]} [options.outerScope]
  * @returns {QueryPlan}
  */
-function planFrom({ select, ctePlans, cteColumns, hints, tables }) {
+function planFrom({ select, ctePlans, cteColumns, hints, tables, outerScope }) {
   if (select.from.type === 'table') {
     const ctePlan = ctePlans?.get(select.from.table.toLowerCase())
     if (ctePlan) {
@@ -271,6 +280,7 @@ function planFrom({ select, ctePlans, cteColumns, hints, tables }) {
       ctePlans,
       cteColumns,
       tables,
+      outerScope,
       parentColumns: hints.columns?.map(name => ({ type: 'identifier', name, positionStart: 0, positionEnd: 0 })),
     })
     // Validate that requested columns exist in subquery output

package/src/types.d.ts

@@ -40,12 +40,21 @@ export interface ExecuteContext {
   tables: Record<string, AsyncDataSource>
   functions?: Record<string, UserDefinedFunction>
   signal?: AbortSignal
+  // current query's FROM + JOIN aliases (e.g. ['a', 'b'])
+  scope?: string[]
+  // the enclosing query's current row, for resolving correlated references
+  outerRow?: AsyncRow
+  // aliases from the enclosing query that are valid correlated references
+  outerAliases?: Set<string>
 }
 
 // AsyncRow represents a row with async cell values
 export interface AsyncRow {
   columns: string[]
   cells: AsyncCells
+  // Optional pre-materialized row values keyed by output column name.
+  // When present, consumers can skip the AsyncCell Promise roundtrip.
+  resolved?: Record<string, SqlPrimitive>
 }
 export type AsyncCells = Record<string, AsyncCell>
 export type AsyncCell = () => Promise<SqlPrimitive>
@@ -110,9 +119,9 @@ export interface UserDefinedFunction {
   arguments: FunctionSignature
 }
 
-export type AggregateFunc = 'COUNT' | 'SUM' | 'AVG' | 'MIN' | 'MAX' | 'JSON_ARRAYAGG' | 'STDDEV_SAMP' | 'STDDEV_POP' | 'MEDIAN' | 'PERCENTILE_CONT' | 'APPROX_QUANTILE'
+export type AggregateFunc = 'COUNT' | 'SUM' | 'AVG' | 'MIN' | 'MAX' | 'JSON_ARRAYAGG' | 'STDDEV_SAMP' | 'STDDEV_POP' | 'MEDIAN' | 'PERCENTILE_CONT' | 'APPROX_QUANTILE' | 'STRING_AGG'
 
-export type RegExpFunction = 'REGEXP_SUBSTR' | 'REGEXP_EXTRACT' | 'REGEXP_REPLACE'
+export type RegExpFunction = 'REGEXP_SUBSTR' | 'REGEXP_EXTRACT' | 'REGEXP_REPLACE' | 'REGEXP_MATCHES'
 
 export type MathFunc =
   | 'FLOOR'

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', 'SUM', 'AVG', 'MIN', 'MAX', 'JSON_ARRAYAGG', 'STDDEV_SAMP', 'STDDEV_POP', 'MEDIAN', 'PERCENTILE_CONT', 'APPROX_QUANTILE'].includes(name)
+  return ['COUNT', 'SUM', 'AVG', 'MIN', 'MAX', 'JSON_ARRAYAGG', 'STDDEV_SAMP', 'STDDEV_POP', 'MEDIAN', 'PERCENTILE_CONT', 'APPROX_QUANTILE', 'STRING_AGG'].includes(name)
 }
 
 /**
@@ -31,7 +31,7 @@ export function isMathFunc(name) {
  * @returns {name is RegExpFunction}
  */
 export function isRegexpFunc(name) {
-  return ['REGEXP_SUBSTR', 'REGEXP_EXTRACT', 'REGEXP_REPLACE'].includes(name)
+  return ['REGEXP_SUBSTR', 'REGEXP_EXTRACT', 'REGEXP_REPLACE', 'REGEXP_MATCHES'].includes(name)
 }
 
 /**
@@ -112,6 +112,7 @@ export const FUNCTION_SIGNATURES = {
   REGEXP_SUBSTR: { min: 2, max: 4, signature: 'string, pattern[, position[, occurrence]]' },
   REGEXP_EXTRACT: { min: 2, max: 4, signature: 'string, pattern[, position[, occurrence]]' },
   REGEXP_REPLACE: { min: 3, max: 5, signature: 'string, pattern, replacement[, position[, occurrence]]' },
+  REGEXP_MATCHES: { min: 2, max: 2, signature: 'string, pattern' },
 
   // Date/time functions
   RANDOM: { min: 0, max: 0, signature: '' },
@@ -154,6 +155,7 @@ export const FUNCTION_SIGNATURES = {
   JSON_QUERY: { min: 2, max: 2, signature: 'expression, path' },
   JSON_EXTRACT: { min: 2, max: 2, signature: 'expression, path' },
   JSON_OBJECT: { min: 0, signature: 'key1, value1[, ...]' },
+  JSON_ARRAY_LENGTH: { min: 1, max: 1, signature: 'array' },
   JSON_ARRAYAGG: { min: 1, max: 1, signature: 'expression' },
 
   // Array functions
@@ -165,6 +167,8 @@ export const FUNCTION_SIGNATURES = {
   // Conditional functions
   COALESCE: { min: 1, signature: 'value1, value2[, ...]' },
   NULLIF: { min: 2, max: 2, signature: 'value1, value2' },
+  GREATEST: { min: 1, signature: 'value1[, value2, ...]' },
+  LEAST: { min: 1, signature: 'value1[, value2, ...]' },
 
   // Aggregate functions
   COUNT: { min: 1, max: 1, signature: 'expression' },
@@ -177,6 +181,7 @@ export const FUNCTION_SIGNATURES = {
   MEDIAN: { min: 1, max: 1, signature: 'expression' },
   PERCENTILE_CONT: { min: 2, max: 2, signature: 'fraction, expression' },
   APPROX_QUANTILE: { min: 2, max: 2, signature: 'expression, fraction' },
+  STRING_AGG: { min: 2, max: 2, signature: 'expression, separator' },
 
   // Spatial functions
   ST_INTERSECTS: { min: 2, max: 2, signature: 'geometry, geometry' },

package/src/validation/parseErrors.js

@@ -1,5 +1,12 @@
 import { FUNCTION_SIGNATURES } from './functions.js'
 
+/** Well-known window functions that are not supported */
+const WINDOW_FUNCTIONS = new Set([
+  'ROW_NUMBER', 'RANK', 'DENSE_RANK', 'NTILE',
+  'LAG', 'LEAD', 'FIRST_VALUE', 'LAST_VALUE', 'NTH_VALUE',
+  'CUME_DIST', 'PERCENT_RANK',
+])
+
 /**
  * Structured parse error with position range.
  */
@@ -103,10 +110,16 @@ export class UnknownFunctionError extends ParseError {
    * @param {number} options.positionEnd
    */
   constructor({ funcName, positionStart, positionEnd }) {
-    const suggestions = suggestFunctions(funcName)
-    let message = `Unknown function "${funcName}" at position ${positionStart}.`
-    if (suggestions.length) {
-      message += ` Did you mean ${suggestions.join(', ')}?`
+    const upper = funcName.toUpperCase()
+    let message
+    if (WINDOW_FUNCTIONS.has(upper)) {
+      message = `Window function "${funcName}" is not supported at position ${positionStart}`
+    } else {
+      const suggestions = suggestFunctions(funcName)
+      message = `Unknown function "${funcName}" at position ${positionStart}.`
+      if (suggestions.length) {
+        message += ` Did you mean ${suggestions.join(', ')}?`
+      }
     }
     super({ message, positionStart, positionEnd })
   }