squirreling 0.13.0 → 0.15.0

package/README.md

@@ -146,7 +146,8 @@ Squirreling mostly follows the SQL standard. The following features are supporte
 - `JOIN` operations: `INNER JOIN`, `LEFT JOIN`, `RIGHT JOIN`, `FULL JOIN`, `CROSS JOIN`, `POSITIONAL JOIN`, `LATERAL VIEW [OUTER] EXPLODE(...)`, with `ON` or `USING (col, ...)` conditions
 - `GROUP BY` and `HAVING` clauses
 - Set operations: `UNION`, `UNION ALL`, `INTERSECT`, `INTERSECT ALL`, `EXCEPT`, `EXCEPT ALL`
-- Expressions: `CASE`, `CAST`, `BETWEEN`, `IN`, `LIKE`, `IS NULL`, `IS NOT NULL`
+- Expressions: `CASE`, `CAST`, `BETWEEN`, `IN`, `LIKE`, `IS NULL`, `IS NOT NULL`, string concatenation `||`
+- Subscript access: zero-based array indexing `col[0]`, struct field access `col['field']`, and chains like `col[0].field`
 
 ### Quoting
 
@@ -158,7 +159,7 @@ Squirreling mostly follows the SQL standard. The following features are supporte
 
 - Aggregate: `COUNT`, `COUNTIF`, `SUM`, `AVG`, `MIN`, `MAX`, `MEDIAN`, `PERCENTILE_CONT`, `APPROX_QUANTILE`, `STDDEV_POP`, `STDDEV_SAMP`, `ARRAY_AGG`, `JSON_ARRAYAGG`, `STRING_AGG`
 - Window: `ROW_NUMBER`, `LAG`, `LEAD`
-- String: `CONCAT`, `SUBSTRING`, `REPLACE`, `LENGTH`, `UPPER`, `LOWER`, `TRIM`, `LEFT`, `RIGHT`, `INSTR`, `POSITION`, `STRPOS`
+- String: `CONCAT`, `SUBSTRING`, `REPLACE`, `LENGTH`, `OCTET_LENGTH`, `UPPER`, `LOWER`, `TRIM`, `LEFT`, `RIGHT`, `INSTR`, `POSITION`, `STRPOS`, `SPLIT_PART`, `STRING_SPLIT`
 - Math: `ABS`, `SIGN`, `CEIL`, `FLOOR`, `ROUND`, `MOD`, `RAND`, `RANDOM`, `LN`, `LOG10`, `EXP`, `POWER`, `SQRT`
 - Trig: `SIN`, `COS`, `TAN`, `COT`, `ASIN`, `ACOS`, `ATAN`, `ATAN2`, `DEGREES`, `RADIANS`, `PI`
 - Date: `CURRENT_DATE`, `CURRENT_TIME`, `CURRENT_TIMESTAMP`, `DATE_DIFF`, `DATEDIFF`, `DATE_PART`, `DATE_TRUNC`, `EPOCH`, `EXTRACT`, `INTERVAL`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "squirreling",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "Squirreling Async SQL Engine",
   "author": "Hyperparam",
   "homepage": "https://hyperparam.app",
@@ -39,11 +39,11 @@
     "test": "vitest run"
   },
   "devDependencies": {
-    "@types/node": "26.1.0",
-    "@vitest/coverage-v8": "4.1.9",
+    "@types/node": "26.1.1",
+    "@vitest/coverage-v8": "4.1.10",
     "eslint": "9.39.4",
-    "eslint-plugin-jsdoc": "63.0.11",
-    "typescript": "6.0.3",
-    "vitest": "4.1.9"
+    "eslint-plugin-jsdoc": "63.0.13",
+    "typescript": "7.0.2",
+    "vitest": "4.1.10"
   }
 }

package/src/ast.d.ts

@@ -70,7 +70,7 @@ export interface FromFunction extends AstBase {
 
 export type ArithmeticOp = '+' | '-' | '*' | '/' | '%'
 
-export type BinaryOp = 'AND' | 'OR' | 'LIKE' | ComparisonOp | ArithmeticOp
+export type BinaryOp = 'AND' | 'OR' | 'LIKE' | '||' | ComparisonOp | ArithmeticOp
 
 export type ComparisonOp = '=' | '==' | '!=' | '<>' | '<' | '>' | '<=' | '>='
 
@@ -114,7 +114,7 @@ export interface WindowFunctionNode extends AstBase {
   orderBy: OrderByItem[]
 }
 
-export type CastType = 'TEXT' | 'STRING' | 'VARCHAR' | 'INTEGER' | 'INT' | 'BIGINT' | 'FLOAT' | 'REAL' | 'DOUBLE' | 'BOOLEAN' | 'BOOL'
+export type CastType = 'TEXT' | 'STRING' | 'VARCHAR' | 'INTEGER' | 'INT' | 'BIGINT' | 'FLOAT' | 'REAL' | 'DOUBLE' | 'BOOLEAN' | 'BOOL' | 'TIMESTAMP'
 
 export interface CastNode extends AstBase {
   type: 'cast'
@@ -168,6 +168,12 @@ export interface StarNode extends AstBase {
   type: 'star'
 }
 
+export interface SubscriptNode extends AstBase {
+  type: 'subscript'
+  expr: ExprNode
+  index: ExprNode
+}
+
 export type ExprNode =
   | LiteralNode
   | IdentifierNode
@@ -183,6 +189,7 @@ export type ExprNode =
   | SubqueryNode
   | IntervalNode
   | StarNode
+  | SubscriptNode
 
 export interface StarColumn extends AstBase {
   type: 'star'

package/src/execute/aggregates.js

@@ -1,7 +1,8 @@
 import { derivedAlias } from '../expression/alias.js'
 import { evaluateExpr } from '../expression/evaluate.js'
 import { finalizeAccumulator, newAccumulator, updateAccumulator } from './accumulator.js'
-import { executePlan, selectColumnNames } from './execute.js'
+import { executePlan, executeScan, selectColumnNames } from './execute.js'
+import { normalizeScanColumnResult } from './scanColumn.js'
 import { sortEntriesByTerms } from './sort.js'
 import { planStreamingAggregates, streamingHashAggregateRows, streamingScalarAggregateRows } from './streamingAggregate.js'
 import { keyify } from './utils.js'
@@ -195,17 +196,21 @@ export function executeHashAggregate(plan, context) {
  */
 export function executeScalarAggregate(plan, context) {
   // Fast path: use scanColumn when available
-  const fast = tryColumnScanAggregate(plan, context)
-  if (fast) {
+  const columnScan = tryColumnScanAggregate(plan, context)
+  if (columnScan?.rows) {
     return {
       columns: selectColumnNames(plan.columns, []),
       numRows: 1,
       maxRows: 1,
-      rows: fast,
+      rows: columnScan.rows,
     }
   }
 
-  const child = executePlan({ plan: plan.child, context })
+  // A declined pushdown still returned a usable one-column scan. Transfer it
+  // to the ordinary scan path instead of calling the source a second time.
+  const child = columnScan?.fallback
+    ? executeScan(columnScan.fallback.plan, context, columnScan.fallback.result)
+    : executePlan({ plan: plan.child, context })
   const streaming = planStreamingAggregates(plan, child.columns)
   if (streaming) {
     return {
@@ -263,6 +268,7 @@ export function executeScalarAggregate(plan, context) {
  *   column: string,
  *   alias: string,
  *   distinct?: boolean,
+ *   star?: boolean,
  * }} ColumnAggSpec
  */
 
@@ -272,7 +278,13 @@ export function executeScalarAggregate(plan, context) {
  *
  * @param {ScalarAggregateNode} plan
  * @param {ExecuteContext} context
- * @returns {(() => AsyncGenerator<AsyncRow>) | undefined}
+ * @returns {{
+ *   rows?: () => AsyncGenerator<AsyncRow>,
+ *   fallback?: {
+ *     plan: import('../plan/types.js').ScanNode,
+ *     result: import('../types.js').ScanColumnResults,
+ *   },
+ * } | undefined}
  */
 function tryColumnScanAggregate(plan, { tables, signal }) {
   // No HAVING support in fast path
@@ -281,61 +293,96 @@ function tryColumnScanAggregate(plan, { tables, signal }) {
   if (plan.child.type !== 'Scan') return
   const scanNode = plan.child
   const { limit, offset, where } = scanNode.hints
-  // scanColumn doesn't support filtering
-  if (where) return
 
   const table = tables[scanNode.table]
   if (!table?.scanColumn) return
 
+  // COUNT(*) needs a physical column whose filtered chunk lengths can be
+  // counted. Prefer a predicate/projection column, then any table column.
+  const starColumn = scanNode.hints.columns?.[0] ?? table.columns[0]
+  if (!starColumn) return
+
   // All columns must be simple aggregates on plain identifiers
   /** @type {ColumnAggSpec[]} */
   const specs = []
   for (const col of plan.columns) {
     if (col.type !== 'derived') return
-    const spec = extractColumnAggSpec(col)
+    const spec = extractColumnAggSpec(col, starColumn)
     if (!spec) return
     specs.push(spec)
   }
 
-  return async function* () {
-    /** @type {string[]} */
-    const columns = []
-    /** @type {AsyncCells} */
-    const cells = {}
-
-    // Group specs by column so each column is scanned at most once no matter how
-    // many aggregates read it (e.g. MIN(x), MAX(x), AVG(x) share one pass).
-    /** @type {Map<string, ColumnAggSpec[]>} */
-    const specsByColumn = new Map()
-    for (const spec of specs) {
-      const group = specsByColumn.get(spec.column)
-      if (group) group.push(spec)
-      else specsByColumn.set(spec.column, [spec])
+  const physicalColumns = new Set(specs.map(spec => spec.column))
+  const hasPushdown = where || limit !== undefined || offset !== undefined
+  if (hasPushdown) {
+    // If negotiation fails, the returned column stream can only replace the
+    // ordinary scan when that scan needs the same single column. Otherwise a
+    // probe could allocate work that no correct fallback is able to consume.
+    const scanColumns = scanNode.hints.columns
+    if (physicalColumns.size !== 1 || scanColumns?.length !== 1 ||
+      !physicalColumns.has(scanColumns[0])) return
+  }
+
+  // Ask once per physical column and retain the returned chunks. Sources
+  // report applied hints just like scan(); declined hints use the normal path.
+  /** @type {Map<string, import('../types.js').ScanColumnResults>} */
+  const columnScans = new Map()
+  for (const { column } of specs) {
+    if (columnScans.has(column)) continue
+    const options = { column, where, limit, offset, signal }
+    const result = normalizeScanColumnResult(table.scanColumn(options), options)
+    if (where && !result.appliedWhere) {
+      return { fallback: { plan: scanNode, result } }
+    }
+    if ((limit !== undefined || offset !== undefined) && !result.appliedLimitOffset) {
+      return { fallback: { plan: scanNode, result } }
     }
+    columnScans.set(column, result)
+  }
 
-    // Each column's single pass is computed once and shared by all its cells;
-    // a column is only scanned if one of its aggregates is actually read.
-    /** @type {Map<string, Promise<Map<string, SqlPrimitive>>>} */
-    const passes = new Map()
-    /**
-     * @param {string} column
-     * @returns {Promise<Map<string, SqlPrimitive>>}
-     */
-    function scanOnce(column) {
-      let pass = passes.get(column)
-      if (!pass) {
-        pass = scanColumnGroup({ table, specs: specsByColumn.get(column) ?? [], limit, offset, signal })
-        passes.set(column, pass)
+  return {
+    async *rows() {
+      /** @type {string[]} */
+      const columns = []
+      /** @type {AsyncCells} */
+      const cells = {}
+
+      // Group specs by column so each column is scanned at most once no matter how
+      // many aggregates read it (e.g. MIN(x), MAX(x), AVG(x) share one pass).
+      /** @type {Map<string, ColumnAggSpec[]>} */
+      const specsByColumn = new Map()
+      for (const spec of specs) {
+        const group = specsByColumn.get(spec.column)
+        if (group) group.push(spec)
+        else specsByColumn.set(spec.column, [spec])
       }
-      return pass
-    }
 
-    for (const spec of specs) {
-      columns.push(spec.alias)
-      cells[spec.alias] = async () => (await scanOnce(spec.column)).get(spec.alias) ?? null
-    }
+      // Each column's single pass is computed once and shared by all its cells;
+      // a column is only scanned if one of its aggregates is actually read.
+      /** @type {Map<string, Promise<Map<string, SqlPrimitive>>>} */
+      const passes = new Map()
+      /**
+       * @param {string} column
+       * @returns {Promise<Map<string, SqlPrimitive>>}
+       */
+      function scanOnce(column) {
+        let pass = passes.get(column)
+        if (!pass) {
+          const scan = columnScans.get(column)
+          if (!scan) throw new Error(`missing scanColumn result for ${column}`)
+          pass = scanColumnGroup({ values: scan.chunks(), specs: specsByColumn.get(column) ?? [], signal })
+          passes.set(column, pass)
+        }
+        return pass
+      }
 
-    yield { columns, cells }
+      for (const spec of specs) {
+        columns.push(spec.alias)
+        cells[spec.alias] = async () => (await scanOnce(spec.column)).get(spec.alias) ?? null
+      }
+
+      yield { columns, cells }
+    },
   }
 }
 
@@ -344,16 +391,27 @@ function tryColumnScanAggregate(plan, { tables, signal }) {
  * Returns undefined if the expression is not a supported simple aggregate.
  *
  * @param {DerivedColumn} col
+ * @param {string} starColumn
  * @returns {ColumnAggSpec | undefined}
  */
-function extractColumnAggSpec({ expr, alias }) {
+function extractColumnAggSpec({ expr, alias }, starColumn) {
   if (expr.type !== 'function') return
   if (expr.filter) return // FILTER not supported in fast path
   const funcName = expr.funcName.toUpperCase()
   if (!['COUNT', 'SUM', 'AVG', 'MIN', 'MAX'].includes(funcName)) return
 
-  // Argument must be a plain column identifier
+  // Argument must be a plain column identifier, except COUNT(*), which counts
+  // the lengths of filtered chunks from an arbitrary physical column.
   const arg = expr.args[0]
+  if (arg.type === 'star') {
+    if (funcName !== 'COUNT' || expr.distinct) return
+    return {
+      funcName,
+      column: starColumn,
+      alias: alias ?? derivedAlias(expr),
+      star: true,
+    }
+  }
   if (arg.type !== 'identifier') return
   return {
     funcName,
@@ -368,26 +426,23 @@ function extractColumnAggSpec({ expr, alias }) {
  * All specs share the one scanColumn walk, so MIN(x)/MAX(x)/AVG(x) decode x once.
  *
  * @param {Object} options
- * @param {AsyncDataSource} options.table
+ * @param {AsyncIterable<ArrayLike<SqlPrimitive>>} options.values
  * @param {ColumnAggSpec[]} options.specs - aggregates over the same column
- * @param {number} [options.limit]
- * @param {number} [options.offset]
  * @param {AbortSignal} [options.signal]
  * @returns {Promise<Map<string, SqlPrimitive>>} alias → aggregate value
  */
-async function scanColumnGroup({ table, specs, limit, offset, signal }) {
-  const { column } = specs[0]
-  const values = table.scanColumn({ column, limit, offset, signal })
-
+async function scanColumnGroup({ values, specs, signal }) {
   const accs = specs.map(spec => ({ spec, acc: newAccumulator(spec.funcName, spec.distinct) }))
 
   for await (const chunk of values) {
     signal?.throwIfAborted()
     for (let i = 0; i < chunk.length; i++) {
       const v = chunk[i]
-      if (v == null) continue
       for (const { spec, acc } of accs) {
-        updateAccumulator(spec.funcName, acc, v)
+        // COUNT(*) counts matching rows even when the arbitrary carrier column
+        // selected for scanColumn is null. Other aggregates ignore nulls.
+        if (spec.star) acc.count++
+        else if (v != null) updateAccumulator(spec.funcName, acc, v)
       }
     }
   }

package/src/execute/execute.js

@@ -7,6 +7,7 @@ import { statementScope } from '../plan/columns.js'
 import { validateScan, validateTable } from '../validation/tables.js'
 import { executeHashAggregate, executeScalarAggregate } from './aggregates.js'
 import { executeHashJoin, executeNestedLoopJoin, executePositionalJoin } from './join.js'
+import { normalizeScanColumnResult } from './scanColumn.js'
 import { executeSort } from './sort.js'
 import { addBounds, minBounds, stableRowKey } from './utils.js'
 import { executeWindow } from './window.js'
@@ -269,40 +270,63 @@ export function selectColumnNames(selectColumns, childColumns) {
 /**
  * @param {ScanNode} plan
  * @param {ExecuteContext} context
+ * @param {import('../types.js').ScanColumnResults} [existingColumnResult]
  * @returns {QueryResults}
  */
-function executeScan(plan, context) {
+export function executeScan(plan, context, existingColumnResult) {
   const { tables, signal } = context
   const table = validateTable({ ...plan, tables })
   validateScan({ ...plan, tables })
   const hasLimitOffset = plan.hints.limit !== undefined || plan.hints.offset // 0 offset is noop
 
-  // Fast path: single column scan without WHERE
-  if (table.scanColumn && plan.hints.columns?.length === 1 && !plan.hints.where) {
+  // Fast path: single column scan. As with scan(), hints the source did not
+  // apply are handled by the engine over the returned column values.
+  const scanColumnOptions = plan.hints.columns?.length === 1
+    ? plan.hints.where
+      // Do not push a filtered range until WHERE is known to be applied: an
+      // older source may ignore WHERE but eagerly apply LIMIT/OFFSET.
+      ? { column: plan.hints.columns[0], where: plan.hints.where, signal }
+      : { column: plan.hints.columns[0], ...plan.hints, signal }
+    : undefined
+  const columnResult = existingColumnResult ?? (table.scanColumn && scanColumnOptions
+    ? normalizeScanColumnResult(table.scanColumn(scanColumnOptions), scanColumnOptions)
+    : undefined)
+  if (columnResult && scanColumnOptions) {
     const column = plan.hints.columns[0]
-    const chunks = table.scanColumn({
-      column,
-      limit: plan.hints.limit,
-      offset: plan.hints.offset,
-      signal,
-    })
     const scanRows = computeScanRows(table.numRows, plan.hints.limit, plan.hints.offset)
     return {
       columns: [column],
-      numRows: scanRows,
+      numRows: plan.hints.where ? undefined : scanRows,
       maxRows: scanRows,
       async *rows() {
         const columns = [column]
-        for await (const chunk of chunks) {
-          signal?.throwIfAborted()
-          for (let i = 0; i < chunk.length; i++) {
-            const value = chunk[i]
-            yield {
-              columns,
-              cells: { [column]: () => Promise.resolve(value) },
+        let result = (async function* () {
+          // Creating the chunk stream may itself start I/O, so leave it until
+          // the returned rows are actually consumed.
+          for await (const chunk of columnResult.chunks()) {
+            signal?.throwIfAborted()
+            for (let i = 0; i < chunk.length; i++) {
+              const value = chunk[i]
+              yield {
+                columns,
+                cells: { [column]: () => Promise.resolve(value) },
+              }
             }
           }
+        })()
+
+        if (!columnResult.appliedWhere && plan.hints.where) {
+          result = filterRows(result, plan.hints.where, context, plan.hints.limit)
         }
+        // Filtered LIMIT/OFFSET was intentionally not passed to scanColumn.
+        const appliedLimitOffset = plan.hints.where
+          ? false
+          : columnResult.appliedLimitOffset
+        if (!appliedLimitOffset && hasLimitOffset) {
+          result = limitRows(result, plan.hints.limit, plan.hints.offset, signal)
+        }
+
+        yield* result
         // A data source may end its stream cooperatively on abort; surface
         // the abort so a truncated scan is not mistaken for a complete one
         signal?.throwIfAborted()

package/src/execute/scanColumn.js

@@ -0,0 +1,17 @@
+/**
+ * Normalizes scanColumn's legacy AsyncIterable return into ScanColumnResults.
+ * Legacy implementations are valid for unfiltered scans only: they cannot
+ * claim to have applied a WHERE predicate they predate.
+ *
+ * @param {AsyncIterable<ArrayLike<import('../types.js').SqlPrimitive>> | import('../types.js').ScanColumnResults} result
+ * @param {import('../types.js').ScanColumnOptions} options
+ * @returns {import('../types.js').ScanColumnResults}
+ */
+export function normalizeScanColumnResult(result, options) {
+  if ('chunks' in result) return result
+  return {
+    chunks: () => result,
+    appliedWhere: !options.where,
+    appliedLimitOffset: !options.where,
+  }
+}

package/src/execute/streamingAggregate.js

@@ -161,6 +161,8 @@ export function planStreamingAggregates({ columns, having, orderBy, groupBy }, c
     case 'in valuelist':
       // values after the first are skipped once an earlier value matches
       return walk(node.expr, lazy) && node.values.every((v, i) => walk(v, lazy || i > 0))
+    case 'subscript':
+      return walk(node.expr, lazy) && walk(node.index, lazy)
     case 'function': {
       const funcName = node.funcName.toUpperCase()
       if (!isAggregateFunc(funcName)) {
@@ -257,6 +259,8 @@ function isScalarExpr(node) {
       (!node.elseResult || isScalarExpr(node.elseResult))
   case 'in valuelist':
     return isScalarExpr(node.expr) && node.values.every(v => isScalarExpr(v))
+  case 'subscript':
+    return isScalarExpr(node.expr) && isScalarExpr(node.index)
   case 'function':
     return !isAggregateFunc(node.funcName.toUpperCase()) && node.args.every(arg => isScalarExpr(arg))
   default:
@@ -316,6 +320,11 @@ function substituteValues(node, values) {
     const valueNodes = node.values.map(v => substituteValues(v, values))
     return { ...node, expr, values: valueNodes }
   }
+  case 'subscript': {
+    const expr = substituteValues(node.expr, values)
+    const index = substituteValues(node.index, values)
+    return expr === node.expr && index === node.index ? node : { ...node, expr, index }
+  }
   case 'function': {
     const args = node.args.map(arg => substituteValues(arg, values))
     return args.every((arg, i) => arg === node.args[i]) ? node : { ...node, args }

package/src/expression/alias.js

@@ -37,5 +37,12 @@ export function derivedAlias(expr) {
   if (expr.type === 'interval') {
     return `interval_${expr.value}_${expr.unit.toLowerCase()}`
   }
+  if (expr.type === 'subscript') {
+    // string subscript is struct field access, alias to the field name
+    if (expr.index.type === 'literal' && typeof expr.index.value === 'string') {
+      return expr.index.value
+    }
+    return `${derivedAlias(expr.expr)}[${derivedAlias(expr.index)}]`
+  }
   return 'expr'
 }

package/src/expression/binary.js

@@ -23,6 +23,12 @@ export function applyBinaryOp(op, a, b) {
     if (op === '%') return numB === 0 ? null : numA % numB
   }
 
+  // String concatenation returns null if either operand is null
+  if (op === '||') {
+    if (a == null || b == null) return null
+    return String(a) + String(b)
+  }
+
   // Comparison and logical operators
   if (a == null || b == null) {
     return false

package/src/expression/date.js

@@ -130,7 +130,7 @@ export function dateDiff(unit, startVal, endVal) {
  * @param {SqlPrimitive} val
  * @returns {Date | null}
  */
-function toDate(val) {
+export function toDate(val) {
   if (val instanceof Date) return val
   const dateOrTime = /^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2})?/
   if (typeof val === 'string' && dateOrTime.test(val)) {

package/src/expression/evaluate.js

@@ -7,7 +7,7 @@ import { UnknownFunctionError } from '../validation/parseErrors.js'
 import { ColumnNotFoundError } from '../validation/tables.js'
 import { derivedAlias } from './alias.js'
 import { applyBinaryOp } from './binary.js'
-import { applyIntervalToDate, dateDiff, dateTrunc, extractField } from './date.js'
+import { applyIntervalToDate, dateDiff, dateTrunc, extractField, toDate } from './date.js'
 import { evaluateMathFunc } from './math.js'
 import { evaluateRegexpFunc } from './regexp.js'
 import { evaluateSpatialFunc } from '../spatial/spatial.js'
@@ -130,6 +130,23 @@ export async function evaluateExpr({ node, row, rowIndex, rows, context }) {
     })
   }
 
+  // Subscript access: array indexing (arr[0]) or struct field access (obj['key'])
+  if (node.type === 'subscript') {
+    const value = await evaluateExpr({ node: node.expr, row, rowIndex, rows, context })
+    if (value == null) return null
+    const index = await evaluateExpr({ node: node.index, row, rowIndex, rows, context })
+    if (index == null) return null
+    if (typeof index === 'number' || typeof index === 'bigint') {
+      if (!Array.isArray(value)) return null
+      return value[Number(index)] ?? null
+    }
+    const key = String(index)
+    if (isPlainObject(value) && Object.prototype.hasOwnProperty.call(value, key)) {
+      return value[key]
+    }
+    return null
+  }
+
   // Scalar subquery - returns a single value
   if (node.type === 'subquery') {
     const outerScope = context.scope
@@ -710,6 +727,14 @@ export async function evaluateExpr({ node, row, rowIndex, rows, context }) {
     if (toType === 'BOOLEAN' || toType === 'BOOL') {
       return Boolean(val)
     }
+    if (toType === 'TIMESTAMP') {
+      if (typeof val === 'number' || typeof val === 'bigint') {
+        const date = new Date(Number(val))
+        if (isNaN(date.getTime())) return null
+        return date
+      }
+      return toDate(val)
+    }
   }
 
   // IN and NOT IN with value lists

package/src/expression/strings.js

@@ -4,6 +4,8 @@ import { ArgValueError } from '../validation/executionErrors.js'
  * @import { FunctionNode, SqlPrimitive, StringFunc } from '../types.js'
  */
 
+const textEncoder = new TextEncoder()
+
 /**
  * Evaluate a string function
  *
@@ -43,6 +45,16 @@ export function evaluateStringFunc({ funcName, node, args, rowIndex }) {
     })
   }
 
+  if (funcName === 'OCTET_LENGTH') {
+    if (typeof val === 'string') return textEncoder.encode(val).length
+    throw new ArgValueError({
+      ...node,
+      message: `expected string, got ${typeof val === 'object' ? val instanceof Date ? 'date' : 'object' : typeof val}`,
+      hint: 'Use CAST to convert to a string first.',
+      rowIndex,
+    })
+  }
+
   if (typeof val === 'object' && !(val instanceof Date)) {
     throw new ArgValueError({
       ...node,
@@ -131,6 +143,32 @@ export function evaluateStringFunc({ funcName, node, args, rowIndex }) {
     return str.substring(str.length - len)
   }
 
+  if (funcName === 'SPLIT_PART') {
+    const delimiter = args[1]
+    if (delimiter == null) return null
+    const index = Number(args[2])
+    if (!Number.isInteger(index) || index === 0) {
+      throw new ArgValueError({
+        ...node,
+        message: `index must be a non-zero integer, got ${args[2]}`,
+        hint: 'Field indexes are 1-based.',
+        rowIndex,
+      })
+    }
+    const delim = String(delimiter)
+    const parts = delim === '' ? [str] : str.split(delim)
+    // Negative index counts from the end
+    const partIdx = index < 0 ? parts.length + index : index - 1
+    return parts[partIdx] ?? ''
+  }
+
+  if (funcName === 'STRING_SPLIT') {
+    const delimiter = args[1]
+    if (delimiter == null) return null
+    const delim = String(delimiter)
+    return delim === '' ? [str] : str.split(delim)
+  }
+
   if (funcName === 'INSTR' || funcName === 'POSITION' || funcName === 'STRPOS') {
     const search = args[1]
     if (search == null) return null

package/src/parse/expression.js

@@ -9,7 +9,7 @@ import { consume, current, expect, match } from './state.js'
  */
 
 // Precedence (lowest to highest):
-// OR, AND, NOT, Comparison, Additive, Multiplicative, Primary
+// OR, AND, NOT, Comparison, Concat, Additive, Multiplicative, Primary
 
 /**
  * @param {ParserState} state
@@ -88,7 +88,7 @@ function parseNot(state) {
  * @returns {ExprNode}
  */
 function parseComparison(state) {
-  const left = parseAdditive(state)
+  const left = parseConcat(state)
   const { positionStart } = left
 
   // IS [NOT] NULL
@@ -108,7 +108,7 @@ function parseComparison(state) {
   if (match(state, 'keyword', 'NOT')) {
     // NOT LIKE
     if (match(state, 'keyword', 'LIKE')) {
-      const right = parseAdditive(state)
+      const right = parseConcat(state)
       return {
         type: 'unary',
         op: 'NOT',
@@ -127,9 +127,9 @@ function parseComparison(state) {
 
     // NOT BETWEEN - convert to range comparison
     if (match(state, 'keyword', 'BETWEEN')) {
-      const lower = parseAdditive(state)
+      const lower = parseConcat(state)
       expect(state, 'keyword', 'AND')
-      const upper = parseAdditive(state)
+      const upper = parseConcat(state)
       // NOT BETWEEN -> expr < lower OR expr > upper
       return {
         type: 'binary',
@@ -163,7 +163,7 @@ function parseComparison(state) {
 
   // LIKE
   if (match(state, 'keyword', 'LIKE')) {
-    const right = parseAdditive(state)
+    const right = parseConcat(state)
     return {
       type: 'binary',
       op: 'LIKE',
@@ -176,9 +176,9 @@ function parseComparison(state) {
 
   // BETWEEN - convert to range comparison
   if (match(state, 'keyword', 'BETWEEN')) {
-    const lower = parseAdditive(state)
+    const lower = parseConcat(state)
     expect(state, 'keyword', 'AND')
-    const upper = parseAdditive(state)
+    const upper = parseConcat(state)
     // BETWEEN -> expr >= lower AND expr <= upper
     return {
       type: 'binary',
@@ -198,7 +198,7 @@ function parseComparison(state) {
   const opTok = current(state)
   if (opTok.type === 'operator' && isBinaryOp(opTok.value)) {
     consume(state)
-    const right = parseAdditive(state)
+    const right = parseConcat(state)
     return {
       type: 'binary',
       op: opTok.value,
@@ -212,6 +212,33 @@ function parseComparison(state) {
   return left
 }
 
+/**
+ * @param {ParserState} state
+ * @returns {ExprNode}
+ */
+export function parseConcat(state) {
+  let left = parseAdditive(state)
+  while (true) {
+    const tok = current(state)
+    if (tok.type === 'operator' && tok.value === '||') {
+      consume(state)
+      const right = parseAdditive(state)
+      // Recursive left-associative binary operator
+      left = {
+        type: 'binary',
+        op: '||',
+        left,
+        right,
+        positionStart: left.positionStart,
+        positionEnd: right.positionEnd,
+      }
+    } else {
+      break
+    }
+  }
+  return left
+}
+
 /**
  * @param {ParserState} state
  * @returns {ExprNode}

package/src/parse/extractTables.js

@@ -110,6 +110,10 @@ function walkExpr(expr, cteScope, refs) {
     walkExpr(expr.expr, cteScope, refs)
     for (const v of expr.values) walkExpr(v, cteScope, refs)
     return
+  case 'subscript':
+    walkExpr(expr.expr, cteScope, refs)
+    walkExpr(expr.index, cteScope, refs)
+    return
   case 'exists':
   case 'not exists':
     walkStatement(expr.subquery, cteScope, refs)

package/src/parse/functions.js

@@ -1,6 +1,6 @@
 import { isAggregateFunc, isKnownFunction, isWindowFunc, niladicFuncs, validateFunctionArgs } from '../validation/functions.js'
 import { ParseError, UnknownFunctionError } from '../validation/parseErrors.js'
-import { parseExpression } from './expression.js'
+import { parseConcat, parseExpression } from './expression.js'
 import { consume, current, expect, match } from './state.js'
 
 /**
@@ -60,6 +60,17 @@ export function parseFunctionCall(state, positionStart) {
         positionStart: next.positionStart,
         positionEnd: state.lastPos,
       })
+    } else if (funcNameUpper === 'POSITION' && !args.length) {
+      // ANSI syntax: POSITION(needle IN haystack), stored as (haystack, needle).
+      // The needle is parsed below comparison precedence so IN is not consumed
+      // as the set-membership operator.
+      const needle = parseConcat(state)
+      if (match(state, 'keyword', 'IN')) {
+        const haystack = parseExpression(state)
+        args.push(haystack, needle)
+        break
+      }
+      args.push(needle)
     } else {
       args.push(parseExpression(state))
     }

package/src/parse/parse.js

@@ -48,6 +48,14 @@ export function parseSql({ query, functions }) {
 export function parseStatement(state) {
   const positionStart = state.lastPos
   if (match(state, 'keyword', 'WITH')) {
+    const recursiveTok = current(state)
+    if (recursiveTok.type === 'identifier' && recursiveTok.value.toUpperCase() === 'RECURSIVE') {
+      throw new ParseError({
+        message: `WITH RECURSIVE is not supported at position ${recursiveTok.positionStart}`,
+        ...recursiveTok,
+      })
+    }
+
     /** @type {CTEDefinition[]} */
     const ctes = []
     /** @type {Set<string>} */

package/src/parse/primary.js

@@ -11,12 +11,65 @@ import { consume, current, expect, match, parseError, peekToken } from './state.
  */
 
 /**
- * Parse a primary expression, which is the innermost order of operations.
+ * Parse a primary expression, which is the innermost order of operations,
+ * followed by any postfix subscript operators.
  *
  * @param {ParserState} state
  * @returns {ExprNode}
  */
 export function parsePrimary(state) {
+  return parsePostfix(state, parsePrimaryBase(state))
+}
+
+/**
+ * Parses postfix subscript operators after a primary expression: bracket
+ * indexing (`expr[0]`, `expr['key']`) and struct field access on a subscript
+ * result (`expr[0].field`).
+ *
+ * @param {ParserState} state
+ * @param {ExprNode} expr
+ * @returns {ExprNode}
+ */
+function parsePostfix(state, expr) {
+  while (true) {
+    if (match(state, 'bracket', '[')) {
+      const index = parseExpression(state)
+      expect(state, 'bracket', ']')
+      expr = {
+        type: 'subscript',
+        expr,
+        index,
+        positionStart: expr.positionStart,
+        positionEnd: state.lastPos,
+      }
+    } else if (expr.type === 'subscript' && current(state).type === 'dot') {
+      consume(state)
+      const fieldTok = expect(state, 'identifier')
+      expr = {
+        type: 'subscript',
+        expr,
+        index: {
+          type: 'literal',
+          value: fieldTok.value,
+          positionStart: fieldTok.positionStart,
+          positionEnd: fieldTok.positionEnd,
+        },
+        positionStart: expr.positionStart,
+        positionEnd: state.lastPos,
+      }
+    } else {
+      return expr
+    }
+  }
+}
+
+/**
+ * Parse a primary expression without postfix operators.
+ *
+ * @param {ParserState} state
+ * @returns {ExprNode}
+ */
+function parsePrimaryBase(state) {
   const tok = current(state)
   const { positionStart } = tok
 
@@ -82,7 +135,7 @@ export function parsePrimary(state) {
       const toType = typeTok.value.toUpperCase()
       if (!isCastType(toType)) {
         throw new SyntaxError({
-          expected: 'cast type (STRING, INT, BIGINT, FLOAT, BOOL)',
+          expected: 'cast type (STRING, INT, BIGINT, FLOAT, BOOL, TIMESTAMP)',
           after: 'AS',
           ...typeTok,
         })
@@ -97,6 +150,24 @@ export function parsePrimary(state) {
       }
     }
 
+    // TIMESTAMP '2026-01-01 00:00:00' typed literal
+    if (funcNameUpper === 'TIMESTAMP' && next.type === 'string') {
+      consume(state) // TIMESTAMP
+      const strTok = consume(state) // string literal
+      return {
+        type: 'cast',
+        expr: {
+          type: 'literal',
+          value: strTok.value,
+          positionStart: strTok.positionStart,
+          positionEnd: strTok.positionEnd,
+        },
+        toType: 'TIMESTAMP',
+        positionStart,
+        positionEnd: state.lastPos,
+      }
+    }
+
     // EXTRACT(field FROM expr)
     if (funcNameUpper === 'EXTRACT' && next.type === 'paren' && next.value === '(') {
       consume(state) // EXTRACT
@@ -157,16 +228,21 @@ 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')
+    } else {
+      // table['column'] string subscript is equivalent to dot access; other
+      // subscripts (numeric, expression) are left for the postfix parser
+      const open = current(state)
+      const fieldTok = peekToken(state, 1)
+      const close = peekToken(state, 2)
+      if (open.type === 'bracket' && open.value === '[' &&
+          fieldTok.type === 'string' &&
+          close.type === 'bracket' && close.value === ']') {
+        consume(state) // '['
+        consume(state) // string
+        consume(state) // ']'
+        prefix = name
+        name = fieldTok.value
       }
-      consume(state)
-      expect(state, 'bracket', ']')
-      prefix = name
-      name = fieldTok.value
     }
 
     return {

package/src/parse/tokenize.js

@@ -172,6 +172,18 @@ export function tokenizeSql(query) {
       continue
     }
 
+    // string concatenation operator
+    if (ch === '|' && next === '|') {
+      i += 2
+      tokens.push({
+        type: 'operator',
+        value: '||',
+        positionStart,
+        positionEnd: i,
+      })
+      continue
+    }
+
     // operators
     if ('<>!=+-*/%'.includes(ch)) {
       let op = nextChar()

package/src/plan/columns.js

@@ -255,6 +255,9 @@ export function collectColumnsFromExpr(expr, columns, aliases) {
     }
   } else if (expr.type === 'in') {
     collectColumnsFromExpr(expr.expr, columns, aliases)
+  } else if (expr.type === 'subscript') {
+    collectColumnsFromExpr(expr.expr, columns, aliases)
+    collectColumnsFromExpr(expr.index, columns, aliases)
   } else if (expr.type === 'case') {
     if (expr.caseExpr) {
       collectColumnsFromExpr(expr.caseExpr, columns, aliases)

package/src/plan/plan.js

@@ -637,6 +637,9 @@ function resolveAliases(node, aliases) {
     const values = node.values.map(v => resolveAliases(v, aliases))
     return { ...node, expr, values }
   }
+  if (node.type === 'subscript') {
+    return { ...node, expr: resolveAliases(node.expr, aliases), index: resolveAliases(node.index, aliases) }
+  }
   if (node.type === 'case') {
     const caseExpr = resolveAliases(node.caseExpr, aliases)
     const whenClauses = node.whenClauses.map(w => {
@@ -697,6 +700,13 @@ function normalizeIdentifiers(node, sourceColumns) {
       values: node.values.map(v => normalizeIdentifiers(v, sourceColumns)),
     }
   }
+  if (node.type === 'subscript') {
+    return {
+      ...node,
+      expr: normalizeIdentifiers(node.expr, sourceColumns),
+      index: normalizeIdentifiers(node.index, sourceColumns),
+    }
+  }
   if (node.type === 'case') {
     return {
       ...node,
@@ -872,6 +882,9 @@ function validateLateralSubqueries({ expr, ctePlans, cteColumns, tables, outerSc
     for (const val of expr.values) {
       validateLateralSubqueries({ expr: val, ctePlans, cteColumns, tables, outerScope })
     }
+  } else if (expr.type === 'subscript') {
+    validateLateralSubqueries({ expr: expr.expr, ctePlans, cteColumns, tables, outerScope })
+    validateLateralSubqueries({ expr: expr.index, ctePlans, cteColumns, tables, outerScope })
   } else if (expr.type === 'case') {
     validateLateralSubqueries({ expr: expr.caseExpr, ctePlans, cteColumns, tables, outerScope })
     for (const w of expr.whenClauses) {
@@ -930,6 +943,13 @@ function collectWindows(expr, windows) {
       values: expr.values.map(v => collectWindows(v, windows)),
     }
   }
+  if (expr.type === 'subscript') {
+    return {
+      ...expr,
+      expr: collectWindows(expr.expr, windows),
+      index: collectWindows(expr.index, windows),
+    }
+  }
   if (expr.type === 'case') {
     return {
       ...expr,
@@ -979,6 +999,7 @@ function findWindow(expr) {
     return undefined
   }
   if (expr.type === 'cast') return findWindow(expr.expr)
+  if (expr.type === 'subscript') return findWindow(expr.expr) || findWindow(expr.index)
   if (expr.type === 'in valuelist') {
     const found = findWindow(expr.expr)
     if (found) return found

package/src/types.d.ts

@@ -79,7 +79,7 @@ export interface AsyncDataSource {
   columns: string[]
   scan(options: ScanOptions): ScanResults
   // Optional method for fast column scans
-  scanColumn?(options: ScanColumnOptions): AsyncIterable<ArrayLike<SqlPrimitive>>
+  scanColumn?(options: ScanColumnOptions): AsyncIterable<ArrayLike<SqlPrimitive>> | ScanColumnResults
 }
 
 /**
@@ -113,11 +113,19 @@ export interface ScanOptions {
  */
 export interface ScanColumnOptions {
   column: string
+  where?: ExprNode
   limit?: number
   offset?: number
   signal?: AbortSignal
 }
 
+/** Result of a column scan, mirroring the ScanResults hint flags. */
+export interface ScanColumnResults {
+  chunks(): AsyncIterable<ArrayLike<SqlPrimitive>>
+  appliedWhere: boolean
+  appliedLimitOffset: boolean
+}
+
 export interface FunctionSignature {
   min: number
   max?: number
@@ -166,6 +174,7 @@ export type StringFunc =
   | 'LOWER'
   | 'CONCAT'
   | 'LENGTH'
+  | 'OCTET_LENGTH'
   | 'SUBSTRING'
   | 'SUBSTR'
   | 'TRIM'
@@ -175,6 +184,8 @@ export type StringFunc =
   | 'INSTR'
   | 'POSITION'
   | 'STRPOS'
+  | 'SPLIT_PART'
+  | 'STRING_SPLIT'
 
 export type SpatialFunc =
   | 'ST_INTERSECTS'

package/src/validation/aggregates.js

@@ -31,6 +31,9 @@ export function findAggregate(expr) {
   if (expr.type === 'cast') {
     return findAggregate(expr.expr)
   }
+  if (expr.type === 'subscript') {
+    return findAggregate(expr.expr) || findAggregate(expr.index)
+  }
   if (expr.type === 'case') {
     if (expr.caseExpr) {
       const found = findAggregate(expr.caseExpr)

package/src/validation/functions.js

@@ -86,7 +86,7 @@ export function isExtractField(name) {
  * @returns {name is CastType}
  */
 export function isCastType(name) {
-  return ['TEXT', 'STRING', 'VARCHAR', 'INTEGER', 'INT', 'BIGINT', 'FLOAT', 'REAL', 'DOUBLE', 'BOOLEAN', 'BOOL'].includes(name)
+  return ['TEXT', 'STRING', 'VARCHAR', 'INTEGER', 'INT', 'BIGINT', 'FLOAT', 'REAL', 'DOUBLE', 'BOOLEAN', 'BOOL', 'TIMESTAMP'].includes(name)
 }
 
 /**
@@ -95,8 +95,8 @@ export function isCastType(name) {
  */
 export function isStringFunc(name) {
   return [
-    'UPPER', 'LOWER', 'CONCAT', 'LENGTH', 'SUBSTRING', 'SUBSTR', 'TRIM',
-    'REPLACE', 'LEFT', 'RIGHT', 'INSTR', 'POSITION', 'STRPOS',
+    'UPPER', 'LOWER', 'CONCAT', 'LENGTH', 'OCTET_LENGTH', 'SUBSTRING', 'SUBSTR', 'TRIM',
+    'REPLACE', 'LEFT', 'RIGHT', 'INSTR', 'POSITION', 'STRPOS', 'SPLIT_PART', 'STRING_SPLIT',
   ].includes(name)
 }
 
@@ -117,6 +117,7 @@ export const FUNCTION_SIGNATURES = {
   UPPER: { min: 1, max: 1, signature: 'string' },
   LOWER: { min: 1, max: 1, signature: 'string' },
   LENGTH: { min: 1, max: 1, signature: 'string' },
+  OCTET_LENGTH: { min: 1, max: 1, signature: 'string' },
   TRIM: { min: 1, max: 1, signature: 'string' },
   REPLACE: { min: 3, max: 3, signature: 'string, search, replacement' },
   SUBSTRING: { min: 2, max: 3, signature: 'string, start[, length]' },
@@ -127,6 +128,8 @@ export const FUNCTION_SIGNATURES = {
   INSTR: { min: 2, max: 2, signature: 'string, substring' },
   POSITION: { min: 2, max: 2, signature: 'string, substring' },
   STRPOS: { min: 2, max: 2, signature: 'string, substring' },
+  SPLIT_PART: { min: 3, max: 3, signature: 'string, delimiter, index' },
+  STRING_SPLIT: { min: 2, max: 2, signature: 'string, delimiter' },
   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]]' },

package/src/validation/tables.js

@@ -90,6 +90,9 @@ export function validateNoIdentifiers(expr, context, outerScope) {
   } else if (expr.type === 'in') {
     // LHS is in our scope; subquery is self-contained and planned separately.
     validateNoIdentifiers(expr.expr, context, outerScope)
+  } else if (expr.type === 'subscript') {
+    validateNoIdentifiers(expr.expr, context, outerScope)
+    validateNoIdentifiers(expr.index, context, outerScope)
   } else if (expr.type === 'case') {
     validateNoIdentifiers(expr.caseExpr, context, outerScope)
     for (const w of expr.whenClauses) {
@@ -144,6 +147,9 @@ export function validateTableRefs(expr, tables, scopeColumns) {
     for (const val of expr.values) {
       validateTableRefs(val, tables, scopeColumns)
     }
+  } else if (expr.type === 'subscript') {
+    validateTableRefs(expr.expr, tables, scopeColumns)
+    validateTableRefs(expr.index, tables, scopeColumns)
   } else if (expr.type === 'case') {
     validateTableRefs(expr.caseExpr, tables, scopeColumns)
     for (const w of expr.whenClauses) {