squirreling 0.16.6 → 0.16.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "squirreling",
-  "version": "0.16.6",
+  "version": "0.16.7",
   "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.2",
+    "@vitest/coverage-v8": "5.0.2",
+    "eslint": "10.11.0",
+    "eslint-plugin-jsdoc": "64.5.4",
     "globals": "17.12.0",
     "typescript": "7.0.2",
-    "vitest": "5.0.1"
+    "vitest": "5.0.2"
   }
 }

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/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