@nshiab/simple-data-analysis-core 2.1.11 → 2.1.13

package/src/methods/paths.ts

@@ -0,0 +1,405 @@
+import prepareGraphMetricOptions from "../helpers/prepareGraphMetricOptions.ts";
+import type SimpleTable from "../class/SimpleTable.ts";
+import {
+  type PreparedGraphRouteEndpoints,
+  prepareGraphRouteEndpoints,
+  prepareGraphRouteSql,
+  validateGraphRouteInputs,
+} from "../helpers/prepareGraphRouteSql.ts";
+import graphRouteResultSchema from "../helpers/graphRouteResultSchema.ts";
+import graphRouteResultSelect from "../helpers/graphRouteResultSelect.ts";
+import type { GraphId } from "../helpers/prepareGraphStarts.ts";
+import prepareGraphTemporalSql, {
+  type GraphTemporalOptions,
+  type PreparedGraphTemporalOptions,
+  prepareGraphTemporalOptions,
+} from "../helpers/prepareGraphTemporalSql.ts";
+import type { GraphDirection } from "../helpers/prepareGraphTraversal.ts";
+import queueGraphResult from "../helpers/queueGraphResult.ts";
+import quoteIdentifier from "../helpers/quoteIdentifier.ts";
+import validateGraphTemporalEvents from "../helpers/validateGraphTemporalEvents.ts";
+import type { TableSchema } from "../helpers/pendingOps.ts";
+
+type PathsOptions = GraphTemporalOptions & {
+  elapsedTime?: boolean;
+  direction?: GraphDirection;
+  outputTable?: string | boolean;
+  weight?: string;
+};
+
+export default function paths(
+  simpleTable: SimpleTable,
+  sourceColumn: string,
+  targetColumn: string,
+  edgeId: string,
+  start: GraphId,
+  end: GraphId,
+  options: PathsOptions = {},
+): SimpleTable {
+  if (typeof sourceColumn !== "string") {
+    throw new TypeError("paths() sourceColumn must be a string.");
+  }
+  if (typeof targetColumn !== "string") {
+    throw new TypeError("paths() targetColumn must be a string.");
+  }
+  if (typeof edgeId !== "string") {
+    throw new TypeError("paths() edgeId must be a string.");
+  }
+  if (options === null || typeof options !== "object" || Array.isArray(options)) {
+    throw new TypeError("paths() options must be an object.");
+  }
+  if (
+    options.direction !== undefined &&
+    !["outgoing", "incoming", "both"].includes(options.direction)
+  ) {
+    throw new TypeError('paths() options.direction must be "outgoing", "incoming", or "both".');
+  }
+  if (options.weight !== undefined && typeof options.weight !== "string") {
+    throw new TypeError("paths() options.weight must be a string.");
+  }
+  if (
+    options.outputTable !== undefined &&
+    typeof options.outputTable !== "string" &&
+    typeof options.outputTable !== "boolean"
+  ) {
+    throw new TypeError("paths() options.outputTable must be a string or boolean.");
+  }
+
+  const metric = prepareGraphMetricOptions(options, "paths()", false);
+  const endpoints = prepareGraphRouteEndpoints(start, end, "paths()");
+  const direction = options.direction ?? "outgoing";
+  const temporalOptions = prepareGraphTemporalOptions(options, direction, "paths()");
+  options = structuredClone(options);
+  const parameters = {
+    sourceColumn,
+    targetColumn,
+    edgeId,
+    start,
+    end,
+    options,
+  };
+
+  return queueGraphResult(simpleTable, {
+    method: "paths()",
+    parameters,
+    outputTable: options.outputTable,
+    preflight:
+      temporalOptions === undefined
+        ? undefined
+        : (input) => validateGraphTemporalEvents(input, temporalOptions, "paths()", parameters),
+    values: (schema) => {
+      const validated = validateGraphRouteInputs(
+        schema,
+        sourceColumn,
+        targetColumn,
+        edgeId,
+        endpoints,
+        options.weight,
+        "paths()",
+      );
+      graphRouteResultSchema(schema, validated.distanceType, "paths()", metric.elapsedTime);
+      const temporal =
+        temporalOptions === undefined
+          ? undefined
+          : prepareGraphTemporalSql(schema, temporalOptions, "paths()");
+      return temporal === undefined
+        ? endpoints.values.values
+        : [temporal.gapParameter, ...endpoints.values.values];
+    },
+    buildSelect: (input, schema) =>
+      pathsSelect(
+        input,
+        schema,
+        sourceColumn,
+        targetColumn,
+        edgeId,
+        endpoints,
+        direction,
+        options.weight,
+        temporalOptions,
+        metric.elapsedTime,
+      ),
+    outputSchema: (schema) => {
+      const validated = validateGraphRouteInputs(
+        schema,
+        sourceColumn,
+        targetColumn,
+        edgeId,
+        endpoints,
+        options.weight,
+        "paths()",
+      );
+      if (temporalOptions !== undefined) {
+        prepareGraphTemporalSql(schema, temporalOptions, "paths()");
+      }
+      return graphRouteResultSchema(schema, validated.distanceType, "paths()", metric.elapsedTime);
+    },
+  });
+}
+
+function pathsSelect(
+  input: string,
+  schema: TableSchema,
+  source: string,
+  target: string,
+  edgeId: string,
+  routeEndpoints: PreparedGraphRouteEndpoints,
+  direction: GraphDirection,
+  weight: string | undefined,
+  temporalOptions: PreparedGraphTemporalOptions | undefined,
+  elapsedTime: boolean,
+): string {
+  const route = prepareGraphRouteSql(
+    input,
+    schema,
+    source,
+    target,
+    edgeId,
+    routeEndpoints,
+    weight,
+    "paths()",
+  );
+  const prepared = route.traversal;
+  if (temporalOptions !== undefined) {
+    const temporal = prepareGraphTemporalSql(schema, temporalOptions, "paths()");
+    return temporalPathsSelect(
+      route,
+      direction as Exclude<GraphDirection, "both">,
+      temporal,
+      elapsedTime,
+    );
+  }
+  const distanceType = route.distanceType;
+  const q = quoteIdentifier;
+
+  const relations = prepared.relationNames([
+    "graph_route_endpoints",
+    "graph_edges",
+    "graph_nodes",
+    "graph_to_end",
+    "graph_routes",
+    "graph_complete_routes",
+    "graph_ranked_routes",
+  ]);
+  const endpointRelation = relations.graph_route_endpoints;
+  const edgesRelation = relations.graph_edges;
+  const nodesRelation = relations.graph_nodes;
+  const toEndRelation = relations.graph_to_end;
+  const routesRelation = relations.graph_routes;
+  const completeRelation = relations.graph_complete_routes;
+  const rankedRelation = relations.graph_ranked_routes;
+  const edgeFromKey = `${q("edges")}.${q("__from_key")}`;
+  const edgeToKey = `${q("edges")}.${q("__to_key")}`;
+  const edgeTo = `${q("edges")}.${q("__to")}`;
+  const edgeCost = `${q("edges")}.${q("__weight")}`;
+  const candidateDistance = `CAST(${q("routes")}.${q(
+    "distance",
+  )} + ${edgeCost} AS ${distanceType})`;
+
+  return `WITH RECURSIVE ${endpointRelation}(
+      ${q("start")}, ${q("end")}, ${q("__start_key")}, ${q("__end_key")}
+    ) AS (
+      SELECT ${q("start")}, ${q("end")},
+        ${prepared.key(q("start"))}, ${prepared.key(q("end"))}
+      FROM (SELECT ${route.endpointValue} AS ${q("start")},
+        ${route.endpointValue} AS ${q("end")}) AS ${q("values")}
+    ), ${edgesRelation} AS (
+      ${prepared.edges(direction, [
+        `${route.typedEdgeId} AS ${q("__edge_id")}`,
+        `${route.edgeKey} AS ${q("__edge_key")}`,
+        `${route.edgeWeight} AS ${q("__weight")}`,
+      ])}
+    ), ${nodesRelation} AS (
+      SELECT ${q("__from_key")} AS ${q("__key")} FROM ${edgesRelation}
+      UNION
+      SELECT ${q("__to_key")} AS ${q("__key")} FROM ${edgesRelation}
+    ), ${toEndRelation}(${q("__key")}) AS (
+      SELECT ${q("__end_key")}
+      FROM ${endpointRelation}
+      INNER JOIN ${nodesRelation}
+        ON ${q("__end_key")} = ${q("__key")}
+      UNION
+      SELECT ${edgeFromKey}
+      FROM ${toEndRelation} AS ${q("reached")}
+      INNER JOIN ${edgesRelation} AS ${q("edges")}
+        ON ${q("reached")}.${q("__key")} = ${edgeToKey}
+    ), ${routesRelation}(
+      ${q("node")}, ${q("__node_key")}, ${q("__visited")},
+      ${q("__edge_keys")}, ${q("steps")}, ${q("distance")}
+    ) AS (
+      SELECT ${q("start")}, ${q("__start_key")},
+        [${q("__start_key")}], CAST([] AS ${route.keyType}[]),
+        CAST([] AS ${route.stepType}[]), CAST(0 AS ${distanceType})
+      FROM ${endpointRelation}
+      INNER JOIN ${toEndRelation}
+        ON ${q("__start_key")} = ${q("__key")}
+      UNION ALL
+      SELECT ${edgeTo}, ${edgeToKey},
+        list_append(${q("routes")}.${q("__visited")}, ${edgeToKey}),
+        list_append(${q("routes")}.${q("__edge_keys")}, ${q("edges")}.${q("__edge_key")}),
+        list_append(${q("routes")}.${q("steps")}, struct_pack(
+          ${q("edgeId")} := ${q("edges")}.${q("__edge_id")},
+          ${q("source")} := ${q("edges")}.${q("__from")},
+          ${q("target")} := ${edgeTo},
+          ${q("weight")} := ${edgeCost},
+          ${q("distance")} := ${candidateDistance}
+        )), ${candidateDistance}
+      FROM ${routesRelation} AS ${q("routes")}
+      INNER JOIN ${edgesRelation} AS ${q("edges")}
+        ON ${q("routes")}.${q("__node_key")} = ${edgeFromKey}
+      INNER JOIN ${toEndRelation} AS ${q("can_reach_end")}
+        ON ${edgeToKey} = ${q("can_reach_end")}.${q("__key")}
+      CROSS JOIN ${endpointRelation}
+      WHERE ${q("routes")}.${q("__node_key")} <> ${q("__end_key")}
+        AND NOT list_contains(${q("routes")}.${q("__visited")}, ${edgeToKey})
+    ), ${completeRelation} AS (
+      SELECT ${q("__edge_keys")}, ${q("steps")}
+      FROM ${routesRelation}
+      CROSS JOIN ${endpointRelation}
+      WHERE ${q("__node_key")} = ${q("__end_key")}
+    ), ${rankedRelation} AS (
+      SELECT CAST(row_number() OVER (ORDER BY ${q("__edge_keys")}) - 1 AS BIGINT) AS ${q("pathId")},
+        ${q("steps")}
+      FROM ${completeRelation}
+    )
+    ${graphRouteResultSelect(rankedRelation, route.input, route.edgeIdColumn)}`;
+}
+
+function temporalPathsSelect(
+  route: ReturnType<typeof prepareGraphRouteSql>,
+  direction: Exclude<GraphDirection, "both">,
+  temporal: ReturnType<typeof prepareGraphTemporalSql>,
+  elapsedTime: boolean,
+): string {
+  const prepared = route.traversal;
+  const distanceType = route.distanceType;
+  const q = quoteIdentifier;
+  const relations = prepared.relationNames([
+    "graph_route_endpoints",
+    "graph_temporal_settings",
+    "graph_event_rows",
+    "graph_edges",
+    "graph_nodes",
+    "graph_to_end",
+    "graph_routes",
+    "graph_complete_routes",
+    "graph_ranked_routes",
+  ]);
+  const endpointRelation = relations.graph_route_endpoints;
+  const settingsRelation = relations.graph_temporal_settings;
+  const eventRowsRelation = relations.graph_event_rows;
+  const edgesRelation = relations.graph_edges;
+  const nodesRelation = relations.graph_nodes;
+  const toEndRelation = relations.graph_to_end;
+  const routesRelation = relations.graph_routes;
+  const completeRelation = relations.graph_complete_routes;
+  const rankedRelation = relations.graph_ranked_routes;
+  const edgeFromKey = `${q("edges")}.${q("__from_key")}`;
+  const edgeToKey = `${q("edges")}.${q("__to_key")}`;
+  const edgeTo = `${q("edges")}.${q("__to")}`;
+  const edgeCost = `${q("edges")}.${q("__weight")}`;
+  const edgeKey = `${q("edges")}.${q("__edge_key")}`;
+  const candidateDistance = `CAST(${q("routes")}.${q(
+    "distance",
+  )} + ${edgeCost} AS ${distanceType})`;
+  const gap = `${q("settings")}.${q("__gap")}`;
+  const firstAnchor = temporal.journeyAnchor("edges", direction);
+  const anchor = `${q("routes")}.${q("__journey_anchor")}`;
+  const step = (distance: string, journeyAnchor: string) =>
+    `struct_pack(
+          ${q("edgeId")} := ${q("edges")}.${q("__edge_id")},
+          ${q("source")} := ${q("edges")}.${q("__from")},
+          ${q("target")} := ${edgeTo},
+          ${q("weight")} := ${edgeCost},
+          ${q("distance")} := ${distance}${
+            elapsedTime
+              ? `, ${q("elapsedTimeMs")} := ${temporal.elapsedMilliseconds(
+                  temporal.journeyElapsed("edges", journeyAnchor, direction),
+                )}`
+              : ""
+          }
+        )`;
+
+  return `WITH RECURSIVE ${settingsRelation} AS MATERIALIZED (
+      SELECT CAST(? AS HUGEINT) AS ${q("__gap")}
+    ), ${endpointRelation}(
+      ${q("start")}, ${q("end")}, ${q("__start_key")}, ${q("__end_key")}
+    ) AS (
+      SELECT ${q("start")}, ${q("end")},
+        ${prepared.key(q("start"))}, ${prepared.key(q("end"))}
+      FROM (SELECT ${route.endpointValue} AS ${q("start")},
+        ${route.endpointValue} AS ${q("end")}) AS ${q("values")}
+    ), ${eventRowsRelation} AS MATERIALIZED (
+      ${prepared.edges(direction, [
+        `${route.typedEdgeId} AS ${q("__edge_id")}`,
+        `${route.edgeKey} AS ${q("__edge_key")}`,
+        `${route.edgeWeight} AS ${q("__weight")}`,
+        ...temporal.eventSelections("edges"),
+      ])}
+    ), ${edgesRelation} AS MATERIALIZED (
+      SELECT *
+      FROM ${eventRowsRelation} AS ${q("events")}
+      WHERE ${temporal.eventValidity("events")}
+    ), ${nodesRelation} AS (
+      SELECT ${q("__from_key")} AS ${q("__key")} FROM ${edgesRelation}
+      UNION
+      SELECT ${q("__to_key")} AS ${q("__key")} FROM ${edgesRelation}
+    ), ${toEndRelation}(${q("__key")}) AS (
+      SELECT ${q("__end_key")}
+      FROM ${endpointRelation}
+      INNER JOIN ${nodesRelation}
+        ON ${q("__end_key")} = ${q("__key")}
+      UNION
+      SELECT ${edgeFromKey}
+      FROM ${toEndRelation} AS ${q("reached")}
+      INNER JOIN ${edgesRelation} AS ${q("edges")}
+        ON ${q("reached")}.${q("__key")} = ${edgeToKey}
+    ), ${routesRelation}(
+      ${q("node")}, ${q("__node_key")}, ${q("__visited")},
+      ${q("__edge_keys")}, ${q("steps")}, ${q("distance")},
+      ${q("__event_id")}, ${q("__event_start")}, ${q("__event_end")}${
+        elapsedTime ? `, ${q("__journey_anchor")}` : ""
+      }
+    ) AS (
+      SELECT ${edgeTo}, ${edgeToKey},
+        [${q("__start_key")}, ${edgeToKey}], [${edgeKey}],
+        [${step(edgeCost, firstAnchor)}], ${edgeCost},
+        ${q("edges")}.${q("__event_id")},
+        ${q("edges")}.${q("__event_start")},
+        ${q("edges")}.${q("__event_end")}${elapsedTime ? `, ${firstAnchor}` : ""}
+      FROM ${endpointRelation}
+      INNER JOIN ${edgesRelation} AS ${q("edges")}
+        ON ${q("__start_key")} = ${edgeFromKey}
+      INNER JOIN ${toEndRelation} AS ${q("can_reach_end")}
+        ON ${edgeToKey} = ${q("can_reach_end")}.${q("__key")}
+      WHERE ${q("__start_key")} <> ${edgeToKey}
+      UNION ALL
+      SELECT ${edgeTo}, ${edgeToKey},
+        list_append(${q("routes")}.${q("__visited")}, ${edgeToKey}),
+        list_append(${q("routes")}.${q("__edge_keys")}, ${edgeKey}),
+        list_append(${q("routes")}.${q("steps")}, ${step(candidateDistance, anchor)}),
+        ${candidateDistance}, ${q("edges")}.${q("__event_id")},
+        ${q("edges")}.${q("__event_start")},
+        ${q("edges")}.${q("__event_end")}${elapsedTime ? `, ${anchor}` : ""}
+      FROM ${routesRelation} AS ${q("routes")}
+      INNER JOIN ${edgesRelation} AS ${q("edges")}
+        ON ${q("routes")}.${q("__node_key")} = ${edgeFromKey}
+      INNER JOIN ${toEndRelation} AS ${q("can_reach_end")}
+        ON ${edgeToKey} = ${q("can_reach_end")}.${q("__key")}
+      CROSS JOIN ${endpointRelation}
+      CROSS JOIN ${settingsRelation} AS ${q("settings")}
+      WHERE ${q("routes")}.${q("__node_key")} <> ${q("__end_key")}
+        AND NOT list_contains(${q("routes")}.${q("__visited")}, ${edgeToKey})
+        AND ${temporal.transition("routes", "edges", direction, gap)}
+    ), ${completeRelation} AS (
+      SELECT ${q("__edge_keys")}, ${q("steps")}
+      FROM ${routesRelation}
+      CROSS JOIN ${endpointRelation}
+      WHERE ${q("__node_key")} = ${q("__end_key")}
+    ), ${rankedRelation} AS (
+      SELECT CAST(row_number() OVER (ORDER BY ${q("__edge_keys")}) - 1 AS BIGINT)
+          AS ${q("pathId")}, ${q("steps")}
+      FROM ${completeRelation}
+    )
+    ${graphRouteResultSelect(rankedRelation, route.input, route.edgeIdColumn, false, elapsedTime)}`;
+}

package/src/methods/perimeter.ts

@@ -0,0 +1,36 @@
+import quoteIdentifier from "../helpers/quoteIdentifier.ts";
+import assertNewColumns from "../helpers/assertNewColumns.ts";
+import findGeoColumnFromSchema from "../helpers/findGeoColumnFromSchema.ts";
+import queueOp from "../helpers/queueOp.ts";
+import type SimpleTable from "../class/SimpleTable.ts";
+
+export default function perimeter(
+  simpleTable: SimpleTable,
+  newColumn: string,
+  options: { unit?: "m" | "km"; column?: string; decimals?: number } = {},
+) {
+  options = structuredClone(options);
+  queueOp(simpleTable, {
+    kind: "fusable",
+    method: "perimeter()",
+    parameters: { newColumn, options },
+    needsSchema: true,
+    needsSpatial: true,
+    buildSelect: (input, types) => {
+      assertNewColumns(types, [newColumn], "perimeter()");
+      const column =
+        typeof options.column === "string"
+          ? options.column
+          : findGeoColumnFromSchema(types, "perimeter()", simpleTable.name);
+      let expression = `ST_Perimeter_Spheroid(${quoteIdentifier(column)}) ${
+        options.unit === "km" ? "/ 1000" : ""
+      }`;
+      if (typeof options.decimals === "number") {
+        expression = `ROUND(${expression}, ${options.decimals})`;
+      }
+      return `SELECT *, CAST(${expression} AS DOUBLE) AS ${quoteIdentifier(
+        newColumn,
+      )} FROM ${input}`;
+    },
+  });
+}

package/src/methods/quantiles.ts

@@ -0,0 +1,36 @@
+import quoteIdentifier from "../helpers/quoteIdentifier.ts";
+import assertNewColumns from "../helpers/assertNewColumns.ts";
+import queueOp from "../helpers/queueOp.ts";
+import stringToArray from "../helpers/stringToArray.ts";
+import type SimpleTable from "../class/SimpleTable.ts";
+
+export default function quantiles(
+  simpleTable: SimpleTable,
+  column: string,
+  count: number,
+  newColumn: string,
+  options: {
+    by?: string | string[];
+  } = {},
+) {
+  options = structuredClone(options);
+  queueOp(simpleTable, {
+    kind: "fusable",
+    method: "quantiles()",
+    parameters: { column, count, newColumn, options },
+    needsSchema: true,
+    buildSelect: (input, schema) => {
+      assertNewColumns(schema, [newColumn], "quantiles()");
+
+      const by = options.by ? stringToArray(options.by) : [];
+
+      const partition =
+        by.length === 0 ? "" : `PARTITION BY ${by.map((d) => `${quoteIdentifier(d)}`).join(",")} `;
+
+      return `SELECT *, ntile(${count}) OVER (${partition}ORDER BY ${quoteIdentifier(
+        column,
+      )}) AS ${quoteIdentifier(newColumn)}
+    FROM ${input}`;
+    },
+  });
+}

package/src/methods/randomPoint.ts

@@ -0,0 +1,136 @@
+import quoteIdentifier from "../helpers/quoteIdentifier.ts";
+import findGeoColumn from "../helpers/findGeoColumn.ts";
+import mergeOptions from "../helpers/mergeOptions.ts";
+import queryDB from "../helpers/queryDB.ts";
+import queueOp from "../helpers/queueOp.ts";
+import type SimpleTable from "../class/SimpleTable.ts";
+import ensureSpatial from "../helpers/ensureSpatial.ts";
+
+export default function randomPoint(
+  simpleTable: SimpleTable,
+  newColumn: string,
+  tries: number,
+  options: { column?: string; strict?: boolean } = {},
+) {
+  options = structuredClone(options);
+  // This validation doesn't need the database, so it stays at call time.
+  if (!Number.isFinite(tries) || !Number.isInteger(tries) || tries < 0) {
+    throw new Error("randomPoint() tries must be a finite integer greater than or equal to 0.");
+  }
+
+  // The generated points are checked against the data afterwards, so
+  // randomPoint can't be expressed as a single SELECT over its input: it
+  // executes as a barrier.
+  queueOp(simpleTable, {
+    kind: "barrier",
+    method: "randomPoint()",
+    parameters: { newColumn, tries, options },
+    execute: () => executeRandomPoint(simpleTable, newColumn, tries, options),
+  });
+}
+
+async function executeRandomPoint(
+  simpleTable: SimpleTable,
+  newColumn: string,
+  tries: number,
+  options: { column?: string; strict?: boolean },
+): Promise<void> {
+  await ensureSpatial(simpleTable);
+  const column =
+    typeof options.column === "string"
+      ? options.column
+      : await findGeoColumn(simpleTable, "randomPoint()");
+
+  const geoType = await simpleTable.getProjection(column);
+
+  await queryDB(
+    simpleTable,
+    randomPointQuery(simpleTable.name, column, newColumn, tries, geoType, options.strict !== false),
+    mergeOptions(simpleTable, {
+      table: simpleTable.name,
+      method: "randomPoint()",
+      parameters: { column, newColumn, tries, options, geoType },
+    }),
+  );
+}
+
+function randomPointQuery(
+  table: string,
+  column: string,
+  newColumn: string,
+  tries: number,
+  geoType: string,
+  strict: boolean,
+) {
+  // Recursive CTE approach: each iteration only carries forward the rows that
+  // have NOT yet found a valid interior point, so DuckDB stops per-row as soon
+  // as ST_Within is satisfied — giving O(1) behaviour for easy polygons instead
+  // of the O(N) materialisation that occurs with LATERAL + range() + WHERE.
+  //
+  // Zero-tries contract: `WHERE 1 <= ${tries}` in the base case
+  // produces no rows when tries is 0, so the LEFT JOIN returns NULL for
+  // every row and the UPDATE sets the column to NULL — no special-case branch
+  // needed and the normal UPDATE code path is always exercised.
+  //
+  // Volatility guard: `CASE WHEN (rid + n) IS NOT NULL THEN random() END`
+  // prevents the planner from constant-folding random() across iterations while
+  // still evaluating to random() for every non-null row.
+  const failedExpression = strict
+    ? `CASE WHEN v.failed_count > 0 THEN error(CONCAT(CAST(v.failed_count AS VARCHAR), ' points could not be generated. Consider increasing tries or set options.strict to false.')) ELSE v.pt::${geoType} END`
+    : `v.pt::${geoType}`;
+  const select =
+    newColumn === column
+      ? `t.* REPLACE (${failedExpression} AS ${quoteIdentifier(newColumn)})`
+      : `t.*, ${failedExpression} AS ${quoteIdentifier(newColumn)}`;
+
+  return `CREATE OR REPLACE TABLE ${quoteIdentifier(table)} AS
+WITH RECURSIVE
+base AS (
+    SELECT
+        rowid AS rid,
+        ${quoteIdentifier(column)} AS geom,
+        ST_XMin(${quoteIdentifier(column)}) AS xmin,
+        ST_XMax(${quoteIdentifier(column)}) - ST_XMin(${quoteIdentifier(column)}) AS xdiff,
+        ST_YMin(${quoteIdentifier(column)}) AS ymin,
+        ST_YMax(${quoteIdentifier(column)}) - ST_YMin(${quoteIdentifier(column)}) AS ydiff
+    FROM ${quoteIdentifier(table)}
+),
+attempts(rid, geom, xmin, xdiff, ymin, ydiff, pt, n) AS (
+    SELECT
+        rid, geom, xmin, xdiff, ymin, ydiff,
+        ST_Point(
+            xmin + CASE WHEN rid IS NOT NULL THEN random() END * xdiff,
+            ymin + CASE WHEN rid IS NOT NULL THEN random() END * ydiff
+        ),
+        1
+    FROM base
+    WHERE 1 <= ${tries}
+    UNION ALL
+    SELECT
+        rid, geom, xmin, xdiff, ymin, ydiff,
+        ST_Point(
+            xmin + CASE WHEN (rid + n) IS NOT NULL THEN random() END * xdiff,
+            ymin + CASE WHEN (rid + n) IS NOT NULL THEN random() END * ydiff
+        ),
+        n + 1
+    FROM attempts
+    WHERE NOT ST_Within(pt, geom) AND n < ${tries}
+),
+valid_points AS (
+    SELECT rid, pt
+    FROM attempts
+    WHERE ST_Within(pt, geom)
+    QUALIFY ROW_NUMBER() OVER (PARTITION BY rid ORDER BY n) = 1
+),
+generated AS (
+    SELECT
+        b.rid,
+        vp.pt,
+        COUNT(*) FILTER (WHERE vp.pt IS NULL) OVER () AS failed_count
+    FROM (SELECT rowid AS rid FROM ${quoteIdentifier(table)}) b
+    LEFT JOIN valid_points vp ON b.rid = vp.rid
+)
+SELECT ${select}
+FROM ${quoteIdentifier(table)} t
+JOIN generated v ON t.rowid = v.rid;`;
+}

package/src/methods/ranks.ts

@@ -0,0 +1,39 @@
+import quoteIdentifier from "../helpers/quoteIdentifier.ts";
+import assertNewColumns from "../helpers/assertNewColumns.ts";
+import queueOp from "../helpers/queueOp.ts";
+import stringToArray from "../helpers/stringToArray.ts";
+import type SimpleTable from "../class/SimpleTable.ts";
+
+export default function ranks(
+  simpleTable: SimpleTable,
+  column: string,
+  newColumn: string,
+  options: {
+    order?: "asc" | "desc";
+    by?: string | string[];
+    dense?: boolean;
+  } = {},
+) {
+  options = structuredClone(options);
+  queueOp(simpleTable, {
+    kind: "fusable",
+    method: "ranks()",
+    parameters: { column, newColumn, options },
+    needsSchema: true,
+    buildSelect: (input, schema) => {
+      assertNewColumns(schema, [newColumn], "ranks()");
+
+      const by = options.by ? stringToArray(options.by) : [];
+
+      const partition =
+        by.length === 0 ? "" : `PARTITION BY ${by.map((d) => `${quoteIdentifier(d)}`).join(",")} `;
+
+      return `SELECT *, ${
+        options.dense ? "dense_rank()" : "rank()"
+      } OVER (${partition}ORDER BY ${quoteIdentifier(column)} ${
+        typeof options.order === "string" ? options.order.toUpperCase() : ""
+      }) AS ${quoteIdentifier(newColumn)}
+    FROM ${input}`;
+    },
+  });
+}