@protobase/query 0.19.15 → 0.20.0

package/dist/group-totals.d.ts

@@ -0,0 +1,25 @@
+import { Db } from "./db.js";
+import { Scope } from "./scope.js";
+import { Measure } from "./measure.js";
+import { CheckedFilter, ResourceModel } from "@protobase/schema";
+//#region src/group-totals.d.ts
+export type GroupTotalsOptions = {
+  statementTimeoutMs: number;
+  filter?: CheckedFilter;
+  measure?: Measure;
+  limit?: number;
+  scope?: Scope;
+};
+/** One value of the grouped field: how many rows have it and, with a measure, their sum or average. */
+export type GroupTotal = {
+  value: unknown;
+  count: number;
+  sum?: number | null;
+  average?: number | null;
+};
+/**
+ * Rows per value of `field` under the whole filter, largest first: by the measure when there is one, else by count.
+ * Unlike facets, the filter's own terms on `field` apply too, so the groups add up to what the filter finds.
+ */
+export declare const groupTotals: (db: Db, model: ResourceModel, field: string, options: GroupTotalsOptions) => Promise<GroupTotal[]>;
+//#endregion

package/dist/group-totals.js

@@ -0,0 +1,43 @@
+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 { withStatementTimeout } from "./with-statement-timeout.js";
+import { measureSql, measureValue } from "./measure.js";
+import { sql } from "kysely";
+//#region src/group-totals.ts
+const defaultLimit = 100;
+const maxLimit = 1e3;
+/**
+* Rows per value of `field` under the whole filter, largest first: by the measure when there is one, else by count.
+* Unlike facets, the filter's own terms on `field` apply too, so the groups add up to what the filter finds.
+*/
+const groupTotals = async (db, model, field, options) => {
+	const target = requireField(model, field, "filterable");
+	if (target.type === "json") throw new QueryError("unsupported_field_type", `Cannot group by "${field}", which is json`);
+	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;
+	const column = columnRef(target);
+	await assertFilterRequirements(db, options.filter, options.scope);
+	return withStatementTimeout(db, options.statementTimeoutMs, async (trx) => {
+		return (await baseQuery(trx, model, options.filter, options.scope).select([
+			sql`${column}`.as("value"),
+			sql`count(*)::text`.as("n"),
+			...amount ? [sql`${amount}::text`.as("m")] : []
+		]).groupBy(column).orderBy(amount ? sql`${amount} desc nulls last` : sql`count(*) desc`).orderBy(column, "asc").limit(limit).execute()).map((row) => {
+			const total = {
+				value: row.value,
+				count: toNumber(row.n)
+			};
+			return measure ? {
+				...total,
+				[measure.kind]: measureValue(row.m)
+			} : total;
+		});
+	});
+};
+//#endregion
+export { groupTotals };

package/dist/index.d.ts

@@ -7,6 +7,8 @@ import { estimateCount } from "./estimate-count.js";
 import { exactCount } from "./exact-count.js";
 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 { Histogram, HistogramBucket, histogram } from "./histogram.js";
 import { MapBounds, MapBucket, MapBuckets, MapPosition, cellsAcross, checkMapPosition, mapBuckets, mapCellPixels, maxMapBuckets, maxMapZoom } from "./map-buckets.js";
@@ -16,4 +18,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 Histogram, type HistogramBucket, type IndexKey, type IndexNeed, 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, type TableIndex, type TableIndexes, type UncoveredColumn, buildListQuery, buildRelatedRows, cellsAcross, checkMapPosition, compileFilter, countUpTo, estimateCount, exactCount, facetCounts, 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 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 };

package/dist/index.js

@@ -7,6 +7,7 @@ import { exactCount } from "./exact-count.js";
 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 { series } from "./series.js";
 import { histogram } from "./histogram.js";
 import { cellsAcross, checkMapPosition, mapBuckets, mapCellPixels, maxMapBuckets, maxMapZoom } from "./map-buckets.js";
@@ -14,4 +15,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, 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, tableIndexes, uncoveredColumns, withoutField };

package/dist/measure.d.ts

@@ -0,0 +1,8 @@
+import { ResourceModel } from "@protobase/schema";
+//#region src/measure.d.ts
+/** What a group adds up besides its count: the sum or the average of a numeric field over its rows. */
+export type Measure = {
+  kind: 'sum' | 'average';
+  field: string;
+};
+//#endregion

package/dist/measure.js

@@ -0,0 +1,21 @@
+import { QueryError } from "./fields/query-error.js";
+import { columnRef, findField } from "./columns.js";
+import { sql } from "kysely";
+//#region src/measure.ts
+const numericTypes = [
+	"integer",
+	"bigint",
+	"decimal"
+];
+/** The SQL aggregate of a measure; select it `::text`, so a decimal keeps its digits until it is read. */
+const measureSql = (model, measure) => {
+	const field = findField(model, measure.field);
+	if (!numericTypes.includes(field.type)) throw new QueryError("unsupported_field_type", `A ${measure.kind} needs a numeric field, "${measure.field}" is ${field.type}`);
+	if (field.sensitive) throw new QueryError("unsupported_field_type", `"${measure.field}" is sensitive, so it cannot be added up`);
+	const column = columnRef(field);
+	return measure.kind === "sum" ? sql`sum(${column})` : sql`avg(${column})`;
+};
+/** A measure's value: `null` when no row of the group has a value to add up. */
+const measureValue = (raw) => raw === null || raw === void 0 ? null : Number(raw);
+//#endregion
+export { measureSql, measureValue };

package/dist/series.d.ts

@@ -1,5 +1,6 @@
 import { Db } from "./db.js";
 import { Scope } from "./scope.js";
+import { Measure } from "./measure.js";
 import { CheckedFilter, ResourceModel } from "@protobase/schema";
 //#region src/series.d.ts
 declare const approxMs: {
@@ -19,15 +20,20 @@ export type SeriesOptions = {
   timeZone?: string;
   filter?: CheckedFilter;
   scope?: Scope;
+  /** Adds up a numeric field per bucket besides the count. */
+  measure?: Measure;
 };
 export type SeriesPoint = {
   bucket: string;
   count: number;
+  sum?: number | null;
+  average?: number | null;
 };
 /**
  * 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;
- * `timestamp` columns without a zone are read in the session time zone.
+ * `timestamp` columns without a zone are read in the session time zone. With a measure, a bucket without a row to add
+ * up has `null` for it.
  */
 export declare const series: (db: Db, model: ResourceModel, field: string, options: SeriesOptions) => Promise<SeriesPoint[]>;
 //#endregion

package/dist/series.js

@@ -3,6 +3,7 @@ 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 { sql } from "kysely";
 //#region src/series.ts
@@ -25,7 +26,8 @@ const checkTimeZone = (timeZone) => {
 /**
 * 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;
-* `timestamp` columns without a zone are read in the session time zone.
+* `timestamp` columns without a zone are read in the session time zone. With a measure, a bucket without a row to add
+* up has `null` for it.
 */
 const series = async (db, model, field, options) => {
 	const target = requireField(model, field, "filterable");
@@ -38,6 +40,8 @@ const series = async (db, model, field, options) => {
 	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 { 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);
@@ -46,18 +50,28 @@ const series = async (db, model, field, options) => {
 	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")]).groupBy(sql`1`);
+	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"),
+		...amount ? [sql`${amount}::text`.as("m")] : []
+	]).groupBy(sql`1`);
 	return (await sql`
     with b as (
       select generate_series(date_trunc(${unit}, ${local(from)}), ${laterBucket}, ${step}) as bucket
     ), c as (${counts})
-    select to_char(b.bucket, 'YYYY-MM-DD"T"HH24:MI:SS') as bucket, coalesce(c.n, '0') as n
+    select to_char(b.bucket, 'YYYY-MM-DD"T"HH24:MI:SS') as bucket, coalesce(c.n, '0') as n${amount ? sql`, c.m` : sql``}
     from b left join c on c.bucket = b.bucket
     order by b.bucket
-  `.execute(db)).rows.map((row) => ({
-		bucket: row.bucket,
-		count: toNumber(row.n)
-	}));
+  `.execute(db)).rows.map((row) => {
+		const point = {
+			bucket: row.bucket,
+			count: toNumber(row.n)
+		};
+		return measure ? {
+			...point,
+			[measure.kind]: measureValue(row.m)
+		} : point;
+	});
 };
 //#endregion
 export { series };

package/package.json

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