leangraph 1.1.2 → 1.1.3

package/dist/executor.js

@@ -1,6 +1,8 @@
 // Query Executor - Full pipeline: Cypher → Parse → Translate → Execute → Format
 import { parse, } from "./parser.js";
 import { Translator } from "./translator.js";
+import { HybridExecutor } from "./engine/hybrid-executor.js";
+import { analyzeForHybrid, isHybridCompatiblePattern } from "./engine/query-planner.js";
 // ============================================================================
 // Timezone Helpers
 // ============================================================================
@@ -80,8 +82,11 @@ export class Executor {
     edgePropertyCache = new Map();
     // Cache for full edge info (type, source_id, target_id) - populated by batchGetEdgeInfo
     edgeInfoCache = new Map();
+    // Hybrid executor for var-length pattern queries
+    hybridExecutor;
     constructor(db) {
         this.db = db;
+        this.hybridExecutor = new HybridExecutor(db);
     }
     /**
      * Get node properties from cache or parse from JSON string and cache them
@@ -222,70 +227,80 @@ export class Executor {
                     },
                 };
             };
+            // EXPLAIN and PROFILE queries should go directly to SQL translation
+            // Skip special execution paths for these
+            const isExplainOrProfile = parseResult.query.explain || parseResult.query.profile;
             // Dispatch based on pattern (each try* method still validates and may return null)
-            switch (pattern) {
-                case "PHASED": {
-                    const result = this.tryPhasedExecution(parseResult.query, params);
-                    if (result !== null)
-                        return makeResult(result);
-                    break;
-                }
-                case "UNWIND_CREATE": {
-                    const result = this.tryUnwindCreateExecution(parseResult.query, params);
-                    if (result !== null)
-                        return makeResult(result);
-                    break;
-                }
-                case "UNWIND_MERGE": {
-                    const result = this.tryUnwindMergeExecution(parseResult.query, params);
-                    if (result !== null)
-                        return makeResult(result);
-                    break;
-                }
-                case "COLLECT_UNWIND": {
-                    const result = this.tryCollectUnwindExecution(parseResult.query, params);
-                    if (result !== null)
-                        return makeResult(result);
-                    break;
-                }
-                case "COLLECT_DELETE": {
-                    const result = this.tryCollectDeleteExecution(parseResult.query, params);
-                    if (result !== null)
-                        return makeResult(result);
-                    break;
-                }
-                case "CREATE_RETURN": {
-                    const result = this.tryCreateReturnExecution(parseResult.query, params);
-                    if (result !== null)
-                        return makeResult(result);
-                    break;
-                }
-                case "BOUND_REL_LIST": {
-                    const result = this.tryBoundRelationshipListExecution(parseResult.query, params);
-                    if (result !== null)
-                        return makeResult(result);
-                    break;
-                }
-                case "MERGE": {
-                    const result = this.tryMergeExecution(parseResult.query, params);
-                    if (result !== null)
-                        return makeResult(result);
-                    break;
-                }
-                case "MULTI_PHASE": {
-                    const result = this.tryMultiPhaseExecution(parseResult.query, params);
-                    if (result !== null)
-                        return makeResult(result);
-                    break;
-                }
-                case "FOREACH": {
-                    const result = this.tryForeachExecution(parseResult.query, params);
-                    if (result !== null)
-                        return makeResult(result);
-                    break;
+            if (!isExplainOrProfile)
+                switch (pattern) {
+                    case "PHASED": {
+                        const result = this.tryPhasedExecution(parseResult.query, params);
+                        if (result !== null)
+                            return makeResult(result);
+                        break;
+                    }
+                    case "UNWIND_CREATE": {
+                        const result = this.tryUnwindCreateExecution(parseResult.query, params);
+                        if (result !== null)
+                            return makeResult(result);
+                        break;
+                    }
+                    case "UNWIND_MERGE": {
+                        const result = this.tryUnwindMergeExecution(parseResult.query, params);
+                        if (result !== null)
+                            return makeResult(result);
+                        break;
+                    }
+                    case "COLLECT_UNWIND": {
+                        const result = this.tryCollectUnwindExecution(parseResult.query, params);
+                        if (result !== null)
+                            return makeResult(result);
+                        break;
+                    }
+                    case "COLLECT_DELETE": {
+                        const result = this.tryCollectDeleteExecution(parseResult.query, params);
+                        if (result !== null)
+                            return makeResult(result);
+                        break;
+                    }
+                    case "CREATE_RETURN": {
+                        const result = this.tryCreateReturnExecution(parseResult.query, params);
+                        if (result !== null)
+                            return makeResult(result);
+                        break;
+                    }
+                    case "BOUND_REL_LIST": {
+                        const result = this.tryBoundRelationshipListExecution(parseResult.query, params);
+                        if (result !== null)
+                            return makeResult(result);
+                        break;
+                    }
+                    case "MERGE": {
+                        const result = this.tryMergeExecution(parseResult.query, params);
+                        if (result !== null)
+                            return makeResult(result);
+                        break;
+                    }
+                    case "MULTI_PHASE": {
+                        const result = this.tryMultiPhaseExecution(parseResult.query, params);
+                        if (result !== null)
+                            return makeResult(result);
+                        break;
+                    }
+                    case "FOREACH": {
+                        const result = this.tryForeachExecution(parseResult.query, params);
+                        if (result !== null)
+                            return makeResult(result);
+                        break;
+                    }
+                    case "HYBRID_VAR_LENGTH": {
+                        const result = this.tryHybridVarLengthExecution(parseResult.query, params);
+                        if (result !== null)
+                            return makeResult(result);
+                        break;
+                    }
+                    // STANDARD falls through to SQL translation below
                 }
-                // STANDARD falls through to SQL translation below
-            }
             // 3. Standard single-phase execution: Translate to SQL
             const translator = new Translator(params);
             const translation = translator.translate(parseResult.query);
@@ -295,8 +310,9 @@ export class Executor {
             this.db.transaction(() => {
                 for (const stmt of translation.statements) {
                     const result = this.db.execute(stmt.sql, stmt.params);
-                    // If this is a SELECT (RETURN clause), capture the results
-                    if (result.rows.length > 0 || stmt.sql.trim().toUpperCase().startsWith("SELECT")) {
+                    // If this is a SELECT or EXPLAIN (RETURN clause), capture the results
+                    const sqlUpper = stmt.sql.trim().toUpperCase();
+                    if (result.rows.length > 0 || sqlUpper.startsWith("SELECT") || sqlUpper.startsWith("EXPLAIN")) {
                         rows = result.rows;
                     }
                 }
@@ -559,7 +575,11 @@ export class Executor {
                 }
             }
         }
-        // 11. STANDARD - Default SQL translation
+        // 11. HYBRID_VAR_LENGTH - Var-length pattern suitable for hybrid execution
+        if (isHybridCompatiblePattern(query)) {
+            return "HYBRID_VAR_LENGTH";
+        }
+        // 12. STANDARD - Default SQL translation
         return "STANDARD";
     }
     /**
@@ -1976,7 +1996,7 @@ export class Executor {
     executeCreateNodeInContext(pattern, rowContext, globalContext, params) {
         const id = crypto.randomUUID();
         const labelJson = this.normalizeLabelToJson(pattern.label);
-        const props = this.resolvePropertiesInContext(pattern.properties || {}, rowContext, params);
+        const props = this.resolveNodePatternProperties(pattern, params, rowContext);
         this.db.execute("INSERT INTO nodes (id, label, properties) VALUES (?, ?, ?)", [id, labelJson, JSON.stringify(props)]);
         if (pattern.variable) {
             // Store as a node object with _nf_id for consistency with MATCH output
@@ -2031,7 +2051,7 @@ export class Executor {
         else {
             // Create new source node
             sourceId = crypto.randomUUID();
-            const props = this.resolvePropertiesInContext(pattern.source.properties || {}, rowContext, params);
+            const props = this.resolveNodePatternProperties(pattern.source, params, rowContext);
             this.db.execute("INSERT INTO nodes (id, label, properties) VALUES (?, ?, ?)", [sourceId, this.normalizeLabelToJson(pattern.source.label), JSON.stringify(props)]);
             if (pattern.source.variable) {
                 rowContext.set(pattern.source.variable, sourceId);
@@ -2052,7 +2072,7 @@ export class Executor {
         else {
             // Create new target node
             targetId = crypto.randomUUID();
-            const props = this.resolvePropertiesInContext(pattern.target.properties || {}, rowContext, params);
+            const props = this.resolveNodePatternProperties(pattern.target, params, rowContext);
             this.db.execute("INSERT INTO nodes (id, label, properties) VALUES (?, ?, ?)", [targetId, this.normalizeLabelToJson(pattern.target.label), JSON.stringify(props)]);
             if (pattern.target.variable) {
                 rowContext.set(pattern.target.variable, targetId);
@@ -3830,7 +3850,13 @@ export class Executor {
             case "+": return leftNum + rightNum;
             case "-": return leftNum - rightNum;
             case "*": return leftNum * rightNum;
-            case "/": return leftNum / rightNum;
+            case "/": {
+                // Cypher integer division: if both operands are integers, truncate toward zero
+                if (Number.isInteger(leftNum) && Number.isInteger(rightNum)) {
+                    return Math.trunc(leftNum / rightNum);
+                }
+                return leftNum / rightNum;
+            }
             case "%": return leftNum % rightNum;
             case "^": return Math.pow(leftNum, rightNum);
             default: return null;
@@ -3864,7 +3890,13 @@ export class Executor {
                 case "+": return leftNum + rightNum;
                 case "-": return leftNum - rightNum;
                 case "*": return leftNum * rightNum;
-                case "/": return leftNum / rightNum;
+                case "/": {
+                    // Cypher integer division: if both operands are integers, truncate toward zero
+                    if (Number.isInteger(leftNum) && Number.isInteger(rightNum)) {
+                        return Math.trunc(leftNum / rightNum);
+                    }
+                    return leftNum / rightNum;
+                }
                 case "%": return leftNum % rightNum;
                 case "^": return Math.pow(leftNum, rightNum);
                 default: return null;
@@ -4548,12 +4580,20 @@ export class Executor {
         else if (expr.type === "binary") {
             const left = this.evaluateExpressionWithPropertyAliases(expr.left, resolvedIds, capturedPropertyValues, propertyAliasMap, params);
             const right = this.evaluateExpressionWithPropertyAliases(expr.right, resolvedIds, capturedPropertyValues, propertyAliasMap, params);
+            const leftNum = left;
+            const rightNum = right;
             switch (expr.operator) {
-                case "+": return left + right;
-                case "-": return left - right;
-                case "*": return left * right;
-                case "/": return left / right;
-                case "%": return left % right;
+                case "+": return leftNum + rightNum;
+                case "-": return leftNum - rightNum;
+                case "*": return leftNum * rightNum;
+                case "/": {
+                    // Cypher integer division: if both operands are integers, truncate toward zero
+                    if (Number.isInteger(leftNum) && Number.isInteger(rightNum)) {
+                        return Math.trunc(leftNum / rightNum);
+                    }
+                    return leftNum / rightNum;
+                }
+                case "%": return leftNum % rightNum;
                 default: return null;
             }
         }
@@ -4593,12 +4633,20 @@ export class Executor {
         else if (expr.type === "binary") {
             const left = this.evaluateExpressionForFilter(expr.left, createdIds, params);
             const right = this.evaluateExpressionForFilter(expr.right, createdIds, params);
+            const leftNum = left;
+            const rightNum = right;
             switch (expr.operator) {
-                case "+": return left + right;
-                case "-": return left - right;
-                case "*": return left * right;
-                case "/": return left / right;
-                case "%": return left % right;
+                case "+": return leftNum + rightNum;
+                case "-": return leftNum - rightNum;
+                case "*": return leftNum * rightNum;
+                case "/": {
+                    // Cypher integer division: if both operands are integers, truncate toward zero
+                    if (Number.isInteger(leftNum) && Number.isInteger(rightNum)) {
+                        return Math.trunc(leftNum / rightNum);
+                    }
+                    return leftNum / rightNum;
+                }
+                case "%": return leftNum % rightNum;
                 default: return null;
             }
         }
@@ -5276,7 +5324,13 @@ export class Executor {
                 case "+": return left + right;
                 case "-": return left - right;
                 case "*": return left * right;
-                case "/": return left / right;
+                case "/": {
+                    // Cypher integer division: if both operands are integers, truncate toward zero
+                    if (Number.isInteger(left) && Number.isInteger(right)) {
+                        return Math.trunc(left / right);
+                    }
+                    return left / right;
+                }
                 case "%": return left % right;
                 case "^": return Math.pow(left, right);
                 default: throw new Error(`Unsupported operator: ${expr.operator}`);
@@ -5302,11 +5356,16 @@ export class Executor {
     }
     /**
      * Resolve properties, including unwind variable references and binary expressions
+     * Note: In Cypher, setting a property to null means the property is not stored.
      */
     resolvePropertiesWithUnwind(props, params, unwindContext) {
         const resolved = {};
         for (const [key, value] of Object.entries(props)) {
-            resolved[key] = this.resolvePropertyValueWithUnwind(value, params, unwindContext);
+            const resolvedValue = this.resolvePropertyValueWithUnwind(value, params, unwindContext);
+            // In Cypher, setting a property to null means the property is not stored
+            if (resolvedValue !== null) {
+                resolved[key] = resolvedValue;
+            }
         }
         return resolved;
     }
@@ -5347,7 +5406,13 @@ export class Executor {
                     case "+": return leftNum + rightNum;
                     case "-": return leftNum - rightNum;
                     case "*": return leftNum * rightNum;
-                    case "/": return leftNum / rightNum;
+                    case "/": {
+                        // Cypher integer division: if both operands are integers, truncate toward zero
+                        if (Number.isInteger(leftNum) && Number.isInteger(rightNum)) {
+                            return Math.trunc(leftNum / rightNum);
+                        }
+                        return leftNum / rightNum;
+                    }
                     case "%": return leftNum % rightNum;
                     case "^": return Math.pow(leftNum, rightNum);
                     default: return null;
@@ -5741,7 +5806,7 @@ export class Executor {
                     // Handle node pattern
                     const id = crypto.randomUUID();
                     const labelJson = this.normalizeLabelToJson(pattern.label);
-                    const props = this.resolveProperties(pattern.properties || {}, params);
+                    const props = this.resolveNodePatternProperties(pattern, params);
                     this.db.execute("INSERT INTO nodes (id, label, properties) VALUES (?, ?, ?)", [id, labelJson, JSON.stringify(props)]);
                     if (pattern.variable) {
                         createdIds.set(pattern.variable, id);
@@ -5769,12 +5834,29 @@ export class Executor {
                 const variable = item.expression.variable;
                 const id = createdIds.get(variable);
                 if (id) {
-                    // Query the node
+                    // Try nodes first
                     const nodeResult = this.db.execute("SELECT id, label, properties FROM nodes WHERE id = ?", [id]);
                     if (nodeResult.rows.length > 0) {
                         const row = nodeResult.rows[0];
-                        // Neo4j 3.5 format: return properties directly
-                        resultRow[alias] = this.getNodeProperties(row.id, row.properties);
+                        // Neo4j 3.5 format: return properties directly, but include _nf_id for identity
+                        const props = this.getNodeProperties(row.id, row.properties);
+                        resultRow[alias] = { ...props, _nf_id: row.id };
+                    }
+                    else {
+                        // Try edges if not found in nodes (relationship variable)
+                        const edgeResult = this.db.execute("SELECT id, type, properties FROM edges WHERE id = ?", [id]);
+                        if (edgeResult.rows.length > 0) {
+                            const row = edgeResult.rows[0];
+                            const props = typeof row.properties === "string"
+                                ? JSON.parse(row.properties)
+                                : row.properties || {};
+                            // Return relationship in Neo4j format
+                            resultRow[alias] = {
+                                _type: "relationship",
+                                type: row.type,
+                                properties: props
+                            };
+                        }
                     }
                 }
             }
@@ -5783,16 +5865,23 @@ export class Executor {
                 const property = item.expression.property;
                 const id = createdIds.get(variable);
                 if (id) {
-                    // Try nodes first
-                    const nodeResult = this.db.execute(`SELECT json_extract(properties, '$.${property}') as value FROM nodes WHERE id = ?`, [id]);
+                    // Try nodes first - fetch full properties to preserve boolean types
+                    // (SQLite's json_extract returns 0/1 for booleans, losing type info)
+                    const nodeResult = this.db.execute(`SELECT properties FROM nodes WHERE id = ?`, [id]);
                     if (nodeResult.rows.length > 0) {
-                        resultRow[alias] = this.deepParseJson(nodeResult.rows[0].value);
+                        const props = typeof nodeResult.rows[0].properties === "string"
+                            ? JSON.parse(nodeResult.rows[0].properties)
+                            : nodeResult.rows[0].properties || {};
+                        resultRow[alias] = props[property];
                     }
                     else {
                         // Try edges if not found in nodes
-                        const edgeResult = this.db.execute(`SELECT json_extract(properties, '$.${property}') as value FROM edges WHERE id = ?`, [id]);
+                        const edgeResult = this.db.execute(`SELECT properties FROM edges WHERE id = ?`, [id]);
                         if (edgeResult.rows.length > 0) {
-                            resultRow[alias] = this.deepParseJson(edgeResult.rows[0].value);
+                            const props = typeof edgeResult.rows[0].properties === "string"
+                                ? JSON.parse(edgeResult.rows[0].properties)
+                                : edgeResult.rows[0].properties || {};
+                            resultRow[alias] = props[property];
                         }
                     }
                 }
@@ -7054,7 +7143,13 @@ export class Executor {
                 case "+": return leftNum + rightNum;
                 case "-": return leftNum - rightNum;
                 case "*": return leftNum * rightNum;
-                case "/": return leftNum / rightNum;
+                case "/": {
+                    // Cypher integer division: if both operands are integers, truncate toward zero
+                    if (Number.isInteger(leftNum) && Number.isInteger(rightNum)) {
+                        return Math.trunc(leftNum / rightNum);
+                    }
+                    return leftNum / rightNum;
+                }
                 case "%": return leftNum % rightNum;
                 default: return null;
             }
@@ -7562,7 +7657,7 @@ export class Executor {
         else {
             // Create new source node (with or without label - anonymous nodes are valid)
             sourceId = crypto.randomUUID();
-            const props = this.resolveProperties(rel.source.properties || {}, params);
+            const props = this.resolveNodePatternProperties(rel.source, params);
             const labelJson = this.normalizeLabelToJson(rel.source.label);
             this.db.execute("INSERT INTO nodes (id, label, properties) VALUES (?, ?, ?)", [sourceId, labelJson, JSON.stringify(props)]);
             if (rel.source.variable) {
@@ -7580,7 +7675,7 @@ export class Executor {
         else {
             // Create new target node (with or without label - anonymous nodes are valid)
             targetId = crypto.randomUUID();
-            const props = this.resolveProperties(rel.target.properties || {}, params);
+            const props = this.resolveNodePatternProperties(rel.target, params);
             const labelJson = this.normalizeLabelToJson(rel.target.label);
             this.db.execute("INSERT INTO nodes (id, label, properties) VALUES (?, ?, ?)", [targetId, labelJson, JSON.stringify(props)]);
             if (rel.target.variable) {
@@ -7681,6 +7776,68 @@ export class Executor {
         }
         return [];
     }
+    /**
+     * Try to execute a hybrid var-length pattern query using the in-memory graph engine.
+     * Falls back to null if the query can't be executed via hybrid approach.
+     *
+     * Supports generalized pattern chains with N nodes and multiple var-length edges.
+     */
+    tryHybridVarLengthExecution(query, params) {
+        // Analyze the query for hybrid execution
+        const analysis = analyzeForHybrid(query, params);
+        if (!analysis.suitable || !analysis.params) {
+            // Fall back to SQL execution
+            return null;
+        }
+        // Execute using hybrid executor (generalized chain execution)
+        const rawResults = this.hybridExecutor.executePatternChain(analysis.params);
+        // Get the RETURN clause to understand what columns to output
+        const returnClause = query.clauses.find((c) => c.type === "RETURN");
+        if (!returnClause) {
+            return null;
+        }
+        // Format results according to the RETURN clause
+        const formattedResults = [];
+        for (const result of rawResults) {
+            const row = {};
+            for (const item of returnClause.items) {
+                const alias = item.alias || this.getReturnItemKey(item);
+                if (item.expression.type === "property") {
+                    // Property access: a.name, b.age, etc.
+                    const varName = item.expression.variable;
+                    const propName = item.expression.property;
+                    // Look up the node by variable name in the result Map
+                    const node = varName ? result.get(varName) : undefined;
+                    if (node && propName) {
+                        row[alias] = node.properties[propName];
+                    }
+                }
+                else if (item.expression.type === "variable") {
+                    // Full node: a, b, c
+                    const varName = item.expression.variable;
+                    // Look up the node by variable name in the result Map
+                    const node = varName ? result.get(varName) : undefined;
+                    if (node) {
+                        row[alias] = node.properties;
+                    }
+                }
+            }
+            formattedResults.push(row);
+        }
+        return formattedResults;
+    }
+    /**
+     * Get a key for a return item (used when no alias is provided).
+     */
+    getReturnItemKey(item) {
+        if (item.expression.type === "property") {
+            return `${item.expression.variable}.${item.expression.property}`;
+        }
+        else if (item.expression.type === "variable") {
+            return item.expression.variable || "";
+        }
+        return "";
+    }
     /**
      * Execute a FOREACH clause within PhaseContext.
      */
@@ -8011,9 +8168,19 @@ export class Executor {
         const referencedInSet = new Set();
         for (const setClause of setClauses) {
             for (const assignment of setClause.assignments) {
-                const resolved = resolveAlias(assignment.variable);
-                if (resolved) {
-                    referencedInSet.add(resolved);
+                const resolvedTarget = resolveAlias(assignment.variable);
+                if (resolvedTarget) {
+                    referencedInSet.add(resolvedTarget);
+                }
+                if (assignment.value) {
+                    const valueVars = [];
+                    this.collectExpressionVariables(assignment.value, valueVars);
+                    for (const v of valueVars) {
+                        const resolvedValueVar = resolveAlias(v);
+                        if (resolvedValueVar) {
+                            referencedInSet.add(resolvedValueVar);
+                        }
+                    }
                 }
             }
         }
@@ -9276,7 +9443,7 @@ export class Executor {
         else {
             // Create new source node (with or without label - anonymous nodes are valid)
             sourceId = crypto.randomUUID();
-            const props = this.resolveProperties(rel.source.properties || {}, params);
+            const props = this.resolveNodePatternProperties(rel.source, params);
             const labelJson = this.normalizeLabelToJson(rel.source.label);
             this.db.execute("INSERT INTO nodes (id, label, properties) VALUES (?, ?, ?)", [sourceId, labelJson, JSON.stringify(props)]);
             // Add to resolvedIds so subsequent patterns can reference it
@@ -9295,7 +9462,7 @@ export class Executor {
         else {
             // Create new target node (with or without label - anonymous nodes are valid)
             targetId = crypto.randomUUID();
-            const props = this.resolveProperties(rel.target.properties || {}, params);
+            const props = this.resolveNodePatternProperties(rel.target, params);
             const labelJson = this.normalizeLabelToJson(rel.target.label);
             this.db.execute("INSERT INTO nodes (id, label, properties) VALUES (?, ?, ?)", [targetId, labelJson, JSON.stringify(props)]);
             // Add to resolvedIds so subsequent patterns can reference it
@@ -9315,6 +9482,25 @@ export class Executor {
             resolvedIds[rel.edge.variable] = edgeId;
         }
     }
+    /**
+     * Resolve node properties, including (n $props) parameter maps.
+     */
+    resolveNodePatternProperties(pattern, params, rowContext) {
+        const resolved = rowContext
+            ? this.resolvePropertiesInContext(pattern.properties || {}, rowContext, params)
+            : this.resolveProperties(pattern.properties || {}, params);
+        if (!pattern.propertiesParam) {
+            return resolved;
+        }
+        const paramValue = params[pattern.propertiesParam.name];
+        if (paramValue === undefined || paramValue === null) {
+            return resolved;
+        }
+        if (typeof paramValue !== "object" || Array.isArray(paramValue)) {
+            throw new Error(`Expected parameter $${pattern.propertiesParam.name} to be a map`);
+        }
+        return { ...paramValue, ...resolved };
+    }
     /**
      * Resolve parameter references and binary expressions in properties
      */