squirreling 0.12.7 → 0.12.9

package/README.md

@@ -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`, `STRING_AGG`
+- Aggregate: `COUNT`, `SUM`, `AVG`, `MIN`, `MAX`, `MEDIAN`, `PERCENTILE_CONT`, `APPROX_QUANTILE`, `STDDEV_POP`, `STDDEV_SAMP`, `ARRAY_AGG`, `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_ARRAY_LENGTH`
+- Json: `JSON_VALUE`, `JSON_QUERY`, `JSON_EXTRACT`, `JSON_OBJECT`, `JSON_ARRAY_LENGTH`, `JSON_VALID`, `JSON_TYPE`
 - Array: `ARRAY_LENGTH`, `ARRAY_POSITION`, `ARRAY_SORT`, `CARDINALITY`
-- Table functions: `UNNEST`
+- Table functions: `UNNEST`, `JSON_EACH`
 - 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`, `GREATEST`, `LEAST`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "squirreling",
-  "version": "0.12.7",
+  "version": "0.12.9",
   "description": "Squirreling Async SQL Engine",
   "author": "Hyperparam",
   "homepage": "https://hyperparam.app",

package/src/ast.d.ts

@@ -65,7 +65,7 @@ export interface FromFunction extends AstBase {
   funcName: string
   args: ExprNode[]
   alias?: string
-  columnAlias?: string
+  columnAliases: string[]
 }
 
 export type ArithmeticOp = '+' | '-' | '*' | '/' | '%'
@@ -106,6 +106,14 @@ export interface FunctionNode extends AstBase {
   filter?: ExprNode
 }
 
+export interface WindowFunctionNode extends AstBase {
+  type: 'window'
+  funcName: string
+  args: ExprNode[]
+  partitionBy: ExprNode[]
+  orderBy: OrderByItem[]
+}
+
 export type CastType = 'TEXT' | 'STRING' | 'VARCHAR' | 'INTEGER' | 'INT' | 'BIGINT' | 'FLOAT' | 'REAL' | 'DOUBLE' | 'BOOLEAN' | 'BOOL'
 
 export interface CastNode extends AstBase {
@@ -166,6 +174,7 @@ export type ExprNode =
   | UnaryNode
   | BinaryNode
   | FunctionNode
+  | WindowFunctionNode
   | CastNode
   | InSubqueryNode
   | InValuesNode

package/src/execute/execute.js

@@ -9,6 +9,7 @@ import { executeHashAggregate, executeScalarAggregate } from './aggregates.js'
 import { executeHashJoin, executeNestedLoopJoin, executePositionalJoin } from './join.js'
 import { executeSort } from './sort.js'
 import { addBounds, minBounds, stableRowKey } from './utils.js'
+import { executeWindow } from './window.js'
 
 /**
  * @import { AsyncCells, AsyncDataSource, AsyncRow, DerivedColumn, ExecuteContext, ExecuteSqlOptions, ExprNode, IdentifierNode, QueryResults, SelectColumn, SqlPrimitive, Statement } from '../types.js'
@@ -120,24 +121,38 @@ export function executePlan({ plan, context }) {
     return executeSetOperation(plan, context)
   } else if (plan.type === 'TableFunction') {
     return executeTableFunction(plan, context)
+  } else if (plan.type === 'Window') {
+    return executeWindow(plan, context)
   }
   return { columns: [], async *rows() {} }
 }
 
 /**
- * Executes a table-valued function (e.g. UNNEST).
- * Evaluates the argument once against an empty row and yields one row per
- * element of the resulting array. Null or non-array input yields zero rows.
+ * Executes a table-valued function (e.g. UNNEST, JSON_EACH).
+ * Evaluates the argument once against the outer row (for lateral joins) or an
+ * empty row, then yields rows derived from the resulting value.
  *
  * @param {TableFunctionNode} plan
  * @param {ExecuteContext} context
  * @returns {QueryResults}
  */
 function executeTableFunction(plan, context) {
-  if (plan.funcName !== 'UNNEST') {
-    throw new Error(`Unsupported table function: ${plan.funcName}`)
+  if (plan.funcName === 'UNNEST') {
+    return executeUnnest(plan, context)
+  } else if (plan.funcName === 'JSON_EACH') {
+    return executeJsonEach(plan, context)
   }
-  const columns = [plan.columnName]
+  throw new Error(`Unsupported table function: ${plan.funcName}`)
+}
+
+/**
+ * @param {TableFunctionNode} plan
+ * @param {ExecuteContext} context
+ * @returns {QueryResults}
+ */
+function executeUnnest(plan, context) {
+  const columns = plan.columnNames
+  const [columnName] = columns
   return {
     columns,
     async *rows() {
@@ -149,9 +164,65 @@ function executeTableFunction(plan, context) {
         if (context.signal?.aborted) return
         yield {
           columns,
-          cells: { [plan.columnName]: () => Promise.resolve(element) },
+          cells: { [columnName]: () => Promise.resolve(element) },
+        }
+      }
+    },
+  }
+}
+
+/**
+ * @param {TableFunctionNode} plan
+ * @param {ExecuteContext} context
+ * @returns {QueryResults}
+ */
+function executeJsonEach(plan, context) {
+  const columns = plan.columnNames
+  const [keyCol, valueCol] = columns
+  return {
+    columns,
+    async *rows() {
+      /** @type {AsyncRow} */
+      const row = context.outerRow ?? { columns: [], cells: {} }
+      const value = await evaluateExpr({ node: plan.args[0], row, rowIndex: 1, context })
+      if (value == null) return
+      let parsed = value
+      if (typeof value === 'string') {
+        try {
+          parsed = JSON.parse(value)
+        } catch {
+          throw new Error('JSON_EACH(value): invalid JSON string. Argument must be valid JSON.')
+        }
+      }
+      if (Array.isArray(parsed)) {
+        for (let i = 0; i < parsed.length; i++) {
+          if (context.signal?.aborted) return
+          const k = i
+          const v = parsed[i]
+          yield {
+            columns,
+            cells: {
+              [keyCol]: () => Promise.resolve(k),
+              [valueCol]: () => Promise.resolve(v),
+            },
+          }
+        }
+        return
+      }
+      if (typeof parsed === 'object' && parsed !== null) {
+        for (const [k, v] of Object.entries(parsed)) {
+          if (context.signal?.aborted) return
+          yield {
+            columns,
+            cells: {
+              [keyCol]: () => Promise.resolve(k),
+              [valueCol]: () => Promise.resolve(v),
+            },
+          }
         }
+        return
       }
+      throw new Error('JSON_EACH(value): argument must be a JSON object or array')
     },
   }
 }

package/src/execute/join.js

@@ -95,7 +95,7 @@ export function executeNestedLoopJoin(plan, context) {
 function executeLateralJoin(plan, context) {
   const left = executePlan({ plan: plan.left, context })
   // Right columns are known statically for table functions (the common case).
-  const rightCols = plan.right.type === 'TableFunction' ? [plan.right.columnName] : []
+  const rightCols = plan.right.type === 'TableFunction' ? plan.right.columnNames : []
   return {
     columns: mergeColumnNames(left.columns, rightCols, plan.leftAlias, plan.rightAlias),
     async *rows() {

package/src/execute/window.js

@@ -0,0 +1,154 @@
+import { evaluateExpr } from '../expression/evaluate.js'
+import { executePlan } from './execute.js'
+import { compareForTerm, keyify } from './utils.js'
+
+/**
+ * @import { AsyncRow, ExecuteContext, QueryResults, SqlPrimitive } from '../types.js'
+ * @import { WindowNode, WindowSpec } from '../plan/types.js'
+ */
+
+/**
+ * Executes a Window plan node: buffers the child's rows, assigns each window
+ * function's output per partition, and yields rows in input order with the
+ * synthetic window cells attached.
+ *
+ * @param {WindowNode} plan
+ * @param {ExecuteContext} context
+ * @returns {QueryResults}
+ */
+export function executeWindow(plan, context) {
+  const child = executePlan({ plan: plan.child, context })
+  const extraColumns = plan.windows.map(w => w.alias)
+
+  // Streaming fast path: every window is OVER () with no partition/order, so
+  // each row's output depends only on its position in the input stream. Avoids
+  // buffering — critical for large scans (e.g. parquet).
+  const streamable = plan.windows.every(w => w.partitionBy.length === 0 && w.orderBy.length === 0)
+
+  if (streamable) {
+    return {
+      columns: [...child.columns, ...extraColumns],
+      numRows: child.numRows,
+      maxRows: child.maxRows,
+      async *rows() {
+        let i = 0
+        for await (const row of child.rows()) {
+          if (context.signal?.aborted) return
+          i++
+          const cells = { ...row.cells }
+          for (const w of plan.windows) {
+            const value = assignRowNumber(w.funcName, i - 1)
+            cells[w.alias] = () => Promise.resolve(value)
+          }
+          yield {
+            columns: [...row.columns, ...extraColumns],
+            cells,
+          }
+        }
+      },
+    }
+  }
+
+  return {
+    columns: [...child.columns, ...extraColumns],
+    numRows: child.numRows,
+    maxRows: child.maxRows,
+    async *rows() {
+      /** @type {AsyncRow[]} */
+      const rows = []
+      for await (const row of child.rows()) {
+        if (context.signal?.aborted) return
+        rows.push(row)
+      }
+      if (rows.length === 0) return
+
+      // One SqlPrimitive per window spec per row, indexed by row input position.
+      /** @type {SqlPrimitive[][]} */
+      const windowValues = plan.windows.map(() => new Array(rows.length))
+
+      for (let w = 0; w < plan.windows.length; w++) {
+        await computeWindow(plan.windows[w], rows, windowValues[w], context)
+        if (context.signal?.aborted) return
+      }
+
+      for (let i = 0; i < rows.length; i++) {
+        if (context.signal?.aborted) return
+        const row = rows[i]
+        const cells = { ...row.cells }
+        for (let w = 0; w < plan.windows.length; w++) {
+          const { alias } = plan.windows[w]
+          const value = windowValues[w][i]
+          cells[alias] = () => Promise.resolve(value)
+        }
+        yield {
+          columns: [...row.columns, ...extraColumns],
+          cells,
+        }
+      }
+    },
+  }
+}
+
+/**
+ * Computes a single window function across all rows, writing the per-row
+ * output values into `output`.
+ *
+ * @param {WindowSpec} spec
+ * @param {AsyncRow[]} rows
+ * @param {SqlPrimitive[]} output
+ * @param {ExecuteContext} context
+ */
+async function computeWindow(spec, rows, output, context) {
+  // Bucket row indices by partition key.
+  /** @type {Map<string | number | bigint | boolean, number[]>} */
+  const partitions = new Map()
+  const partitionKeys = await Promise.all(rows.map(row =>
+    Promise.all(spec.partitionBy.map(expr => evaluateExpr({ node: expr, row, context })))
+  ))
+  for (let i = 0; i < rows.length; i++) {
+    const key = keyify(...partitionKeys[i])
+    let bucket = partitions.get(key)
+    if (!bucket) {
+      bucket = []
+      partitions.set(key, bucket)
+    }
+    bucket.push(i)
+  }
+
+  for (const bucket of partitions.values()) {
+    if (context.signal?.aborted) return
+
+    // Order within the partition. Empty ORDER BY → input order.
+    if (spec.orderBy.length) {
+      const orderValues = await Promise.all(bucket.map(idx =>
+        Promise.all(spec.orderBy.map(term => evaluateExpr({ node: term.expr, row: rows[idx], context })))
+      ))
+      /** @type {{ idx: number, values: SqlPrimitive[], pos: number }[]} */
+      const entries = bucket.map((idx, k) => ({ idx, values: orderValues[k], pos: k }))
+      entries.sort((a, b) => {
+        for (let i = 0; i < spec.orderBy.length; i++) {
+          const cmp = compareForTerm(a.values[i], b.values[i], spec.orderBy[i])
+          if (cmp !== 0) return cmp
+        }
+        return a.pos - b.pos
+      })
+      for (let k = 0; k < entries.length; k++) {
+        output[entries[k].idx] = assignRowNumber(spec.funcName, k)
+      }
+    } else {
+      for (let k = 0; k < bucket.length; k++) {
+        output[bucket[k]] = assignRowNumber(spec.funcName, k)
+      }
+    }
+  }
+}
+
+/**
+ * @param {string} funcName
+ * @param {number} rank - 0-based rank within the partition
+ * @returns {SqlPrimitive}
+ */
+function assignRowNumber(funcName, rank) {
+  if (funcName === 'ROW_NUMBER') return rank + 1
+  throw new Error(`Unsupported window function: ${funcName}`)
+}

package/src/expression/alias.js

@@ -31,6 +31,9 @@ export function derivedAlias(expr) {
     }
     return expr.funcName.toLowerCase() + '_' + expr.args.map(derivedAlias).join('_')
   }
+  if (expr.type === 'window') {
+    return expr.funcName.toLowerCase()
+  }
   if (expr.type === 'interval') {
     return `interval_${expr.value}_${expr.unit.toLowerCase()}`
   }

package/src/expression/evaluate.js

@@ -272,7 +272,7 @@ export async function evaluateExpr({ node, row, rowIndex, rows, context }) {
         return values[lower] + (values[upper] - values[lower]) * (pos - lower)
       }
 
-      if (funcName === 'JSON_ARRAYAGG') {
+      if (funcName === 'JSON_ARRAYAGG' || funcName === 'ARRAY_AGG') {
         if (node.distinct) {
           /** @type {SqlPrimitive[]} */
           const values = []
@@ -417,6 +417,40 @@ export async function evaluateExpr({ node, row, rowIndex, rows, context }) {
       return result
     }
 
+    if (funcName === 'JSON_VALID') {
+      const value = args[0]
+      if (value == null) return null
+      if (typeof value !== 'string') return false
+      try {
+        JSON.parse(value)
+        return true
+      } catch {
+        return false
+      }
+    }
+
+    if (funcName === 'JSON_TYPE') {
+      let value = args[0]
+      if (value == null) return null
+      if (typeof value === 'string') {
+        try {
+          value = JSON.parse(value)
+        } catch {
+          throw new ArgValueError({
+            ...node,
+            message: 'invalid JSON string',
+            hint: 'Argument must be valid JSON.',
+            rowIndex,
+          })
+        }
+      }
+      if (value === null) return 'null'
+      if (Array.isArray(value)) return 'array'
+      if (value instanceof Date) return 'string'
+      if (typeof value === 'bigint') return 'number'
+      return typeof value
+    }
+
     if (funcName === 'JSON_ARRAY_LENGTH') {
       let arr = args[0]
       if (arr == null) return null

package/src/parse/functions.js

@@ -1,10 +1,10 @@
-import { isAggregateFunc, isKnownFunction, niladicFuncs, validateFunctionArgs } from '../validation/functions.js'
+import { isAggregateFunc, isKnownFunction, isWindowFunc, niladicFuncs, validateFunctionArgs } from '../validation/functions.js'
 import { ParseError, UnknownFunctionError } from '../validation/parseErrors.js'
 import { parseExpression } from './expression.js'
 import { consume, current, expect, match } from './state.js'
 
 /**
- * @import { ExprNode, ParserState } from '../types.js'
+ * @import { ExprNode, OrderByItem, ParserState } from '../types.js'
  */
 
 /**
@@ -84,6 +84,30 @@ export function parseFunctionCall(state, positionStart) {
     })
   }
 
+  // Check for WITHIN GROUP (ORDER BY expr) clause — standard SQL ordered-set aggregate syntax.
+  // Supported for PERCENTILE_CONT: PERCENTILE_CONT(fraction) WITHIN GROUP (ORDER BY expr)
+  const withinTok = current(state)
+  if (match(state, 'keyword', 'WITHIN')) {
+    if (funcNameUpper !== 'PERCENTILE_CONT') {
+      throw new ParseError({
+        message: `WITHIN GROUP is only supported for PERCENTILE_CONT, not "${funcName}"`,
+        ...withinTok,
+      })
+    }
+    if (args.length !== 1) {
+      throw new ParseError({
+        message: `${funcName}: cannot combine WITHIN GROUP with a value argument`,
+        ...withinTok,
+      })
+    }
+    expect(state, 'keyword', 'GROUP')
+    expect(state, 'paren', '(')
+    expect(state, 'keyword', 'ORDER')
+    expect(state, 'keyword', 'BY')
+    args.push(parseExpression(state))
+    expect(state, 'paren', ')')
+  }
+
   // Validate argument count at parse time
   validateFunctionArgs(funcNameUpper, args.length, positionStart, state.lastPos, state.functions)
 
@@ -104,13 +128,43 @@ export function parseFunctionCall(state, positionStart) {
     expect(state, 'paren', ')')
   }
 
-  // Check for OVER clause (window functions not supported)
+  // Check for OVER clause
   const overTok = current(state)
-  if (overTok.type === 'identifier' && overTok.value.toUpperCase() === 'OVER') {
+  const hasOver = overTok.type === 'identifier' && overTok.value.toUpperCase() === 'OVER'
+
+  if (hasOver) {
+    if (!isWindowFunc(funcNameUpper)) {
+      throw new ParseError({
+        message: `Window functions are not supported: ${funcName}(...) OVER (...)`,
+        positionStart,
+        positionEnd: overTok.positionEnd,
+      })
+    }
+    if (filter) {
+      throw new ParseError({
+        message: `FILTER cannot be combined with OVER for "${funcName}"`,
+        positionStart,
+        positionEnd: overTok.positionEnd,
+      })
+    }
+    consume(state)
+    const { partitionBy, orderBy } = parseWindowSpec(state, positionStart)
+    return {
+      type: 'window',
+      funcName,
+      args,
+      partitionBy,
+      orderBy,
+      positionStart,
+      positionEnd: state.lastPos,
+    }
+  }
+
+  if (isWindowFunc(funcNameUpper)) {
     throw new ParseError({
-      message: `Window functions are not supported: ${funcName}(...) OVER (...)`,
+      message: `${funcName}() requires an OVER clause at position ${positionStart}`,
       positionStart,
-      positionEnd: overTok.positionEnd,
+      positionEnd: state.lastPos,
     })
   }
 
@@ -124,3 +178,64 @@ export function parseFunctionCall(state, positionStart) {
     positionEnd: state.lastPos,
   }
 }
+
+/**
+ * Parses the window spec after OVER: ( [PARTITION BY expr[, ...]] [ORDER BY expr [ASC|DESC] [NULLS FIRST|LAST][, ...]] )
+ *
+ * @param {ParserState} state
+ * @param {number} positionStart - start position of the enclosing function call (for OrderByItem positions)
+ * @returns {{ partitionBy: ExprNode[], orderBy: OrderByItem[] }}
+ */
+function parseWindowSpec(state, positionStart) {
+  expect(state, 'paren', '(')
+  /** @type {ExprNode[]} */
+  const partitionBy = []
+  /** @type {OrderByItem[]} */
+  const orderBy = []
+
+  const partitionTok = current(state)
+  if (partitionTok.type === 'identifier' && partitionTok.value.toUpperCase() === 'PARTITION') {
+    consume(state)
+    expect(state, 'keyword', 'BY')
+    while (true) {
+      partitionBy.push(parseExpression(state))
+      if (!match(state, 'comma')) break
+    }
+  }
+
+  if (match(state, 'keyword', 'ORDER')) {
+    expect(state, 'keyword', 'BY')
+    while (true) {
+      const expr = parseExpression(state)
+      /** @type {'ASC' | 'DESC'} */
+      let direction = 'ASC'
+      if (match(state, 'keyword', 'ASC')) {
+        direction = 'ASC'
+      } else if (match(state, 'keyword', 'DESC')) {
+        direction = 'DESC'
+      }
+      /** @type {'FIRST' | 'LAST' | undefined} */
+      let nulls
+      if (match(state, 'keyword', 'NULLS')) {
+        const tok = consume(state)
+        const upper = tok.value.toUpperCase()
+        if (tok.type === 'identifier' && upper === 'FIRST') {
+          nulls = 'FIRST'
+        } else if (tok.type === 'identifier' && upper === 'LAST') {
+          nulls = 'LAST'
+        } else {
+          throw new ParseError({
+            message: `Expected FIRST or LAST after NULLS at position ${tok.positionStart}`,
+            positionStart: tok.positionStart,
+            positionEnd: tok.positionEnd,
+          })
+        }
+      }
+      orderBy.push({ expr, direction, nulls, positionStart, positionEnd: state.lastPos })
+      if (!match(state, 'comma')) break
+    }
+  }
+
+  expect(state, 'paren', ')')
+  return { partitionBy, orderBy }
+}

package/src/parse/parse.js

@@ -468,15 +468,22 @@ export function parseFromFunction(state) {
   validateFunctionArgs(funcName, args.length, positionStart, state.lastPos, state.functions)
 
   const alias = parseTableAlias(state)
-  /** @type {string | undefined} */
-  let columnAlias
+  /** @type {string[]} */
+  const columnAliases = []
   if (alias && match(state, 'paren', '(')) {
     const colStart = state.lastPos
-    const colTok = expect(state, 'identifier')
-    columnAlias = colTok.value
-    if (match(state, 'comma')) {
+    while (true) {
+      const colTok = expect(state, 'identifier')
+      columnAliases.push(colTok.value)
+      if (!match(state, 'comma')) break
+    }
+    const maxCols = tableFunctionColumnCount(funcName)
+    if (columnAliases.length > maxCols) {
+      const colLabels = tableFunctionDefaultColumns(funcName).join(', ')
       throw new ParseError({
-        message: `${funcName} produces a single column; only one column alias is allowed`,
+        message: maxCols === 1
+          ? `${funcName} produces a single column; only one column alias is allowed`
+          : `${funcName} produces at most ${maxCols} columns (${colLabels}); too many column aliases`,
         positionStart: colStart,
         positionEnd: state.lastPos,
       })
@@ -489,12 +496,31 @@ export function parseFromFunction(state) {
     funcName,
     args,
     alias,
-    columnAlias,
+    columnAliases,
     positionStart,
     positionEnd: state.lastPos,
   }
 }
 
+/**
+ * Default column names produced by a table-valued function.
+ * @param {string} funcName
+ * @returns {string[]}
+ */
+export function tableFunctionDefaultColumns(funcName) {
+  if (funcName === 'JSON_EACH') return ['key', 'value']
+  return [funcName.toLowerCase()]
+}
+
+/**
+ * Maximum number of output columns a table-valued function can produce.
+ * @param {string} funcName
+ * @returns {number}
+ */
+export function tableFunctionColumnCount(funcName) {
+  return tableFunctionDefaultColumns(funcName).length
+}
+
 /**
  * Parses an optional table alias (e.g., "FROM users u" or "FROM users AS u")
  * @param {ParserState} state

package/src/plan/columns.js

@@ -1,3 +1,4 @@
+import { tableFunctionDefaultColumns } from '../parse/parse.js'
 import { derivedAlias } from '../expression/alias.js'
 
 /**
@@ -18,13 +19,19 @@ export function fromAlias(from) {
 }
 
 /**
- * Returns the single output column name for a FROM table function.
+ * Returns the output column names for a FROM table function, applying any
+ * column aliases over the function's default column names.
  *
  * @param {FromFunction} from
- * @returns {string}
+ * @returns {string[]}
  */
-export function tableFunctionColumnName(from) {
-  return from.columnAlias ?? from.funcName.toLowerCase()
+export function tableFunctionColumnNames(from) {
+  const defaults = tableFunctionDefaultColumns(from.funcName)
+  const result = []
+  for (let i = 0; i < defaults.length; i++) {
+    result.push(from.columnAliases[i] ?? defaults[i])
+  }
+  return result
 }
 
 /**
@@ -204,6 +211,10 @@ function collectColumnsFromExpr(expr, columns, aliases) {
       collectColumnsFromExpr(arg, columns, aliases)
     }
     collectColumnsFromExpr(expr.filter, columns, aliases)
+  } else if (expr.type === 'window') {
+    for (const arg of expr.args) collectColumnsFromExpr(arg, columns, aliases)
+    for (const p of expr.partitionBy) collectColumnsFromExpr(p, columns, aliases)
+    for (const o of expr.orderBy) collectColumnsFromExpr(o.expr, columns, aliases)
   } else if (expr.type === 'cast') {
     collectColumnsFromExpr(expr.expr, columns, aliases)
   } else if (expr.type === 'in valuelist') {
@@ -330,18 +341,21 @@ export function inferSelectSourceColumns({ select, cteColumns, tables }) {
   }
 
   if (select.from.type === 'function') {
-    // Table functions currently produce a single column
     if (!select.joins.length) {
-      return [tableFunctionColumnName(select.from)]
+      return tableFunctionColumnNames(select.from)
     }
     /** @type {string[]} */
     const result = []
     const alias = fromAlias(select.from)
-    result.push(`${alias}.${tableFunctionColumnName(select.from)}`)
+    for (const col of tableFunctionColumnNames(select.from)) {
+      result.push(`${alias}.${col}`)
+    }
     for (const join of select.joins) {
       const joinAlias = join.alias ?? join.table
       if (join.fromFunction) {
-        result.push(`${joinAlias}.${tableFunctionColumnName(join.fromFunction)}`)
+        for (const col of tableFunctionColumnNames(join.fromFunction)) {
+          result.push(`${joinAlias}.${col}`)
+        }
       } else {
         for (const col of lookupTableColumns(join.table, cteColumns, tables)) {
           result.push(`${joinAlias}.${col}`)
@@ -365,7 +379,9 @@ export function inferSelectSourceColumns({ select, cteColumns, tables }) {
   for (const join of select.joins) {
     const joinAlias = join.alias ?? join.table
     if (join.fromFunction) {
-      result.push(`${joinAlias}.${tableFunctionColumnName(join.fromFunction)}`)
+      for (const col of tableFunctionColumnNames(join.fromFunction)) {
+        result.push(`${joinAlias}.${col}`)
+      }
     } else {
       for (const col of lookupTableColumns(join.table, cteColumns, tables)) {
         result.push(`${joinAlias}.${col}`)

package/src/plan/plan.js

@@ -1,13 +1,14 @@
 import { derivedAlias } from '../expression/alias.js'
 import { parseSql } from '../parse/parse.js'
 import { findAggregate } from '../validation/aggregates.js'
+import { ParseError } from '../validation/parseErrors.js'
 import { ColumnNotFoundError, TableNotFoundError } from '../validation/tables.js'
 import { validateNoIdentifiers, validateScan, validateTableRefs } from '../validation/tables.js'
-import { extractColumns, fromAlias, inferSelectSourceColumns, inferStatementColumns, tableFunctionColumnName } from './columns.js'
+import { extractColumns, fromAlias, inferSelectSourceColumns, inferStatementColumns, tableFunctionColumnNames } from './columns.js'
 
 /**
- * @import { AsyncDataSource, ExprNode, DerivedColumn, IdentifierNode, JoinClause, PlanSqlOptions, ScanOptions, SelectColumn, SelectStatement, SetOperationStatement, Statement } from '../types.js'
- * @import { QueryPlan } from './types.d.ts'
+ * @import { AsyncDataSource, ExprNode, DerivedColumn, IdentifierNode, JoinClause, PlanSqlOptions, ScanOptions, SelectColumn, SelectStatement, SetOperationStatement, Statement, WindowFunctionNode } from '../types.js'
+ * @import { QueryPlan, WindowSpec } from './types.d.ts'
  */
 
 /**
@@ -106,12 +107,51 @@ function planSetOperation({ compound, ctePlans, cteColumns, tables, parentColumn
  * @returns {QueryPlan}
  */
 function planSelect({ select, ctePlans, cteColumns, tables, parentColumns, outerScope }) {
+  // Reject window functions in clauses where they're not permitted.
+  expectNoWindowFunction(select.where, 'WHERE')
+  expectNoWindowFunction(select.having, 'HAVING')
+  for (const expr of select.groupBy) expectNoWindowFunction(expr, 'GROUP BY')
+  for (const term of select.orderBy) expectNoWindowFunction(term.expr, 'ORDER BY')
+  for (const join of select.joins) expectNoWindowFunction(join.on, 'JOIN ON')
+
+  // Collect window functions from SELECT columns and rewrite them to identifiers
+  // pointing at the synthetic cells produced by the Window plan node.
+  /** @type {WindowSpec[]} */
+  const windows = []
+  const windowColumns = select.columns.map(col => {
+    if (col.type !== 'derived') return col
+    const originalAlias = col.alias ?? derivedAlias(col.expr)
+    const expr = collectWindows(col.expr, windows)
+    if (expr === col.expr) return col
+    return { ...col, expr, alias: originalAlias }
+  })
+
+  if (windows.length && select.columns.some(col => col.type === 'derived' && findAggregate(col.expr))) {
+    throw new ParseError({
+      message: 'Window functions are not supported in queries with aggregation',
+      ...select,
+    })
+  }
+  if (windows.length && select.groupBy.length) {
+    throw new ParseError({
+      message: 'Window functions are not supported in queries with aggregation',
+      ...select,
+    })
+  }
+
+  // Preserve the pre-substitution columns for column-extraction, so synthetic
+  // `__window_N` identifiers are not requested from the data source.
+  const originalSelect = select
+  select = { ...select, columns: windowColumns }
+
   // Check for aggregation
   const hasAggregate = select.columns.some(col =>
     col.type === 'derived' && findAggregate(col.expr)
   )
   const useGrouping = hasAggregate || select.groupBy.length > 0
-  const needsBuffering = useGrouping || select.orderBy.length > 0
+  // Windows with PARTITION BY or ORDER BY buffer; `OVER ()` streams.
+  const bufferingWindows = windows.some(w => w.partitionBy.length > 0 || w.orderBy.length > 0)
+  const needsBuffering = useGrouping || select.orderBy.length > 0 || bufferingWindows
 
   // Source alias for FROM clause
   const sourceAlias = fromAlias(select.from)
@@ -155,7 +195,7 @@ function planSelect({ select, ctePlans, cteColumns, tables, parentColumns, outer
   // included so they are only applied to fresh scans, not CTE/subquery plans)
   /** @type {ScanOptions} */
   const hints = {}
-  const perTableColumns = extractColumns({ select, parentColumns })
+  const perTableColumns = extractColumns({ select: originalSelect, 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.
@@ -219,6 +259,12 @@ function planSelect({ select, ctePlans, cteColumns, tables, parentColumns, outer
   } else {
     // Non-aggregation path
 
+    // Window functions: insert before Sort so outer ORDER BY can reference
+    // the window output aliases.
+    if (windows.length) {
+      plan = { type: 'Window', windows, child: plan }
+    }
+
     // ORDER BY (before projection so it can access all columns)
     // Resolve SELECT aliases in ORDER BY expressions at plan time
     if (select.orderBy.length) {
@@ -321,7 +367,7 @@ function planTableFunction(from) {
     type: 'TableFunction',
     funcName: from.funcName,
     args: from.args,
-    columnName: tableFunctionColumnName(from),
+    columnNames: tableFunctionColumnNames(from),
   }
 }
 
@@ -609,6 +655,126 @@ function validateLateralSubqueries({ expr, ctePlans, cteColumns, tables, outerSc
   }
 }
 
+/**
+ * Walks an expression, replacing every window function subnode with an
+ * identifier that points at a synthetic `__window_N` cell. The collected
+ * WindowSpec entries drive the Window plan node. Returns the same node
+ * reference when no window function is present, so untouched expressions
+ * aren't shallow-cloned.
+ *
+ * @param {ExprNode} expr
+ * @param {WindowSpec[]} windows
+ * @returns {ExprNode}
+ */
+function collectWindows(expr, windows) {
+  if (!expr || !findWindow(expr)) return expr
+  if (expr.type === 'window') {
+    const alias = `__window_${windows.length}`
+    windows.push({
+      alias,
+      funcName: expr.funcName.toUpperCase(),
+      args: expr.args,
+      partitionBy: expr.partitionBy,
+      orderBy: expr.orderBy,
+    })
+    return {
+      type: 'identifier',
+      name: alias,
+      positionStart: expr.positionStart,
+      positionEnd: expr.positionEnd,
+    }
+  }
+  if (expr.type === 'unary') {
+    return { ...expr, argument: collectWindows(expr.argument, windows) }
+  }
+  if (expr.type === 'binary') {
+    return { ...expr, left: collectWindows(expr.left, windows), right: collectWindows(expr.right, windows) }
+  }
+  if (expr.type === 'function') {
+    return { ...expr, args: expr.args.map(a => collectWindows(a, windows)) }
+  }
+  if (expr.type === 'cast') {
+    return { ...expr, expr: collectWindows(expr.expr, windows) }
+  }
+  if (expr.type === 'in valuelist') {
+    return {
+      ...expr,
+      expr: collectWindows(expr.expr, windows),
+      values: expr.values.map(v => collectWindows(v, windows)),
+    }
+  }
+  if (expr.type === 'case') {
+    return {
+      ...expr,
+      caseExpr: expr.caseExpr && collectWindows(expr.caseExpr, windows),
+      whenClauses: expr.whenClauses.map(w => ({
+        ...w,
+        condition: collectWindows(w.condition, windows),
+        result: collectWindows(w.result, windows),
+      })),
+      elseResult: expr.elseResult && collectWindows(expr.elseResult, windows),
+    }
+  }
+  return expr
+}
+
+/**
+ * Throws if the expression tree contains a window function.
+ *
+ * @param {ExprNode | undefined} expr
+ * @param {string} clause
+ */
+function expectNoWindowFunction(expr, clause) {
+  const win = findWindow(expr)
+  if (win) {
+    throw new ParseError({
+      message: `Window function ${win.funcName.toUpperCase()} is not allowed in ${clause} clause`,
+      positionStart: win.positionStart,
+      positionEnd: win.positionEnd,
+    })
+  }
+}
+
+/**
+ * @param {ExprNode | undefined} expr
+ * @returns {WindowFunctionNode | undefined}
+ */
+function findWindow(expr) {
+  if (!expr) return undefined
+  if (expr.type === 'window') return expr
+  if (expr.type === 'binary') return findWindow(expr.left) || findWindow(expr.right)
+  if (expr.type === 'unary') return findWindow(expr.argument)
+  if (expr.type === 'function') {
+    for (const arg of expr.args) {
+      const found = findWindow(arg)
+      if (found) return found
+    }
+    return undefined
+  }
+  if (expr.type === 'cast') return findWindow(expr.expr)
+  if (expr.type === 'in valuelist') {
+    const found = findWindow(expr.expr)
+    if (found) return found
+    for (const val of expr.values) {
+      const f = findWindow(val)
+      if (f) return f
+    }
+    return undefined
+  }
+  if (expr.type === 'case') {
+    if (expr.caseExpr) {
+      const f = findWindow(expr.caseExpr)
+      if (f) return f
+    }
+    for (const w of expr.whenClauses) {
+      const f = findWindow(w.condition) || findWindow(w.result)
+      if (f) return f
+    }
+    if (expr.elseResult) return findWindow(expr.elseResult)
+  }
+  return undefined
+}
+
 /**
  * Checks if every SELECT column is a plain COUNT(*).
  *

package/src/plan/types.d.ts

@@ -15,6 +15,7 @@ export type QueryPlan =
   | PositionalJoinNode
   | SetOperationNode
   | TableFunctionNode
+  | WindowNode
 
 // Scan node
 export interface ScanNode {
@@ -122,5 +123,19 @@ export interface TableFunctionNode {
   type: 'TableFunction'
   funcName: string
   args: ExprNode[]
-  columnName: string
+  columnNames: string[]
+}
+
+export interface WindowSpec {
+  alias: string
+  funcName: string
+  args: ExprNode[]
+  partitionBy: ExprNode[]
+  orderBy: OrderByItem[]
+}
+
+export interface WindowNode {
+  type: 'Window'
+  windows: WindowSpec[]
+  child: QueryPlan
 }

package/src/types.d.ts

@@ -129,7 +129,7 @@ export interface UserDefinedFunction {
   arguments: FunctionSignature
 }
 
-export type AggregateFunc = 'COUNT' | 'SUM' | 'AVG' | 'MIN' | 'MAX' | 'JSON_ARRAYAGG' | 'STDDEV_SAMP' | 'STDDEV_POP' | 'MEDIAN' | 'PERCENTILE_CONT' | 'APPROX_QUANTILE' | 'STRING_AGG'
+export type AggregateFunc = 'COUNT' | 'SUM' | 'AVG' | 'MIN' | 'MAX' | 'ARRAY_AGG' | 'JSON_ARRAYAGG' | 'STDDEV_SAMP' | 'STDDEV_POP' | 'MEDIAN' | 'PERCENTILE_CONT' | 'APPROX_QUANTILE' | 'STRING_AGG'
 
 export type RegExpFunction = 'REGEXP_SUBSTR' | 'REGEXP_EXTRACT' | 'REGEXP_REPLACE' | 'REGEXP_MATCHES'
 

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', 'STRING_AGG'].includes(name)
+  return ['COUNT', 'SUM', 'AVG', 'MIN', 'MAX', 'ARRAY_AGG', 'JSON_ARRAYAGG', 'STDDEV_SAMP', 'STDDEV_POP', 'MEDIAN', 'PERCENTILE_CONT', 'APPROX_QUANTILE', 'STRING_AGG'].includes(name)
 }
 
 /**
@@ -26,6 +26,14 @@ export function isMathFunc(name) {
   ].includes(name)
 }
 
+/**
+ * @param {string} name
+ * @returns {boolean}
+ */
+export function isWindowFunc(name) {
+  return ['ROW_NUMBER'].includes(name)
+}
+
 /**
  * @param {string} name
  * @returns {name is RegExpFunction}
@@ -41,7 +49,7 @@ export function isRegexpFunc(name) {
  * @returns {boolean}
  */
 export function isTableFunction(name) {
-  return ['UNNEST'].includes(name)
+  return ['UNNEST', 'JSON_EACH'].includes(name)
 }
 
 /**
@@ -166,7 +174,10 @@ export const FUNCTION_SIGNATURES = {
   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_VALID: { min: 1, max: 1, signature: 'value' },
+  JSON_TYPE: { min: 1, max: 1, signature: 'value' },
   JSON_ARRAYAGG: { min: 1, max: 1, signature: 'expression' },
+  ARRAY_AGG: { min: 1, max: 1, signature: 'expression' },
 
   // Array functions
   ARRAY_LENGTH: { min: 1, max: 1, signature: 'array' },
@@ -176,6 +187,7 @@ export const FUNCTION_SIGNATURES = {
 
   // Table functions (used in FROM clause)
   UNNEST: { min: 1, max: 1, signature: 'array' },
+  JSON_EACH: { min: 1, max: 1, signature: 'value' },
 
   // Conditional functions
   COALESCE: { min: 1, signature: 'value1, value2[, ...]' },
@@ -196,6 +208,9 @@ export const FUNCTION_SIGNATURES = {
   APPROX_QUANTILE: { min: 2, max: 2, signature: 'expression, fraction' },
   STRING_AGG: { min: 2, max: 2, signature: 'expression, separator' },
 
+  // Window functions
+  ROW_NUMBER: { min: 0, max: 0, signature: '' },
+
   // Spatial functions
   ST_INTERSECTS: { min: 2, max: 2, signature: 'geometry, geometry' },
   ST_CONTAINS: { min: 2, max: 2, signature: 'geometry, geometry' },

package/src/validation/keywords.js

@@ -4,7 +4,7 @@ export const KEYWORDS = new Set([
   'DISTINCT', 'TRUE', 'FALSE', 'NULL', 'LIKE', 'IN', 'EXISTS', 'BETWEEN',
   'CASE', 'WHEN', 'THEN', 'ELSE', 'END', 'JOIN', 'INNER', 'LEFT', 'RIGHT',
   'FULL', 'OUTER', 'CROSS', 'POSITIONAL', 'LATERAL', 'ON', 'INTERVAL', 'DAY', 'MONTH', 'YEAR',
-  'HOUR', 'MINUTE', 'SECOND', 'FILTER',
+  'HOUR', 'MINUTE', 'SECOND', 'FILTER', 'WITHIN',
   'UNION', 'INTERSECT', 'EXCEPT',
 ])
 

package/src/validation/parseErrors.js

@@ -2,7 +2,7 @@ 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',
+  'RANK', 'DENSE_RANK', 'NTILE',
   'LAG', 'LEAD', 'FIRST_VALUE', 'LAST_VALUE', 'NTH_VALUE',
   'CUME_DIST', 'PERCENT_RANK',
 ])

package/src/validation/tables.js

@@ -119,6 +119,10 @@ export function validateTableRefs(expr, tables) {
     for (const arg of expr.args) {
       validateTableRefs(arg, tables)
     }
+  } else if (expr.type === 'window') {
+    for (const arg of expr.args) validateTableRefs(arg, tables)
+    for (const p of expr.partitionBy) validateTableRefs(p, tables)
+    for (const o of expr.orderBy) validateTableRefs(o.expr, tables)
   } else if (expr.type === 'cast') {
     validateTableRefs(expr.expr, tables)
   } else if (expr.type === 'in valuelist') {