squirreling 0.12.8 → 0.12.10

package/package.json

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

package/src/ast.d.ts

@@ -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/aggregates.js

@@ -1,6 +1,7 @@
 import { derivedAlias } from '../expression/alias.js'
 import { evaluateExpr } from '../expression/evaluate.js'
 import { executePlan, selectColumnNames } from './execute.js'
+import { sortEntriesByTerms } from './sort.js'
 import { keyify } from './utils.js'
 
 /**
@@ -50,6 +51,22 @@ function projectAggregateColumns(selectColumns, group, context) {
   return { columns, cells }
 }
 
+/**
+ * Builds the row visible to post-aggregation expressions such as HAVING and
+ * grouped ORDER BY: source group columns plus aggregate output aliases.
+ *
+ * @param {AsyncRow[]} group
+ * @param {AsyncRow} aggregateRow
+ * @returns {AsyncRow}
+ */
+function aggregateContextRow(group, aggregateRow) {
+  const baseRow = group[0] ?? { columns: [], cells: {} }
+  return {
+    columns: [...baseRow.columns, ...aggregateRow.columns],
+    cells: { ...baseRow.cells, ...aggregateRow.cells },
+  }
+}
+
 /**
  * Executes a hash aggregate operation (GROUP BY)
  *
@@ -85,27 +102,42 @@ export function executeHashAggregate(plan, context) {
         group.push(row)
       }
 
-      // Yield one row per group
+      /** @type {{ row: AsyncRow, group: AsyncRow[], contextRow: AsyncRow }[]} */
+      const aggregateRows = []
+
       for (const group of groups.values()) {
         const asyncRow = projectAggregateColumns(plan.columns, group, context)
+        const contextRow = aggregateContextRow(group, asyncRow)
 
         // Apply HAVING filter
         if (plan.having) {
-          /** @type {AsyncRow} */
-          const havingRow = {
-            columns: [...group[0].columns, ...asyncRow.columns],
-            cells: { ...group[0].cells, ...asyncRow.cells },
-          }
           const passes = await evaluateExpr({
             node: plan.having,
-            row: havingRow,
+            row: contextRow,
             rows: group,
             context,
           })
           if (!passes) continue
         }
 
-        yield asyncRow
+        aggregateRows.push({ row: asyncRow, group, contextRow })
+      }
+
+      if (plan.orderBy?.length) {
+        const sortedRows = await sortEntriesByTerms({
+          entries: aggregateRows.map((aggregateRow, idx) => ({
+            row: aggregateRow.contextRow,
+            rows: aggregateRow.group,
+            idx,
+          })),
+          orderBy: plan.orderBy,
+          context,
+        })
+        aggregateRows.splice(0, aggregateRows.length, ...sortedRows.map(({ idx }) => aggregateRows[idx]))
+      }
+
+      for (const { row } of aggregateRows) {
+        yield row
       }
     },
   }

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,6 +121,8 @@ 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() {} }
 }

package/src/execute/sort.js

@@ -4,12 +4,117 @@ import { executePlan } from './execute.js'
 import { compareForTerm } from './utils.js'
 
 /**
- * @import { AsyncRow, ExecuteContext, QueryResults, SqlPrimitive } from '../types.js'
+ * @import { AsyncRow, ExecuteContext, OrderByItem, QueryResults, SqlPrimitive } from '../types.js'
  * @import { SortNode } from '../plan/types.js'
  */
 
 const MAX_CHUNK = 256
 
+/**
+ * @typedef {{
+ *   row: AsyncRow,
+ *   rows?: AsyncRow[],
+ * }} SortEntry
+ */
+
+/**
+ * Sorts rows by ORDER BY terms while evaluating async sort keys in concurrent
+ * chunks and delaying later terms until earlier terms tie.
+ *
+ * @template {SortEntry} T
+ * @param {{
+ *   entries: T[],
+ *   orderBy: OrderByItem[],
+ *   context: ExecuteContext,
+ *   cacheValues?: boolean,
+ * }} options
+ * @returns {Promise<T[]>}
+ */
+export async function sortEntriesByTerms({ entries, orderBy, context, cacheValues = false }) {
+  if (entries.length === 0) return []
+
+  /** @type {(SqlPrimitive | undefined)[][]} */
+  const evaluatedValues = entries.map(() => Array(orderBy.length))
+
+  /** @type {number[][]} */
+  let groups = [entries.map((_, i) => i)]
+
+  for (let orderByIdx = 0; orderByIdx < orderBy.length; orderByIdx++) {
+    const term = orderBy[orderByIdx]
+    /** @type {number[][]} */
+    const nextGroups = []
+
+    for (const group of groups) {
+      if (group.length <= 1) {
+        nextGroups.push(group)
+        continue
+      }
+
+      const alias = derivedAlias(term.expr)
+      /** @type {number[]} */
+      const missing = []
+      for (const idx of group) {
+        if (evaluatedValues[idx][orderByIdx] === undefined) missing.push(idx)
+      }
+      let chunkSize = 1
+      let start = 0
+      while (start < missing.length) {
+        if (context.signal?.aborted) return []
+        const chunk = missing.slice(start, start + chunkSize)
+        const values = await Promise.all(chunk.map(idx =>
+          evaluateExpr({
+            node: term.expr,
+            row: entries[idx].row,
+            rows: entries[idx].rows,
+            context,
+          })
+        ))
+        for (let i = 0; i < chunk.length; i++) {
+          const idx = chunk[i]
+          const value = values[i]
+          evaluatedValues[idx][orderByIdx] = value
+          if (cacheValues && !(alias in entries[idx].row.cells)) {
+            entries[idx].row.cells[alias] = () => Promise.resolve(value)
+          }
+        }
+        start += chunk.length
+        chunkSize = Math.min(chunkSize * 2, MAX_CHUNK)
+      }
+
+      group.sort((aIdx, bIdx) => {
+        const av = evaluatedValues[aIdx][orderByIdx]
+        const bv = evaluatedValues[bIdx][orderByIdx]
+        return compareForTerm(av, bv, term)
+      })
+
+      if (orderByIdx < orderBy.length - 1) {
+        /** @type {number[]} */
+        let currentSubGroup = [group[0]]
+        for (let i = 1; i < group.length; i++) {
+          const prevIdx = group[i - 1]
+          const currIdx = group[i]
+          const prevVal = evaluatedValues[prevIdx][orderByIdx]
+          const currVal = evaluatedValues[currIdx][orderByIdx]
+
+          if (compareForTerm(prevVal, currVal, term) === 0) {
+            currentSubGroup.push(currIdx)
+          } else {
+            nextGroups.push(currentSubGroup)
+            currentSubGroup = [currIdx]
+          }
+        }
+        nextGroups.push(currentSubGroup)
+      } else {
+        nextGroups.push(group)
+      }
+    }
+
+    groups = nextGroups
+  }
+
+  return groups.flat().map(idx => entries[idx])
+}
+
 /**
  * Executes a sort operation (ORDER BY)
  *
@@ -32,92 +137,16 @@ export function executeSort(plan, context) {
         rows.push(row)
       }
 
-      if (rows.length === 0) return
-
-      // Multi-pass lazy sorting
-      /** @type {(SqlPrimitive | undefined)[][]} */
-      const evaluatedValues = rows.map(() => Array(plan.orderBy.length))
-
-      /** @type {number[][]} */
-      let groups = [rows.map((_, i) => i)]
-
-      for (let orderByIdx = 0; orderByIdx < plan.orderBy.length; orderByIdx++) {
-        const term = plan.orderBy[orderByIdx]
-        /** @type {number[][]} */
-        const nextGroups = []
-
-        for (const group of groups) {
-          if (group.length <= 1) {
-            nextGroups.push(group)
-            continue
-          }
-
-          // Evaluate this column for all rows in the group, in parallel
-          // chunks that double up to MAX_CHUNK so a slow UDF doesn't serialize.
-          // Cache each value back into the row so downstream projection can
-          // reuse it instead of re-invoking the expression.
-          const alias = derivedAlias(term.expr)
-          /** @type {number[]} */
-          const missing = []
-          for (const idx of group) {
-            if (evaluatedValues[idx][orderByIdx] === undefined) missing.push(idx)
-          }
-          let chunkSize = 1
-          let start = 0
-          while (start < missing.length) {
-            if (context.signal?.aborted) return
-            const chunk = missing.slice(start, start + chunkSize)
-            const values = await Promise.all(chunk.map(idx =>
-              evaluateExpr({ node: term.expr, row: rows[idx], context })
-            ))
-            for (let i = 0; i < chunk.length; i++) {
-              const idx = chunk[i]
-              const value = values[i]
-              evaluatedValues[idx][orderByIdx] = value
-              if (!(alias in rows[idx].cells)) {
-                rows[idx].cells[alias] = () => Promise.resolve(value)
-              }
-            }
-            start += chunk.length
-            chunkSize = Math.min(chunkSize * 2, MAX_CHUNK)
-          }
-
-          // Sort the group by this column
-          group.sort((aIdx, bIdx) => {
-            const av = evaluatedValues[aIdx][orderByIdx]
-            const bv = evaluatedValues[bIdx][orderByIdx]
-            return compareForTerm(av, bv, term)
-          })
-
-          // Split into sub-groups based on ties
-          if (orderByIdx < plan.orderBy.length - 1) {
-            /** @type {number[]} */
-            let currentSubGroup = [group[0]]
-            for (let i = 1; i < group.length; i++) {
-              const prevIdx = group[i - 1]
-              const currIdx = group[i]
-              const prevVal = evaluatedValues[prevIdx][orderByIdx]
-              const currVal = evaluatedValues[currIdx][orderByIdx]
-
-              if (compareForTerm(prevVal, currVal, term) === 0) {
-                currentSubGroup.push(currIdx)
-              } else {
-                nextGroups.push(currentSubGroup)
-                currentSubGroup = [currIdx]
-              }
-            }
-            nextGroups.push(currentSubGroup)
-          } else {
-            nextGroups.push(group)
-          }
-        }
-
-        groups = nextGroups
-      }
+      const sortedRows = await sortEntriesByTerms({
+        entries: rows.map(row => ({ row })),
+        orderBy: plan.orderBy,
+        context,
+        cacheValues: true,
+      })
 
       // Yield sorted rows
-      for (const idx of groups.flat()) {
-        yield rows[idx]
+      for (const { row } of sortedRows) {
+        yield row
       }
     },
   }

package/src/execute/utils.js

@@ -121,6 +121,19 @@ export function maxBounds(a, b) {
   return a ?? b
 }
 
+/**
+ * Returns true for plain object SqlPrimitive values, excluding null, arrays, and Dates.
+ *
+ * @param {SqlPrimitive} value
+ * @returns {value is Record<string, SqlPrimitive>}
+ */
+export function isPlainObject(value) {
+  return value != null
+    && typeof value === 'object'
+    && !Array.isArray(value)
+    && !(value instanceof Date)
+}
+
 /**
  * @param {SqlPrimitive} value
  * @returns {string}

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

@@ -1,5 +1,5 @@
 import { executeStatement } from '../execute/execute.js'
-import { keyify, stringify } from '../execute/utils.js'
+import { isPlainObject, keyify, stringify } from '../execute/utils.js'
 import { ArgValueError, ExecutionError } from '../validation/executionErrors.js'
 import { isAggregateFunc, isMathFunc, isRegexpFunc, isSpatialFunc, isStringFunc } from '../validation/functions.js'
 import { UnknownFunctionError } from '../validation/parseErrors.js'
@@ -39,6 +39,14 @@ export async function evaluateExpr({ node, row, rowIndex, rows, context }) {
       if (qualified in row.cells) {
         return row.cells[qualified]()
       }
+      const prefix = node.prefix + '.'
+      const prefixedColumns = row.columns.filter(col => col.startsWith(prefix))
+      if (prefixedColumns.length === 1) {
+        const value = await row.cells[prefixedColumns[0]]()
+        if (isPlainObject(value) && Object.prototype.hasOwnProperty.call(value, node.name)) {
+          return value[node.name]
+        }
+      }
       // 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]()
@@ -473,6 +481,23 @@ export async function evaluateExpr({ node, row, rowIndex, rows, context }) {
     if (funcName === 'ARRAY_LENGTH' || funcName === 'CARDINALITY') {
       const arr = args[0]
       if (!Array.isArray(arr)) return null
+      if (funcName === 'ARRAY_LENGTH' && args.length === 2) {
+        const dim = args[1]
+        if (typeof dim !== 'number' && typeof dim !== 'bigint') return null
+        const d = Number(dim)
+        if (!Number.isInteger(d) || d < 1) return null
+        let level = arr
+        for (let i = 1; i < d; i++) {
+          if (!Array.isArray(level) || level.length === 0) return null
+          const first = level[0]
+          if (!Array.isArray(first)) return null
+          for (const item of level) {
+            if (!Array.isArray(item) || item.length !== first.length) return null
+          }
+          level = first
+        }
+        return level.length
+      }
       return arr.length
     }
 

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'
  */
 
 /**
@@ -128,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,
     })
   }
 
@@ -148,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/primary.js

@@ -157,6 +157,16 @@ export function parsePrimary(state) {
     if (match(state, 'dot')) {
       prefix = name
       name = expect(state, 'identifier').value
+    } else if (match(state, 'bracket', '[')) {
+      // table['column'] — string subscript is equivalent to dot access
+      const fieldTok = current(state)
+      if (fieldTok.type !== 'string') {
+        throw parseError(state, 'string literal')
+      }
+      consume(state)
+      expect(state, 'bracket', ']')
+      prefix = name
+      name = fieldTok.value
     }
 
     return {

package/src/plan/columns.js

@@ -211,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') {

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, 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, OrderByItem, 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)
@@ -137,6 +177,7 @@ function planSelect({ select, ctePlans, cteColumns, tables, parentColumns, outer
     }
     return col
   })
+  const orderBy = resolveOrderByAliases(select.orderBy, aliases)
 
   // Validate qualified references in other clauses
   validateTableRefs(select.where, scopeTables)
@@ -155,7 +196,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.
@@ -195,7 +236,16 @@ function planSelect({ select, ctePlans, cteColumns, tables, parentColumns, outer
       const groupBy = aliases.size > 0
         ? select.groupBy.map(expr => resolveAliases(expr, aliases))
         : select.groupBy
-      plan = { type: 'HashAggregate', groupBy, columns, having: select.having, child: plan }
+      /** @type {QueryPlan} */
+      const aggregatePlan = {
+        type: 'HashAggregate',
+        groupBy,
+        columns,
+        having: select.having,
+        child: plan,
+      }
+      if (orderBy.length) aggregatePlan.orderBy = orderBy
+      plan = aggregatePlan
     } else if (!select.having && !select.where && plan.type === 'Scan' && isOwnScan && isAllCountStar(select.columns)) {
       plan = { type: 'Count', table: plan.table, columns: select.columns }
     } else {
@@ -203,8 +253,8 @@ function planSelect({ select, ctePlans, cteColumns, tables, parentColumns, outer
     }
 
     // ORDER BY (after aggregation)
-    if (select.orderBy.length) {
-      plan = { type: 'Sort', orderBy: select.orderBy, child: plan }
+    if (orderBy.length && !select.groupBy.length) {
+      plan = { type: 'Sort', orderBy, child: plan }
     }
 
     // DISTINCT
@@ -219,12 +269,15 @@ 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) {
-      const orderBy = aliases.size > 0
-        ? select.orderBy.map(term => ({ ...term, expr: resolveAliases(term.expr, aliases) }))
-        : select.orderBy
+    if (orderBy.length) {
       plan = { type: 'Sort', orderBy, child: plan }
     }
 
@@ -423,6 +476,19 @@ function planJoin({ left, joins, leftTable, ctePlans, cteColumns, perTableColumn
   return plan
 }
 
+/**
+ * Recursively replaces identifier nodes in ORDER BY terms that match SELECT
+ * aliases with their aliased expressions.
+ *
+ * @param {OrderByItem[]} orderBy
+ * @param {Map<string, ExprNode>} aliases
+ * @returns {OrderByItem[]}
+ */
+function resolveOrderByAliases(orderBy, aliases) {
+  if (!aliases.size) return orderBy
+  return orderBy.map(term => ({ ...term, expr: resolveAliases(term.expr, aliases) }))
+}
+
 /**
  * Recursively replaces identifier nodes that match SELECT aliases
  * with their aliased expressions.
@@ -446,7 +512,8 @@ function resolveAliases(node, aliases) {
   }
   if (node.type === 'function') {
     const args = node.args.map(arg => resolveAliases(arg, aliases))
-    return { ...node, args }
+    if (!node.filter) return { ...node, args }
+    return { ...node, args, filter: resolveAliases(node.filter, aliases) }
   }
   if (node.type === 'cast') {
     return { ...node, expr: resolveAliases(node.expr, aliases) }
@@ -609,6 +676,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 {
@@ -66,6 +67,7 @@ export interface HashAggregateNode {
   type: 'HashAggregate'
   groupBy: ExprNode[]
   columns: SelectColumn[]
+  orderBy?: OrderByItem[]
   having?: ExprNode
   child: QueryPlan
 }
@@ -124,3 +126,17 @@ export interface TableFunctionNode {
   args: ExprNode[]
   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/validation/functions.js

@@ -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}
@@ -172,7 +180,7 @@ export const FUNCTION_SIGNATURES = {
   ARRAY_AGG: { min: 1, max: 1, signature: 'expression' },
 
   // Array functions
-  ARRAY_LENGTH: { min: 1, max: 1, signature: 'array' },
+  ARRAY_LENGTH: { min: 1, max: 2, signature: 'array[, dimension]' },
   ARRAY_POSITION: { min: 2, max: 2, signature: 'array, element' },
   ARRAY_SORT: { min: 1, max: 1, signature: 'array' },
   CARDINALITY: { min: 1, max: 1, signature: 'array' },
@@ -200,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/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') {