squirreling 0.16.7 → 0.16.9

package/README.md

@@ -12,7 +12,7 @@
 
 Squirreling is a streaming async SQL engine in pure JavaScript. Built for the browser from the ground up: streaming input and output, pluggable data sources, and lazy async cell evaluation. This makes Squirreling ideal for querying data from network sources, APIs, or LLMs where latency and cost matter.
 
-> Part of **[HypStack](https://hypstack.ai/)**, an open-source stack for AI observability.
+> Powers **[HypAware](https://hypaware.ai/?utm_source=github-readme)**, the improvement loop for all your agents.
 
 - **Standard SQL**: Full SQL support for querying data (read-only)
 - **Async UDFs**: User-defined functions can call APIs or models
@@ -146,6 +146,7 @@ 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, including `GROUP BY ALL`
 - Set operations: `UNION`, `UNION ALL`, `INTERSECT`, `INTERSECT ALL`, `EXCEPT`, `EXCEPT ALL`
+- `SHOW TABLES` to list the available tables
 - Expressions: `CASE`, `CAST`, `TRY_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`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "squirreling",
-  "version": "0.16.7",
+  "version": "0.16.9",
   "description": "Squirreling Async SQL Engine",
   "author": "Hyperparam",
   "homepage": "https://hyperparam.app",
@@ -40,12 +40,12 @@
   },
   "devDependencies": {
     "@eslint/js": "10.0.1",
-    "@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",
+    "@types/node": "26.6.5",
+    "@vitest/coverage-v8": "5.0.4",
+    "eslint": "10.12.0",
+    "eslint-plugin-jsdoc": "65.3.4",
+    "globals": "17.13.0",
     "typescript": "7.0.2",
-    "vitest": "5.0.2"
+    "vitest": "5.0.4"
   }
 }

package/src/ast.d.ts

@@ -41,7 +41,12 @@ export interface WithStatement extends AstBase {
   query: Statement
 }
 
-export type Statement = SelectStatement | SetOperationStatement | WithStatement
+// SHOW TABLES statement: lists the names of the available tables
+export interface ShowTablesStatement extends AstBase {
+  type: 'show tables'
+}
+
+export type Statement = SelectStatement | SetOperationStatement | WithStatement | ShowTablesStatement
 
 export interface CTEDefinition extends AstBase {
   name: string

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

@@ -37,6 +37,9 @@ const YIELD_INTERVAL = 4000
 export function executeSql({ tables, query, functions, signal }) {
   const parsed = typeof query === 'string' ? parseSql({ query, functions }) : query
 
+  // Listing names does not require table contents or inferred schemas.
+  if (parsed.type === 'show tables') return executeShowTables({ tables, signal })
+
   // Normalize tables: convert arrays to AsyncDataSource
   /** @type {Record<string, AsyncDataSource>} */
   const normalizedTables = {}
@@ -97,6 +100,8 @@ export function executePlan({ plan, context }) {
     return executeScan(plan, context)
   } else if (plan.type === 'SingleRow') {
     return executeSingleRow()
+  } else if (plan.type === 'ShowTables') {
+    return executeShowTables(context)
   } else if (plan.type === 'Count') {
     return executeCount(plan, context)
   } else if (plan.type === 'Filter') {
@@ -148,6 +153,31 @@ function executeSingleRow() {
   }
 }
 
+/**
+ * Executes SHOW TABLES: yields one row per available table name, sorted.
+ *
+ * @param {Pick<ExecuteSqlOptions, 'tables' | 'signal'>} context
+ * @returns {QueryResults}
+ */
+function executeShowTables(context) {
+  const columns = ['name']
+  const names = Object.keys(context.tables).sort()
+  return {
+    columns,
+    numRows: names.length,
+    maxRows: names.length,
+    async *rows() {
+      for (const name of names) {
+        context.signal?.throwIfAborted()
+        yield {
+          columns,
+          cells: { name: () => Promise.resolve(name) },
+        }
+      }
+    },
+  }
+}
+
 /**
  * Executes a table-valued function (e.g. UNNEST, JSON_EACH).
  * Evaluates the argument once against the outer row (for lateral joins) or an

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

@@ -35,6 +35,7 @@ export type {
   ScanResults,
   SelectStatement,
   SetOperationStatement,
+  ShowTablesStatement,
   SqlType,
   SqlPrimitive,
   Statement,

package/src/parse/extractTables.js

@@ -46,6 +46,10 @@ function walkStatement(stmt, cteScope, refs) {
     for (const o of stmt.orderBy) walkExpr(o.expr, cteScope, refs)
     return
   }
+  if (stmt.type === 'show tables') {
+    // SHOW TABLES references no source tables
+    return
+  }
   // select
   if (!stmt.from) {
     // FROM-less SELECT (e.g. `SELECT 1`), no source tables

package/src/parse/parse.js

@@ -47,6 +47,17 @@ export function parseSql({ query, functions }) {
  */
 export function parseStatement(state) {
   const positionStart = state.lastPos
+  const showTok = current(state)
+  if (showTok.type === 'identifier' && showTok.value.toUpperCase() === 'SHOW') {
+    consume(state)
+    const tok = current(state)
+    if (tok.type !== 'identifier' || tok.value.toUpperCase() !== 'TABLES') {
+      throw parseError(state, 'TABLES')
+    }
+    consume(state)
+    match(state, 'semicolon')
+    return { type: 'show tables', positionStart: showTok.positionStart, positionEnd: state.lastPos }
+  }
   if (match(state, 'keyword', 'WITH')) {
     const recursiveTok = current(state)
     if (recursiveTok.type === 'identifier' && recursiveTok.value.toUpperCase() === 'RECURSIVE') {

package/src/plan/columns.js

@@ -40,7 +40,7 @@ export function fromAlias(from) {
  */
 export function statementScope(stmt) {
   if (stmt.type === 'with') return statementScope(stmt.query)
-  if (stmt.type === 'compound') return undefined
+  if (stmt.type === 'compound' || stmt.type === 'show tables') return undefined
   const alias = fromAlias(stmt.from)
   const joins = stmt.joins.map(j => j.alias ?? j.table)
   return alias === undefined ? joins : [alias, ...joins]
@@ -329,6 +329,7 @@ export function collectColumnsFromExpr(expr, columns, aliases, context) {
  * @param {ColumnCollectionContext} [context]
  */
 function collectCorrelatedColumnsFromStatement(stmt, columns, context) {
+  if (stmt.type === 'show tables') return
   if (stmt.type === 'compound') {
     collectCorrelatedColumnsFromStatement(stmt.left, columns, context)
     collectCorrelatedColumnsFromStatement(stmt.right, columns, context)
@@ -386,6 +387,7 @@ function collectCorrelatedColumnsFromStatement(stmt, columns, context) {
  * @param {ColumnCollectionContext} [context]
  */
 function collectFromFunctionArgs(stmt, columns, context) {
+  if (stmt.type === 'show tables') return
   if (stmt.type === 'compound') {
     collectFromFunctionArgs(stmt.left, columns, context)
     collectFromFunctionArgs(stmt.right, columns, context)
@@ -414,6 +416,9 @@ function collectFromFunctionArgs(stmt, columns, context) {
  * @returns {string[]}
  */
 export function inferStatementColumns({ stmt, cteColumns, tables }) {
+  if (stmt.type === 'show tables') {
+    return ['name']
+  }
   if (stmt.type === 'with') {
     return inferStatementColumns({ stmt: stmt.query, cteColumns, tables })
   }

package/src/plan/plan.js

@@ -38,6 +38,9 @@ export function planSql({ query, functions, tables, ctePlans, cteColumns }) {
  * @returns {QueryPlan}
  */
 export function planStatement({ stmt, ctePlans, cteColumns, tables, parentColumns, outerScope }) {
+  if (stmt.type === 'show tables') {
+    return { type: 'ShowTables' }
+  }
   if (stmt.type === 'with') {
     // Build CTE plans in order (each CTE can reference preceding CTEs)
     ctePlans ??= new Map()

package/src/plan/types.d.ts

@@ -15,6 +15,7 @@ export type QueryPlan =
   | NestedLoopJoinNode
   | PositionalJoinNode
   | SetOperationNode
+  | ShowTablesNode
   | SubqueryNode
   | TableFunctionNode
   | WindowNode
@@ -35,6 +36,11 @@ export interface SingleRowNode {
   type: 'SingleRow'
 }
 
+// SHOW TABLES: yields one row per available table name
+export interface ShowTablesNode {
+  type: 'ShowTables'
+}
+
 // Count node for COUNT(*) optimization
 export interface CountNode {
   type: 'Count'