@nshiab/simple-data-analysis-core 2.1.7 → 2.1.8

package/script/methods/distances.js

@@ -98,7 +98,10 @@ function distances(simpleTable, sourceColumn, targetColumn, startNodes, options
             return {
                 start: validated.idType,
                 node: validated.idType,
-                total: validated.distanceType,
+                steps: "BIGINT",
+                ...(options.weight === undefined
+                    ? {}
+                    : { total: validated.distanceType }),
                 ...(metrics.elapsedTime ? { elapsedTimeMs: "DOUBLE" } : {}),
             };
         },
@@ -123,12 +126,14 @@ function distancesSelect(input, schema, source, target, starts, direction, weigh
     const edgeWeight = weightColumn === undefined
         ? `CAST(1 AS ${distanceType})`
         : `CAST(${(0, quoteIdentifier_js_1.default)("edges")}.${(0, quoteIdentifier_js_1.default)(weightColumn.column)} AS ${distanceType})`;
-    if (temporalOptions !== undefined) {
-        const temporal = (0, prepareGraphTemporalSql_js_1.default)(schema, temporalOptions, "distances()");
-        if (metrics.elapsedTime) {
-            return elapsedDistancesSelect(prepared, direction, temporal, distanceType, edgeWeight, metrics.minimize);
-        }
-        return temporalDistancesSelect(prepared, direction, temporal, distanceType, edgeWeight);
+    const temporal = temporalOptions === undefined
+        ? undefined
+        : (0, prepareGraphTemporalSql_js_1.default)(schema, temporalOptions, "distances()");
+    if (weight !== undefined || metrics.elapsedTime) {
+        return summaryDistancesSelect(prepared, direction, temporal, distanceType, edgeWeight, metrics, weight !== undefined, weightColumn?.type === "FLOAT" || weightColumn?.type === "DOUBLE");
+    }
+    if (temporal !== undefined) {
+        return temporalDistancesSelect(prepared, direction, temporal, distanceType, edgeWeight, "steps", false);
     }
     const relations = prepared.relationNames([
         "graph_start_values",
@@ -152,6 +157,14 @@ function distancesSelect(input, schema, source, target, starts, direction, weigh
     const edgeCost = `${(0, quoteIdentifier_js_1.default)("edges")}.${(0, quoteIdentifier_js_1.default)("__weight")}`;
     const bestDistance = `${(0, quoteIdentifier_js_1.default)("best")}.${(0, quoteIdentifier_js_1.default)("distance")}`;
     const candidateDistance = `CAST(${reachedDistance} + ${edgeCost} AS ${distanceType})`;
+    const candidateSteps = `${(0, quoteIdentifier_js_1.default)("reached")}.${(0, quoteIdentifier_js_1.default)("steps")} + 1`;
+    const bestSteps = `${(0, quoteIdentifier_js_1.default)("best")}.${(0, quoteIdentifier_js_1.default)("steps")}`;
+    const order = (distance, steps) => metrics.minimize === "steps"
+        ? `ROW(${steps}, ${distance})`
+        : `ROW(${distance}, ${steps})`;
+    const candidateOrder = order(candidateDistance, candidateSteps);
+    const selectedDistance = `arg_min(${candidateDistance}, ${candidateOrder})`;
+    const selectedSteps = `arg_min(${candidateSteps}, ${candidateOrder})`;
     return `WITH RECURSIVE ${startValuesRelation}(${(0, quoteIdentifier_js_1.default)("start")}) AS (
       VALUES ${prepared.startValues}
     ), ${startsRelation} AS (
@@ -165,19 +178,20 @@ function distancesSelect(input, schema, source, target, starts, direction, weigh
     ), ${distancesRelation}(
       ${(0, quoteIdentifier_js_1.default)("start")}, ${(0, quoteIdentifier_js_1.default)("node")},
       ${(0, quoteIdentifier_js_1.default)("__start_key")}, ${(0, quoteIdentifier_js_1.default)("__node_key")},
-      ${(0, quoteIdentifier_js_1.default)("distance")}
+      ${(0, quoteIdentifier_js_1.default)("distance")}, ${(0, quoteIdentifier_js_1.default)("steps")}
     ) USING KEY(
       ${(0, quoteIdentifier_js_1.default)("__start_key")}, ${(0, quoteIdentifier_js_1.default)("__node_key")}
     ) AS (
       SELECT ${start}, ${edgeTo}, ${startKey}, ${edgeToKey},
-        MIN(${edgeCost}) AS ${(0, quoteIdentifier_js_1.default)("distance")}
+        MIN(${edgeCost}) AS ${(0, quoteIdentifier_js_1.default)("distance")}, CAST(1 AS BIGINT)
       FROM ${startsRelation} AS ${(0, quoteIdentifier_js_1.default)("starts")}
       INNER JOIN ${edgesRelation} AS ${(0, quoteIdentifier_js_1.default)("edges")}
         ON ${startKey} = ${edgeFromKey}
       GROUP BY ${start}, ${edgeTo}, ${startKey}, ${edgeToKey}
       UNION
       SELECT ${reachedStart}, ${edgeTo}, ${reachedStartKey}, ${edgeToKey},
-        MIN(${candidateDistance}) AS ${(0, quoteIdentifier_js_1.default)("distance")}
+        ${selectedDistance} AS ${(0, quoteIdentifier_js_1.default)("distance")},
+        ${selectedSteps} AS ${(0, quoteIdentifier_js_1.default)("steps")}
       FROM ${distancesRelation} AS ${(0, quoteIdentifier_js_1.default)("reached")}
       INNER JOIN ${edgesRelation} AS ${(0, quoteIdentifier_js_1.default)("edges")}
         ON ${reachedNodeKey} = ${edgeFromKey}
@@ -185,111 +199,259 @@ function distancesSelect(input, schema, source, target, starts, direction, weigh
         ON ${reachedStartKey} = ${(0, quoteIdentifier_js_1.default)("best")}.${(0, quoteIdentifier_js_1.default)("__start_key")}
         AND ${edgeToKey} = ${(0, quoteIdentifier_js_1.default)("best")}.${(0, quoteIdentifier_js_1.default)("__node_key")}
       GROUP BY ${reachedStart}, ${edgeTo}, ${reachedStartKey}, ${edgeToKey},
-        ${bestDistance}
-      HAVING ${bestDistance} IS NULL OR MIN(${candidateDistance}) < ${bestDistance}
+        ${bestDistance}, ${bestSteps}
+      HAVING ${bestDistance} IS NULL OR
+        ${order(selectedDistance, selectedSteps)} < ${order(bestDistance, bestSteps)}
     )
     SELECT ${(0, quoteIdentifier_js_1.default)("start")}, ${(0, quoteIdentifier_js_1.default)("node")},
-      ${(0, quoteIdentifier_js_1.default)("distance")} AS ${(0, quoteIdentifier_js_1.default)("total")}
+      ${(0, quoteIdentifier_js_1.default)("steps")}${weight === undefined
+        ? ""
+        : `, ${(0, quoteIdentifier_js_1.default)("distance")} AS ${(0, quoteIdentifier_js_1.default)("total")}`}
     FROM ${distancesRelation}
-    ORDER BY ${(0, quoteIdentifier_js_1.default)("__start_key")}, ${(0, quoteIdentifier_js_1.default)("distance")}, ${(0, quoteIdentifier_js_1.default)("__node_key")}`;
+    ORDER BY ${(0, quoteIdentifier_js_1.default)("__start_key")}, ${(0, quoteIdentifier_js_1.default)(metrics.minimize === "steps" ? "steps" : "distance")}, ${(0, quoteIdentifier_js_1.default)("__node_key")}`;
 }
-function temporalDistancesSelect(prepared, direction, temporal, distanceType, edgeWeight) {
+function temporalDistancesSelect(prepared, direction, temporal, distanceType, edgeWeight, minimize, includeTotal) {
     const q = quoteIdentifier_js_1.default;
     const startsSelect = `SELECT ${q("start")},
         ${prepared.key(q("start"))} AS ${q("__key")}
       FROM (VALUES ${prepared.startValues}) AS ${q("start_values")}(${q("start")})`;
-    const costStates = (0, buildGraphTemporalCostStateSql_js_1.default)(prepared, startsSelect, direction, temporal, distanceType, edgeWeight);
+    const costStates = (0, buildGraphTemporalCostStateSql_js_1.default)(prepared, startsSelect, direction, temporal, distanceType, edgeWeight, [], minimize);
+    const order = minimize === "steps"
+        ? `${q("steps")}, ${q("distance")}`
+        : `${q("distance")}, ${q("steps")}`;
     return `${costStates.withClause}
-    SELECT ${q("start")}, ${q("node")},
-      MIN(${q("distance")}) AS ${q("total")}
+    SELECT ${q("start")}, ${q("node")}, ${q("steps")}${includeTotal ? `, ${q("distance")} AS ${q("total")}` : ""}
     FROM ${costStates.costRelation}
-    GROUP BY ${q("start")}, ${q("node")}, ${q("__start_key")},
-      ${q("__node_key")}
-    ORDER BY ${q("__start_key")}, ${q("total")}, ${q("__node_key")}`;
+    QUALIFY row_number() OVER (
+      PARTITION BY ${q("__start_key")}, ${q("__node_key")}
+      ORDER BY ${order}
+    ) = 1
+    ORDER BY ${q("__start_key")}, ${q(minimize === "steps" ? "steps" : "distance")}, ${q("__node_key")}`;
 }
-function elapsedDistancesSelect(prepared, direction, temporal, distanceType, edgeWeight, minimize) {
+// Distinct visited sets, metrics, and temporal boundaries are enough to extend
+// summaries. No edge IDs or full connection sequences are needed. Keeping the
+// visited set is necessary: equal summaries can have different legal extensions.
+function summaryDistancesSelect(prepared, direction, temporal, distanceType, edgeWeight, metrics, includeTotal, floatingWeight) {
     const q = quoteIdentifier_js_1.default;
     const relations = prepared.relationNames([
         "graph_starts",
         "graph_temporal_settings",
         "graph_event_rows",
         "graph_edges",
-        "graph_elapsed_states",
-        "graph_elapsed_results",
+        "graph_summaries",
+        "graph_metric_results",
+        "graph_tied_summaries",
+        "graph_best_metrics",
+        "graph_metric_bounds",
     ]);
     const starts = relations.graph_starts;
     const settings = relations.graph_temporal_settings;
     const events = relations.graph_event_rows;
     const edges = relations.graph_edges;
-    const states = relations.graph_elapsed_states;
-    const results = relations.graph_elapsed_results;
+    const summaries = relations.graph_summaries;
+    const results = relations.graph_metric_results;
+    const tied = relations.graph_tied_summaries;
     const ref = (alias, column) => `${q(alias)}.${q(column)}`;
-    const anchor = temporal.journeyAnchor("edges", direction);
-    const reachedAnchor = ref("reached", "__anchor");
-    const candidateDistance = `CAST(${ref("reached", "distance")} + ${ref("edges", "__weight")} AS ${distanceType})`;
-    const order = minimize === "elapsedTime"
-        ? `${q("__elapsed")}, ${q("distance")}`
-        : `${q("distance")}, ${q("__elapsed")}`;
-    // A physical event and the first departure (last arrival for incoming
-    // traversal) fix elapsed time. Keep the cheapest cost for each such state;
-    // merging different anchors would lose later-departing, faster journeys.
-    // The state space is finite, and strict improvements terminate zero cycles.
-    return `WITH RECURSIVE ${settings} AS MATERIALIZED (
-      SELECT CAST(? AS HUGEINT) AS ${q("__gap")}
+    const searchDirection = direction;
+    const firstAnchor = temporal?.journeyAnchor("edges", searchDirection);
+    const sum = `CAST(${ref("reached", "distance")} + ${ref("edges", "__weight")} AS ${distanceType})`;
+    // Reported costs must not reject routes before the primary objective has
+    // selected its results. NULL marks overflow and propagates through sums;
+    // non-negative weights cannot bring an overflowing total back into range.
+    const nextDistance = metrics.minimize === "weight" ? sum : `TRY(${sum})`;
+    const temporalColumns = temporal === undefined
+        ? ""
+        : `, ${q("__event_start")}, ${q("__event_end")}`;
+    const eventValues = temporal === undefined
+        ? ""
+        : `, ${ref("edges", "__event_start")}, ${ref("edges", "__event_end")}`;
+    const metric = metrics.minimize === "steps"
+        ? q("steps")
+        : metrics.minimize === "weight"
+            ? q("distance")
+            : q("__elapsed");
+    // Use native time precision for selection. Collapse equal reported values
+    // after conversion to milliseconds, since these are summary rows.
+    const reportedElapsed = metrics.elapsedTime
+        ? `, ${temporal.elapsedMilliseconds(q("__elapsed"))} AS ${q("elapsedTimeMs")}`
+        : "";
+    const order = metrics.minimize === "steps"
+        ? [
+            q("steps"),
+            q("__node_key"),
+            ...(includeTotal ? [q("total")] : []),
+            ...(metrics.elapsedTime ? [q("elapsedTimeMs")] : []),
+        ]
+        : metrics.minimize === "weight"
+            ? [
+                q("total"),
+                q("__node_key"),
+                q("steps"),
+                ...(metrics.elapsedTime ? [q("elapsedTimeMs")] : []),
+            ]
+            : [
+                q("elapsedTimeMs"),
+                q("__node_key"),
+                q("steps"),
+                ...(includeTotal ? [q("total")] : []),
+            ];
+    const bounds = summaryBoundsSql(relations.graph_best_metrics, relations.graph_metric_bounds, starts, edges, settings, temporal, searchDirection, metrics.minimize, distanceType, floatingWeight);
+    return `WITH RECURSIVE ${settings} AS (
+      ${temporal === undefined
+        ? `SELECT 0 AS ${q("__gap")}`
+        : `SELECT CAST(? AS HUGEINT) AS ${q("__gap")}`}
     ), ${events} AS MATERIALIZED (
       ${prepared.edges(direction, [
         `${edgeWeight} AS ${q("__weight")}`,
-        ...temporal.eventSelections("edges"),
+        ...(temporal?.eventSelections("edges") ?? []),
     ])}
     ), ${edges} AS MATERIALIZED (
-      SELECT * FROM ${events} AS ${q("events")}
-      WHERE ${temporal.eventValidity("events")}
-    ), ${starts} AS MATERIALIZED (
+      SELECT DISTINCT ${q("__from")}, ${q("__to")}, ${q("__from_key")},
+        ${q("__to_key")}, ${q("__weight")}${temporalColumns}
+      FROM ${events} AS ${q("events")}
+      ${temporal === undefined ? "" : `WHERE ${temporal.eventValidity("events")}`}
+    ), ${starts} AS (
       SELECT ${q("start")}, ${prepared.key(q("start"))} AS ${q("__key")}
       FROM (VALUES ${prepared.startValues}) AS ${q("start_values")}(${q("start")})
-    ), ${states}(
+    ), ${bounds.ctes}, ${summaries}(
       ${q("start")}, ${q("node")}, ${q("__start_key")}, ${q("__node_key")},
-      ${q("__event_id")}, ${q("__event_start")}, ${q("__event_end")},
-      ${q("__anchor")}, ${q("distance")}
-    ) USING KEY(${q("__start_key")}, ${q("__event_id")}, ${q("__anchor")}) AS (
+      ${q("__visited")}, ${q("steps")}, ${q("distance")}${temporalColumns}${metrics.elapsedTime ? `, ${q("__anchor")}` : ""}
+    ) AS (
       SELECT ${ref("starts", "start")}, ${ref("edges", "__to")},
         ${ref("starts", "__key")}, ${ref("edges", "__to_key")},
-        ${ref("edges", "__event_id")}, ${ref("edges", "__event_start")},
-        ${ref("edges", "__event_end")}, ${anchor}, ${ref("edges", "__weight")}
+        list_sort(list_distinct([${ref("starts", "__key")}, ${ref("edges", "__to_key")}])),
+        CAST(1 AS BIGINT), ${ref("edges", "__weight")}${eventValues}${metrics.elapsedTime ? `, ${firstAnchor}` : ""}
       FROM ${starts} AS ${q("starts")}
       INNER JOIN ${edges} AS ${q("edges")}
         ON ${ref("starts", "__key")} = ${ref("edges", "__from_key")}
+      ${bounds.join(ref("starts", "__key"))}
+      WHERE ${bounds.test("CAST(1 AS BIGINT)", ref("edges", "__weight"), firstAnchor)}
       UNION
       SELECT ${ref("reached", "start")}, ${ref("edges", "__to")},
         ${ref("reached", "__start_key")}, ${ref("edges", "__to_key")},
-        ${ref("edges", "__event_id")}, ${ref("edges", "__event_start")},
-        ${ref("edges", "__event_end")}, ${reachedAnchor},
-        MIN(${candidateDistance}) AS ${q("distance")}
-      FROM ${states} AS ${q("reached")}
+        list_sort(list_distinct(list_append(${ref("reached", "__visited")}, ${ref("edges", "__to_key")}))),
+        ${ref("reached", "steps")} + 1, ${nextDistance}${eventValues}${metrics.elapsedTime ? `, ${ref("reached", "__anchor")}` : ""}
+      FROM ${summaries} AS ${q("reached")}
       INNER JOIN ${edges} AS ${q("edges")}
         ON ${ref("reached", "__node_key")} = ${ref("edges", "__from_key")}
       CROSS JOIN ${settings} AS ${q("settings")}
-      LEFT JOIN recurring.${states} AS ${q("best")}
-        ON ${ref("reached", "__start_key")} = ${ref("best", "__start_key")}
-        AND ${ref("edges", "__event_id")} = ${ref("best", "__event_id")}
-        AND ${reachedAnchor} = ${ref("best", "__anchor")}
-      WHERE ${temporal.transition("reached", "edges", direction, ref("settings", "__gap"))}
-      GROUP BY ${ref("reached", "start")}, ${ref("edges", "__to")},
-        ${ref("reached", "__start_key")}, ${ref("edges", "__to_key")},
-        ${ref("edges", "__event_id")}, ${ref("edges", "__event_start")},
-        ${ref("edges", "__event_end")}, ${reachedAnchor}, ${ref("best", "distance")}
-      HAVING ${ref("best", "distance")} IS NULL OR
-        MIN(${candidateDistance}) < ${ref("best", "distance")}
+      ${bounds.join(ref("reached", "__start_key"))}
+      WHERE ${bounds.test(`${ref("reached", "steps")} + 1`, nextDistance, ref("reached", "__anchor"))}
+        AND ${ref("reached", "__node_key")} <> ${ref("reached", "__start_key")}
+        AND (NOT list_contains(${ref("reached", "__visited")}, ${ref("edges", "__to_key")})
+          OR ${ref("edges", "__to_key")} = ${ref("reached", "__start_key")})
+        ${temporal === undefined ? "" : `AND ${temporal.transition("reached", "edges", searchDirection, ref("settings", "__gap"))}`}
     ), ${results} AS (
-      SELECT *, ${temporal.journeyElapsed("states", ref("states", "__anchor"), direction)} AS ${q("__elapsed")}
-      FROM ${states} AS ${q("states")}
+      SELECT *${metrics.elapsedTime
+        ? `, ${temporal.journeyElapsed("summaries", ref("summaries", "__anchor"), searchDirection)} AS ${q("__elapsed")}`
+        : ""}
+      FROM ${summaries} AS ${q("summaries")}
+    ), ${tied} AS MATERIALIZED (
+      SELECT DISTINCT ${q("start")}, ${q("node")}, ${q("__start_key")}, ${q("__node_key")},
+        ${q("steps")}${includeTotal ? `, ${q("distance")} AS ${q("total")}` : ""}${reportedElapsed}
+      FROM ${results}
+      QUALIFY ${metric} = MIN(${metric}) OVER (
+        PARTITION BY ${q("__start_key")}, ${q("__node_key")}
+      )
     )
-    SELECT ${q("start")}, ${q("node")}, ${q("distance")} AS ${q("total")},
-      ${temporal.elapsedMilliseconds(q("__elapsed"))} AS ${q("elapsedTimeMs")}
-    FROM ${results}
-    QUALIFY row_number() OVER (
-      PARTITION BY ${q("__start_key")}, ${q("__node_key")}
-      ORDER BY ${order}, ${q("__event_id")}, ${q("__anchor")}
-    ) = 1
-    ORDER BY ${q("__start_key")}, ${order}, ${q("__node_key")}`;
+    SELECT ${q("start")}, ${q("node")}, ${q("steps")}${includeTotal
+        ? `, CASE WHEN ${q("total")} IS NULL
+          THEN error('distances() total exceeds the supported ${distanceType} range for an optimal route.')
+          ELSE ${q("total")} END AS ${q("total")}`
+        : ""}${metrics.elapsedTime ? `, ${q("elapsedTimeMs")}` : ""}
+    FROM ${tied}
+    ORDER BY ${q("__start_key")}, ${order.join(", ")}`;
+}
+// Compute primary optima without enumerating visited sets. Exact additive
+// objectives have optimal prefixes (at the same event boundary in temporal
+// traversal). Floating addition can erase prefix differences, and elapsed
+// optima can depend on a later departure, so those use a per-start upper bound.
+function summaryBoundsSql(best, limits, starts, edges, settings, temporal, direction, minimize, distanceType, floatingWeight) {
+    const q = quoteIdentifier_js_1.default;
+    const ref = (alias, column) => `${q(alias)}.${q(column)}`;
+    const elapsed = minimize === "elapsedTime";
+    const globalBound = elapsed || (minimize === "weight" && floatingWeight);
+    const boundaries = temporal === undefined
+        ? []
+        : ["__event_start", "__event_end"];
+    const keys = [
+        "__start_key",
+        "__node_key",
+        ...boundaries,
+        ...(elapsed ? ["__anchor"] : []),
+    ];
+    const firstAnchor = elapsed
+        ? temporal.journeyAnchor("edges", direction)
+        : undefined;
+    const firstKeys = [
+        ref("starts", "__key"),
+        ref("edges", "__to_key"),
+        ...boundaries.map((key) => ref("edges", key)),
+        ...(elapsed ? [firstAnchor] : []),
+    ];
+    const nextKeys = [
+        ref("reached", "__start_key"),
+        ref("edges", "__to_key"),
+        ...boundaries.map((key) => ref("edges", key)),
+        ...(elapsed ? [ref("reached", "__anchor")] : []),
+    ];
+    const firstMetric = minimize === "steps"
+        ? "CAST(1 AS BIGINT)"
+        : elapsed
+            ? temporal.journeyElapsed("edges", firstAnchor, direction)
+            : ref("edges", "__weight");
+    const nextMetric = minimize === "steps"
+        ? `${ref("reached", "__metric")} + 1`
+        : elapsed
+            ? temporal.journeyElapsed("edges", ref("reached", "__anchor"), direction)
+            : `CAST(${ref("reached", "__metric")} + ${ref("edges", "__weight")} AS ${distanceType})`;
+    const minimum = `MIN(${nextMetric})`;
+    const bestMetric = ref("best", "__metric");
+    const ctes = `${best}(${keys.map(q).join(", ")}, ${q("__metric")})
+    USING KEY(${keys.map(q).join(", ")}) AS (
+      SELECT ${firstKeys.join(", ")}, MIN(${firstMetric})
+      FROM ${starts} AS ${q("starts")}
+      INNER JOIN ${edges} AS ${q("edges")}
+        ON ${ref("starts", "__key")} = ${ref("edges", "__from_key")}
+      GROUP BY ${firstKeys.join(", ")}
+      UNION
+      SELECT ${nextKeys.join(", ")}, ${minimum}
+      FROM ${best} AS ${q("reached")}
+      INNER JOIN ${edges} AS ${q("edges")}
+        ON ${ref("reached", "__node_key")} = ${ref("edges", "__from_key")}
+      CROSS JOIN ${settings} AS ${q("settings")}
+      LEFT JOIN recurring.${best} AS ${q("best")}
+        ON ${keys.map((key, i) => `${ref("best", key)} = ${nextKeys[i]}`).join(" AND ")}
+      WHERE ${ref("reached", "__node_key")} <> ${ref("reached", "__start_key")}
+        ${temporal === undefined ? "" : `AND ${temporal.transition("reached", "edges", direction, ref("settings", "__gap"))}`}
+      GROUP BY ${nextKeys.join(", ")}, ${bestMetric}
+      HAVING ${bestMetric} IS NULL OR ${minimum} < ${bestMetric}
+    )${globalBound
+        ? `, ${limits} AS (
+      SELECT ${q("__start_key")}, MAX(${q("__minimum")}) AS ${q("__metric")}
+      FROM (
+        SELECT ${q("__start_key")}, ${q("__node_key")}, MIN(${q("__metric")}) AS ${q("__minimum")}
+        FROM ${best}
+        GROUP BY ${q("__start_key")}, ${q("__node_key")}
+      ) AS ${q("minima")}
+      GROUP BY ${q("__start_key")}
+    )`
+        : ""}`;
+    return {
+        ctes,
+        join: (startKey) => `INNER JOIN ${globalBound ? limits : best} AS ${q("bounds")}
+      ON ${ref("bounds", "__start_key")} = ${startKey}
+      ${globalBound
+            ? ""
+            : `AND ${ref("bounds", "__node_key")} = ${ref("edges", "__to_key")}
+        ${boundaries.map((key) => `AND ${ref("bounds", key)} = ${ref("edges", key)}`).join(" ")}`}`,
+        test: (steps, distance, anchor) => {
+            const metric = minimize === "steps"
+                ? steps
+                : elapsed
+                    ? temporal.journeyElapsed("edges", anchor, direction)
+                    : distance;
+            return `${metric} ${globalBound ? "<=" : "="} ${ref("bounds", "__metric")}`;
+        },
+    };
 }

package/script/methods/shortestPath.d.ts

@@ -7,7 +7,7 @@ type ShortestPathOptions = GraphTemporalOptions & {
     outputTable?: string | boolean;
     weight?: string;
     elapsedTime?: boolean;
-    minimize?: "weight" | "elapsedTime";
+    minimize?: "steps" | "weight" | "elapsedTime";
 };
 export default function shortestPath(simpleTable: SimpleTable, sourceColumn: string, targetColumn: string, edgeId: string, start: GraphId, end: GraphId, options?: ShortestPathOptions): SimpleTable;
 export {};

package/script/methods/shortestPath.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shortestPath.d.ts","sourceRoot":"","sources":["../../src/methods/shortestPath.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AAMvD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,kCAAkC,CAAC;AAShE,OAAgC,EAC9B,KAAK,oBAAoB,EAG1B,MAAM,uCAAuC,CAAC;AAC/C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qCAAqC,CAAC;AAK1E,KAAK,mBAAmB,GAAG,oBAAoB,GAAG;IAChD,SAAS,CAAC,EAAE,cAAc,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,QAAQ,CAAC,EAAE,QAAQ,GAAG,aAAa,CAAC;CACrC,CAAC;AAEF,MAAM,CAAC,OAAO,UAAU,YAAY,CAClC,WAAW,EAAE,WAAW,EACxB,YAAY,EAAE,MAAM,EACpB,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,OAAO,EACd,GAAG,EAAE,OAAO,EACZ,OAAO,GAAE,mBAAwB,GAChC,WAAW,CAsHb"}
+{"version":3,"file":"shortestPath.d.ts","sourceRoot":"","sources":["../../src/methods/shortestPath.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AAMvD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,kCAAkC,CAAC;AAShE,OAAgC,EAC9B,KAAK,oBAAoB,EAG1B,MAAM,uCAAuC,CAAC;AAC/C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qCAAqC,CAAC;AAK1E,KAAK,mBAAmB,GAAG,oBAAoB,GAAG;IAChD,SAAS,CAAC,EAAE,cAAc,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,QAAQ,CAAC,EAAE,OAAO,GAAG,QAAQ,GAAG,aAAa,CAAC;CAC/C,CAAC;AAEF,MAAM,CAAC,OAAO,UAAU,YAAY,CAClC,WAAW,EAAE,WAAW,EACxB,YAAY,EAAE,MAAM,EACpB,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,OAAO,EACd,GAAG,EAAE,OAAO,EACZ,OAAO,GAAE,mBAAwB,GAChC,WAAW,CAyHb"}

package/script/methods/shortestPath.js

@@ -92,7 +92,7 @@ function shortestPath(simpleTable, sourceColumn, targetColumn, edgeId, start, en
             ? undefined
             : (input) => (0, validateGraphTemporalEvents_js_1.default)(input, temporalOptions, "shortestPath()", parameters),
         values: (schema) => {
-            (0, prepareGraphRouteSql_js_1.validateGraphRouteInputs)(schema, sourceColumn, targetColumn, edgeId, endpoints, options.weight, "shortestPath()");
+            (0, prepareGraphRouteSql_js_1.validateGraphRouteInputs)(schema, sourceColumn, targetColumn, edgeId, endpoints, options.weight, "shortestPath()", options.weight !== undefined);
             const temporal = temporalOptions === undefined
                 ? undefined
                 : (0, prepareGraphTemporalSql_js_1.default)(schema, temporalOptions, "shortestPath()");
@@ -102,27 +102,28 @@ function shortestPath(simpleTable, sourceColumn, targetColumn, edgeId, start, en
         },
         buildSelect: (input, schema) => shortestPathSelect(input, schema, sourceColumn, targetColumn, edgeId, endpoints, direction, options.weight, temporalOptions, metrics),
         outputSchema: (schema) => {
-            const validated = (0, prepareGraphRouteSql_js_1.validateGraphRouteInputs)(schema, sourceColumn, targetColumn, edgeId, endpoints, options.weight, "shortestPath()");
+            const validated = (0, prepareGraphRouteSql_js_1.validateGraphRouteInputs)(schema, sourceColumn, targetColumn, edgeId, endpoints, options.weight, "shortestPath()", options.weight !== undefined);
             if (temporalOptions !== undefined) {
                 (0, prepareGraphTemporalSql_js_1.default)(schema, temporalOptions, "shortestPath()");
             }
-            return (0, graphRouteResultSchema_js_1.default)(schema, validated.distanceType, "shortestPath()", metrics.elapsedTime);
+            return (0, graphRouteResultSchema_js_1.default)(schema, validated.distanceType, "shortestPath()", metrics.elapsedTime, options.weight !== undefined);
         },
     });
 }
 function shortestPathSelect(input, schema, source, target, edgeId, routeEndpoints, direction, weight, temporalOptions, metrics) {
-    const route = (0, prepareGraphRouteSql_js_1.prepareGraphRouteSql)(input, schema, source, target, edgeId, routeEndpoints, weight, "shortestPath()");
+    const route = (0, prepareGraphRouteSql_js_1.prepareGraphRouteSql)(input, schema, source, target, edgeId, routeEndpoints, weight, "shortestPath()", weight !== undefined);
     const prepared = route.traversal;
     if (temporalOptions !== undefined) {
         const temporal = (0, prepareGraphTemporalSql_js_1.default)(schema, temporalOptions, "shortestPath()");
-        return temporalShortestPathSelect(route, direction, temporal, metrics);
+        return temporalShortestPathSelect(route, direction, temporal, metrics, weight !== undefined);
     }
     const distanceType = route.distanceType;
     // Exact shortest routes have optimal prefixes. Floating addition can erase
     // a prefix-cost difference later, so retain all simple prefixes up to the
     // best complete cost before selecting the full-route ties.
-    const floating = route.weightType === "FLOAT" ||
-        route.weightType === "DOUBLE";
+    const floating = metrics.minimize === "weight" &&
+        (route.weightType === "FLOAT" || route.weightType === "DOUBLE");
+    const metricType = metrics.minimize === "steps" ? "BIGINT" : distanceType;
     const relations = prepared.relationNames([
         "graph_route_endpoints",
         "graph_edges",
@@ -148,8 +149,17 @@ function shortestPathSelect(input, schema, source, target, edgeId, routeEndpoint
     const edgeToKey = `${q("edges")}.${q("__to_key")}`;
     const edgeTo = `${q("edges")}.${q("__to")}`;
     const edgeCost = `${q("edges")}.${q("__weight")}`;
+    const edgeMetric = metrics.minimize === "steps"
+        ? "CAST(1 AS BIGINT)"
+        : edgeCost;
     const routeDistance = `${q("routes")}.${q("distance")}`;
     const candidateDistance = `CAST(${routeDistance} + ${edgeCost} AS ${distanceType})`;
+    const routeMetric = metrics.minimize === "steps"
+        ? `len(${q("routes")}.${q("steps")})`
+        : routeDistance;
+    const candidateMetric = metrics.minimize === "steps"
+        ? `${routeMetric} + 1`
+        : candidateDistance;
     return `WITH RECURSIVE ${endpointRelation}(
       ${q("start")}, ${q("end")}, ${q("__start_key")}, ${q("__end_key")}
     ) AS (
@@ -181,13 +191,13 @@ function shortestPathSelect(input, schema, source, target, edgeId, routeEndpoint
       ${q("node")}, ${q("__node_key")}, ${q("distance")}
     ) USING KEY(${q("__node_key")}) AS (
       SELECT ${q("start")}, ${q("__start_key")},
-        CAST(0 AS ${distanceType})
+        CAST(0 AS ${metricType})
       FROM ${endpointRelation}
       INNER JOIN ${toEndRelation}
         ON ${q("__start_key")} = ${q("__key")}
       UNION
       SELECT ${edgeTo}, ${edgeToKey},
-        MIN(CAST(${q("reached")}.${q("distance")} + ${edgeCost} AS ${distanceType}))
+        MIN(CAST(${q("reached")}.${q("distance")} + ${edgeMetric} AS ${metricType}))
       FROM ${distancesRelation} AS ${q("reached")}
       INNER JOIN ${edgesRelation} AS ${q("edges")}
         ON ${q("reached")}.${q("__node_key")} = ${edgeFromKey}
@@ -197,7 +207,7 @@ function shortestPathSelect(input, schema, source, target, edgeId, routeEndpoint
         ON ${edgeToKey} = ${q("best")}.${q("__node_key")}
       GROUP BY ${edgeTo}, ${edgeToKey}, ${q("best")}.${q("distance")}
       HAVING ${q("best")}.${q("distance")} IS NULL
-        OR MIN(CAST(${q("reached")}.${q("distance")} + ${edgeCost} AS ${distanceType})) < ${q("best")}.${q("distance")}
+        OR MIN(CAST(${q("reached")}.${q("distance")} + ${edgeMetric} AS ${metricType})) < ${q("best")}.${q("distance")}
     ), ${bestTotalRelation} AS (
       SELECT ${q("distances")}.${q("distance")}
       FROM ${distancesRelation} AS ${q("distances")}
@@ -236,23 +246,23 @@ function shortestPathSelect(input, schema, source, target, edgeId, routeEndpoint
       WHERE ${q("routes")}.${q("__node_key")} <> ${q("__end_key")}
         AND NOT list_contains(${q("routes")}.${q("__visited")}, ${edgeToKey})
         AND ${floating
-        ? `${candidateDistance} <= ${q("best_total")}.${q("distance")}`
-        : `${candidateDistance} = ${q("best_prefix")}.${q("distance")}`}
+        ? `${candidateMetric} <= ${q("best_total")}.${q("distance")}`
+        : `${candidateMetric} = ${q("best_prefix")}.${q("distance")}`}
     ), ${shortestRelation} AS (
       SELECT ${q("__edge_keys")}, ${q("steps")}
-      FROM ${routesRelation}
+      FROM ${routesRelation} AS ${q("routes")}
       CROSS JOIN ${endpointRelation}
       CROSS JOIN ${bestTotalRelation} AS ${q("best_total")}
       WHERE ${q("__node_key")} = ${q("__end_key")}
-        AND ${routesRelation}.${q("distance")} = ${q("best_total")}.${q("distance")}
+        AND ${routeMetric} = ${q("best_total")}.${q("distance")}
     ), ${rankedRelation} AS (
       SELECT CAST(row_number() OVER (ORDER BY ${q("__edge_keys")}) - 1 AS BIGINT) AS ${q("pathId")},
         ${q("steps")}
       FROM ${shortestRelation}
     )
-    ${(0, graphRouteResultSelect_js_1.default)(rankedRelation, route.input, route.edgeIdColumn)}`;
+    ${(0, graphRouteResultSelect_js_1.default)(rankedRelation, route.input, route.edgeIdColumn, false, false, weight !== undefined)}`;
 }
-function temporalShortestPathSelect(route, direction, temporal, metrics) {
+function temporalShortestPathSelect(route, direction, temporal, metrics, includeTotal) {
     const prepared = route.traversal;
     const q = quoteIdentifier_js_1.default;
     const startsSelect = `SELECT ${q("start")},
@@ -265,7 +275,7 @@ function temporalShortestPathSelect(route, direction, temporal, metrics) {
         : (0, buildGraphTemporalCostStateSql_js_1.default)(prepared, startsSelect, direction, temporal, route.distanceType, route.edgeWeight, [
             `${route.typedEdgeId} AS ${q("__edge_id")}`,
             `${route.edgeKey} AS ${q("__edge_key")}`,
-        ]);
+        ], metrics.minimize === "steps" ? "steps" : "weight");
     const relations = prepared.relationNames([
         "graph_route_endpoints",
         "graph_nodes",
@@ -295,15 +305,21 @@ function temporalShortestPathSelect(route, direction, temporal, metrics) {
     const routeAnchor = `${q("routes")}.${q("__journey_anchor")}`;
     const firstElapsed = temporal.journeyElapsed("edges", firstAnchor, direction);
     const candidateElapsed = temporal.journeyElapsed("edges", routeAnchor, direction);
-    const firstMetric = metrics.minimize === "elapsedTime"
-        ? firstElapsed
-        : edgeCost;
-    const candidateMetric = metrics.minimize === "elapsedTime"
-        ? candidateElapsed
-        : candidateDistance;
-    const routeMetric = metrics.minimize === "elapsedTime"
-        ? `${q("routes")}.${q("__elapsed")}`
-        : routeDistance;
+    const firstMetric = metrics.minimize === "steps"
+        ? "1"
+        : metrics.minimize === "elapsedTime"
+            ? firstElapsed
+            : edgeCost;
+    const routeMetric = metrics.minimize === "steps"
+        ? `len(${q("routes")}.${q("steps")})`
+        : metrics.minimize === "elapsedTime"
+            ? `${q("routes")}.${q("__elapsed")}`
+            : routeDistance;
+    const candidateMetric = metrics.minimize === "steps"
+        ? `${routeMetric} + 1`
+        : metrics.minimize === "elapsedTime"
+            ? candidateElapsed
+            : candidateDistance;
     const step = (distance, elapsed) => `struct_pack(
           ${q("edgeId")} := ${q("edges")}.${q("__edge_id")},
           ${q("source")} := ${q("edges")}.${q("__from")},
@@ -336,7 +352,7 @@ function temporalShortestPathSelect(route, direction, temporal, metrics) {
       INNER JOIN ${edgesRelation} AS ${q("edges")}
         ON ${q("reached")}.${q("__key")} = ${edgeToKey}
     ), ${bestTotalRelation} AS (
-      SELECT MIN(${q("costs")}.${q("distance")}) AS ${q("distance")}
+      SELECT MIN(${q("costs")}.${q(metrics.minimize === "steps" ? "steps" : "distance")}) AS ${q("distance")}
       FROM ${costs.costRelation} AS ${q("costs")}
       INNER JOIN ${endpointRelation}
         ON ${q("costs")}.${q("__node_key")} = ${q("__end_key")}
@@ -391,7 +407,7 @@ function temporalShortestPathSelect(route, direction, temporal, metrics) {
           AS ${q("pathId")}, ${q("steps")}
       FROM ${shortestRelation}
     )
-    ${(0, graphRouteResultSelect_js_1.default)(rankedRelation, route.input, route.edgeIdColumn, false, metrics.elapsedTime)}`;
+    ${(0, graphRouteResultSelect_js_1.default)(rankedRelation, route.input, route.edgeIdColumn, false, metrics.elapsedTime, includeTotal)}`;
 }
 // At the same physical event a later departure (or earlier incoming arrival)
 // dominates every future elapsed duration. Keyed improvements find the optimum