@undefineds.co/xpod 0.1.0-local.202602081751

package/dist/storage/sparql/AlgebraUtils.js

@@ -0,0 +1,118 @@
+"use strict";
+/**
+ * AlgebraUtils - SPARQL algebra tree traversal utilities
+ *
+ * Provides helper functions for working with SPARQL algebra trees:
+ * - Variable extraction
+ * - Term extraction from expressions
+ * - Literal value extraction
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractVariable = extractVariable;
+exports.extractStrVariable = extractStrVariable;
+exports.extractLiteralValue = extractLiteralValue;
+exports.extractLiteral = extractLiteral;
+exports.extractTerm = extractTerm;
+exports.extractVariables = extractVariables;
+exports.isVariableInPattern = isVariableInPattern;
+exports.getVariablePosition = getVariablePosition;
+/**
+ * Extract variable name from an expression
+ * Returns the variable name (without ?) if it's a variable, null otherwise
+ */
+function extractVariable(expr) {
+    if (expr.expressionType === 'term' && expr.term.termType === 'Variable') {
+        return expr.term.value;
+    }
+    return null;
+}
+/**
+ * Extract variable name from STR(?var) expression
+ * Handles both direct variable and STR() wrapped variable
+ */
+function extractStrVariable(expr) {
+    // Direct variable
+    const direct = extractVariable(expr);
+    if (direct)
+        return direct;
+    // STR(?var)
+    if (expr.expressionType === 'operator') {
+        const opExpr = expr;
+        if (opExpr.operator === 'str' && opExpr.args.length === 1) {
+            return extractVariable(opExpr.args[0]);
+        }
+    }
+    return null;
+}
+/**
+ * Extract literal value from an expression
+ * Returns the string value if it's a literal, null otherwise
+ */
+function extractLiteralValue(expr) {
+    if (expr.expressionType === 'term' && expr.term.termType === 'Literal') {
+        return expr.term.value;
+    }
+    return null;
+}
+/**
+ * Extract literal with datatype from an expression
+ */
+function extractLiteral(expr) {
+    if (expr.expressionType === 'term' && expr.term.termType === 'Literal') {
+        const lit = expr.term;
+        return {
+            value: lit.value,
+            datatype: lit.datatype?.value
+        };
+    }
+    return null;
+}
+/**
+ * Extract a term from an expression
+ */
+function extractTerm(expr) {
+    if (expr.expressionType === 'term') {
+        return expr.term;
+    }
+    return null;
+}
+/**
+ * Extract all variables from a pattern
+ */
+function extractVariables(pattern) {
+    const vars = [];
+    const seen = new Set();
+    for (const pos of ['subject', 'predicate', 'object', 'graph']) {
+        const term = pattern[pos];
+        if (term && term.termType === 'Variable' && !seen.has(term.value)) {
+            seen.add(term.value);
+            vars.push(term);
+        }
+    }
+    return vars;
+}
+/**
+ * Check if a variable is used in a pattern position
+ */
+function isVariableInPattern(varName, pattern) {
+    for (const pos of ['subject', 'predicate', 'object', 'graph']) {
+        const term = pattern[pos];
+        if (term && term.termType === 'Variable' && term.value === varName) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Get the position of a variable in a pattern
+ */
+function getVariablePosition(varName, pattern) {
+    for (const pos of ['subject', 'predicate', 'object', 'graph']) {
+        const term = pattern[pos];
+        if (term && term.termType === 'Variable' && term.value === varName) {
+            return pos;
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=AlgebraUtils.js.map

package/dist/storage/sparql/AlgebraUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AlgebraUtils.js","sourceRoot":"","sources":["../../../src/storage/sparql/AlgebraUtils.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * AlgebraUtils - SPARQL algebra tree traversal utilities\n * \n * Provides helper functions for working with SPARQL algebra trees:\n * - Variable extraction\n * - Term extraction from expressions\n * - Literal value extraction\n */\n\nimport type { Term, Variable } from '@rdfjs/types';\nimport type { Algebra } from 'sparqlalgebrajs';\n\n/**\n * Extract variable name from an expression\n * Returns the variable name (without ?) if it's a variable, null otherwise\n */\nexport function extractVariable(expr: Algebra.Expression): string | null {\n  if (expr.expressionType === 'term' && expr.term.termType === 'Variable') {\n    return expr.term.value;\n  }\n  return null;\n}\n\n/**\n * Extract variable name from STR(?var) expression\n * Handles both direct variable and STR() wrapped variable\n */\nexport function extractStrVariable(expr: Algebra.Expression): string | null {\n  // Direct variable\n  const direct = extractVariable(expr);\n  if (direct) return direct;\n  \n  // STR(?var)\n  if (expr.expressionType === 'operator') {\n    const opExpr = expr as Algebra.OperatorExpression;\n    if (opExpr.operator === 'str' && opExpr.args.length === 1) {\n      return extractVariable(opExpr.args[0]);\n    }\n  }\n  return null;\n}\n\n/**\n * Extract literal value from an expression\n * Returns the string value if it's a literal, null otherwise\n */\nexport function extractLiteralValue(expr: Algebra.Expression): string | null {\n  if (expr.expressionType === 'term' && expr.term.termType === 'Literal') {\n    return expr.term.value;\n  }\n  return null;\n}\n\n/**\n * Extract literal with datatype from an expression\n */\nexport function extractLiteral(expr: Algebra.Expression): { value: string; datatype?: string } | null {\n  if (expr.expressionType === 'term' && expr.term.termType === 'Literal') {\n    const lit = expr.term as any;\n    return {\n      value: lit.value,\n      datatype: lit.datatype?.value\n    };\n  }\n  return null;\n}\n\n/**\n * Extract a term from an expression\n */\nexport function extractTerm(expr: Algebra.Expression): Term | null {\n  if (expr.expressionType === 'term') {\n    return expr.term;\n  }\n  return null;\n}\n\n/**\n * Extract all variables from a pattern\n */\nexport function extractVariables(pattern: Algebra.Pattern): Variable[] {\n  const vars: Variable[] = [];\n  const seen = new Set<string>();\n  \n  for (const pos of ['subject', 'predicate', 'object', 'graph'] as const) {\n    const term = pattern[pos];\n    if (term && term.termType === 'Variable' && !seen.has(term.value)) {\n      seen.add(term.value);\n      vars.push(term);\n    }\n  }\n  \n  return vars;\n}\n\n/**\n * Check if a variable is used in a pattern position\n */\nexport function isVariableInPattern(varName: string, pattern: Algebra.Pattern): boolean {\n  for (const pos of ['subject', 'predicate', 'object', 'graph'] as const) {\n    const term = pattern[pos];\n    if (term && term.termType === 'Variable' && term.value === varName) {\n      return true;\n    }\n  }\n  return false;\n}\n\n/**\n * Get the position of a variable in a pattern\n */\nexport function getVariablePosition(varName: string, pattern: Algebra.Pattern): 'subject' | 'predicate' | 'object' | 'graph' | null {\n  for (const pos of ['subject', 'predicate', 'object', 'graph'] as const) {\n    const term = pattern[pos];\n    if (term && term.termType === 'Variable' && term.value === varName) {\n      return pos;\n    }\n  }\n  return null;\n}\n"]}

package/dist/storage/sparql/ComunicaOptimizedEngine.d.ts

@@ -0,0 +1,59 @@
+/**
+ * ComunicaOptimizedEngine - 基于 Comunica 的优化查询引擎
+ *
+ * 通过自定义 Source 实现查询下推优化：
+ * 1. 在查询执行前分析 SPARQL，提取 LIMIT/ORDER BY 等优化参数
+ * 2. 将参数存储在 Engine 实例上
+ * 3. 自定义 Source 在 match() 时读取这些参数并传给 quadstore
+ */
+import type { Quad } from '@rdfjs/types';
+import type { Bindings, ResultStream } from '@rdfjs/types';
+import { Quadstore } from 'quadstore';
+export interface ComunicaOptimizedEngineOptions {
+    debug?: boolean;
+}
+export interface QueryContext {
+    sources?: unknown[];
+    baseIRI?: string;
+    [key: string]: unknown;
+}
+export declare class ComunicaOptimizedEngine {
+    private readonly store;
+    private readonly source;
+    private readonly engine;
+    private readonly debug;
+    private currentOptimizeParams;
+    constructor(store: Quadstore, options?: ComunicaOptimizedEngineOptions);
+    /**
+     * 执行 SELECT 查询
+     */
+    queryBindings(query: string, context?: QueryContext): Promise<ResultStream<Bindings>>;
+    /**
+     * 执行 ASK 查询
+     */
+    queryBoolean(query: string, context?: QueryContext): Promise<boolean>;
+    /**
+     * 执行 CONSTRUCT/DESCRIBE 查询
+     */
+    queryQuads(query: string, context?: QueryContext): Promise<ResultStream<Quad>>;
+    /**
+     * 执行 UPDATE 查询
+     */
+    queryVoid(query: string, context?: QueryContext): Promise<void>;
+    /**
+     * 分析查询，提取优化参数
+     */
+    private analyzeQuery;
+    /**
+     * 从 Algebra 提取优化参数
+     *
+     * 只提取可以安全下推的参数：
+     * - LIMIT（对于单 BGP 查询可以直接下推）
+     * - ORDER BY（简单变量排序）
+     */
+    private extractOptimizeParams;
+    /**
+     * 将 SPARQL 变量名映射到 quadstore 的 TermName
+     */
+    private variableToTermName;
+}

package/dist/storage/sparql/ComunicaOptimizedEngine.js

@@ -0,0 +1,254 @@
+"use strict";
+/**
+ * ComunicaOptimizedEngine - 基于 Comunica 的优化查询引擎
+ *
+ * 通过自定义 Source 实现查询下推优化：
+ * 1. 在查询执行前分析 SPARQL，提取 LIMIT/ORDER BY 等优化参数
+ * 2. 将参数存储在 Engine 实例上
+ * 3. 自定义 Source 在 match() 时读取这些参数并传给 quadstore
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ComunicaOptimizedEngine = void 0;
+const query_sparql_rdfjs_1 = require("@comunica/query-sparql-rdfjs");
+const sparqlalgebrajs_1 = require("sparqlalgebrajs");
+const asynciterator_1 = require("asynciterator");
+/**
+ * 自定义 RDF/JS Source，通过闭包访问优化参数
+ */
+class OptimizedSource {
+    constructor(store, getParams, debug) {
+        this.store = store;
+        this.getParams = getParams;
+        this.debug = debug;
+    }
+    match(subject, predicate, object, graph) {
+        // 构建 quadstore pattern
+        const pattern = {};
+        if (subject && subject.termType !== 'Variable') {
+            pattern.subject = subject;
+        }
+        if (predicate && predicate.termType !== 'Variable') {
+            pattern.predicate = predicate;
+        }
+        if (object && object.termType !== 'Variable') {
+            pattern.object = object;
+        }
+        if (graph && graph.termType !== 'Variable' && graph.termType !== 'DefaultGraph') {
+            pattern.graph = graph;
+        }
+        // 获取优化参数
+        const params = this.getParams();
+        const opts = {};
+        if (params) {
+            if (params.limit !== undefined) {
+                // 如果有 offset，需要多获取一些
+                opts.limit = params.limit + (params.offset ?? 0);
+            }
+            if (params.order !== undefined) {
+                opts.order = params.order;
+            }
+            if (params.reverse !== undefined) {
+                opts.reverse = params.reverse;
+            }
+        }
+        if (this.debug) {
+            console.log(`[OptimizedSource] match() called`);
+            console.log(`  pattern: ${JSON.stringify(pattern)}`);
+            console.log(`  opts: ${JSON.stringify(opts)}`);
+        }
+        // 使用 wrap 函数将 Promise<Array> 转换为 AsyncIterator
+        // wrap 会正确处理空数组的情况
+        const promiseIterator = (0, asynciterator_1.wrap)(this.store.get(pattern, opts).then(result => result.items));
+        return promiseIterator;
+    }
+}
+class ComunicaOptimizedEngine {
+    constructor(store, options) {
+        // 当前查询的优化参数（通过闭包共享给 Source）
+        this.currentOptimizeParams = null;
+        this.store = store;
+        this.debug = options?.debug ?? false;
+        // 创建 Source，通过闭包访问 currentOptimizeParams
+        this.source = new OptimizedSource(store, () => this.currentOptimizeParams, this.debug);
+        this.engine = new query_sparql_rdfjs_1.QueryEngine();
+    }
+    /**
+     * 执行 SELECT 查询
+     */
+    async queryBindings(query, context) {
+        // 分析查询，设置优化参数
+        this.currentOptimizeParams = this.analyzeQuery(query);
+        if (this.debug && this.currentOptimizeParams) {
+            console.log(`[ComunicaOptimizedEngine] Optimization params:`, this.currentOptimizeParams);
+        }
+        try {
+            return await this.engine.queryBindings(query, {
+                sources: [this.source],
+                ...context,
+            });
+        }
+        finally {
+            // 查询完成后清除参数
+            this.currentOptimizeParams = null;
+        }
+    }
+    /**
+     * 执行 ASK 查询
+     */
+    async queryBoolean(query, context) {
+        this.currentOptimizeParams = this.analyzeQuery(query);
+        // 对于 ASK，设置 limit=1 优化
+        if (!this.currentOptimizeParams) {
+            this.currentOptimizeParams = { limit: 1 };
+        }
+        else if (this.currentOptimizeParams.limit === undefined) {
+            this.currentOptimizeParams.limit = 1;
+        }
+        try {
+            return await this.engine.queryBoolean(query, {
+                sources: [this.source],
+                ...context,
+            });
+        }
+        finally {
+            this.currentOptimizeParams = null;
+        }
+    }
+    /**
+     * 执行 CONSTRUCT/DESCRIBE 查询
+     */
+    async queryQuads(query, context) {
+        this.currentOptimizeParams = this.analyzeQuery(query);
+        try {
+            return await this.engine.queryQuads(query, {
+                sources: [this.source],
+                ...context,
+            });
+        }
+        finally {
+            this.currentOptimizeParams = null;
+        }
+    }
+    /**
+     * 执行 UPDATE 查询
+     */
+    async queryVoid(query, context) {
+        // UPDATE 不需要优化
+        return this.engine.queryVoid(query, {
+            sources: [this.source],
+            ...context,
+        });
+    }
+    /**
+     * 分析查询，提取优化参数
+     */
+    analyzeQuery(query) {
+        try {
+            const algebra = (0, sparqlalgebrajs_1.translate)(query, { quads: true });
+            return this.extractOptimizeParams(algebra);
+        }
+        catch (error) {
+            if (this.debug) {
+                console.log(`[ComunicaOptimizedEngine] Failed to analyze query:`, error);
+            }
+            return null;
+        }
+    }
+    /**
+     * 从 Algebra 提取优化参数
+     *
+     * 只提取可以安全下推的参数：
+     * - LIMIT（对于单 BGP 查询可以直接下推）
+     * - ORDER BY（简单变量排序）
+     */
+    extractOptimizeParams(algebra) {
+        let limit;
+        let offset;
+        let order;
+        let reverse;
+        let currentOp = algebra;
+        let canPushLimit = true; // 是否可以下推 LIMIT
+        while (currentOp) {
+            switch (currentOp.type) {
+                case 'slice': {
+                    const slice = currentOp;
+                    if (slice.length !== undefined) {
+                        limit = slice.length;
+                    }
+                    if (slice.start !== undefined) {
+                        offset = slice.start;
+                    }
+                    currentOp = slice.input;
+                    break;
+                }
+                case 'orderby': {
+                    const orderBy = currentOp;
+                    if (orderBy.expressions.length === 1) {
+                        const expr = orderBy.expressions[0];
+                        if (expr.expression.expressionType === 'term' &&
+                            expr.expression.term.termType === 'Variable') {
+                            const varName = expr.expression.term.value;
+                            const termName = this.variableToTermName(varName);
+                            if (termName) {
+                                order = [termName];
+                                reverse = !expr.ascending;
+                            }
+                        }
+                    }
+                    currentOp = orderBy.input;
+                    break;
+                }
+                case 'project':
+                case 'distinct':
+                case 'reduced': {
+                    currentOp = currentOp.input;
+                    break;
+                }
+                case 'bgp': {
+                    const bgp = currentOp;
+                    if (bgp.patterns.length === 1) {
+                        // 单个 triple pattern，可以完全下推
+                        return { limit, offset, order, reverse };
+                    }
+                    // 多个 patterns 需要 JOIN，只能下推到每个 pattern
+                    // 但 LIMIT 不能直接下推（会影响 JOIN 结果）
+                    canPushLimit = false;
+                    return canPushLimit ? { limit, offset, order, reverse } : null;
+                }
+                case 'join':
+                case 'leftjoin':
+                case 'union':
+                case 'minus':
+                    // 复杂操作，不能直接下推 LIMIT
+                    canPushLimit = false;
+                    return null;
+                case 'filter':
+                case 'extend':
+                case 'group':
+                    // 这些操作不支持优化
+                    return null;
+                default:
+                    return null;
+            }
+        }
+        return null;
+    }
+    /**
+     * 将 SPARQL 变量名映射到 quadstore 的 TermName
+     */
+    variableToTermName(varName) {
+        const mapping = {
+            's': 'subject',
+            'subject': 'subject',
+            'p': 'predicate',
+            'predicate': 'predicate',
+            'o': 'object',
+            'object': 'object',
+            'g': 'graph',
+            'graph': 'graph',
+        };
+        return mapping[varName.toLowerCase()] ?? null;
+    }
+}
+exports.ComunicaOptimizedEngine = ComunicaOptimizedEngine;
+//# sourceMappingURL=ComunicaOptimizedEngine.js.map

package/dist/storage/sparql/ComunicaOptimizedEngine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ComunicaOptimizedEngine.js","sourceRoot":"","sources":["../../../src/storage/sparql/ComunicaOptimizedEngine.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * ComunicaOptimizedEngine - 基于 Comunica 的优化查询引擎\n * \n * 通过自定义 Source 实现查询下推优化：\n * 1. 在查询执行前分析 SPARQL，提取 LIMIT/ORDER BY 等优化参数\n * 2. 将参数存储在 Engine 实例上\n * 3. 自定义 Source 在 match() 时读取这些参数并传给 quadstore\n */\n\nimport type { Quad, Term } from '@rdfjs/types';\nimport type { Bindings, ResultStream } from '@rdfjs/types';\nimport type * as RDF from '@rdfjs/types';\nimport { QueryEngine } from '@comunica/query-sparql-rdfjs';\nimport { Quadstore, type TermName, type GetOpts, type Pattern } from 'quadstore';\nimport { translate, type Algebra } from 'sparqlalgebrajs';\nimport { wrap, AsyncIterator } from 'asynciterator';\n\nexport interface ComunicaOptimizedEngineOptions {\n  debug?: boolean;\n}\n\nexport interface QueryContext {\n  sources?: unknown[];\n  baseIRI?: string;\n  [key: string]: unknown;\n}\n\ninterface OptimizeParams {\n  limit?: number;\n  offset?: number;\n  order?: TermName[];\n  reverse?: boolean;\n}\n\n/**\n * 自定义 RDF/JS Source，通过闭包访问优化参数\n */\nclass OptimizedSource implements RDF.Source {\n  constructor(\n    private readonly store: Quadstore,\n    private readonly getParams: () => OptimizeParams | null,\n    private readonly debug: boolean\n  ) {}\n\n  match(\n    subject?: Term | null,\n    predicate?: Term | null,\n    object?: Term | null,\n    graph?: Term | null\n  ): RDF.Stream {\n    // 构建 quadstore pattern\n    const pattern: Pattern = {};\n    if (subject && subject.termType !== 'Variable') {\n      pattern.subject = subject as any;\n    }\n    if (predicate && predicate.termType !== 'Variable') {\n      pattern.predicate = predicate as any;\n    }\n    if (object && object.termType !== 'Variable') {\n      pattern.object = object as any;\n    }\n    if (graph && graph.termType !== 'Variable' && graph.termType !== 'DefaultGraph') {\n      pattern.graph = graph as any;\n    }\n\n    // 获取优化参数\n    const params = this.getParams();\n    const opts: GetOpts = {};\n    \n    if (params) {\n      if (params.limit !== undefined) {\n        // 如果有 offset，需要多获取一些\n        opts.limit = params.limit + (params.offset ?? 0);\n      }\n      if (params.order !== undefined) {\n        opts.order = params.order;\n      }\n      if (params.reverse !== undefined) {\n        opts.reverse = params.reverse;\n      }\n    }\n\n    if (this.debug) {\n      console.log(`[OptimizedSource] match() called`);\n      console.log(`  pattern: ${JSON.stringify(pattern)}`);\n      console.log(`  opts: ${JSON.stringify(opts)}`);\n    }\n\n    // 使用 wrap 函数将 Promise<Array> 转换为 AsyncIterator\n    // wrap 会正确处理空数组的情况\n    const promiseIterator = wrap(\n      this.store.get(pattern, opts).then(result => result.items)\n    );\n\n    return promiseIterator as any;\n  }\n}\n\nexport class ComunicaOptimizedEngine {\n  private readonly store: Quadstore;\n  private readonly source: OptimizedSource;\n  private readonly engine: QueryEngine;\n  private readonly debug: boolean;\n  \n  // 当前查询的优化参数（通过闭包共享给 Source）\n  private currentOptimizeParams: OptimizeParams | null = null;\n\n  constructor(store: Quadstore, options?: ComunicaOptimizedEngineOptions) {\n    this.store = store;\n    this.debug = options?.debug ?? false;\n    \n    // 创建 Source，通过闭包访问 currentOptimizeParams\n    this.source = new OptimizedSource(\n      store,\n      () => this.currentOptimizeParams,\n      this.debug\n    );\n    \n    this.engine = new QueryEngine();\n  }\n\n  /**\n   * 执行 SELECT 查询\n   */\n  async queryBindings(query: string, context?: QueryContext): Promise<ResultStream<Bindings>> {\n    // 分析查询，设置优化参数\n    this.currentOptimizeParams = this.analyzeQuery(query);\n    \n    if (this.debug && this.currentOptimizeParams) {\n      console.log(`[ComunicaOptimizedEngine] Optimization params:`, this.currentOptimizeParams);\n    }\n\n    try {\n      return await this.engine.queryBindings(query, {\n        sources: [this.source],\n        ...context,\n      } as any);\n    } finally {\n      // 查询完成后清除参数\n      this.currentOptimizeParams = null;\n    }\n  }\n\n  /**\n   * 执行 ASK 查询\n   */\n  async queryBoolean(query: string, context?: QueryContext): Promise<boolean> {\n    this.currentOptimizeParams = this.analyzeQuery(query);\n    // 对于 ASK，设置 limit=1 优化\n    if (!this.currentOptimizeParams) {\n      this.currentOptimizeParams = { limit: 1 };\n    } else if (this.currentOptimizeParams.limit === undefined) {\n      this.currentOptimizeParams.limit = 1;\n    }\n    \n    try {\n      return await this.engine.queryBoolean(query, {\n        sources: [this.source],\n        ...context,\n      } as any);\n    } finally {\n      this.currentOptimizeParams = null;\n    }\n  }\n\n  /**\n   * 执行 CONSTRUCT/DESCRIBE 查询\n   */\n  async queryQuads(query: string, context?: QueryContext): Promise<ResultStream<Quad>> {\n    this.currentOptimizeParams = this.analyzeQuery(query);\n    \n    try {\n      return await this.engine.queryQuads(query, {\n        sources: [this.source],\n        ...context,\n      } as any);\n    } finally {\n      this.currentOptimizeParams = null;\n    }\n  }\n\n  /**\n   * 执行 UPDATE 查询\n   */\n  async queryVoid(query: string, context?: QueryContext): Promise<void> {\n    // UPDATE 不需要优化\n    return this.engine.queryVoid(query, {\n      sources: [this.source],\n      ...context,\n    } as any);\n  }\n\n  /**\n   * 分析查询，提取优化参数\n   */\n  private analyzeQuery(query: string): OptimizeParams | null {\n    try {\n      const algebra = translate(query, { quads: true });\n      return this.extractOptimizeParams(algebra);\n    } catch (error) {\n      if (this.debug) {\n        console.log(`[ComunicaOptimizedEngine] Failed to analyze query:`, error);\n      }\n      return null;\n    }\n  }\n\n  /**\n   * 从 Algebra 提取优化参数\n   * \n   * 只提取可以安全下推的参数：\n   * - LIMIT（对于单 BGP 查询可以直接下推）\n   * - ORDER BY（简单变量排序）\n   */\n  private extractOptimizeParams(algebra: Algebra.Operation): OptimizeParams | null {\n    let limit: number | undefined;\n    let offset: number | undefined;\n    let order: TermName[] | undefined;\n    let reverse: boolean | undefined;\n    let currentOp = algebra;\n    let canPushLimit = true;  // 是否可以下推 LIMIT\n\n    while (currentOp) {\n      switch (currentOp.type) {\n        case 'slice': {\n          const slice = currentOp as Algebra.Slice;\n          if (slice.length !== undefined) {\n            limit = slice.length;\n          }\n          if (slice.start !== undefined) {\n            offset = slice.start;\n          }\n          currentOp = slice.input;\n          break;\n        }\n        \n        case 'orderby': {\n          const orderBy = currentOp as Algebra.OrderBy;\n          if (orderBy.expressions.length === 1) {\n            const expr = orderBy.expressions[0];\n            if (expr.expression.expressionType === 'term' && \n                expr.expression.term.termType === 'Variable') {\n              const varName = expr.expression.term.value;\n              const termName = this.variableToTermName(varName);\n              if (termName) {\n                order = [termName];\n                reverse = !expr.ascending;\n              }\n            }\n          }\n          currentOp = orderBy.input;\n          break;\n        }\n\n        case 'project':\n        case 'distinct':\n        case 'reduced': {\n          currentOp = (currentOp as any).input;\n          break;\n        }\n\n        case 'bgp': {\n          const bgp = currentOp as Algebra.Bgp;\n          if (bgp.patterns.length === 1) {\n            // 单个 triple pattern，可以完全下推\n            return { limit, offset, order, reverse };\n          }\n          // 多个 patterns 需要 JOIN，只能下推到每个 pattern\n          // 但 LIMIT 不能直接下推（会影响 JOIN 结果）\n          canPushLimit = false;\n          return canPushLimit ? { limit, offset, order, reverse } : null;\n        }\n\n        case 'join':\n        case 'leftjoin':\n        case 'union':\n        case 'minus':\n          // 复杂操作，不能直接下推 LIMIT\n          canPushLimit = false;\n          return null;\n\n        case 'filter':\n        case 'extend':\n        case 'group':\n          // 这些操作不支持优化\n          return null;\n\n        default:\n          return null;\n      }\n    }\n\n    return null;\n  }\n\n  /**\n   * 将 SPARQL 变量名映射到 quadstore 的 TermName\n   */\n  private variableToTermName(varName: string): TermName | null {\n    const mapping: Record<string, TermName> = {\n      's': 'subject',\n      'subject': 'subject',\n      'p': 'predicate',\n      'predicate': 'predicate',\n      'o': 'object',\n      'object': 'object',\n      'g': 'graph',\n      'graph': 'graph',\n    };\n    return mapping[varName.toLowerCase()] ?? null;\n  }\n}\n"]}

package/dist/storage/sparql/ComunicaQuintEngine.d.ts

@@ -0,0 +1,134 @@
+/**
+ * ComunicaQuintEngine - Comunica SPARQL engine backed by QuintStore
+ *
+ * Features:
+ * 1. Query pushdown optimization (LIMIT/ORDER BY)
+ * 2. FILTER pushdown via IQuerySource interface
+ * 3. External filters for security boundaries (ACL)
+ * 4. OPTIONAL optimization via QueryOptimizer
+ *
+ * Architecture:
+ * - Uses QuintQuerySource (IQuerySource) for proper FILTER pushdown
+ * - Uses QueryOptimizer for OPTIONAL and Compound Query optimization
+ * - Comunica pushes FILTER operations down to sources that declare support
+ * - QuintQuerySource extracts filters from algebra and applies them to QuintStore
+ */
+import type { Quad, Bindings, ResultStream } from '@rdfjs/types';
+import { type Algebra } from 'sparqlalgebrajs';
+import type { QuintStore, TermOperators } from '../quint/types';
+export interface ComunicaQuintEngineOptions {
+    debug?: boolean;
+}
+/**
+ * Security/ACL filters passed from upstream
+ * These are applied unconditionally to restrict query scope
+ */
+export interface SecurityFilters {
+    subject?: TermOperators;
+    predicate?: TermOperators;
+    object?: TermOperators;
+    graph?: TermOperators;
+}
+export interface QueryContext {
+    sources?: unknown[];
+    baseIRI?: string;
+    /** Security filters for access control */
+    filters?: SecurityFilters;
+    [key: string]: unknown;
+}
+/**
+ * Query analysis result (stateless)
+ */
+export interface QueryAnalysis {
+    hasFilter: boolean;
+    filterTypes: string[];
+    pushdownable: string[];
+    nonPushdownable: string[];
+    estimatedPushdownRate: number;
+}
+export declare class ComunicaQuintEngine {
+    private readonly store;
+    private readonly rdfStore;
+    private readonly querySource;
+    private readonly queryOptimizer;
+    private readonly simpleExecutor;
+    private readonly engine;
+    private readonly debug;
+    private bindingsFactory;
+    private currentOptimizeParams;
+    private currentSecurityFilters;
+    private currentFilterExpressions;
+    constructor(store: QuintStore, options?: ComunicaQuintEngineOptions);
+    /**
+     * Analyze a query's pushdown potential (stateless)
+     * Returns analysis of what can/cannot be pushed down without executing the query
+     */
+    analyzeQuery(query: string): QueryAnalysis;
+    /**
+     * Analyze algebra tree for pushdown potential
+     */
+    private analyzeAlgebra;
+    /**
+     * Walk algebra tree and collect filter info
+     */
+    private walkAlgebra;
+    /**
+     * Analyze a filter expression
+     */
+    private analyzeExpression;
+    /**
+     * Execute SELECT query
+     * Uses IQuerySource for proper FILTER pushdown
+     *
+     * OPTIONAL 优化：
+     * 如果查询包含多个 OPTIONAL 且只是获取属性（不参与过滤），
+     * 则先执行核心条件获取 subjects，再批量获取属性
+     */
+    queryBindings(query: string, context?: QueryContext): Promise<ResultStream<Bindings>>;
+    /**
+     * 执行核心查询（不含 OPTIONAL）
+     */
+    private executeCoreQuery;
+    /**
+     * Extract FILTER expressions from query and store them for later pushdown
+     * Maps variable names to their filter expressions
+     */
+    private extractAndStoreFilters;
+    /**
+     * Recursively collect FILTER expressions and their variable bindings
+     */
+    private collectFilterExpressions;
+    /**
+     * Get variable names from an expression
+     */
+    private getExpressionVariables;
+    /**
+     * Get the current filter expression for a variable (used by QuintQuerySource)
+     */
+    getFilterExpressionForVariable(varName: string): Algebra.Expression | undefined;
+    /**
+     * Execute ASK query
+     */
+    queryBoolean(query: string, context?: QueryContext): Promise<boolean>;
+    /**
+     * Execute CONSTRUCT/DESCRIBE query
+     */
+    queryQuads(query: string, context?: QueryContext): Promise<ResultStream<Quad>>;
+    /**
+     * Execute UPDATE query (INSERT/DELETE)
+     * Uses RDF.Store interface since UPDATE doesn't need FILTER pushdown
+     */
+    queryVoid(query: string, context?: QueryContext): Promise<void>;
+    /**
+     * Extract optimization params from SPARQL query
+     */
+    private extractOptimizeParams;
+    /**
+     * Extract optimization params from SPARQL algebra
+     */
+    private extractOptimizeParamsFromAlgebra;
+    /**
+     * Map SPARQL variable name to TermName
+     */
+    private variableToTermName;
+}