@pythia-software/query-table-core 0.9.5 → 0.9.6

package/dist/index.d.ts

@@ -278,7 +278,26 @@ interface MetricDateGrouping {
     range: "query" | "observed" | "custom";
     start?: string;
     end?: string;
-}
+    /** "exclude" leaves out intervals the query's bounds cut, and intervals that
+     * have not ended by the evaluation time; omitted includes them. */
+    partialIntervals?: "include" | "exclude";
+}
+/** A trailing window over a calendar metric's intervals. */
+interface MetricWindow {
+    /** Intervals per point, its own included (2–1,000), or "all" for a running
+     * value from the first interval. */
+    periods: number | "all";
+    /** "total" (default) evaluates the metric over every row in the window, so
+     * ratios pool their parts. "mean" averages the per-interval values of a
+     * single SUM, COUNT or COUNT_DISTINCT. */
+    reduce?: "total" | "mean";
+    /** Points whose window starts before the first interval have no value
+     * ("omit", default) or use the intervals available ("include"). */
+    partial?: "omit" | "include";
+}
+/** Divide each bucket by the total of all groups ("total") or of its first
+ * grouping key ("group0"), such as one calendar interval. */
+type MetricShare = "total" | "group0";
 interface MetricValueFormat {
     kind: "number" | "percent" | "duration" | "date" | "time" | "datetime";
     decimals?: number;
@@ -795,6 +814,11 @@ interface AggregationClause {
      *  sorting, `groupLimit` and Other. Requires at least one grouping field;
      *  integer 1–1,000,000. Removed groups are reported as `hiddenGroups`. */
     minCount?: number;
+    /** A trailing window or running value over the calendar intervals of
+     * `dateGrouping`. Computed from ordinary metrics, so every engine supports it. */
+    window?: MetricWindow;
+    /** Express each bucket as a fraction of a total of the same measure. */
+    share?: MetricShare;
 }
 /** Detail affordances are presentation state, never backend SELECT fields. */
 type ItemPropertyMode = "hover" | "modal" | "expand";
@@ -995,6 +1019,9 @@ interface AggregationBucket {
      *  cohort is inspected (`count`/`value` are then the bin's count). Never part
      *  of a transport result. */
     bin?: MetricHistogramBin;
+    /** Calendar intervals combined into a windowed point (`AggregationClause.window`);
+     *  fewer than its periods where the window starts before the first interval. */
+    intervals?: number;
     /** The metric: a number for count/sum/avg, or the column's value for min/max
      *  (which may be a string for text/datetime). null when undefined (e.g. avg of
      *  an all-null column). */
@@ -1228,6 +1255,9 @@ interface MetricEvaluationOptions<Row = unknown> extends QueryEvaluationOptions,
 }
 /** Typed lexicographic ordering with null placement independent of direction. */
 declare function compareMetricValues(a: MetricValue, b: MetricValue): number;
+/** Order buckets as a metric result: errors last, then `clause.sort`
+ * (chronological for calendar groups, largest value first otherwise), then keys. */
+declare function sortMetricBuckets(buckets: AggregationBucket[], c: Pick<AggregationClause, "sort" | "dateGrouping">): AggregationBucket[];
 declare function evaluateMetrics<Row>(rows: Row[], q: QueryState, schema: FieldSchema<Row>, options?: MetricEvaluationOptions<Row>): AggregationResult;
 
 interface ApplyResult<Row> {
@@ -1481,10 +1511,52 @@ declare const METRIC_DATE_INTERVALS: readonly ["hour", "day", "week", "month", "
 declare function metricDateTime(value: MetricValue, timeZone?: string): number;
 declare function metricDateFloor(time: number, interval: MetricDateGrouping["interval"], timeZone?: string): number;
 declare function metricDateNext(time: number, interval: MetricDateGrouping["interval"], timeZone?: string): number;
+/** A date-only Through value includes the whole local day, even for hourly groups. */
+declare function metricCustomEndTime(value: string, timeZone?: string): number;
 declare function validateDateGrouping(config: MetricDateGrouping): void;
 /** Only conjunctive bounds prove a domain; OR alternatives are not bounds. */
 declare function metricDateRange(config: MetricDateGrouping, query: QueryState, observed: readonly number[], now: number, canonical: (field: string) => string): [number, number] | undefined;
 
+declare const MAX_METRIC_WINDOW_PERIODS = 1000;
+/** Whether a clause needs planMetricSeries before an engine can run it. */
+declare function hasMetricSeries(c: AggregationClause): boolean;
+/** Throws when a clause's window or share cannot be computed exactly. */
+declare function validateMetricSeries(c: AggregationClause, plan: FormulaPlan): void;
+/** The whole intervals inside the conjunctive bounds on the date field (the
+ * query's and the metric's own), ending by `now`: [start, end). */
+declare function wholeIntervalSpan(c: AggregationClause, query: QueryState, schema: FieldSchema, now: number): {
+    start?: number;
+    end: number;
+};
+interface MetricSeriesOptions {
+    /** The evaluation clock: intervals ending after it are partial. */
+    now?: number;
+    resolveComputed?: (name: string) => FormulaPlan | undefined;
+}
+interface MetricSeriesPlan {
+    /** Plain metric queries within the metric budget. A clause's parts always
+     * share one query, so they read one population. */
+    queries: QueryState[];
+    /** The requested clauses' results, in request order, from the metric
+     * results of every query. */
+    combine(results: readonly AggregationResultEntry[]): AggregationResultEntry[];
+}
+/** Expand clauses with a window, a share or whole intervals into plain
+ * metrics, or return undefined when no clause has them.
+ *
+ * - **Window.** Each point is the metric over the rows of its trailing
+ *   intervals (`reduce: "total"`), or the mean of their per-interval values
+ *   (`reduce: "mean"`), with the window's row count. Points whose window starts
+ *   before the first interval have no value unless `partial: "include"`.
+ * - **Share.** Each bucket divided by the total of its first grouping key, or
+ *   of every group. With a window, both are windowed first.
+ * - **Whole intervals.** `partialIntervals: "exclude"` narrows the metric to
+ *   the intervals the query bounds and `now` leave whole.
+ *
+ * `sort`, `groupLimit` and `minCount` (counting a window's rows) apply to the
+ * combined buckets. Windowed and share results have no Other remainder. */
+declare function planMetricSeries(query: QueryState, schema: FieldSchema, options?: MetricSeriesOptions): MetricSeriesPlan | undefined;
+
 interface SavedPropertyView {
     id: string;
     name: string;
@@ -1522,7 +1594,8 @@ declare function sourceDependencies<Row>(query: QueryState, schema: FieldSchema<
  * - Each `clause.groupBy` key adds `=`; a null key adds `is_null` (legacy
  *   aggregates already place empty text in that bucket).
  * - A date-grouped key becomes `>= start` and `< next`, using the clause's
- *   interval and timezone.
+ *   interval and timezone. A windowed point starts at its window's first
+ *   interval, or has no lower bound for a running value.
  * - A histogram bin (`bucket.bin`) adds `>= min` and `< max` (`<= max` for
  *   the final bin) on the distribution input, which must be a field reference.
  *   Box cohorts are their group keys.
@@ -1567,4 +1640,4 @@ declare function groupLinkQuery(query: QueryState, value: GroupLinkValue): Query
  * routes and unresolvable values return `href: null` with a `problem`. */
 declare function resolveGroupLink(query: QueryState, value: GroupLinkValue, targets?: LinkTargets): ResolvedGroupLink;
 
-export { AGG_OPS_BY_TYPE, AGG_OPS_NEEDING_FIELD, type AggOp, type AggregateConfig, type AggregationBucket, type AggregationClause, type AggregationRequest, type AggregationResult, type AggregationResultEntry, type Align, type ApplyPatchOptions, type ApplyResult, type BackendField, COMPUTED_PREFIX, type CellDisplay, type CellRenderer, type ColumnPreview, type ComputedCellError, type ComputedColumn, type ComputedColumnDraft, type ComputedColumnStore, type ComputedExecution, type ComputedFieldCapabilities, type DerivedField, type DistinctValuesQuery, type DistinctValuesResult, EMPTY_QUERY, FORMULA_FUNCTIONS, type FetchRowsResult, type FetchRowsResultV2, type FieldDef, type FieldOrigin, type FieldRelationship, type FieldSchema, type FieldSource, type FieldStats, type FieldType, type FilterConfig, type FilterOp, type FilterValues, type ForeignKey, type FormulaDiagnostic, FormulaError, type FormulaFunction, type FormulaNode, type FormulaPlan, type FormulaResult, type FormulaType, type FormulaValue, GROUP_ID_FIELD, GROUP_LINK_RENDER, type GroupLinkValue, type GroupedRow, type GroupingDefinition, type GroupingModel, type GroupingState, type GroupingView, ITEM_DETAILS_COLUMN, type ItemDetailMode, type ItemDetailsState, type ItemPageOptions, type ItemPropertyMode, type JsonCellDisplay, type LinkDestination, type LinkSpec, type LinkTargets, MAX_AGGREGATIONS, MAX_GROUP_BY_FIELDS, MAX_ORDER_BY_TERMS, MAX_PROPERTIES, MAX_QUERY_LIMIT, MAX_QUERY_OFFSET, MAX_QUERY_STATE_BYTES, MAX_QUERY_TOKEN_LENGTH, MAX_RELATIVE_TIME_MS, MAX_REPRESENTATIVE_SORTS, MAX_RESULT_GROUPS, MAX_SELECT_COLUMNS, MAX_SUMMARY_COLUMNS, MAX_WHERE_CLAUSES, METRIC_DATE_INTERVALS, METRIC_FUNCTIONS, type MetricAxisScale, type MetricBoxSummary, type MetricCapabilities, type MetricDateGrouping, type MetricDiagnostic, type MetricDisplay, type MetricDistribution, type MetricDistributionResult, type MetricEvaluationOptions, type MetricHistogramBin, type MetricKey, type MetricLayout, type MetricPlan, type MetricPopulationSupport, type MetricQuery, type MetricReductionOptions, type MetricScope, type MetricSort, type MetricValue, type MetricValueFormat, NULLARY_OPS, OPS_BY_TYPE, OP_LABEL, type ObjectReference, type ObjectTypeDefinition, type OpChoice, type OpPair, type OrGroup, type OrderByClause, type PreviewGroup, type PropertyFieldConfig, type PropertyFormat, type PropertySelection, type PropertyViewState, type PropertyViewStorage, type QueryCapabilitiesV3, QueryDecodeError, type QueryEvaluationOptions, type QueryFacet, type QueryLink, type QueryLinkOptions, type QueryLinkService, type QueryPatch, type QueryPatchMatch, type QueryRequestV3, type QueryResultV3, type QuerySnapshot, type QuerySnapshotCache, QuerySnapshotHttpError, type QuerySnapshotHttpErrorCode, type QuerySnapshotStore, type QueryState, type RegexInspection, type RelationshipAdapter, type RepresentativeOrder, type RepresentativeRow, type ResolvedGroupLink, type ResolvedObjectReference, type RowComputedValues, type RowId, type SavedPropertyView, type SavedQuery, type SelectColumn, type SelectConfig, type ServerQuery, type ServerQueryV2, type SetFilterMetadata, type SetFilterMode, type SetFilterTarget, type SortConfig, type SourceDependencies, type StorageAdapter, type SummaryColumn, type SummaryOp, type Transport, type WhereClause, type WhereTerm, aggOpAllowedForType, aggOpNeedsField, aggOpsForField, applyAggregations, applyPatch, applyQuery, boxSummary, coerceValue, compareMetricValues, compileFormula, compileMetric, computedFieldName, createGroupingModel, createPropertyView, createQueryLinkService, createSetFilter, decodeQuery, decodeQueryStrict, discoverFieldRelationships, encodeQuery, evaluateMetricReductions, evaluateMetrics, exitGrouping, filterValues, formulaRuntime, groupLinkQuery, groupPreview, groupSourceQuery, hasRegex, histogramCounts, histogramEdges, httpComputedColumnStore, httpQuerySnapshotStore, indexFields, inspectBucketQuery, isComputedCellError, isComputedField, isFilterable, isGroupLinkField, isGroupLinkValue, isGroupable, isMeasurable, isNegativePredicate, isOrGroup, isPushdownFilter, isSelectable, isSortable, itemPageFields, jsonPropertyViewStorage, loadSchema, localPropertyViewStorage, localQuerySnapshotCache, localStorageAdapter, mapSetFilterValues, matchPatch, matchesClause, memoryComputedColumnStore, memoryPropertyViewStorage, memoryQuerySnapshotCache, memoryStorageAdapter, metricAggregatePlans, metricComputationKey, metricDateFloor, metricDateNext, metricDateRange, metricDateTime, metricDependencies, metricExpression, metricPlans, metricPopulationError, negateClause, normalizePropertyFormat, normalizePropertyView, normalizeQueryState, objectReferenceKey, opAllowedForType, opPairsForField, opsForField, parseRelativeDuration, percentile, predicatesOf, prepareGrouping, queriesEqual, readFieldValue, readObjectReference, readSetFilter, reduceMetricValues, removePatch, renderItemPageTemplate, resolveFieldName, resolveGroupLink, selectMetricShownRows, selectedFields, setFilterModes, setFilterTarget, sourceDependencies, sourceExecutionSchema, stripSetFilter, toAggregationQuery, toMetricQuery, toQueryRequestV3, toServerQuery, toServerQueryV2, validateComputedColumn, validateDateGrouping, validateItemPageTemplate, validateMetric, validateQueryResultV3, validateQuerySnapshot, withGroupingKeys, withoutGrouping, withoutLinkSummaries };
+export { AGG_OPS_BY_TYPE, AGG_OPS_NEEDING_FIELD, type AggOp, type AggregateConfig, type AggregationBucket, type AggregationClause, type AggregationRequest, type AggregationResult, type AggregationResultEntry, type Align, type ApplyPatchOptions, type ApplyResult, type BackendField, COMPUTED_PREFIX, type CellDisplay, type CellRenderer, type ColumnPreview, type ComputedCellError, type ComputedColumn, type ComputedColumnDraft, type ComputedColumnStore, type ComputedExecution, type ComputedFieldCapabilities, type DerivedField, type DistinctValuesQuery, type DistinctValuesResult, EMPTY_QUERY, FORMULA_FUNCTIONS, type FetchRowsResult, type FetchRowsResultV2, type FieldDef, type FieldOrigin, type FieldRelationship, type FieldSchema, type FieldSource, type FieldStats, type FieldType, type FilterConfig, type FilterOp, type FilterValues, type ForeignKey, type FormulaDiagnostic, FormulaError, type FormulaFunction, type FormulaNode, type FormulaPlan, type FormulaResult, type FormulaType, type FormulaValue, GROUP_ID_FIELD, GROUP_LINK_RENDER, type GroupLinkValue, type GroupedRow, type GroupingDefinition, type GroupingModel, type GroupingState, type GroupingView, ITEM_DETAILS_COLUMN, type ItemDetailMode, type ItemDetailsState, type ItemPageOptions, type ItemPropertyMode, type JsonCellDisplay, type LinkDestination, type LinkSpec, type LinkTargets, MAX_AGGREGATIONS, MAX_GROUP_BY_FIELDS, MAX_METRIC_WINDOW_PERIODS, MAX_ORDER_BY_TERMS, MAX_PROPERTIES, MAX_QUERY_LIMIT, MAX_QUERY_OFFSET, MAX_QUERY_STATE_BYTES, MAX_QUERY_TOKEN_LENGTH, MAX_RELATIVE_TIME_MS, MAX_REPRESENTATIVE_SORTS, MAX_RESULT_GROUPS, MAX_SELECT_COLUMNS, MAX_SUMMARY_COLUMNS, MAX_WHERE_CLAUSES, METRIC_DATE_INTERVALS, METRIC_FUNCTIONS, type MetricAxisScale, type MetricBoxSummary, type MetricCapabilities, type MetricDateGrouping, type MetricDiagnostic, type MetricDisplay, type MetricDistribution, type MetricDistributionResult, type MetricEvaluationOptions, type MetricHistogramBin, type MetricKey, type MetricLayout, type MetricPlan, type MetricPopulationSupport, type MetricQuery, type MetricReductionOptions, type MetricScope, type MetricSeriesOptions, type MetricSeriesPlan, type MetricShare, type MetricSort, type MetricValue, type MetricValueFormat, type MetricWindow, NULLARY_OPS, OPS_BY_TYPE, OP_LABEL, type ObjectReference, type ObjectTypeDefinition, type OpChoice, type OpPair, type OrGroup, type OrderByClause, type PreviewGroup, type PropertyFieldConfig, type PropertyFormat, type PropertySelection, type PropertyViewState, type PropertyViewStorage, type QueryCapabilitiesV3, QueryDecodeError, type QueryEvaluationOptions, type QueryFacet, type QueryLink, type QueryLinkOptions, type QueryLinkService, type QueryPatch, type QueryPatchMatch, type QueryRequestV3, type QueryResultV3, type QuerySnapshot, type QuerySnapshotCache, QuerySnapshotHttpError, type QuerySnapshotHttpErrorCode, type QuerySnapshotStore, type QueryState, type RegexInspection, type RelationshipAdapter, type RepresentativeOrder, type RepresentativeRow, type ResolvedGroupLink, type ResolvedObjectReference, type RowComputedValues, type RowId, type SavedPropertyView, type SavedQuery, type SelectColumn, type SelectConfig, type ServerQuery, type ServerQueryV2, type SetFilterMetadata, type SetFilterMode, type SetFilterTarget, type SortConfig, type SourceDependencies, type StorageAdapter, type SummaryColumn, type SummaryOp, type Transport, type WhereClause, type WhereTerm, aggOpAllowedForType, aggOpNeedsField, aggOpsForField, applyAggregations, applyPatch, applyQuery, boxSummary, coerceValue, compareMetricValues, compileFormula, compileMetric, computedFieldName, createGroupingModel, createPropertyView, createQueryLinkService, createSetFilter, decodeQuery, decodeQueryStrict, discoverFieldRelationships, encodeQuery, evaluateMetricReductions, evaluateMetrics, exitGrouping, filterValues, formulaRuntime, groupLinkQuery, groupPreview, groupSourceQuery, hasMetricSeries, hasRegex, histogramCounts, histogramEdges, httpComputedColumnStore, httpQuerySnapshotStore, indexFields, inspectBucketQuery, isComputedCellError, isComputedField, isFilterable, isGroupLinkField, isGroupLinkValue, isGroupable, isMeasurable, isNegativePredicate, isOrGroup, isPushdownFilter, isSelectable, isSortable, itemPageFields, jsonPropertyViewStorage, loadSchema, localPropertyViewStorage, localQuerySnapshotCache, localStorageAdapter, mapSetFilterValues, matchPatch, matchesClause, memoryComputedColumnStore, memoryPropertyViewStorage, memoryQuerySnapshotCache, memoryStorageAdapter, metricAggregatePlans, metricComputationKey, metricCustomEndTime, metricDateFloor, metricDateNext, metricDateRange, metricDateTime, metricDependencies, metricExpression, metricPlans, metricPopulationError, negateClause, normalizePropertyFormat, normalizePropertyView, normalizeQueryState, objectReferenceKey, opAllowedForType, opPairsForField, opsForField, parseRelativeDuration, percentile, planMetricSeries, predicatesOf, prepareGrouping, queriesEqual, readFieldValue, readObjectReference, readSetFilter, reduceMetricValues, removePatch, renderItemPageTemplate, resolveFieldName, resolveGroupLink, selectMetricShownRows, selectedFields, setFilterModes, setFilterTarget, sortMetricBuckets, sourceDependencies, sourceExecutionSchema, stripSetFilter, toAggregationQuery, toMetricQuery, toQueryRequestV3, toServerQuery, toServerQueryV2, validateComputedColumn, validateDateGrouping, validateItemPageTemplate, validateMetric, validateMetricSeries, validateQueryResultV3, validateQuerySnapshot, wholeIntervalSpan, withGroupingKeys, withoutGrouping, withoutLinkSummaries };