squirreling 0.16.6 → 0.16.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "squirreling",
-  "version": "0.16.6",
+  "version": "0.16.8",
   "description": "Squirreling Async SQL Engine",
   "author": "Hyperparam",
   "homepage": "https://hyperparam.app",
@@ -40,12 +40,12 @@
   },
   "devDependencies": {
     "@eslint/js": "10.0.1",
-    "@types/node": "26.5.0",
-    "@vitest/coverage-v8": "5.0.1",
-    "eslint": "10.10.0",
-    "eslint-plugin-jsdoc": "64.5.2",
+    "@types/node": "26.6.3",
+    "@vitest/coverage-v8": "5.0.2",
+    "eslint": "10.11.0",
+    "eslint-plugin-jsdoc": "65.0.0",
     "globals": "17.12.0",
     "typescript": "7.0.2",
-    "vitest": "5.0.1"
+    "vitest": "5.0.2"
   }
 }

package/src/backend/batch.js

@@ -125,6 +125,7 @@ export function selectVector(vector, selection) {
     throw new Error(`Cannot select ${selection.length} rows from vector length ${vector.length}`)
   }
   if (selection.type === 'all') return vector
+  if (vector.type === 'constant') return { ...vector, length: selectedRowCount(selection) }
   if (vector.type === 'selected') {
     const composed = composeSelections(vector.selection, selection)
     return {

package/src/execute/aggregates.js

@@ -309,6 +309,9 @@ function tryColumnScanAggregate(plan, { tables, signal }) {
     specs.push(spec)
   }
 
+  // Prepared batches can count selected rows without decoding a physical column.
+  if (table.prepareScan && specs.every(spec => spec.funcName === 'COUNT' && spec.star)) return
+
   const physicalColumns = new Set(specs.map(spec => spec.column))
   const hasPushdown = where || limit !== undefined || offset !== undefined
   if (hasPushdown) {

package/src/execute/batches.js

@@ -238,12 +238,16 @@ function projectedBatchColumn(batch, columnIndex) {
 /**
  * @param {ColumnVector} predicate
  * @param {number} rowCount
- * @returns {{ selection: Extract<RowSelection, { type: 'indices' }>, selectedCount: number }}
+ * @returns {{ selection: RowSelection, selectedCount: number }}
  */
 function predicateSelection(predicate, rowCount) {
   if (predicate.length !== rowCount) {
     throw new Error(`Predicate returned ${predicate.length} rows, expected ${rowCount}`)
   }
+  if (predicate.type === 'constant') {
+    const selectedCount = predicate.value ? rowCount : 0
+    return { selection: { type: 'range', start: 0, end: selectedCount, length: rowCount }, selectedCount }
+  }
   const indices = new Uint32Array(rowCount)
   let selectedCount = 0
   for (let rowIndex = 0; rowIndex < rowCount; rowIndex++) {

package/src/execute/execute.js

@@ -21,7 +21,7 @@ import { yieldToEventLoop } from './yield.js'
 
 /**
  * @import { BatchProjection, CompiledBatchExpression } from '../internalTypes.js'
- * @import { AsyncBatch, AsyncCells, AsyncDataSource, AsyncRow, ColumnDemand, ColumnVector, DerivedColumn, ExecuteContext, ExecuteSqlOptions, ExprNode, IdentifierNode, PreparedScan, QueryResults, RelationSchema, ScanRequest, SelectColumn, SqlPrimitive, Statement } from '../types.js'
+ * @import { AsyncBatch, AsyncCells, AsyncDataSource, AsyncRow, ColumnDemand, ColumnVector, DerivedColumn, ExecuteContext, ExecuteSqlOptions, ExprNode, IdentifierNode, NumericArray, PreparedScan, QueryResults, RelationSchema, ScanColumnResults, ScanRequest, ScanTopK, SelectColumn, SqlPrimitive, Statement } from '../types.js'
  * @import { CountNode, DistinctNode, FilterNode, LimitNode, ProjectNode, QueryPlan, ScanNode, SetOperationNode, TableFunctionNode } from '../plan/types.js'
  */
 
@@ -277,7 +277,7 @@ export function selectColumnNames(selectColumns, childColumns) {
 /**
  * @param {ScanNode} plan
  * @param {ExecuteContext} context
- * @param {import('../types.js').ScanColumnResults} [existingColumnResult]
+ * @param {ScanColumnResults} [existingColumnResult]
  * @returns {QueryResults}
  */
 export function executeScan(plan, context, existingColumnResult) {
@@ -539,12 +539,27 @@ function scanRequest(plan, schema, context) {
       mode: predicate ? 'required' : 'deferred',
     }
   })
-  return {
+  /** @type {ScanRequest} */
+  const request = {
     columns,
     filter: plan.hints.where,
     limit: plan.hints.limit,
     offset: plan.hints.offset,
   }
+  if (plan.topK) {
+    /** @type {ScanTopK['orderBy'][number][]} */
+    const orderBy = []
+    for (const term of plan.topK.orderBy) {
+      const { expr } = term
+      if (expr.type !== 'identifier' ||
+          expr.prefix && expr.prefix !== (plan.alias ?? plan.table)) return request
+      const field = schema.fields.find(field => field.name === expr.name)
+      if (!field) return request
+      orderBy.push({ field: field.id, direction: term.direction, nulls: term.nulls ?? 'FIRST' })
+    }
+    if (orderBy.length) request.topK = { orderBy, limit: plan.topK.limit }
+  }
+  return request
 }
 
 /**
@@ -1016,7 +1031,7 @@ function vectorFromChunk(chunk) {
 
 /**
  * @param {ArrayLike<SqlPrimitive>} values
- * @returns {values is import('../types.js').NumericArray}
+ * @returns {values is NumericArray}
  */
 function isNumericArray(values) {
   return values instanceof Int8Array

package/src/execute/sort.js

@@ -128,8 +128,16 @@ export async function sortEntriesByTerms({ entries, orderBy, context, cacheValue
  * @returns {QueryResults}
  */
 export function executeSort(plan, context) {
-  const child = executePlan({ plan: plan.child, context })
   const { topK } = plan
+  let childPlan = plan.child
+  // Only a directly adjacent scan can prune candidates for this sort. Never
+  // cross filters, joins, aggregates or windows, or change an existing scan
+  // slice. Copy the node: CTE plans can be shared by other consumers.
+  if (Number.isSafeInteger(topK) && topK > 0 && childPlan.type === 'Scan' &&
+      childPlan.hints.limit === undefined && !childPlan.hints.offset) {
+    childPlan = { ...childPlan, topK: { orderBy: plan.orderBy, limit: topK } }
+  }
+  const child = executePlan({ plan: childPlan, context })
   // With a LIMIT bound pushed into the sort, keep at most this many buffered
   // rows: periodically sort and discard everything past topK, so memory is
   // bounded by the limit instead of the input size.

package/src/execute/streamingAggregate.js

@@ -523,6 +523,25 @@ async function accumulateBatch({ batch, inputs, specs, groups, context, rowOffse
     evaluateBatchInputs(inputs.args, batch, context, rowOffset),
   ])
   const rowCount = selectedRowCount(batch.selection)
+  context.signal?.throwIfAborted()
+  if (rowCount > 0 && keys.every(vector => vector?.type === 'constant') &&
+      specs.every(spec => spec.star && spec.funcName === 'COUNT' && !spec.node.distinct && !spec.node.filter)) {
+    const keyValues = keys.map(vector => valueAt(/** @type {ColumnVector} */ vector, 0))
+    const key = keyValues.length === 0
+      ? true
+      : keyValues.length === 1 ? keyify(keyValues[0]) : keyify(...keyValues)
+    let group = groups.get(key)
+    if (!group) {
+      group = {
+        firstRow: undefined,
+        keyValues,
+        accumulators: specs.map(spec => newAccumulator(spec.funcName, spec.node.distinct)),
+      }
+      groups.set(key, group)
+    }
+    for (const accumulator of group.accumulators) accumulator.count += rowCount
+    return
+  }
   for (let rowIndex = 0; rowIndex < rowCount; rowIndex++) {
     if (rowIndex > 0 && rowIndex % CHUNK_SIZE === 0) {
       await yieldToEventLoop()

package/src/expression/batch.js

@@ -626,6 +626,13 @@ function resolveIdentifier(identifier, columns) {
  */
 function evaluateKernel(kernel, vectors, selection, signal, rowOffset = 0, rowOrdinals) {
   const length = selectedRowCount(selection)
+  // Supported kernels are deterministic; streamRowIndex only labels errors.
+  // Empty selections must not evaluate expressions (including invalid casts).
+  if (length > 0 && vectors.every(vector => vector.type === 'constant')) {
+    signal?.throwIfAborted()
+    const ordinal = rowOrdinals ? Number(valueAt(rowOrdinals, 0)) : 0
+    return { type: 'constant', value: kernel(vectors, 0, rowOffset + ordinal), length }
+  }
   if (signal && length > YIELD_INTERVAL) {
     return evaluateKernelAsync(kernel, vectors, length, signal, rowOffset, rowOrdinals)
   }

package/src/index.d.ts

@@ -30,6 +30,7 @@ export type {
   ScanOptions,
   ScanProperties,
   ScanRequest,
+  ScanTopK,
   ScanResidual,
   ScanResults,
   SelectStatement,

package/src/plan/types.d.ts

@@ -25,6 +25,9 @@ export interface ScanNode {
   table: string
   alias?: string
   hints: ScanOptions
+  // Execution-local hint from an immediately enclosing bounded Sort. Kept
+  // separate from scan LIMIT/OFFSET, which select an unordered input slice.
+  topK?: { orderBy: OrderByItem[], limit: number }
 }
 
 // Source for FROM-less SELECT like `SELECT 1`. Yields exactly one empty row.

package/src/types.d.ts

@@ -126,8 +126,25 @@ export interface ColumnDemand {
   mode: 'required' | 'deferred'
 }
 
+/**
+ * Optional candidate-pruning hint for an ordered slice. A source may ignore
+ * it, or omit rows proven unable to enter the first `limit` rows after the
+ * scan's filter. Preserve all boundary ties and the relative input order of
+ * retained rows. Return an unordered superset of the winners, not an arbitrary
+ * `limit` rows. The engine retains the final sort and slice.
+ */
+export interface ScanTopK {
+  orderBy: readonly {
+    field: number
+    direction: 'ASC' | 'DESC'
+    nulls: 'FIRST' | 'LAST'
+  }[]
+  limit: number // Includes the outer OFFSET.
+}
+
 export interface ScanRequest {
   columns: readonly ColumnDemand[]
+  topK?: ScanTopK
   filter?: ExprNode
   limit?: number
   offset?: number