@protobase/query 0.14.1 → 0.14.3

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 import { CompileOptions, compileFilter } from "./compile-filter.js";
 import { Db } from "./db.js";
 import { Scope } from "./scope.js";
+import { RelatedRowsQuery, buildRelatedRows, relatedRows } from "./related-rows.js";
 import { ExtraColumn, ListOptions, ListPlan, ListResult, buildListQuery, listQuery, maxLimit } from "./list-query.js";
 import { estimateCount } from "./estimate-count.js";
 import { exactCount } from "./exact-count.js";
@@ -13,4 +14,4 @@ import { ScrollMode, scrollMode } from "./scroll-mode.js";
 import { GuardFinding, GuardOptions, GuardReport, explainGuard } from "./explain-guard.js";
 import { QueryError, QueryErrorCode } from "./fields/query-error.js";
 import { SeekRequest, seekToPosition } from "./seek-to-position.js";
-export { type CompileOptions, type Db, type ExtraColumn, type FacetCount, type FacetOptions, type Granularity, type GuardFinding, type GuardOptions, type GuardReport, type Histogram, type HistogramBucket, type ListOptions, type ListPlan, type ListResult, type MapBounds, type MapBucket, type MapBuckets, type MapPosition, QueryError, type QueryErrorCode, type Scope, type ScrollMode, type SeekRequest, type SeriesOptions, type SeriesPoint, buildListQuery, cellsAcross, checkMapPosition, compileFilter, countUpTo, estimateCount, exactCount, explainGuard, facetCounts, histogram, listQuery, mapBuckets, mapCellPixels, maxLimit, maxMapBuckets, maxMapZoom, scrollMode, seekToPosition, series };
+export { type CompileOptions, type Db, type ExtraColumn, type FacetCount, type FacetOptions, type Granularity, type GuardFinding, type GuardOptions, type GuardReport, type Histogram, type HistogramBucket, type ListOptions, type ListPlan, type ListResult, type MapBounds, type MapBucket, type MapBuckets, type MapPosition, QueryError, type QueryErrorCode, type RelatedRowsQuery, type Scope, type ScrollMode, type SeekRequest, type SeriesOptions, type SeriesPoint, buildListQuery, buildRelatedRows, cellsAcross, checkMapPosition, compileFilter, countUpTo, estimateCount, exactCount, explainGuard, facetCounts, histogram, listQuery, mapBuckets, mapCellPixels, maxLimit, maxMapBuckets, maxMapZoom, relatedRows, scrollMode, seekToPosition, series };

package/dist/index.js

@@ -1,6 +1,7 @@
 import { QueryError } from "./fields/query-error.js";
 import { compileFilter } from "./compile-filter.js";
 import { buildListQuery, listQuery, maxLimit } from "./list-query.js";
+import { buildRelatedRows, relatedRows } from "./related-rows.js";
 import { estimateCount } from "./estimate-count.js";
 import { exactCount } from "./exact-count.js";
 import { countUpTo } from "./count-up-to.js";
@@ -11,4 +12,4 @@ import { cellsAcross, checkMapPosition, mapBuckets, mapCellPixels, maxMapBuckets
 import { scrollMode } from "./scroll-mode.js";
 import { explainGuard } from "./explain-guard.js";
 import { seekToPosition } from "./seek-to-position.js";
-export { QueryError, buildListQuery, cellsAcross, checkMapPosition, compileFilter, countUpTo, estimateCount, exactCount, explainGuard, facetCounts, histogram, listQuery, mapBuckets, mapCellPixels, maxLimit, maxMapBuckets, maxMapZoom, scrollMode, seekToPosition, series };
+export { QueryError, buildListQuery, buildRelatedRows, cellsAcross, checkMapPosition, compileFilter, countUpTo, estimateCount, exactCount, explainGuard, facetCounts, histogram, listQuery, mapBuckets, mapCellPixels, maxLimit, maxMapBuckets, maxMapZoom, relatedRows, scrollMode, seekToPosition, series };

package/dist/related-rows.d.ts

@@ -0,0 +1,33 @@
+import { Db } from "./db.js";
+import { Scope } from "./scope.js";
+import { KeyValue, ResourceModel, SortSpec } from "@protobase/schema";
+//#region src/related-rows.d.ts
+/** The rows of `model` whose `field` holds one of `values`, at most `limit` for each value, in `sort` order. */
+export type RelatedRowsQuery = {
+  /** The field that points at the records the rows belong to, such as a photo's `listing_id`. */
+  field: string;
+  /** The keys of those records. */
+  values: readonly KeyValue[];
+  /** The fields it reads, by name; `field` is always among them. */
+  columns: string[];
+  /** The order within each value; the primary key decides ties. */
+  sort?: SortSpec;
+  limit: number;
+};
+/**
+ * The query `relatedRows` runs: the values that have rows, each joined to its first `limit` rows by a lateral subquery,
+ * so an index on `field` and the sort reads only those rows. Both sides stay inside the scope.
+ */
+export declare const buildRelatedRows: (db: Db, model: ResourceModel, query: RelatedRowsQuery, scope?: Scope) => import("kysely").SelectQueryBuilder<{
+  [x: string]: any;
+  [x: number]: any;
+  [x: symbol]: any;
+}, "k" | "r", {
+  [x: string]: any;
+}>;
+/**
+ * The rows of every value in one query, in `sort` order for each value, with `field` holding the value they belong to.
+ * The values themselves are never read from the caller's input: they are the keys of records already read.
+ */
+export declare const relatedRows: (db: Db, model: ResourceModel, query: RelatedRowsQuery, scope?: Scope) => Promise<Array<Record<string, unknown>>>;
+//#endregion

package/dist/related-rows.js

@@ -0,0 +1,35 @@
+import { QueryError } from "./fields/query-error.js";
+import { columnRef, findField } from "./columns.js";
+import { baseQuery } from "./base-query.js";
+import { effectiveSort } from "./sort.js";
+import { orderTerm } from "./order.js";
+import "./list-query.js";
+import { sql } from "kysely";
+//#region src/related-rows.ts
+const ownerAlias = "__pb_owner";
+const rankAlias = "__pb_rank";
+/**
+* The query `relatedRows` runs: the values that have rows, each joined to its first `limit` rows by a lateral subquery,
+* so an index on `field` and the sort reads only those rows. Both sides stay inside the scope.
+*/
+const buildRelatedRows = (db, model, query, scope) => {
+	if (!Number.isInteger(query.limit) || query.limit < 1 || query.limit > 500) throw new QueryError("invalid_limit", `limit must be a whole number from 1 to 500`);
+	const owner = findField(model, query.field);
+	const columns = [.../* @__PURE__ */ new Set([query.field, ...query.columns])].map((name) => findField(model, name));
+	const order = effectiveSort(model, query.sort).map((key) => orderTerm(key));
+	const owners = baseQuery(db, model, void 0, scope).select(sql`${columnRef(owner)}`.as(ownerAlias)).distinct().where(sql`${columnRef(owner)} in (${sql.join(query.values)})`);
+	let rows = baseQuery(db, model, void 0, scope).select(columns.map((field) => sql`${columnRef(field)}`.as(field.name))).select(sql`row_number() over (order by ${sql.join(order)})`.as(rankAlias)).where(sql`${columnRef(owner)} = ${sql.ref(`k.${ownerAlias}`)}`);
+	for (const term of order) rows = rows.orderBy(term);
+	return db.selectFrom(owners.as("k")).innerJoinLateral(rows.limit(query.limit).as("r"), (join) => join.onTrue()).selectAll("r").orderBy(sql.ref(`r.${rankAlias}`));
+};
+/**
+* The rows of every value in one query, in `sort` order for each value, with `field` holding the value they belong to.
+* The values themselves are never read from the caller's input: they are the keys of records already read.
+*/
+const relatedRows = async (db, model, query, scope) => {
+	const built = buildRelatedRows(db, model, query, scope);
+	if (query.values.length === 0) return [];
+	return (await built.execute()).map(({ [rankAlias]: _rank, ...row }) => row);
+};
+//#endregion
+export { buildRelatedRows, relatedRows };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@protobase/query",
-  "version": "0.14.1",
+  "version": "0.14.3",
   "description": "Kysely list, filter, count and aggregate queries over Protobase resources.",
   "license": "Apache-2.0",
   "repository": {
@@ -29,7 +29,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@protobase/schema": "0.14.1",
+    "@protobase/schema": "0.14.3",
     "kysely": "^0.29.6"
   }
 }