lakeql 0.1.2 → 0.1.8

package/dist/bin.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
-import { __commonJS, __toESM, LaQLError, readParquetMetadata, createParquetLake, memoryStore, writePartitionedParquet, matches, broadcastJoin, createOutputManifest, partitionedParquetOutputEntries, fingerprint, writeOutputManifest, evaluate } from './chunk-D3A4VN3U.js';
+import { createParquetLake, readParquetMetadata, memoryStore, writePartitionedParquet, broadcastJoin, createOutputManifest, partitionedParquetOutputEntries, fingerprint, writeOutputManifest } from './chunk-MXGEAVHL.js';
+import { __commonJS, __toESM, LakeqlError, matches, evaluate, isTimestampValue } from './chunk-TFD5RFKB.js';
 import { readFile, mkdir, writeFile } from 'fs/promises';
 import { dirname } from 'path';
 
@@ -7292,7 +7293,7 @@ var require_pgsql_ast_parser = __commonJS({
 var import_pgsql_ast_parser = __toESM(require_pgsql_ast_parser(), 1);
 var MAX_SQL_LENGTH = 128e3;
 var MAX_AST_DEPTH = 128;
-function parseSql(sql) {
+function parseSql(sql, options = {}) {
   if (sql.length > MAX_SQL_LENGTH) {
     throwParse(`SQL input length exceeds ${MAX_SQL_LENGTH}`);
   }
@@ -7308,13 +7309,37 @@ function parseSql(sql) {
     throwUnsupported("Only one SELECT statement is supported");
   const statement = asNode(statements[0], "statement");
   assertAstDepth(statement);
+  const context = newSqlParseContext(options);
   if (statement.type === "with")
-    return withStatementToAst(statement);
+    return withStatementToAst(statement, context);
   if (statement.type !== "select")
     throwUnsupported("Only SELECT statements are supported");
-  return selectStatementToAst(statement);
+  return selectStatementToAst(statement, context);
 }
-function withStatementToAst(statement) {
+function parseSqlStatement(sql, options = {}) {
+  const describe = parseDescribeStatement(sql);
+  if (describe !== void 0)
+    return describe;
+  return parseSql(sql, options);
+}
+function parseDescribeStatement(sql) {
+  if (sql.length > MAX_SQL_LENGTH) {
+    throwParse(`SQL input length exceeds ${MAX_SQL_LENGTH}`);
+  }
+  const match = /^\s*describe\s+([A-Za-z_][A-Za-z0-9_]*|"(?:""|[^"])+")\s*;?\s*$/iu.exec(sql);
+  if (match === null)
+    return void 0;
+  const source = match[1];
+  if (source === void 0)
+    throwParse("DESCRIBE requires a table name");
+  return { type: "describe", source: unquoteIdentifier(source) };
+}
+function unquoteIdentifier(value2) {
+  if (!value2.startsWith('"'))
+    return value2;
+  return value2.slice(1, -1).replaceAll('""', '"');
+}
+function withStatementToAst(statement, context) {
   const bindings = optionalArray(statement.bind);
   if (bindings.length !== 1)
     throwUnsupported("Only one CTE is supported");
@@ -7323,12 +7348,12 @@ function withStatementToAst(statement) {
   const inner = asNode(binding.statement, "CTE statement");
   if (inner.type !== "select")
     throwUnsupported("Only SELECT CTEs are supported");
-  const cteQuery = selectStatementToAst(inner);
+  const cteQuery = selectStatementToAst(inner, context);
   validateCteQuery(cteQuery);
   const outer = asNode(statement.in, "CTE outer query");
   if (outer.type !== "select")
     throwUnsupported("Only SELECT after WITH is supported");
-  const ast = selectStatementToAst(outer);
+  const ast = selectStatementToAst(outer, context);
   ast.cte = { name, query: cteQuery };
   return ast;
 }
@@ -7337,7 +7362,7 @@ function validateCteQuery(ast) {
     throwUnsupported("Nested CTE joins and subqueries are not supported");
   }
 }
-function selectStatementToAst(statement) {
+function selectStatementToAst(statement, context = newSqlParseContext()) {
   rejectPresent(statement, "with", "CTEs are not supported");
   rejectPresent(statement, "windows", "Window functions are not supported");
   const from = optionalArray(statement.from);
@@ -7347,7 +7372,6 @@ function selectStatementToAst(statement) {
   const leftSource = sourceTable(from[0]);
   const ast = { source: leftSource.source };
   const scope = new SqlScope(leftSource);
-  const context = newSqlParseContext();
   if (from.length === 2) {
     const join = joinToAst(from[1], leftSource);
     ast.join = join;
@@ -7376,7 +7400,7 @@ function selectStatementToAst(statement) {
     }
     if (expr.type === "call" && isAggregateCall(expr)) {
       const alias2 = aliasName(item.alias) ?? functionName(expr.function);
-      aggregates[alias2] = aggregateCallToSpec(expr, scope);
+      aggregates[alias2] = aggregateCallToSpec(expr, scope, context);
       continue;
     }
     if (expr.type === "ref") {
@@ -7392,7 +7416,7 @@ function selectStatementToAst(statement) {
     if (alias === void 0) {
       throwUnsupported("Computed projections require an explicit alias");
     }
-    projections[alias] = exprToLaql(expr, scope, context);
+    projections[alias] = exprToLakeql(expr, scope, context);
   }
   if (select.length > 0)
     ast.select = select;
@@ -7411,7 +7435,7 @@ function selectStatementToAst(statement) {
     ast.groupBy = optionalArray(statement.groupBy).map((expr) => scope.refName(asNode(expr, "GROUP BY expression")));
   }
   if (statement.having !== void 0) {
-    ast.having = exprToLaql(asNode(statement.having, "HAVING"), scope, context);
+    ast.having = exprToLakeql(asNode(statement.having, "HAVING"), scope, context);
   }
   if (statement.orderBy !== void 0) {
     ast.orderBy = optionalArray(statement.orderBy).map((term) => orderByToTerm(term, scope));
@@ -7420,19 +7444,23 @@ function selectStatementToAst(statement) {
   if (limit !== void 0) {
     const node = asNode(limit, "LIMIT");
     if (node.limit !== void 0)
-      ast.limit = nonNegativeInteger(node.limit, "LIMIT");
+      ast.limit = nonNegativeInteger(node.limit, "LIMIT", context);
     if (node.offset !== void 0)
-      ast.offset = nonNegativeInteger(node.offset, "OFFSET");
+      ast.offset = nonNegativeInteger(node.offset, "OFFSET", context);
   }
   if (Object.keys(context.scalarSubqueries).length > 0) {
     ast.scalarSubqueries = context.scalarSubqueries;
   }
   return ast;
 }
-function newSqlParseContext() {
-  return { scalarSubqueries: {}, nextScalarSubqueryId: 0 };
+function newSqlParseContext(options = {}) {
+  return {
+    scalarSubqueries: {},
+    nextScalarSubqueryId: 0,
+    ...options.parameters === void 0 ? {} : { parameters: options.parameters }
+  };
 }
-function exprToLaql(expr, scope = SqlScope.empty(), context = newSqlParseContext()) {
+function exprToLakeql(expr, scope = SqlScope.empty(), context = newSqlParseContext()) {
   switch (expr.type) {
     case "ref":
       return { kind: "column", name: scope.refName(expr) };
@@ -7443,6 +7471,8 @@ function exprToLaql(expr, scope = SqlScope.empty(), context = newSqlParseContext
       return literal(expr.value);
     case "null":
       return literal(null);
+    case "parameter":
+      return literal(parameterValue(expr, context));
     case "unary":
       return unaryToExpr(expr, scope, context);
     case "binary":
@@ -7460,7 +7490,7 @@ function exprToLaql(expr, scope = SqlScope.empty(), context = newSqlParseContext
       return {
         kind: "call",
         fn: functionName(expr.function),
-        args: optionalArray(expr.args).map((arg) => exprToLaql(asNode(arg, "function argument"), scope, context))
+        args: optionalArray(expr.args).map((arg) => exprToLakeql(asNode(arg, "function argument"), scope, context))
       };
     default:
       throwUnsupported(`Unsupported SQL expression ${String(expr.type)}`);
@@ -7468,10 +7498,10 @@ function exprToLaql(expr, scope = SqlScope.empty(), context = newSqlParseContext
 }
 function binaryToExpr(expr, scope = SqlScope.empty(), context = newSqlParseContext()) {
   const op = String(expr.op).toUpperCase();
-  const left = exprToLaql(asNode(expr.left, "left expression"), scope, context);
+  const left = exprToLakeql(asNode(expr.left, "left expression"), scope, context);
   const right = asNode(expr.right, "right expression");
   if (op === "AND" || op === "OR") {
-    const operands = flattenLogical(op.toLowerCase(), left, exprToLaql(right, scope, context));
+    const operands = flattenLogical(op.toLowerCase(), left, exprToLakeql(right, scope, context));
     return { kind: "logical", op: op.toLowerCase(), operands };
   }
   if (op === "IN" || op === "NOT IN") {
@@ -7481,11 +7511,11 @@ function binaryToExpr(expr, scope = SqlScope.empty(), context = newSqlParseConte
       kind: "in",
       negated: op === "NOT IN",
       target: left,
-      values: optionalArray(right.expressions).map((value2) => exprToLaql(asNode(value2, "IN value"), scope, context))
+      values: optionalArray(right.expressions).map((value2) => exprToLakeql(asNode(value2, "IN value"), scope, context))
     };
   }
   if (op === "LIKE" || op === "NOT LIKE" || op === "ILIKE" || op === "NOT ILIKE") {
-    const pattern = exprToLaql(right, scope, context);
+    const pattern = exprToLakeql(right, scope, context);
     if (pattern.kind !== "literal" || typeof pattern.value !== "string") {
       throwUnsupported("LIKE pattern must be a string literal");
     }
@@ -7502,10 +7532,10 @@ function binaryToExpr(expr, scope = SqlScope.empty(), context = newSqlParseConte
       kind: "arithmetic",
       op: arithmeticOp(op),
       left,
-      right: exprToLaql(right, scope, context)
+      right: exprToLakeql(right, scope, context)
     };
   }
-  return { kind: "compare", op: compareOp(op), left, right: exprToLaql(right, scope, context) };
+  return { kind: "compare", op: compareOp(op), left, right: exprToLakeql(right, scope, context) };
 }
 function whereToAst(expr, scope, context) {
   const predicates = flattenWhereConjuncts(expr);
@@ -7523,12 +7553,12 @@ function whereToAst(expr, scope, context) {
   }
   const out = {};
   if (residual.length === 1)
-    out.where = exprToLaql(residual[0], scope, context);
+    out.where = exprToLakeql(residual[0], scope, context);
   else if (residual.length > 1) {
     out.where = {
       kind: "logical",
       op: "and",
-      operands: residual.map((predicate) => exprToLaql(predicate, scope, context))
+      operands: residual.map((predicate) => exprToLakeql(predicate, scope, context))
     };
   }
   if (subqueryJoin !== void 0)
@@ -7571,7 +7601,7 @@ function subqueryJoinToAst(left, subquery, outerScope, negated) {
     rightKey
   };
   if (subquery.where !== void 0) {
-    out.where = exprToLaql(asNode(subquery.where, "IN subquery WHERE"), subqueryScope);
+    out.where = exprToLakeql(asNode(subquery.where, "IN subquery WHERE"), subqueryScope);
   }
   return out;
 }
@@ -7591,7 +7621,7 @@ function flattenWhereConjuncts(expr) {
   return [expr];
 }
 function scalarSubqueryToExpr(subquery, context) {
-  const query2 = selectStatementToAst(subquery);
+  const query2 = selectStatementToAst(subquery, context);
   const outputColumns = scalarSubqueryOutputColumns(query2);
   if (outputColumns.length !== 1) {
     throwUnsupported("Scalar subqueries must return exactly one column");
@@ -7602,7 +7632,7 @@ function scalarSubqueryToExpr(subquery, context) {
   const id = `scalar_${context.nextScalarSubqueryId}`;
   context.nextScalarSubqueryId += 1;
   context.scalarSubqueries[id] = { query: query2, column: outputColumns[0] };
-  return { kind: "call", fn: "__laql_scalar_subquery", args: [{ kind: "literal", value: id }] };
+  return { kind: "call", fn: "__lakeql_scalar_subquery", args: [{ kind: "literal", value: id }] };
 }
 function scalarSubqueryOutputColumns(query2) {
   return [
@@ -7613,7 +7643,7 @@ function scalarSubqueryOutputColumns(query2) {
 }
 function unaryToExpr(expr, scope = SqlScope.empty(), context = newSqlParseContext()) {
   const op = String(expr.op).toUpperCase();
-  const operand = exprToLaql(asNode(expr.operand, "unary operand"), scope, context);
+  const operand = exprToLakeql(asNode(expr.operand, "unary operand"), scope, context);
   if (op === "NOT")
     return { kind: "not", operand };
   if (op === "IS NULL")
@@ -7632,13 +7662,13 @@ function caseToExpr(expr, scope = SqlScope.empty(), context = newSqlParseContext
   const whens = optionalArray(expr.whens).map((branch) => {
     const node = asNode(branch, "CASE branch");
     return {
-      when: exprToLaql(asNode(node.when, "CASE WHEN expression"), scope, context),
-      value: exprToLaql(asNode(node.value, "CASE THEN expression"), scope, context)
+      when: exprToLakeql(asNode(node.when, "CASE WHEN expression"), scope, context),
+      value: exprToLakeql(asNode(node.value, "CASE THEN expression"), scope, context)
     };
   });
   const out = { kind: "case", whens };
   if (expr.else !== void 0) {
-    out.else = exprToLaql(asNode(expr.else, "CASE ELSE expression"), scope, context);
+    out.else = exprToLakeql(asNode(expr.else, "CASE ELSE expression"), scope, context);
   }
   return out;
 }
@@ -7649,13 +7679,13 @@ function ternaryToExpr(expr, scope = SqlScope.empty(), context = newSqlParseCont
   }
   const between = {
     kind: "between",
-    target: exprToLaql(asNode(expr.value, "BETWEEN target"), scope, context),
-    low: exprToLaql(asNode(expr.lo, "BETWEEN low value"), scope, context),
-    high: exprToLaql(asNode(expr.hi, "BETWEEN high value"), scope, context)
+    target: exprToLakeql(asNode(expr.value, "BETWEEN target"), scope, context),
+    low: exprToLakeql(asNode(expr.lo, "BETWEEN low value"), scope, context),
+    high: exprToLakeql(asNode(expr.hi, "BETWEEN high value"), scope, context)
   };
   return op === "NOT BETWEEN" ? { kind: "not", operand: between } : between;
 }
-function aggregateCallToSpec(expr, scope = SqlScope.empty()) {
+function aggregateCallToSpec(expr, scope = SqlScope.empty(), context = newSqlParseContext()) {
   if ("over" in expr && expr.over !== void 0) {
     throwUnsupported("Window functions are not supported");
   }
@@ -7671,6 +7701,8 @@ function aggregateCallToSpec(expr, scope = SqlScope.empty()) {
     }
     op = "count_distinct";
   }
+  if (op === "quantile")
+    return quantileAggregateCallToSpec(args, scope, context);
   if (op === "count" && (args.length === 0 || args.length === 1 && isWildcard(asNode(args[0], "COUNT argument")))) {
     return { op };
   }
@@ -7679,22 +7711,46 @@ function aggregateCallToSpec(expr, scope = SqlScope.empty()) {
   const arg = asNode(args[0], "aggregate argument");
   if (arg.type === "ref")
     return { op, column: scope.refName(arg) };
-  return { op, expr: exprToLaql(arg, scope) };
+  return { op, expr: exprToLakeql(arg, scope, context) };
+}
+function quantileAggregateCallToSpec(args, scope, context) {
+  if (args.length !== 2)
+    throwUnsupported("quantile_cont requires value and percentile arguments");
+  const value2 = asNode(args[0], "quantile_cont value argument");
+  const percentile = requiredQuantilePercentile(exprToLakeql(asNode(args[1], "quantile_cont percentile argument"), scope, context));
+  if (value2.type === "ref") {
+    return { op: "quantile", column: scope.refName(value2), quantile: percentile };
+  }
+  return { op: "quantile", expr: exprToLakeql(value2, scope, context), quantile: percentile };
+}
+function requiredQuantilePercentile(expr) {
+  if (expr.kind !== "literal" || typeof expr.value !== "number" || !Number.isFinite(expr.value) || expr.value < 0 || expr.value > 1) {
+    throwType("quantile_cont percentile must be a numeric literal between 0 and 1", {
+      function: "quantile_cont"
+    });
+  }
+  return expr.value;
 }
 function isAggregateCall(expr) {
   if (expr.type !== "call")
     return false;
-  return isAggregateOp(functionName(expr.function));
+  return aggregateOpOrUndefined(functionName(expr.function)) !== void 0;
 }
 function isAggregateOp(op) {
   return [
     "count",
     "sum",
     "avg",
+    "var_samp",
+    "var_pop",
+    "stddev_samp",
+    "stddev_pop",
+    "median",
     "min",
     "max",
     "count_distinct",
     "approx_count_distinct",
+    "mode",
     "first",
     "last",
     "any"
@@ -7863,9 +7919,9 @@ function optionalArray(value2) {
     throwUnsupported("Expected SQL AST array");
   return value2;
 }
-function nonNegativeInteger(value2, label) {
+function nonNegativeInteger(value2, label, context = newSqlParseContext()) {
   const node = asNode(value2, label);
-  const parsed = node.value;
+  const parsed = node.type === "parameter" ? parameterValue(node, context) : node.value;
   if (typeof parsed !== "number" || !Number.isInteger(parsed) || parsed < 0) {
     throwUnsupported(`${label} must be a non-negative integer`);
   }
@@ -7913,13 +7969,44 @@ function arithmeticOp(op) {
   }
 }
 function aggregateOp(op) {
+  const aggregate = aggregateOpOrUndefined(op);
+  if (aggregate !== void 0)
+    return aggregate;
+  throwUnsupported(`Unsupported aggregate ${op}`);
+}
+function aggregateOpOrUndefined(op) {
   if (isAggregateOp(op))
     return op;
-  throwUnsupported(`Unsupported aggregate ${op}`);
+  if (op === "var" || op === "variance")
+    return "var_samp";
+  if (op === "stddev")
+    return "stddev_samp";
+  if (op === "quantile_cont")
+    return "quantile";
+  return void 0;
 }
 function literal(value2) {
   return { kind: "literal", value: value2 };
 }
+function parameterValue(expr, context) {
+  const index = parameterIndex(expr.name);
+  const value2 = context.parameters?.[index - 1];
+  if (value2 === void 0) {
+    throwUnsupported(`SQL parameter $${index} has no bound value`);
+  }
+  if (isScalar(value2))
+    return value2;
+  throwType(`SQL parameter $${index} must be a scalar value`, { parameter: index });
+}
+function parameterIndex(name) {
+  if (typeof name !== "string" || !/^\$[1-9][0-9]*$/u.test(name)) {
+    throwUnsupported(`Unsupported SQL parameter ${String(name)}`);
+  }
+  return Number(name.slice(1));
+}
+function isScalar(value2) {
+  return value2 === null || typeof value2 === "string" || typeof value2 === "boolean" || typeof value2 === "bigint" || isTimestampValue(value2) || typeof value2 === "number" && Number.isFinite(value2);
+}
 function assertAstDepth(value2, depth = 0) {
   if (depth > MAX_AST_DEPTH)
     throwParse(`SQL AST nesting exceeds ${MAX_AST_DEPTH}`);
@@ -7945,10 +8032,13 @@ function asNode(value2, label) {
   return value2;
 }
 function throwParse(message) {
-  throw new LaQLError("LAQL_PARSE_ERROR", message);
+  throw new LakeqlError("LAKEQL_PARSE_ERROR", message);
 }
 function throwUnsupported(message) {
-  throw new LaQLError("LAQL_SQL_UNSUPPORTED", message);
+  throw new LakeqlError("LAKEQL_SQL_UNSUPPORTED", message);
+}
+function throwType(message, details) {
+  throw new LakeqlError("LAKEQL_TYPE_ERROR", message, details);
 }
 
 // ../cli/src/index.ts
@@ -7977,7 +8067,7 @@ ${usage()}
 `, 2);
     }
   } catch (error) {
-    if (error instanceof LaQLError) return fail(`${error.code}: ${error.message}
+    if (error instanceof LakeqlError) return fail(`${error.code}: ${error.message}
 `, 1);
     if (error instanceof Error) return fail(`${error.message}
 `, 1);
@@ -8008,7 +8098,11 @@ function usage() {
 async function query(args) {
   const sql = requireOption(args.sql, "--sql");
   const { store, key, preserveSqlSource } = await queryStore(args);
-  const ast = parseCliSql(sql, key, preserveSqlSource);
+  const statement = parseCliSqlStatement(sql, key, preserveSqlSource);
+  if (isDescribeStatement(statement)) {
+    return formatRows([await schemaSummary(store, statement.source)], args.format);
+  }
+  const ast = statement;
   const lake = createParquetLake({ store });
   const executableAst = await materializeCteIfNeeded(store, lake, ast);
   const executableLake = createParquetLake({ store });
@@ -8050,7 +8144,7 @@ async function explain(args) {
   const lake = createParquetLake({ store });
   const ast = parseCliSql(sql, key);
   if (hasAggregation(ast)) {
-    throw new LaQLError("LAQL_SQL_UNSUPPORTED", "EXPLAIN for aggregate SQL is not supported");
+    throw new LakeqlError("LAKEQL_SQL_UNSUPPORTED", "EXPLAIN for aggregate SQL is not supported");
   }
   return `${(await builderFromAst(lake.path(key), ast).explain()).text}
 `;
@@ -8066,9 +8160,7 @@ async function compact(args) {
 async function schema(args) {
   const path = requireOption(args.path, "--path");
   const { store, key } = await localStore(path);
-  const metadata = await readParquetMetadata(store, key);
-  const columns = metadata.schema.filter((field) => field.name !== "root").map((field) => ({ name: field.name, type: field.type ?? field.converted_type ?? "group" }));
-  return `${JSON.stringify({ path, rows: Number(totalRows(metadata.row_groups)), columns })}
+  return `${JSON.stringify(await schemaSummary(store, key, path))}
 `;
 }
 async function inspect(args) {
@@ -8106,7 +8198,7 @@ async function writeRows(outputPrefix, rows, args) {
   for (const file of result2.files) {
     const bytes = await outStore.get(file.path);
     if (bytes === null) {
-      throw new LaQLError("LAQL_OBJECT_NOT_FOUND", `No generated output at ${file.path}`, {
+      throw new LakeqlError("LAKEQL_OBJECT_NOT_FOUND", `No generated output at ${file.path}`, {
         path: file.path
       });
     }
@@ -8133,7 +8225,7 @@ async function writeRows(outputPrefix, rows, args) {
     await writeOutputManifest(outStore, args.manifest, manifest);
     const bytes = await outStore.get(args.manifest);
     if (bytes === null) {
-      throw new LaQLError("LAQL_OBJECT_NOT_FOUND", `No generated output at ${args.manifest}`, {
+      throw new LakeqlError("LAKEQL_OBJECT_NOT_FOUND", `No generated output at ${args.manifest}`, {
         path: args.manifest
       });
     }
@@ -8161,16 +8253,19 @@ function hasAggregation(ast) {
 async function materializeCteIfNeeded(store, lake, ast) {
   if (ast.cte === void 0) return ast;
   if (ast.source !== ast.cte.name) {
-    throw new LaQLError("LAQL_SQL_UNSUPPORTED", "CTEs are only supported as the outer FROM source");
+    throw new LakeqlError(
+      "LAKEQL_SQL_UNSUPPORTED",
+      "CTEs are only supported as the outer FROM source"
+    );
   }
   if (ast.join !== void 0 || ast.subqueryJoin !== void 0) {
-    throw new LaQLError("LAQL_SQL_UNSUPPORTED", "CTEs inside JOINs are not supported yet");
+    throw new LakeqlError("LAKEQL_SQL_UNSUPPORTED", "CTEs inside JOINs are not supported yet");
   }
   const cteRows = hasAggregation(ast.cte.query) ? await aggregateRowsFromAst(lake.path(ast.cte.query.source), ast.cte.query) : await builderFromAst(lake.path(ast.cte.query.source), ast.cte.query).toArray();
   if (cteRows.length === 0) {
-    throw new LaQLError("LAQL_SQL_UNSUPPORTED", "Empty CTE results are not supported yet");
+    throw new LakeqlError("LAKEQL_SQL_UNSUPPORTED", "Empty CTE results are not supported yet");
   }
-  const prefix = `__laql_cte/${ast.cte.name}`;
+  const prefix = `__lakeql_cte/${ast.cte.name}`;
   await writePartitionedParquet(store, prefix, {
     rows: cteRows,
     maxRowsPerFile: cteRows.length
@@ -8184,7 +8279,7 @@ async function resolveScalarSubqueries(lake, ast) {
   for (const [id, subquery] of Object.entries(ast.scalarSubqueries)) {
     const rows = hasAggregation(subquery.query) ? await aggregateRowsFromAst(lake.path(subquery.query.source), subquery.query) : await builderFromAst(lake.path(subquery.query.source), subquery.query).toArray();
     if (rows.length > 1) {
-      throw new LaQLError("LAQL_SQL_UNSUPPORTED", "Scalar subquery returned more than one row");
+      throw new LakeqlError("LAKEQL_SQL_UNSUPPORTED", "Scalar subquery returned more than one row");
     }
     values.set(id, rows.length === 0 ? null : rows[0]?.[subquery.column] ?? null);
   }
@@ -8205,10 +8300,10 @@ async function resolveScalarSubqueries(lake, ast) {
 function replaceScalarSubqueryExpr(expr, values) {
   switch (expr.kind) {
     case "call":
-      if (expr.fn === "__laql_scalar_subquery") {
+      if (expr.fn === "__lakeql_scalar_subquery") {
         const id = expr.args[0];
         if (id?.kind !== "literal" || typeof id.value !== "string" || !values.has(id.value)) {
-          throw new LaQLError("LAQL_SQL_UNSUPPORTED", "Invalid scalar subquery placeholder");
+          throw new LakeqlError("LAKEQL_SQL_UNSUPPORTED", "Invalid scalar subquery placeholder");
         }
         return { kind: "literal", value: values.get(id.value) };
       }
@@ -8264,10 +8359,10 @@ function replaceScalarSubqueryExpr(expr, values) {
   }
 }
 async function joinRowsFromAst(lake, ast, args) {
-  if (ast.join === void 0) throw new LaQLError("LAQL_VALIDATION_ERROR", "Missing SQL JOIN");
+  if (ast.join === void 0) throw new LakeqlError("LAKEQL_VALIDATION_ERROR", "Missing SQL JOIN");
   const join = ast.join;
   if (hasAggregation(ast)) {
-    throw new LaQLError("LAQL_SQL_UNSUPPORTED", "Aggregate SQL over JOIN is not supported yet");
+    throw new LakeqlError("LAKEQL_SQL_UNSUPPORTED", "Aggregate SQL over JOIN is not supported yet");
   }
   const leftAlias = leftJoinAlias(ast);
   const plan = planJoinSides(ast, leftAlias, join.alias);
@@ -8300,7 +8395,7 @@ async function joinRowsFromAst(lake, ast, args) {
   return rows;
 }
 function planJoinSides(ast, leftAlias, rightAlias) {
-  if (ast.join === void 0) throw new LaQLError("LAQL_VALIDATION_ERROR", "Missing SQL JOIN");
+  if (ast.join === void 0) throw new LakeqlError("LAKEQL_VALIDATION_ERROR", "Missing SQL JOIN");
   const leftPredicates = [];
   const rightPredicates = [];
   const residualPredicates = [];
@@ -8509,11 +8604,11 @@ function fillLeftJoinNulls(rows, rightAlias, rightColumns) {
 }
 async function subqueryJoinRowsFromAst(lake, ast, args) {
   if (ast.subqueryJoin === void 0) {
-    throw new LaQLError("LAQL_VALIDATION_ERROR", "Missing SQL IN subquery");
+    throw new LakeqlError("LAKEQL_VALIDATION_ERROR", "Missing SQL IN subquery");
   }
   if (hasAggregation(ast)) {
-    throw new LaQLError(
-      "LAQL_SQL_UNSUPPORTED",
+    throw new LakeqlError(
+      "LAKEQL_SQL_UNSUPPORTED",
       "Aggregate SQL over IN subquery is not supported yet"
     );
   }
@@ -8591,8 +8686,8 @@ function validateAggregateProjection(ast) {
     const { column } = selectColumn(select);
     if (column === "*") continue;
     if (!groupColumns.has(column)) {
-      throw new LaQLError(
-        "LAQL_SQL_UNSUPPORTED",
+      throw new LakeqlError(
+        "LAKEQL_SQL_UNSUPPORTED",
         `Aggregate SQL can only select grouped columns or aggregate expressions, not ${column}`
       );
     }
@@ -8622,7 +8717,7 @@ function projectAggregateRows(rows, ast, hiddenCountAlias) {
 }
 function hiddenAggregateAlias(ast) {
   const reserved = /* @__PURE__ */ new Set([...ast.select ?? [], ...Object.keys(ast.aggregates ?? {})]);
-  let alias = "__laql_group_count";
+  let alias = "__lakeql_group_count";
   while (reserved.has(alias)) alias = `_${alias}`;
   return alias;
 }
@@ -8666,6 +8761,17 @@ function rowsToCsv(rows) {
   return `${lines.join("\n")}
 `;
 }
+function formatRows(rows, format) {
+  if (format === "json") return `${JSON.stringify(rows)}
+`;
+  if (format === "csv") return rowsToCsv(rows);
+  return rows.map((row) => JSON.stringify(row)).join("\n") + (rows.length > 0 ? "\n" : "");
+}
+async function schemaSummary(store, key, displayPath = key) {
+  const metadata = await readParquetMetadata(store, key);
+  const columns = metadata.schema.filter((field) => field.name !== "root").map((field) => ({ name: field.name, type: field.type ?? field.converted_type ?? "group" }));
+  return { path: displayPath, rows: Number(totalRows(metadata.row_groups)), columns };
+}
 function csvCell(value2) {
   if (value2 === null || value2 === void 0) return "";
   const text = String(value2);
@@ -8679,20 +8785,38 @@ function parseCliSql(sql, defaultSource, preserveSqlSource = false) {
   }
   return { ...parseSql(addDefaultFrom(trimmed)), source: defaultSource };
 }
-function applyDefaultSource(ast, defaultSource) {
+function parseCliSqlStatement(sql, defaultSource, preserveSqlSource = false) {
+  const trimmed = sql.trim();
+  if (/^\s*describe\b/iu.test(trimmed)) {
+    const statement = parseSqlStatement(trimmed);
+    if (!isDescribeStatement(statement)) return statement;
+    if (preserveSqlSource || statement.source !== "input") return statement;
+    return { ...statement, source: defaultSource };
+  }
+  return parseCliSql(sql, defaultSource, preserveSqlSource);
+}
+function isDescribeStatement(statement) {
+  return "type" in statement && statement.type === "describe";
+}
+function applyDefaultSource(ast, defaultSource, includeScalarSubqueries = true, seen = /* @__PURE__ */ new WeakSet()) {
+  if (seen.has(ast)) return ast.cte === void 0 ? { ...ast, source: defaultSource } : ast;
+  seen.add(ast);
   const out = { ...ast };
   if (out.cte !== void 0) {
-    out.cte = { ...out.cte, query: applyDefaultSource(out.cte.query, defaultSource) };
+    out.cte = {
+      ...out.cte,
+      query: applyDefaultSource(out.cte.query, defaultSource, includeScalarSubqueries, seen)
+    };
   } else {
     out.source = defaultSource;
   }
   if (out.subqueryJoin !== void 0)
     out.subqueryJoin = { ...out.subqueryJoin, source: defaultSource };
-  if (out.scalarSubqueries !== void 0) {
+  if (includeScalarSubqueries && out.scalarSubqueries !== void 0) {
     out.scalarSubqueries = Object.fromEntries(
       Object.entries(out.scalarSubqueries).map(([id, subquery]) => [
         id,
-        { ...subquery, query: applyDefaultSource(subquery.query, defaultSource) }
+        { ...subquery, query: applyDefaultSource(subquery.query, defaultSource, false, seen) }
       ])
     );
   }
@@ -8700,7 +8824,7 @@ function applyDefaultSource(ast, defaultSource) {
 }
 function addDefaultFrom(sql) {
   if (!/^\s*select\b/iu.test(sql)) {
-    throw new LaQLError("LAQL_PARSE_ERROR", "SQL must start with SELECT");
+    throw new LakeqlError("LAKEQL_PARSE_ERROR", "SQL must start with SELECT");
   }
   const clause = /\b(where|group\s+by|having|order\s+by|limit|offset)\b/iu.exec(sql);
   if (clause === null || clause.index === void 0) return `${sql} from input`;
@@ -8763,45 +8887,45 @@ function parseArgs(argv) {
     } else if (arg === "--job-id") {
       index += 1;
       args.jobId = requireValue(rest, index, arg);
-    } else throw new LaQLError("LAQL_PARSE_ERROR", `Unknown argument ${arg}`);
+    } else throw new LakeqlError("LAKEQL_PARSE_ERROR", `Unknown argument ${arg}`);
   }
   return args;
 }
 function parseTableArg(value2) {
   const separator = value2.indexOf("=");
   if (separator <= 0 || separator === value2.length - 1) {
-    throw new LaQLError("LAQL_PARSE_ERROR", "--table must be name=path.parquet");
+    throw new LakeqlError("LAKEQL_PARSE_ERROR", "--table must be name=path.parquet");
   }
   const name = value2.slice(0, separator);
   if (!/^[A-Za-z_][A-Za-z0-9_]*$/u.test(name)) {
-    throw new LaQLError("LAQL_PARSE_ERROR", "--table name must be a SQL identifier");
+    throw new LakeqlError("LAKEQL_PARSE_ERROR", "--table name must be a SQL identifier");
   }
   return { name, path: value2.slice(separator + 1) };
 }
 function parseFormat(value2) {
   if (value2 === "csv" || value2 === "json" || value2 === "ndjson") return value2;
-  throw new LaQLError("LAQL_PARSE_ERROR", "--format must be csv, json, or ndjson");
+  throw new LakeqlError("LAKEQL_PARSE_ERROR", "--format must be csv, json, or ndjson");
 }
 function requireValue(args, index, flag) {
   const value2 = args[index];
   if (value2 === void 0 || value2.startsWith("--")) {
-    throw new LaQLError("LAQL_PARSE_ERROR", `${flag} requires a value`);
+    throw new LakeqlError("LAKEQL_PARSE_ERROR", `${flag} requires a value`);
   }
   return value2;
 }
 function requireOption(value2, flag) {
-  if (value2 === void 0) throw new LaQLError("LAQL_PARSE_ERROR", `${flag} is required`);
+  if (value2 === void 0) throw new LakeqlError("LAKEQL_PARSE_ERROR", `${flag} is required`);
   return value2;
 }
 function parseCsv(value2, flag) {
   const values = value2.split(",").map((part) => part.trim()).filter((part) => part.length > 0);
-  if (values.length === 0) throw new LaQLError("LAQL_PARSE_ERROR", `${flag} must not be empty`);
+  if (values.length === 0) throw new LakeqlError("LAKEQL_PARSE_ERROR", `${flag} must not be empty`);
   return values;
 }
 function parsePositiveInt(value2, flag) {
   const parsed = Number(value2);
   if (!Number.isInteger(parsed) || parsed <= 0) {
-    throw new LaQLError("LAQL_PARSE_ERROR", `${flag} must be a positive integer`);
+    throw new LakeqlError("LAKEQL_PARSE_ERROR", `${flag} must be a positive integer`);
   }
   return parsed;
 }