squirreling 0.15.1 → 0.15.3

package/README.md

@@ -146,7 +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
 - Set operations: `UNION`, `UNION ALL`, `INTERSECT`, `INTERSECT ALL`, `EXCEPT`, `EXCEPT ALL`
-- Expressions: `CASE`, `CAST`, `BETWEEN`, `IN`, `LIKE`, `IS NULL`, `IS NOT NULL`, string concatenation `||`
+- 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`
 
 ### Quoting
@@ -157,16 +157,16 @@ Squirreling mostly follows the SQL standard. The following features are supporte
 
 ### Functions
 
-- Aggregate: `COUNT`, `COUNTIF`, `SUM`, `AVG`, `MIN`, `MAX`, `MEDIAN`, `PERCENTILE_CONT`, `APPROX_QUANTILE`, `STDDEV_POP`, `STDDEV_SAMP`, `ARRAY_AGG`, `JSON_ARRAYAGG`, `STRING_AGG`
+- Aggregate: `COUNT`, `COUNTIF`, `SUM`, `AVG`, `MIN`, `MAX`, `MIN_BY`, `MAX_BY`, `ANY_VALUE`, `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`, `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`
-- Json: `JSON_VALUE`, `JSON_QUERY`, `JSON_EXTRACT`, `JSON_OBJECT`, `JSON_ARRAY_LENGTH`, `JSON_VALID`, `JSON_TYPE`, `JSON_KEYS`
+- Json: `JSON_VALUE`, `JSON_QUERY`, `JSON_EXTRACT`, `JSON_EXTRACT_STRING`, `JSON_OBJECT`, `JSON_ARRAY_LENGTH`, `JSON_VALID`, `JSON_TYPE`, `JSON_KEYS`
 - Array: `ARRAY_LENGTH`, `ARRAY_POSITION`, `ARRAY_CONTAINS`, `ARRAY_SORT`, `ARRAY_APPEND`, `ARRAY_CONCAT`, `LEN`, `CARDINALITY`, `SIZE`
 - Table functions: `UNNEST`, `EXPLODE`, `JSON_EACH`
-- Regex: `REGEXP_SUBSTR`, `REGEXP_EXTRACT`, `REGEXP_REPLACE`, `REGEXP_MATCHES`
+- Regex: `REGEXP_SUBSTR`, `REGEXP_EXTRACT`, `REGEXP_REPLACE`, `REGEXP_MATCHES`, `REGEXP_LIKE`
 - Spatial: `ST_GeomFromText`, `ST_MakeEnvelope`, `ST_AsText`, `ST_Intersects`, `ST_Contains`, `ST_ContainsProperly`, `ST_Within`, `ST_Overlaps`, `ST_Touches`, `ST_Equals`, `ST_Crosses`, `ST_Covers`, `ST_CoveredBy`, `ST_DWithin`
 - Conditional: `COALESCE`, `NULLIF`, `GREATEST`, `LEAST`
 - User-defined functions (UDFs)

package/package.json

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

package/src/ast.d.ts

@@ -120,6 +120,8 @@ export interface CastNode extends AstBase {
   type: 'cast'
   expr: ExprNode
   toType: CastType
+  /** TRY_CAST returns null instead of throwing when the value cannot be cast */
+  tryCast?: boolean
 }
 
 export interface InSubqueryNode extends AstBase {

package/src/expression/binary.js

@@ -29,12 +29,25 @@ export function applyBinaryOp(op, a, b) {
     return String(a) + String(b)
   }
 
-  // Comparison and logical operators
-  if (a == null || b == null) {
+  // Logical operators use Kleene three-valued logic: null is UNKNOWN, which
+  // only resolves when the other operand decides the answer on its own
+  if (op === 'AND') {
+    if (a != null && !a || b != null && !b) return false
+    if (a == null || b == null) return null
+    return true
+  }
+  if (op === 'OR') {
+    if (a != null && Boolean(a) || b != null && Boolean(b)) return true
+    if (a == null || b == null) return null
     return false
   }
-  if (op === 'AND') return Boolean(a) && Boolean(b)
-  if (op === 'OR') return Boolean(a) || Boolean(b)
+
+  // A comparison with a null operand is UNKNOWN, not false. The difference is
+  // invisible to a WHERE (both exclude the row) but not to a NOT above it,
+  // which must keep UNKNOWN as UNKNOWN rather than flip false to true
+  if (a == null || b == null) {
+    return null
+  }
   // Compare Date values by their time so distinct instances for the same
   // instant are equal, matching SQL TIMESTAMP semantics rather than JS identity.
   if (a instanceof Date && b instanceof Date) {

package/src/expression/evaluate.js

@@ -167,7 +167,9 @@ export async function evaluateExpr({ node, row, rowIndex, rows, context }) {
       if (val == null) return null
       return -val
     }
-    if (node.op === 'NOT') return !val
+    // NOT UNKNOWN is UNKNOWN: JS ! would flip null to true and return rows
+    // SQL excludes, e.g. WHERE NOT (nullable < 300)
+    if (node.op === 'NOT') return val == null ? null : !val
     if (node.op === 'IS NULL') return val == null
     if (node.op === 'IS NOT NULL') return val != null
   }
@@ -186,9 +188,11 @@ export async function evaluateExpr({ node, row, rowIndex, rows, context }) {
 
     const left = await evaluateExpr({ node: node.left, row, rowIndex, rows, context })
 
-    // Short-circuit evaluation for AND and OR
-    if (node.op === 'AND' && !left) return false
-    if (node.op === 'OR' && left) return true
+    // Short-circuit evaluation for AND and OR. A null left cannot
+    // short-circuit AND: NULL AND FALSE is false but NULL AND TRUE is null,
+    // so the right side decides
+    if (node.op === 'AND' && left != null && !left) return false
+    if (node.op === 'OR' && left != null && Boolean(left)) return true
 
     const right = await evaluateExpr({ node: node.right, row, rowIndex, rows, context })
     return applyBinaryOp(node.op, left, right)
@@ -289,6 +293,37 @@ export async function evaluateExpr({ node, row, rowIndex, rows, context }) {
         if (funcName === 'MAX') return max
       }
 
+      if (funcName === 'MIN_BY' || funcName === 'ARG_MIN' || funcName === 'MAX_BY' || funcName === 'ARG_MAX') {
+        // Returns the value at the row with the smallest (or largest) key.
+        // Rows with a null value or key are ignored, and ties keep the first row.
+        const isMin = funcName === 'MIN_BY' || funcName === 'ARG_MIN'
+        const values = await evaluateAll(argNode, filteredRows, context)
+        const keys = await evaluateAll(node.args[1], filteredRows, context)
+        /** @type {SqlPrimitive} */
+        let best = null
+        /** @type {SqlPrimitive} */
+        let bestKey = null
+        for (let i = 0; i < values.length; i++) {
+          const value = values[i]
+          const key = keys[i]
+          if (value == null || key == null) continue
+          if (bestKey === null || (isMin ? key < bestKey : key > bestKey)) {
+            best = value
+            bestKey = key
+          }
+        }
+        return best
+      }
+
+      if (funcName === 'ANY_VALUE') {
+        // Returns an arbitrary non-null value from the group; we pick the first
+        const values = await evaluateAll(argNode, filteredRows, context)
+        for (const v of values) {
+          if (v != null) return v
+        }
+        return null
+      }
+
       if (funcName === 'STDDEV_SAMP' || funcName === 'STDDEV_POP') {
         const rawValues = await evaluateAll(argNode, filteredRows, context)
         let sum = 0
@@ -633,7 +668,7 @@ export async function evaluateExpr({ node, row, rowIndex, rows, context }) {
       })
     }
 
-    if (funcName === 'JSON_VALUE' || funcName === 'JSON_QUERY' || funcName === 'JSON_EXTRACT') {
+    if (funcName === 'JSON_VALUE' || funcName === 'JSON_QUERY' || funcName === 'JSON_EXTRACT' || funcName === 'JSON_EXTRACT_STRING') {
       let jsonArg = args[0]
       const pathArg = args[1]
       if (jsonArg == null || pathArg == null) return null
@@ -682,6 +717,11 @@ export async function evaluateExpr({ node, row, rowIndex, rows, context }) {
       }
 
       if (current == null) return null
+      // JSON_EXTRACT_STRING returns text: unquoted scalars, JSON text for objects and arrays
+      if (funcName === 'JSON_EXTRACT_STRING') {
+        if (typeof current === 'object') return JSON.stringify(current)
+        return String(current)
+      }
       return current
     }
 
@@ -707,6 +747,7 @@ export async function evaluateExpr({ node, row, rowIndex, rows, context }) {
     }
     // Can only cast primitives (and Dates) to other primitive types
     if (typeof val === 'object' && !(val instanceof Date)) {
+      if (node.tryCast) return null
       throw new ExecutionError({ message: `Cannot CAST object to ${toType}`, rowIndex, ...node })
     }
     if (toType === 'INTEGER' || toType === 'INT') {
@@ -717,7 +758,8 @@ export async function evaluateExpr({ node, row, rowIndex, rows, context }) {
     if (toType === 'BIGINT') {
       if (typeof val === 'bigint') return val
       const num = Number(val)
-      if (isNaN(num)) return null
+      // NaN and Infinity have no bigint representation
+      if (!isFinite(num)) return null
       return BigInt(Math.trunc(num))
     }
     if (toType === 'FLOAT' || toType === 'REAL' || toType === 'DOUBLE') {
@@ -738,19 +780,28 @@ export async function evaluateExpr({ node, row, rowIndex, rows, context }) {
     }
   }
 
-  // IN and NOT IN with value lists
+  // IN and NOT IN with value lists. IN is a chain of OR'd equalities, so it
+  // inherits their three-valued logic: a null on either side of any equality
+  // makes a non-match UNKNOWN rather than false, and NOT above it must not
+  // turn that into true
   if (node.type === 'in valuelist') {
     const exprVal = await evaluateExpr({ node: node.expr, row, rowIndex, rows, context })
+    let sawNull = exprVal == null
     for (const valueNode of node.values) {
       const val = await evaluateExpr({ node: valueNode, row, rowIndex, rows, context })
-      if (sqlEquals(exprVal, val)) return true
+      if (val == null) {
+        sawNull = true
+      } else if (exprVal != null && sqlEquals(exprVal, val)) {
+        return true
+      }
     }
-    return false
+    return sawNull ? null : false
   }
-  // IN with subqueries
+  // IN with subqueries, same three-valued logic as the value-list form
   if (node.type === 'in') {
     const exprVal = await evaluateExpr({ node: node.expr, row, rowIndex, rows, context })
     const subResult = executeStatement({ query: node.subquery, context })
+    let sawNull = false
     let innerCount = 0
     for await (const resRow of subResult.rows()) {
       if (++innerCount % YIELD_INTERVAL === 0) {
@@ -758,9 +809,13 @@ export async function evaluateExpr({ node, row, rowIndex, rows, context }) {
         context.signal?.throwIfAborted()
       }
       const value = await resRow.cells[resRow.columns[0]]()
-      if (sqlEquals(exprVal, value)) return true
+      if (exprVal == null || value == null) {
+        sawNull = true
+      } else if (exprVal != null && sqlEquals(exprVal, value)) {
+        return true
+      }
     }
-    return false
+    return sawNull ? null : false
   }
 
   // EXISTS and NOT EXISTS with subqueries

package/src/expression/regexp.js

@@ -78,7 +78,7 @@ export function evaluateRegexpFunc({ funcName, node, args, rowIndex }) {
     return null
   }
 
-  if (funcName === 'REGEXP_MATCHES') {
+  if (funcName === 'REGEXP_MATCHES' || funcName === 'REGEXP_LIKE') {
     const str = args[0]
     const pattern = args[1]
     if (str == null || pattern == null) return null

package/src/parse/primary.js

@@ -125,8 +125,8 @@ function parsePrimaryBase(state) {
     const next = peekToken(state, 1)
     const funcNameUpper = tok.value.toUpperCase()
 
-    // CAST(expr AS type)
-    if (funcNameUpper === 'CAST' && next.type === 'paren' && next.value === '(') {
+    // CAST(expr AS type) and TRY_CAST(expr AS type)
+    if ((funcNameUpper === 'CAST' || funcNameUpper === 'TRY_CAST') && next.type === 'paren' && next.value === '(') {
       consume(state) // CAST
       consume(state) // '('
       const expr = parseExpression(state)
@@ -145,6 +145,7 @@ function parsePrimaryBase(state) {
         type: 'cast',
         expr,
         toType,
+        tryCast: funcNameUpper === 'TRY_CAST' ? true : undefined,
         positionStart,
         positionEnd: state.lastPos,
       }

package/src/types.d.ts

@@ -137,9 +137,9 @@ export interface UserDefinedFunction {
   arguments: FunctionSignature
 }
 
-export type AggregateFunc = 'COUNT' | 'COUNTIF' | 'SUM' | 'AVG' | 'MIN' | 'MAX' | 'ARRAY_AGG' | 'LIST' | 'JSON_ARRAYAGG' | 'STDDEV_SAMP' | 'STDDEV_POP' | 'MEDIAN' | 'PERCENTILE_CONT' | 'APPROX_QUANTILE' | 'STRING_AGG'
+export type AggregateFunc = 'COUNT' | 'COUNTIF' | 'SUM' | 'AVG' | 'MIN' | 'MAX' | 'MIN_BY' | 'ARG_MIN' | 'MAX_BY' | 'ARG_MAX' | 'ANY_VALUE' | 'ARRAY_AGG' | 'LIST' | 'JSON_ARRAYAGG' | 'STDDEV_SAMP' | 'STDDEV_POP' | 'MEDIAN' | 'PERCENTILE_CONT' | 'APPROX_QUANTILE' | 'STRING_AGG'
 
-export type RegExpFunction = 'REGEXP_SUBSTR' | 'REGEXP_EXTRACT' | 'REGEXP_REPLACE' | 'REGEXP_MATCHES'
+export type RegExpFunction = 'REGEXP_SUBSTR' | 'REGEXP_EXTRACT' | 'REGEXP_REPLACE' | 'REGEXP_MATCHES' | 'REGEXP_LIKE'
 
 export type MathFunc =
   | 'FLOOR'

package/src/validation/functions.js

@@ -11,7 +11,7 @@ export const niladicFuncs = ['CURRENT_DATE', 'CURRENT_TIME', 'CURRENT_TIMESTAMP'
  * @returns {name is AggregateFunc}
  */
 export function isAggregateFunc(name) {
-  return ['COUNT', 'COUNTIF', 'SUM', 'AVG', 'MIN', 'MAX', 'ARRAY_AGG', 'LIST', 'JSON_ARRAYAGG', 'STDDEV_SAMP', 'STDDEV_POP', 'MEDIAN', 'PERCENTILE_CONT', 'APPROX_QUANTILE', 'STRING_AGG'].includes(name)
+  return ['COUNT', 'COUNTIF', 'SUM', 'AVG', 'MIN', 'MAX', 'MIN_BY', 'ARG_MIN', 'MAX_BY', 'ARG_MAX', 'ANY_VALUE', 'ARRAY_AGG', 'LIST', 'JSON_ARRAYAGG', 'STDDEV_SAMP', 'STDDEV_POP', 'MEDIAN', 'PERCENTILE_CONT', 'APPROX_QUANTILE', 'STRING_AGG'].includes(name)
 }
 
 /**
@@ -39,7 +39,7 @@ export function isWindowFunc(name) {
  * @returns {name is RegExpFunction}
  */
 export function isRegexpFunc(name) {
-  return ['REGEXP_SUBSTR', 'REGEXP_EXTRACT', 'REGEXP_REPLACE', 'REGEXP_MATCHES'].includes(name)
+  return ['REGEXP_SUBSTR', 'REGEXP_EXTRACT', 'REGEXP_REPLACE', 'REGEXP_MATCHES', 'REGEXP_LIKE'].includes(name)
 }
 
 /**
@@ -134,6 +134,7 @@ export const FUNCTION_SIGNATURES = {
   REGEXP_EXTRACT: { min: 2, max: 4, signature: 'string, pattern[, position[, occurrence]]' },
   REGEXP_REPLACE: { min: 3, max: 5, signature: 'string, pattern, replacement[, position[, occurrence]]' },
   REGEXP_MATCHES: { min: 2, max: 2, signature: 'string, pattern' },
+  REGEXP_LIKE: { min: 2, max: 2, signature: 'string, pattern' },
 
   // Date/time functions
   RANDOM: { min: 0, max: 0, signature: '' },
@@ -178,6 +179,7 @@ export const FUNCTION_SIGNATURES = {
   JSON_VALUE: { min: 2, max: 2, signature: 'expression, path' },
   JSON_QUERY: { min: 2, max: 2, signature: 'expression, path' },
   JSON_EXTRACT: { min: 2, max: 2, signature: 'expression, path' },
+  JSON_EXTRACT_STRING: { min: 2, max: 2, signature: 'expression, path' },
   JSON_OBJECT: { min: 0, signature: 'key1, value1[, ...]' },
   JSON_ARRAY_LENGTH: { min: 1, max: 1, signature: 'array' },
   JSON_VALID: { min: 1, max: 1, signature: 'value' },
@@ -221,6 +223,11 @@ export const FUNCTION_SIGNATURES = {
   AVG: { min: 1, max: 1, signature: 'expression' },
   MIN: { min: 1, max: 1, signature: 'expression' },
   MAX: { min: 1, max: 1, signature: 'expression' },
+  MIN_BY: { min: 2, max: 2, signature: 'value, key' },
+  ARG_MIN: { min: 2, max: 2, signature: 'value, key' },
+  MAX_BY: { min: 2, max: 2, signature: 'value, key' },
+  ARG_MAX: { min: 2, max: 2, signature: 'value, key' },
+  ANY_VALUE: { min: 1, max: 1, signature: 'expression' },
   STDDEV_SAMP: { min: 1, max: 1, signature: 'expression' },
   STDDEV_POP: { min: 1, max: 1, signature: 'expression' },
   MEDIAN: { min: 1, max: 1, signature: 'expression' },