@protobase/query 0.22.5 → 0.22.7

package/dist/index.d.ts

@@ -9,7 +9,9 @@ import { countUpTo } from "./count-up-to.js";
 import { FacetCount, FacetOptions, facetCounts } from "./facet-counts.js";
 import { Measure } from "./measure.js";
 import { GroupTotal, GroupTotalsOptions, groupTotals } from "./group-totals.js";
-import { Granularity, SeriesOptions, SeriesPoint, series } from "./series.js";
+import { Granularity } from "./series-buckets.js";
+import { SeriesOptions, SeriesPoint, series } from "./series.js";
+import { SplitPoint, SplitSeriesOptions, splitSeries } from "./split-series.js";
 import { Histogram, HistogramBucket, histogram } from "./histogram.js";
 import { MapBounds, MapBucket, MapBuckets, MapPosition, cellsAcross, checkMapPosition, mapBuckets, mapCellPixels, maxMapBuckets, maxMapZoom } from "./map-buckets.js";
 import { withoutField } from "./prune-filter.js";
@@ -18,4 +20,4 @@ import { IndexKey, TableIndex, TableIndexes, tableIndexes } from "./table-indexe
 import { ColumnUse, CoverageQuery, IndexNeed, UncoveredColumn, uncoveredColumns } from "./index-coverage.js";
 import { QueryError, QueryErrorCode } from "./fields/query-error.js";
 import { SeekRequest, seekToPosition } from "./seek-to-position.js";
-export { type ColumnUse, type CompileOptions, type CoverageQuery, type Db, type ExtraColumn, type FacetCount, type FacetOptions, type Granularity, type GroupTotal, type GroupTotalsOptions, type Histogram, type HistogramBucket, type IndexKey, type IndexNeed, type ListOptions, type ListPlan, type ListResult, type MapBounds, type MapBucket, type MapBuckets, type MapPosition, type Measure, QueryError, type QueryErrorCode, type RelatedRowsQuery, type Scope, type ScrollMode, type SeekRequest, type SeriesOptions, type SeriesPoint, type TableIndex, type TableIndexes, type UncoveredColumn, buildListQuery, buildRelatedRows, cellsAcross, checkMapPosition, compileFilter, countUpTo, estimateCount, exactCount, facetCounts, groupTotals, histogram, listQuery, mapBuckets, mapCellPixels, maxLimit, maxMapBuckets, maxMapZoom, relatedRows, scrollMode, seekToPosition, series, tableIndexes, uncoveredColumns, withoutField };
+export { type ColumnUse, type CompileOptions, type CoverageQuery, type Db, type ExtraColumn, type FacetCount, type FacetOptions, type Granularity, type GroupTotal, type GroupTotalsOptions, type Histogram, type HistogramBucket, type IndexKey, type IndexNeed, type ListOptions, type ListPlan, type ListResult, type MapBounds, type MapBucket, type MapBuckets, type MapPosition, type Measure, QueryError, type QueryErrorCode, type RelatedRowsQuery, type Scope, type ScrollMode, type SeekRequest, type SeriesOptions, type SeriesPoint, type SplitPoint, type SplitSeriesOptions, type TableIndex, type TableIndexes, type UncoveredColumn, buildListQuery, buildRelatedRows, cellsAcross, checkMapPosition, compileFilter, countUpTo, estimateCount, exactCount, facetCounts, groupTotals, histogram, listQuery, mapBuckets, mapCellPixels, maxLimit, maxMapBuckets, maxMapZoom, relatedRows, scrollMode, seekToPosition, series, splitSeries, tableIndexes, uncoveredColumns, withoutField };

package/dist/index.js

@@ -8,6 +8,7 @@ import { countUpTo } from "./count-up-to.js";
 import { withoutField } from "./prune-filter.js";
 import { facetCounts } from "./facet-counts.js";
 import { groupTotals } from "./group-totals.js";
+import { splitSeries } from "./split-series.js";
 import { series } from "./series.js";
 import { histogram } from "./histogram.js";
 import { cellsAcross, checkMapPosition, mapBuckets, mapCellPixels, maxMapBuckets, maxMapZoom } from "./map-buckets.js";
@@ -15,4 +16,4 @@ import { scrollMode } from "./scroll-mode.js";
 import { tableIndexes } from "./table-indexes.js";
 import { uncoveredColumns } from "./index-coverage.js";
 import { seekToPosition } from "./seek-to-position.js";
-export { QueryError, buildListQuery, buildRelatedRows, cellsAcross, checkMapPosition, compileFilter, countUpTo, estimateCount, exactCount, facetCounts, groupTotals, histogram, listQuery, mapBuckets, mapCellPixels, maxLimit, maxMapBuckets, maxMapZoom, relatedRows, scrollMode, seekToPosition, series, tableIndexes, uncoveredColumns, withoutField };
+export { QueryError, buildListQuery, buildRelatedRows, cellsAcross, checkMapPosition, compileFilter, countUpTo, estimateCount, exactCount, facetCounts, groupTotals, histogram, listQuery, mapBuckets, mapCellPixels, maxLimit, maxMapBuckets, maxMapZoom, relatedRows, scrollMode, seekToPosition, series, splitSeries, tableIndexes, uncoveredColumns, withoutField };

package/dist/series-buckets.d.ts

@@ -0,0 +1,20 @@
+import { sql } from "kysely";
+import { ResourceModel } from "@protobase/schema";
+//#region src/series-buckets.d.ts
+declare const approxMs: {
+  hour: number;
+  day: number;
+  week: number;
+  month: number;
+  year: number;
+};
+export type Granularity = keyof typeof approxMs;
+export type BucketOptions = {
+  range: {
+    from: string | Date;
+    to: string | Date;
+  };
+  granularity: Granularity;
+  timeZone?: string;
+};
+//#endregion

package/dist/series-buckets.js

@@ -0,0 +1,57 @@
+import { QueryError } from "./fields/query-error.js";
+import { columnRef, requireField } from "./columns.js";
+import { rangeBound } from "./range-bound.js";
+import { sql } from "kysely";
+//#region src/series-buckets.ts
+const maxBuckets = 1e4;
+const approxMs = {
+	hour: 36e5,
+	day: 864e5,
+	week: 6048e5,
+	month: 26298e5,
+	year: 315576e5
+};
+const checkTimeZone = (timeZone) => {
+	try {
+		new Intl.DateTimeFormat("en", { timeZone });
+	} catch (error) {
+		if (error instanceof RangeError) throw new QueryError("invalid_option", `Unknown time zone "${timeZone}"`);
+		throw error;
+	}
+};
+/**
+* Validates a date or timestamp field, range, granularity and time zone, and builds the SQL pieces that bucket the
+* field over time. Shared by `series` and `splitSeries`.
+*/
+const seriesBuckets = (model, field, options) => {
+	const target = requireField(model, field, "filterable");
+	if (target.type !== "date" && target.type !== "timestamp") throw new QueryError("unsupported_field_type", `Series needs a date or timestamp field, "${field}" is ${target.type}`);
+	if (!Object.hasOwn(approxMs, options.granularity)) throw new QueryError("invalid_option", "Unknown granularity");
+	const timeZone = options.timeZone ?? "UTC";
+	checkTimeZone(timeZone);
+	const from = rangeBound(options.range.from, target);
+	const to = rangeBound(options.range.to, target);
+	const spanMs = new Date(to).getTime() - new Date(from).getTime();
+	if (!(spanMs > 0)) throw new QueryError("invalid_option", "range.to must be after range.from");
+	if (spanMs / approxMs[options.granularity] > maxBuckets) throw new QueryError("invalid_option", `Range spans more than ${maxBuckets} buckets`);
+	const col = columnRef(target);
+	const unit = sql.lit(options.granularity);
+	const step = sql`${sql.lit(`1 ${options.granularity}`)}::interval`;
+	const isDate = target.type === "date";
+	const bound = sql.raw(isDate ? "date" : "timestamptz");
+	const local = (value) => isDate ? sql`${value}::timestamp` : sql`(${value}::timestamptz at time zone ${timeZone}::text)`;
+	return {
+		target,
+		col,
+		from,
+		to,
+		unit,
+		step,
+		bound,
+		local,
+		laterBucket: sql`date_trunc(${unit}, ${local(to)} - interval '1 microsecond')`,
+		isDate
+	};
+};
+//#endregion
+export { seriesBuckets };

package/dist/series.d.ts

@@ -1,23 +1,10 @@
 import { Db } from "./db.js";
 import { Scope } from "./scope.js";
 import { Measure } from "./measure.js";
+import { BucketOptions, Granularity } from "./series-buckets.js";
 import { CheckedFilter, ResourceModel } from "@protobase/schema";
 //#region src/series.d.ts
-declare const approxMs: {
-  hour: number;
-  day: number;
-  week: number;
-  month: number;
-  year: number;
-};
-export type Granularity = keyof typeof approxMs;
-export type SeriesOptions = {
-  range: {
-    from: string | Date;
-    to: string | Date;
-  };
-  granularity: Granularity;
-  timeZone?: string;
+export type SeriesOptions = BucketOptions & {
   filter?: CheckedFilter;
   scope?: Scope;
   /** Adds up a numeric field per bucket besides the count. */
@@ -36,4 +23,5 @@ export type SeriesPoint = {
  * up has `null` for it.
  */
 export declare const series: (db: Db, model: ResourceModel, field: string, options: SeriesOptions) => Promise<SeriesPoint[]>;
-//#endregion
+//#endregion
+export type { Granularity };

package/dist/series.js

@@ -1,28 +1,10 @@
-import { QueryError } from "./fields/query-error.js";
-import { columnRef, requireField } from "./columns.js";
 import { baseQuery } from "./base-query.js";
 import { assertFilterRequirements } from "./filter-requirements.js";
 import { toNumber } from "./numbers.js";
 import { measureSql, measureValue } from "./measure.js";
-import { rangeBound } from "./range-bound.js";
+import { seriesBuckets } from "./series-buckets.js";
 import { sql } from "kysely";
 //#region src/series.ts
-const maxBuckets = 1e4;
-const approxMs = {
-	hour: 36e5,
-	day: 864e5,
-	week: 6048e5,
-	month: 26298e5,
-	year: 315576e5
-};
-const checkTimeZone = (timeZone) => {
-	try {
-		new Intl.DateTimeFormat("en", { timeZone });
-	} catch (error) {
-		if (error instanceof RangeError) throw new QueryError("invalid_option", `Unknown time zone "${timeZone}"`);
-		throw error;
-	}
-};
 /**
 * Row counts per calendar bucket, in `timeZone`, with empty buckets present. `to` is exclusive.
 * Buckets are returned as local ISO strings without offset. `date` fields ignore the time zone;
@@ -30,26 +12,10 @@ const checkTimeZone = (timeZone) => {
 * up has `null` for it.
 */
 const series = async (db, model, field, options) => {
-	const target = requireField(model, field, "filterable");
-	if (target.type !== "date" && target.type !== "timestamp") throw new QueryError("unsupported_field_type", `Series needs a date or timestamp field, "${field}" is ${target.type}`);
-	if (!Object.hasOwn(approxMs, options.granularity)) throw new QueryError("invalid_option", "Unknown granularity");
-	const timeZone = options.timeZone ?? "UTC";
-	checkTimeZone(timeZone);
-	const from = rangeBound(options.range.from, target);
-	const to = rangeBound(options.range.to, target);
-	const spanMs = new Date(to).getTime() - new Date(from).getTime();
-	if (!(spanMs > 0)) throw new QueryError("invalid_option", "range.to must be after range.from");
-	if (spanMs / approxMs[options.granularity] > maxBuckets) throw new QueryError("invalid_option", `Range spans more than ${maxBuckets} buckets`);
+	const { col, from, to, unit, step, bound, local, laterBucket, isDate } = seriesBuckets(model, field, options);
 	const { measure } = options;
 	const amount = measure ? measureSql(model, measure) : void 0;
 	await assertFilterRequirements(db, options.filter, options.scope);
-	const col = columnRef(target);
-	const unit = sql.lit(options.granularity);
-	const step = sql`${sql.lit(`1 ${options.granularity}`)}::interval`;
-	const isDate = target.type === "date";
-	const bound = sql.raw(isDate ? "date" : "timestamptz");
-	const local = (value) => isDate ? sql`${value}::timestamp` : sql`(${value}::timestamptz at time zone ${timeZone}::text)`;
-	const laterBucket = sql`date_trunc(${unit}, ${local(to)} - interval '1 microsecond')`;
 	const counts = baseQuery(db, model, options.filter, options.scope).where(sql`${col} >= ${from}::${bound} and ${col} < ${to}::${bound}`).select([
 		sql`date_trunc(${unit}, ${isDate ? sql`${col}::timestamp` : local(col)})`.as("bucket"),
 		sql`count(*)::text`.as("n"),

package/dist/split-series.d.ts

@@ -0,0 +1,26 @@
+import { Db } from "./db.js";
+import { SeriesOptions } from "./series.js";
+import { ResourceModel } from "@protobase/schema";
+//#region src/split-series.d.ts
+export type SplitSeriesOptions = SeriesOptions & {
+  limit?: number;
+};
+/** The rows of one split value in one bucket; buckets and values without rows have no point. */
+export type SplitPoint = {
+  bucket: string;
+  split: unknown;
+  count: number;
+  sum?: number | null;
+  average?: number | null;
+};
+/**
+ * The rows of each calendar bucket of `field` (as `series` buckets it) split by the values of another field.
+ * Only the `limit` largest values over the whole range are kept, ranked by the sum with a sum measure and by row count
+ * otherwise (averages of averages add up to nothing); `splits` lists them in rank order, and a point is present only
+ * where a value has rows. What the other values hold is the bucket's total from `series` minus its points.
+ */
+export declare const splitSeries: (db: Db, model: ResourceModel, field: string, split: string, options: SplitSeriesOptions) => Promise<{
+  splits: unknown[];
+  points: SplitPoint[];
+}>;
+//#endregion

package/dist/split-series.js

@@ -0,0 +1,71 @@
+import { QueryError } from "./fields/query-error.js";
+import { columnRef, requireField } from "./columns.js";
+import { baseQuery } from "./base-query.js";
+import { assertFilterRequirements } from "./filter-requirements.js";
+import { toNumber } from "./numbers.js";
+import { measureSql, measureValue } from "./measure.js";
+import { seriesBuckets } from "./series-buckets.js";
+import { sql } from "kysely";
+//#region src/split-series.ts
+const defaultLimit = 8;
+const maxLimit = 100;
+const unsplittable = [
+	"date",
+	"timestamp",
+	"json"
+];
+/**
+* The rows of each calendar bucket of `field` (as `series` buckets it) split by the values of another field.
+* Only the `limit` largest values over the whole range are kept, ranked by the sum with a sum measure and by row count
+* otherwise (averages of averages add up to nothing); `splits` lists them in rank order, and a point is present only
+* where a value has rows. What the other values hold is the bucket's total from `series` minus its points.
+*/
+const splitSeries = async (db, model, field, split, options) => {
+	const { col, from, to, unit, bound, local, isDate } = seriesBuckets(model, field, options);
+	const splitField = requireField(model, split, "filterable");
+	if (unsplittable.includes(splitField.type)) throw new QueryError("unsupported_field_type", `Cannot split by "${split}", which is ${splitField.type}`);
+	if (splitField.sensitive) throw new QueryError("unsupported_field_type", `"${split}" is sensitive, so it cannot be split by`);
+	if (split === field) throw new QueryError("invalid_option", "A series cannot be split by its own field");
+	const limit = options.limit ?? defaultLimit;
+	if (!Number.isInteger(limit) || limit < 1 || limit > maxLimit) throw new QueryError("invalid_option", `limit must be between 1 and ${maxLimit}`);
+	const { measure } = options;
+	const amount = measure ? measureSql(model, measure) : void 0;
+	await assertFilterRequirements(db, options.filter, options.scope);
+	const splitCol = columnRef(splitField);
+	const bucketSql = sql`to_char(date_trunc(${unit}, ${isDate ? sql`${col}::timestamp` : local(col)}), 'YYYY-MM-DD"T"HH24:MI:SS')`;
+	const parts = baseQuery(db, model, options.filter, options.scope).where(sql`${col} >= ${from}::${bound} and ${col} < ${to}::${bound}`).select([
+		bucketSql.as("bucket"),
+		sql`${splitCol}`.as("split"),
+		sql`count(*)`.as("n"),
+		...amount ? [sql`${amount}`.as("m")] : []
+	]).groupBy([sql`1`, sql`2`]);
+	const largest = measure?.kind === "sum" ? sql`sum(m::numeric) desc nulls last` : sql`sum(n::bigint) desc`;
+	const result = await sql`
+    with c as (${parts}), r as (
+      select split, row_number() over (order by ${largest}, split asc) as rank
+      from c group by split order by rank limit ${sql.lit(limit)}
+    )
+    select c.bucket, c.split, r.rank::text as rank, c.n::text as n${amount ? sql`, c.m::text as m` : sql``}
+    from c join r on c.split is not distinct from r.split
+    order by c.bucket, r.rank
+  `.execute(db);
+	const byRank = /* @__PURE__ */ new Map();
+	const points = result.rows.map((row) => {
+		byRank.set(toNumber(row.rank), row.split);
+		const point = {
+			bucket: row.bucket,
+			split: row.split,
+			count: toNumber(row.n)
+		};
+		return measure ? {
+			...point,
+			[measure.kind]: measureValue(row.m)
+		} : point;
+	});
+	return {
+		splits: [...byRank].sort(([a], [b]) => a - b).map(([, value]) => value),
+		points
+	};
+};
+//#endregion
+export { splitSeries };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@protobase/query",
-  "version": "0.22.5",
+  "version": "0.22.7",
   "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.22.5",
+    "@protobase/schema": "0.22.7",
     "kysely": "^0.29.6"
   }
 }