@slexisvn/query-engine 0.1.0 → 0.1.2

package/dist/binder/binder.d.ts

@@ -90,7 +90,8 @@ export declare class Binder {
     functionRegistry: object;
     cteScopes: Map<string, CteInfo>;
     aggregatesFound: BE.BoundExpr[];
-    constructor(catalog: CatalogLike, functionRegistry: object);
+    params: readonly BE.LiteralValue[];
+    constructor(catalog: CatalogLike, functionRegistry: object, params?: readonly BE.LiteralValue[]);
     bind(ast: AST.QueryStmt): BoundQuery;
     bindQuery(node: AST.QueryStmt, scope: BinderScope): BoundQuery;
     bindSetOp(node: AST.SetOpNode, scope: BinderScope): BoundSetOp;
@@ -111,6 +112,7 @@ export declare class Binder {
     bindWindowCall(node: AST.WindowCallNode, scope: BinderScope): BE.BoundWindowNode;
     bindColumnRef(node: AST.ColumnRefNode, scope: BinderScope): BE.BoundColumnRefNode;
     bindLiteral(node: AST.LiteralNode): BE.BoundLiteralNode;
+    bindParameter(node: AST.ParameterNode): BE.BoundLiteralNode;
     bindBinaryExpr(node: AST.BinaryExprNode, scope: BinderScope): BE.BoundBinaryNode;
     bindUnaryExpr(node: AST.UnaryExprNode, scope: BinderScope): BE.BoundUnaryNode;
     bindAggregateCall(node: AST.AggregateCallNode, scope: BinderScope): BE.BoundAggregateNode;

package/dist/dataframe/dataframe.d.ts

@@ -42,6 +42,7 @@ interface EngineLike {
     functionRegistry: FunctionRegistry;
     sql(sqlString: string, options: {
         frames: SqlFrameLike[];
+        params?: readonly ColumnValue[];
     }): DataFrame;
     _nextDfId(): number;
     _runPlan(plan: LogicalPlanNode, outputColumns: OutputColumnLike[], streaming: boolean, cteMap: CteMap | null): Promise<ResultLike>;
@@ -62,7 +63,9 @@ export declare class DataFrame {
     columns(): string[];
     schema(): DFSchema;
     explain(): string;
-    sql(sqlString: string): DataFrame;
+    sql(sqlString: string, options?: {
+        params?: readonly ColumnValue[];
+    }): DataFrame;
     select(...items: (Col | string)[]): DataFrame;
     filter(condition: Col | string): DataFrame;
     where(condition: Col | string): DataFrame;

package/dist/engine/query-engine.d.ts

@@ -8,11 +8,13 @@ import type { LogicalPlanNode } from '../planner/logical-plan.js';
 import { DataFrame } from '../dataframe/dataframe.js';
 import type { Statement, QueryStmt, CreateTableStmtNode, DropTableStmtNode } from '../parser/ast.js';
 import type { BoundQuery, OutputColumn } from '../binder/binder.js';
+import type { LiteralValue } from '../binder/expression-binder.js';
 import type { Catalog } from '../catalog/catalog.js';
 import type { ColumnSchema, ColumnValue } from '../storage/data-type.js';
 import type { TableStatistics } from '../catalog/statistics.js';
 import type { OptimizationPass } from '../optimizer/pass.js';
 import type { Transport } from '../distributed/transport/transport.js';
+export type QueryParam = LiteralValue;
 type StatisticsMap = Map<string, TableStatistics>;
 type DDLStmt = CreateTableStmtNode | DropTableStmtNode;
 interface StorageBackendLike {
@@ -37,6 +39,7 @@ interface SqlFrame {
 }
 interface SqlOptions {
     frames?: SqlFrame[];
+    params?: readonly QueryParam[];
 }
 interface DistributedClusterConfig {
     nodeId?: string;
@@ -113,10 +116,10 @@ export declare class QueryEngine {
     collectStatistics(): Promise<StatisticsMap | null>;
     createOptimizer(statistics: StatisticsMap | null): Optimizer;
     parseSQL(sql: string): Statement;
-    bind(ast: QueryStmt): BoundQuery;
+    bind(ast: QueryStmt, params?: readonly QueryParam[]): BoundQuery;
     plan(boundQuery: BoundQuery): LogicalPlanNode;
     optimize(logicalPlan: LogicalPlanNode): LogicalPlanNode;
-    compile(sql: string): Promise<CompileResult>;
+    compile(sql: string, params?: readonly QueryParam[]): Promise<CompileResult>;
     optimizeCTEMap(cteMap: Map<string, LogicalPlanNode>): Map<string, LogicalPlanNode>;
     _applyDistributedPasses(optimizer: Optimizer, passes: DistributedPassEntry[]): void;
     _ensureStatistics(): Promise<void>;
@@ -126,7 +129,7 @@ export declare class QueryEngine {
     _formatPlan(plan: LogicalPlanNode): Promise<string>;
     _explainPlanResult(plan: LogicalPlanNode): Promise<RunRowsResult>;
     _runPlan(plan: LogicalPlanNode, outputColumns: OutputColumn[], streaming?: boolean, cteMap?: Map<string, LogicalPlanNode> | null): Promise<QueryResult>;
-    run(sql: string): Promise<DDLResult | RunRowsResult>;
+    run(sql: string, params?: readonly QueryParam[]): Promise<DDLResult | RunRowsResult>;
     cancel(): void;
     executeDDL(ddl: DDLStmt): Promise<DDLResult>;
     executeCreateTable(stmt: CreateTableStmtNode): Promise<DDLResult>;

package/dist/index.browser.js

@@ -2283,6 +2283,14 @@ var init_dispatch = __esm({
   }
 });
 
+// node-only-stub:node-only-stub
+var require_node_only_stub = __commonJS({
+  "node-only-stub:node-only-stub"() {
+    init_buffer_shim();
+    throw new Error("[@slexisvn/query-engine] parallel/distributed execution is not available in the browser build; use the Node build for these features.");
+  }
+});
+
 // src/planner/plan-formatter.ts
 var plan_formatter_exports = {};
 __export(plan_formatter_exports, {
@@ -2985,6 +2993,7 @@ var TokenType = /* @__PURE__ */ ((TokenType2) => {
   TokenType2["SEMICOLON"] = "SEMICOLON";
   TokenType2["CONCAT"] = "CONCAT";
   TokenType2["COLON"] = "COLON";
+  TokenType2["PLACEHOLDER"] = "PLACEHOLDER";
   TokenType2["EOF"] = "EOF";
   TokenType2["EXPLAIN"] = "EXPLAIN";
   TokenType2["SELECT"] = "SELECT";
@@ -3100,8 +3109,10 @@ var NON_KEYWORD_TOKENS = /* @__PURE__ */ new Set([
   "SEMICOLON",
   "CONCAT",
   "COLON",
+  "PLACEHOLDER",
   "EOF"
 ]);
+var PLACEHOLDER_PREFIX = "$";
 var KEYWORDS = /* @__PURE__ */ new Map();
 for (const key of Object.keys(TokenType)) {
   if (!NON_KEYWORD_TOKENS.has(key)) {
@@ -3136,6 +3147,8 @@ var Lexer = class {
       const ch = this.input[this.pos];
       if (ch === "'") {
         this.tokens.push(this._readString(start));
+      } else if (ch === PLACEHOLDER_PREFIX) {
+        this.tokens.push(this._readPlaceholder(start));
       } else if (this._isDigit(ch)) {
         this.tokens.push(this._readNumber(start));
       } else if (this._isIdentStart(ch)) {
@@ -3181,6 +3194,17 @@ var Lexer = class {
     }
     throw new Error(`Unterminated string at position ${start}`);
   }
+  _readPlaceholder(start) {
+    this.pos++;
+    const digitsStart = this.pos;
+    while (this.pos < this.input.length && this._isDigit(this.input[this.pos])) {
+      this.pos++;
+    }
+    if (this.pos === digitsStart) {
+      throw new Error(`Expected parameter number after '${PLACEHOLDER_PREFIX}' at position ${start}`);
+    }
+    return new Token("PLACEHOLDER" /* PLACEHOLDER */, this.input.slice(digitsStart, this.pos), start);
+  }
   _readNumber(start) {
     while (this.pos < this.input.length && this._isDigit(this.input[this.pos])) {
       this.pos++;
@@ -3327,6 +3351,9 @@ function ColumnRef(name, table = null) {
 function Literal(value, dataType = null) {
   return { kind: "Literal" /* LITERAL */, value, dataType };
 }
+function Parameter(index) {
+  return { kind: "Parameter" /* PARAMETER */, index };
+}
 function BinaryExpr(op, left, right) {
   return { kind: "BinaryExpr" /* BINARY_EXPR */, op, left, right };
 }
@@ -3631,7 +3658,11 @@ var Parser = class {
       this.expect("RPAREN" /* RPAREN */);
       return inner;
     }
-    const name = this.expectIdent();
+    let name = this.expectIdent();
+    while (this.isAt("DOT" /* DOT */)) {
+      this.advance();
+      name = this.expectIdent();
+    }
     const alias = this.parseOptionalAlias(() => !this.isJoinKeyword() && !this.isClauseKeyword()) ?? name;
     return TableRef(name, alias);
   }
@@ -3909,10 +3940,14 @@ var Parser = class {
     if (this.isAggregateKeyword(token.type)) {
       return this.parseAggregateCall();
     }
+    if (token.type === "PLACEHOLDER" /* PLACEHOLDER */) {
+      this.advance();
+      return Parameter(Number(token.value));
+    }
     if (token.type === "COLON" /* COLON */) {
       this.advance();
       const paramToken = this.expect("NUMBER" /* NUMBER */);
-      return Literal(`:${paramToken.value}`, "PARAM");
+      return Parameter(Number(paramToken.value));
     }
     if (token.type === "IDENT" /* IDENT */) {
       const name = this.advance().value;
@@ -4373,16 +4408,32 @@ var BinderScope = class _BinderScope {
 
 // src/binder/binder.ts
 init_expression_binder();
+function valueDataType(value) {
+  switch (typeof value) {
+    case "boolean":
+      return "BOOLEAN" /* BOOLEAN */;
+    case "bigint":
+      return "INT64" /* INT64 */;
+    case "string":
+      return "VARCHAR" /* VARCHAR */;
+    case "number":
+      return Number.isInteger(value) ? "INT32" /* INT32 */ : "FLOAT64" /* FLOAT64 */;
+    default:
+      return null;
+  }
+}
 var Binder = class {
   catalog;
   functionRegistry;
   cteScopes;
   aggregatesFound;
-  constructor(catalog, functionRegistry) {
+  params;
+  constructor(catalog, functionRegistry, params = []) {
     this.catalog = catalog;
     this.functionRegistry = functionRegistry;
     this.cteScopes = /* @__PURE__ */ new Map();
     this.aggregatesFound = [];
+    this.params = params;
   }
   bind(ast) {
     const scope = new BinderScope();
@@ -4647,6 +4698,8 @@ var Binder = class {
         return this.bindColumnRef(node, scope);
       case "Literal" /* LITERAL */:
         return this.bindLiteral(node);
+      case "Parameter" /* PARAMETER */:
+        return this.bindParameter(node);
       case "BinaryExpr" /* BINARY_EXPR */:
         return this.bindBinaryExpr(node, scope);
       case "UnaryExpr" /* UNARY_EXPR */:
@@ -4760,6 +4813,13 @@ var Binder = class {
     }
     return BoundLiteral(node.value, "VARCHAR" /* VARCHAR */);
   }
+  bindParameter(node) {
+    if (node.index < 1 || node.index > this.params.length) {
+      throw new Error(`Missing value for parameter $${node.index}`);
+    }
+    const value = this.params[node.index - 1];
+    return BoundLiteral(value, valueDataType(value));
+  }
   bindBinaryExpr(node, scope) {
     const left = this.bindExpression(node.left, scope);
     const right = this.bindExpression(node.right, scope);
@@ -13864,7 +13924,7 @@ async function buildExchange(executor, node) {
     const { transport, sourceNodes, channelId, exchangeType } = executor._distributedContext.getExchangeConfig(node);
     const isReceiver = executor._distributedContext.role === "receiver";
     if (isReceiver) {
-      const { ExchangeReceiver } = await import("../../distributed/execution/exchange-operator.js");
+      const { ExchangeReceiver } = await Promise.resolve().then(() => __toESM(require_node_only_stub(), 1));
       const receiver = new ExchangeReceiver(transport, sourceNodes, { channelId });
       await receiver.init();
       return {
@@ -13882,7 +13942,7 @@ async function buildExchange(executor, node) {
         }
       };
     }
-    const { ExchangeSender } = await import("../../distributed/execution/exchange-operator.js");
+    const { ExchangeSender } = await Promise.resolve().then(() => __toESM(require_node_only_stub(), 1));
     const sender = new ExchangeSender(transport, node._targetNodes || [], {
       exchangeType: exchangeType || node.exchangeType,
       channelId,
@@ -13922,7 +13982,7 @@ async function buildMergeExchange(executor, node) {
   const child = await executor.buildPipeline(node.children[0]);
   if (executor._distributedContext) {
     const { transport, sourceNodes, channelId } = executor._distributedContext.getMergeExchangeConfig(node);
-    const { MergeExchangeOperator } = await import("../../distributed/execution/merge-exchange.js");
+    const { MergeExchangeOperator } = await Promise.resolve().then(() => __toESM(require_node_only_stub(), 1));
     const merge = new MergeExchangeOperator(transport, sourceNodes, {
       orderKeys: node.orderKeys,
       limit: node.limit,
@@ -16938,7 +16998,7 @@ var DataFrame = class _DataFrame {
   explain() {
     return planToString(this._plan);
   }
-  sql(sqlString) {
+  sql(sqlString, options = {}) {
     const columns = this._schema.fields.map((f) => ({ name: f.name, dataType: f.dataType }));
     return this._engine.sql(sqlString, {
       frames: [{
@@ -16946,7 +17006,8 @@ var DataFrame = class _DataFrame {
         columns,
         plan: this._plan,
         cteMap: this._cteMap
-      }]
+      }],
+      params: options.params
     });
   }
   select(...items) {
@@ -17418,8 +17479,8 @@ var QueryEngine = class {
   parseSQL(sql) {
     return parse(sql);
   }
-  bind(ast) {
-    const binder = new Binder(this.catalog, this.functionRegistry);
+  bind(ast, params = []) {
+    const binder = new Binder(this.catalog, this.functionRegistry, params);
     return binder.bind(ast);
   }
   plan(boundQuery) {
@@ -17428,7 +17489,7 @@ var QueryEngine = class {
   optimize(logicalPlan) {
     return this.optimizer.optimize(logicalPlan);
   }
-  async compile(sql) {
+  async compile(sql, params = []) {
     const ast = this.parseSQL(sql);
     let isExplain = false;
     let isAnalyze = false;
@@ -17443,7 +17504,7 @@ var QueryEngine = class {
     } else if (ast.kind === "CreateTableStmt" || ast.kind === "DropTableStmt") {
       return { ddl: ast };
     }
-    const bound = this.bind(targetAst);
+    const bound = this.bind(targetAst, params);
     const logicalPlan = this.plan(bound);
     let cteMap = logicalPlan._cteMap || /* @__PURE__ */ new Map();
     await this._ensureStatistics();
@@ -17498,7 +17559,7 @@ var QueryEngine = class {
     if (ast.kind === "CreateTableStmt" || ast.kind === "DropTableStmt" || ast.kind === "ExplainStmt" || ast.kind === "ExplainAnalyzeStmt") {
       throw new Error("sql() supports query statements only");
     }
-    const binder = new Binder(this.catalog, this.functionRegistry);
+    const binder = new Binder(this.catalog, this.functionRegistry, options.params);
     for (const frame of options.frames || []) {
       binder.cteScopes.set(frame.name.toUpperCase(), {
         name: frame.name,
@@ -17537,8 +17598,8 @@ var QueryEngine = class {
     const { sink, columnNames } = await this.executor.execute(optimized, outputColumns, streaming);
     return new QueryResult(columnNames, sink);
   }
-  async run(sql) {
-    const compiled = await this.compile(sql);
+  async run(sql, params = []) {
+    const compiled = await this.compile(sql, params);
     if (compiled.ddl) {
       return this.executeDDL(compiled.ddl);
     }
@@ -17750,7 +17811,7 @@ Rows Returned: ${rows.length}`;
       registerAllKernels2();
       this.wasmEnabled = true;
       const wasmModule = loader.getModule("core");
-      const { WorkerPool } = await import("../parallel/worker-pool.js");
+      const { WorkerPool } = await Promise.resolve().then(() => __toESM(require_node_only_stub(), 1));
       const pool = new WorkerPool({
         maxWorkers: Config2.parallelWorkers,
         wasmModule,
@@ -17759,9 +17820,9 @@ Rows Returned: ${rows.length}`;
       });
       await pool.init();
       const { globalDispatch: globalDispatch2 } = await Promise.resolve().then(() => (init_dispatch(), dispatch_exports));
-      const { ParallelDispatch } = await import("../parallel/parallel-dispatch.js");
+      const { ParallelDispatch } = await Promise.resolve().then(() => __toESM(require_node_only_stub(), 1));
       const parallelDispatch = new ParallelDispatch(pool, regionAllocator, globalDispatch2);
-      const { FragmentPool } = await import("../parallel/fragment-pool.js");
+      const { FragmentPool } = await Promise.resolve().then(() => __toESM(require_node_only_stub(), 1));
       const fragmentPool = new FragmentPool(Config2.parallelWorkers, Config2.aggMorselRows);
       this.executor.setParallelContext(pool, parallelDispatch, fragmentPool);
       this.workerPool = pool;
@@ -17774,13 +17835,13 @@ Rows Returned: ${rows.length}`;
     }
   }
   async enableDistributed(clusterConfig = {}) {
-    const { NodeDescriptor, NodeRole } = await import("../distributed/cluster/node-descriptor.js");
-    const { ClusterManager } = await import("../distributed/cluster/cluster-manager.js");
-    const { PartitionMap } = await import("../distributed/partition/partition-map.js");
-    const { DistributionAwareJoin } = await import("../distributed/optimizer/distribution-aware-join.js");
-    const { PartialAggregatePass } = await import("../distributed/optimizer/partial-aggregate.js");
-    const { DistributedSortPass } = await import("../distributed/optimizer/distributed-sort.js");
-    const { QueryCoordinator } = await import("../distributed/execution/coordinator.js");
+    const { NodeDescriptor, NodeRole } = await Promise.resolve().then(() => __toESM(require_node_only_stub(), 1));
+    const { ClusterManager } = await Promise.resolve().then(() => __toESM(require_node_only_stub(), 1));
+    const { PartitionMap } = await Promise.resolve().then(() => __toESM(require_node_only_stub(), 1));
+    const { DistributionAwareJoin } = await Promise.resolve().then(() => __toESM(require_node_only_stub(), 1));
+    const { PartialAggregatePass } = await Promise.resolve().then(() => __toESM(require_node_only_stub(), 1));
+    const { DistributedSortPass } = await Promise.resolve().then(() => __toESM(require_node_only_stub(), 1));
+    const { QueryCoordinator } = await Promise.resolve().then(() => __toESM(require_node_only_stub(), 1));
     const localNode = new NodeDescriptor({
       nodeId: clusterConfig.nodeId || `node-${Date.now()}`,
       host: clusterConfig.host || "127.0.0.1",
@@ -17800,7 +17861,7 @@ Rows Returned: ${rows.length}`;
     this._distributedPasses = makeDistributedPasses();
     let transport = clusterConfig.transport || null;
     if (!transport) {
-      const { HttpTransport } = await import("../distributed/transport/http-transport.js");
+      const { HttpTransport } = await Promise.resolve().then(() => __toESM(require_node_only_stub(), 1));
       transport = new HttpTransport({ port: localNode.port });
     }
     const coordinator = new QueryCoordinator(this, clusterManager, partitionMap, transport);

package/dist/index.node.js

@@ -12524,6 +12524,7 @@ var TokenType = /* @__PURE__ */ ((TokenType2) => {
   TokenType2["SEMICOLON"] = "SEMICOLON";
   TokenType2["CONCAT"] = "CONCAT";
   TokenType2["COLON"] = "COLON";
+  TokenType2["PLACEHOLDER"] = "PLACEHOLDER";
   TokenType2["EOF"] = "EOF";
   TokenType2["EXPLAIN"] = "EXPLAIN";
   TokenType2["SELECT"] = "SELECT";
@@ -12639,8 +12640,10 @@ var NON_KEYWORD_TOKENS = /* @__PURE__ */ new Set([
   "SEMICOLON",
   "CONCAT",
   "COLON",
+  "PLACEHOLDER",
   "EOF"
 ]);
+var PLACEHOLDER_PREFIX = "$";
 var KEYWORDS = /* @__PURE__ */ new Map();
 for (const key of Object.keys(TokenType)) {
   if (!NON_KEYWORD_TOKENS.has(key)) {
@@ -12675,6 +12678,8 @@ var Lexer = class {
       const ch = this.input[this.pos];
       if (ch === "'") {
         this.tokens.push(this._readString(start));
+      } else if (ch === PLACEHOLDER_PREFIX) {
+        this.tokens.push(this._readPlaceholder(start));
       } else if (this._isDigit(ch)) {
         this.tokens.push(this._readNumber(start));
       } else if (this._isIdentStart(ch)) {
@@ -12720,6 +12725,17 @@ var Lexer = class {
     }
     throw new Error(`Unterminated string at position ${start}`);
   }
+  _readPlaceholder(start) {
+    this.pos++;
+    const digitsStart = this.pos;
+    while (this.pos < this.input.length && this._isDigit(this.input[this.pos])) {
+      this.pos++;
+    }
+    if (this.pos === digitsStart) {
+      throw new Error(`Expected parameter number after '${PLACEHOLDER_PREFIX}' at position ${start}`);
+    }
+    return new Token("PLACEHOLDER" /* PLACEHOLDER */, this.input.slice(digitsStart, this.pos), start);
+  }
   _readNumber(start) {
     while (this.pos < this.input.length && this._isDigit(this.input[this.pos])) {
       this.pos++;
@@ -12865,6 +12881,9 @@ function ColumnRef(name, table = null) {
 function Literal(value, dataType = null) {
   return { kind: "Literal" /* LITERAL */, value, dataType };
 }
+function Parameter(index) {
+  return { kind: "Parameter" /* PARAMETER */, index };
+}
 function BinaryExpr(op, left, right) {
   return { kind: "BinaryExpr" /* BINARY_EXPR */, op, left, right };
 }
@@ -13169,7 +13188,11 @@ var Parser = class {
       this.expect("RPAREN" /* RPAREN */);
       return inner;
     }
-    const name = this.expectIdent();
+    let name = this.expectIdent();
+    while (this.isAt("DOT" /* DOT */)) {
+      this.advance();
+      name = this.expectIdent();
+    }
     const alias = this.parseOptionalAlias(() => !this.isJoinKeyword() && !this.isClauseKeyword()) ?? name;
     return TableRef(name, alias);
   }
@@ -13447,10 +13470,14 @@ var Parser = class {
     if (this.isAggregateKeyword(token.type)) {
       return this.parseAggregateCall();
     }
+    if (token.type === "PLACEHOLDER" /* PLACEHOLDER */) {
+      this.advance();
+      return Parameter(Number(token.value));
+    }
     if (token.type === "COLON" /* COLON */) {
       this.advance();
       const paramToken = this.expect("NUMBER" /* NUMBER */);
-      return Literal(`:${paramToken.value}`, "PARAM");
+      return Parameter(Number(paramToken.value));
     }
     if (token.type === "IDENT" /* IDENT */) {
       const name = this.advance().value;
@@ -13909,16 +13936,32 @@ var BinderScope = class _BinderScope {
 
 // src/binder/binder.ts
 init_expression_binder();
+function valueDataType(value) {
+  switch (typeof value) {
+    case "boolean":
+      return "BOOLEAN" /* BOOLEAN */;
+    case "bigint":
+      return "INT64" /* INT64 */;
+    case "string":
+      return "VARCHAR" /* VARCHAR */;
+    case "number":
+      return Number.isInteger(value) ? "INT32" /* INT32 */ : "FLOAT64" /* FLOAT64 */;
+    default:
+      return null;
+  }
+}
 var Binder = class {
   catalog;
   functionRegistry;
   cteScopes;
   aggregatesFound;
-  constructor(catalog, functionRegistry) {
+  params;
+  constructor(catalog, functionRegistry, params = []) {
     this.catalog = catalog;
     this.functionRegistry = functionRegistry;
     this.cteScopes = /* @__PURE__ */ new Map();
     this.aggregatesFound = [];
+    this.params = params;
   }
   bind(ast) {
     const scope = new BinderScope();
@@ -14183,6 +14226,8 @@ var Binder = class {
         return this.bindColumnRef(node, scope);
       case "Literal" /* LITERAL */:
         return this.bindLiteral(node);
+      case "Parameter" /* PARAMETER */:
+        return this.bindParameter(node);
       case "BinaryExpr" /* BINARY_EXPR */:
         return this.bindBinaryExpr(node, scope);
       case "UnaryExpr" /* UNARY_EXPR */:
@@ -14296,6 +14341,13 @@ var Binder = class {
     }
     return BoundLiteral(node.value, "VARCHAR" /* VARCHAR */);
   }
+  bindParameter(node) {
+    if (node.index < 1 || node.index > this.params.length) {
+      throw new Error(`Missing value for parameter $${node.index}`);
+    }
+    const value = this.params[node.index - 1];
+    return BoundLiteral(value, valueDataType(value));
+  }
   bindBinaryExpr(node, scope) {
     const left = this.bindExpression(node.left, scope);
     const right = this.bindExpression(node.right, scope);
@@ -20174,7 +20226,7 @@ var DataFrame = class _DataFrame {
   explain() {
     return planToString(this._plan);
   }
-  sql(sqlString) {
+  sql(sqlString, options = {}) {
     const columns = this._schema.fields.map((f) => ({ name: f.name, dataType: f.dataType }));
     return this._engine.sql(sqlString, {
       frames: [{
@@ -20182,7 +20234,8 @@ var DataFrame = class _DataFrame {
         columns,
         plan: this._plan,
         cteMap: this._cteMap
-      }]
+      }],
+      params: options.params
     });
   }
   select(...items) {
@@ -20654,8 +20707,8 @@ var QueryEngine = class {
   parseSQL(sql) {
     return parse(sql);
   }
-  bind(ast) {
-    const binder = new Binder(this.catalog, this.functionRegistry);
+  bind(ast, params = []) {
+    const binder = new Binder(this.catalog, this.functionRegistry, params);
     return binder.bind(ast);
   }
   plan(boundQuery) {
@@ -20664,7 +20717,7 @@ var QueryEngine = class {
   optimize(logicalPlan) {
     return this.optimizer.optimize(logicalPlan);
   }
-  async compile(sql) {
+  async compile(sql, params = []) {
     const ast = this.parseSQL(sql);
     let isExplain = false;
     let isAnalyze = false;
@@ -20679,7 +20732,7 @@ var QueryEngine = class {
     } else if (ast.kind === "CreateTableStmt" || ast.kind === "DropTableStmt") {
       return { ddl: ast };
     }
-    const bound = this.bind(targetAst);
+    const bound = this.bind(targetAst, params);
     const logicalPlan = this.plan(bound);
     let cteMap = logicalPlan._cteMap || /* @__PURE__ */ new Map();
     await this._ensureStatistics();
@@ -20734,7 +20787,7 @@ var QueryEngine = class {
     if (ast.kind === "CreateTableStmt" || ast.kind === "DropTableStmt" || ast.kind === "ExplainStmt" || ast.kind === "ExplainAnalyzeStmt") {
       throw new Error("sql() supports query statements only");
     }
-    const binder = new Binder(this.catalog, this.functionRegistry);
+    const binder = new Binder(this.catalog, this.functionRegistry, options.params);
     for (const frame of options.frames || []) {
       binder.cteScopes.set(frame.name.toUpperCase(), {
         name: frame.name,
@@ -20773,8 +20826,8 @@ var QueryEngine = class {
     const { sink, columnNames } = await this.executor.execute(optimized, outputColumns, streaming);
     return new QueryResult(columnNames, sink);
   }
-  async run(sql) {
-    const compiled = await this.compile(sql);
+  async run(sql, params = []) {
+    const compiled = await this.compile(sql, params);
     if (compiled.ddl) {
       return this.executeDDL(compiled.ddl);
     }

package/dist/parser/ast.d.ts

@@ -11,6 +11,7 @@ export declare enum NodeKind {
     SUBQUERY_REF = "SubqueryRef",
     COLUMN_REF = "ColumnRef",
     LITERAL = "Literal",
+    PARAMETER = "Parameter",
     BINARY_EXPR = "BinaryExpr",
     UNARY_EXPR = "UnaryExpr",
     BETWEEN_EXPR = "BetweenExpr",
@@ -36,7 +37,7 @@ export declare enum NodeKind {
     COLUMN_DEF = "ColumnDef",
     EXPLAIN_ANALYZE_STMT = "ExplainAnalyzeStmt"
 }
-export type Expr = ColumnRefNode | LiteralNode | BinaryExprNode | UnaryExprNode | BetweenExprNode | InExprNode | LikeExprNode | IsNullExprNode | ExistsExprNode | SubqueryExprNode | FunctionCallNode | AggregateCallNode | CaseExprNode | CastExprNode | ExtractExprNode | SubstringExprNode | IntervalExprNode | WindowCallNode | AllColumnsNode;
+export type Expr = ColumnRefNode | LiteralNode | ParameterNode | BinaryExprNode | UnaryExprNode | BetweenExprNode | InExprNode | LikeExprNode | IsNullExprNode | ExistsExprNode | SubqueryExprNode | FunctionCallNode | AggregateCallNode | CaseExprNode | CastExprNode | ExtractExprNode | SubstringExprNode | IntervalExprNode | WindowCallNode | AllColumnsNode;
 export type FromItem = TableRefNode | JoinRefNode | SubqueryRefNode;
 export type QueryStmt = SelectStmtNode | SetOpNode;
 export type Statement = QueryStmt | ExplainStmtNode | ExplainAnalyzeStmtNode | CreateTableStmtNode | DropTableStmtNode;
@@ -113,6 +114,10 @@ export interface LiteralNode {
     value: string | number | boolean | null;
     dataType: string | null;
 }
+export interface ParameterNode {
+    kind: NodeKind.PARAMETER;
+    index: number;
+}
 export interface BinaryExprNode {
     kind: NodeKind.BINARY_EXPR;
     op: string;
@@ -272,6 +277,7 @@ export declare function JoinRef(left: FromItem, right: FromItem, joinType: strin
 export declare function SubqueryRef(query: QueryStmt, alias: string | null): SubqueryRefNode;
 export declare function ColumnRef(name: string, table?: string | null): ColumnRefNode;
 export declare function Literal(value: string | number | boolean | null, dataType?: string | null): LiteralNode;
+export declare function Parameter(index: number): ParameterNode;
 export declare function BinaryExpr(op: string, left: Expr, right: Expr | QuantifiedSubqueryNode): BinaryExprNode;
 export declare function UnaryExpr(op: string, operand: Expr): UnaryExprNode;
 export declare function BetweenExpr(expr: Expr, low: Expr, high: Expr, negated?: boolean): BetweenExprNode;

package/dist/parser/lexer.d.ts

@@ -20,6 +20,7 @@ export declare enum TokenType {
     SEMICOLON = "SEMICOLON",
     CONCAT = "CONCAT",
     COLON = "COLON",
+    PLACEHOLDER = "PLACEHOLDER",
     EOF = "EOF",
     EXPLAIN = "EXPLAIN",
     SELECT = "SELECT",
@@ -126,6 +127,7 @@ export declare class Lexer {
     _tokenize(): void;
     _skipWhitespaceAndComments(): void;
     _readString(start: number): Token;
+    _readPlaceholder(start: number): Token;
     _readNumber(start: number): Token;
     _readIdentOrKeyword(start: number): Token;
     _readSymbol(start: number): Token;

package/package.json

@@ -1,60 +1,59 @@
-{
-  "name": "@slexisvn/query-engine",
-  "version": "0.1.0",
-  "type": "module",
-  "main": "./dist/index.node.js",
-  "module": "./dist/index.node.js",
-  "browser": "./dist/index.browser.js",
-  "types": "./dist/index.d.ts",
-  "bin": {
-    "qe": "./dist/index.cli.js"
-  },
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "browser": "./dist/index.browser.js",
-      "import": "./dist/index.node.js",
-      "default": "./dist/index.node.js"
-    },
-    "./browser": {
-      "types": "./dist/browser.d.ts",
-      "import": "./dist/index.browser.js",
-      "default": "./dist/index.browser.js"
-    },
-    "./cli": "./dist/index.cli.js",
-    "./core.wasm": "./dist/core.wasm",
-    "./package.json": "./package.json"
-  },
-  "files": [
-    "dist/index.node.js",
-    "dist/index.browser.js",
-    "dist/index.cli.js",
-    "dist/core.wasm",
-    "dist/**/*.d.ts"
-  ],
-  "publishConfig": {
-    "access": "public"
-  },
-  "scripts": {
-    "typecheck": "tsc --noEmit",
-    "build": "node scripts/build.js && npm run build:wasm && tsc -p tsconfig.build.json",
-    "build:wasm": "asc --config src/wasm/assembly/asconfig.json --target release",
-    "prepack": "npm run build",
-    "test": "vitest run",
-    "start": "node dist/index.cli.js"
-  },
-  "devDependencies": {
-    "@types/node": "^22.19.21",
-    "@vitest/coverage-v8": "^3.2.6",
-    "assemblyscript": "^0.27.0",
-    "buffer": "^6.0.3",
-    "esbuild": "^0.25.0",
-    "typescript": "^6.0.3",
-    "vitest": "^3.2.1"
-  },
-  "dependencies": {
-    "@assemblyscript/loader": "^0.27.0",
-    "cli-highlight": "^2.1.11",
-    "csv-parser": "^3.2.1"
-  }
-}
+{
+  "name": "@slexisvn/query-engine",
+  "version": "0.1.2",
+  "type": "module",
+  "main": "./dist/index.node.js",
+  "module": "./dist/index.node.js",
+  "browser": "./dist/index.browser.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "qe": "./dist/index.cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "browser": "./dist/index.browser.js",
+      "import": "./dist/index.node.js",
+      "default": "./dist/index.node.js"
+    },
+    "./browser": {
+      "types": "./dist/browser.d.ts",
+      "import": "./dist/index.browser.js",
+      "default": "./dist/index.browser.js"
+    },
+    "./cli": "./dist/index.cli.js",
+    "./core.wasm": "./dist/core.wasm",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist/index.node.js",
+    "dist/index.browser.js",
+    "dist/index.cli.js",
+    "dist/core.wasm",
+    "dist/**/*.d.ts"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "build": "node scripts/build.js && npm run build:wasm && tsc -p tsconfig.build.json",
+    "build:wasm": "asc --config src/wasm/assembly/asconfig.json --target release",
+    "test": "vitest run",
+    "start": "node dist/index.cli.js"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.21",
+    "@vitest/coverage-v8": "^3.2.6",
+    "assemblyscript": "^0.27.0",
+    "buffer": "^6.0.3",
+    "esbuild": "^0.25.0",
+    "typescript": "^6.0.3",
+    "vitest": "^3.2.1"
+  },
+  "dependencies": {
+    "@assemblyscript/loader": "^0.27.0",
+    "cli-highlight": "^2.1.11",
+    "csv-parser": "^3.2.1"
+  }
+}