From 4ccdd5b018451043cf0caa957c14a163a95695dc Mon Sep 17 00:00:00 2001 From: Laura Trotta <153528055+l-trotta@users.noreply.github.com> Date: Tue, 7 Oct 2025 11:23:43 +0200 Subject: [PATCH] Add cartesian_bounds, cartesian_centroid and change_point aggregations (#5418) * fix search validation * add variants to changetype * Update specification/_types/aggregations/AggregationContainer.ts Co-authored-by: Quentin Pradet * add ext docs to table csv --------- Co-authored-by: Quentin Pradet (cherry picked from commit 23222d914f80f9858ad508ca6fb5b8749955d7bf) --- specification/_doc_ids/table.csv | 3 + specification/_types/Geo.ts | 11 ++- .../_types/aggregations/Aggregate.ts | 80 ++++++++++++++++++- .../aggregations/AggregationContainer.ts | 23 ++++++ specification/_types/aggregations/metric.ts | 4 + specification/_types/aggregations/pipeline.ts | 2 + 6 files changed, 116 insertions(+), 7 deletions(-) diff --git a/specification/_doc_ids/table.csv b/specification/_doc_ids/table.csv index 6472bec843..095e301749 100644 --- a/specification/_doc_ids/table.csv +++ b/specification/_doc_ids/table.csv @@ -664,6 +664,9 @@ search-aggregations-bucket-significantterms-aggregation,https://www.elastic.co/d search-aggregations-metrics-avg-aggregation,https://www.elastic.co/docs/reference/aggregations/search-aggregations-metrics-avg-aggregation,, search-aggregations-metrics-boxplot-aggregation,https://www.elastic.co/docs/reference/aggregations/search-aggregations-metrics-boxplot-aggregation,, search-aggregations-metrics-cardinality-aggregation,https://www.elastic.co/docs/reference/aggregations/search-aggregations-metrics-cardinality-aggregation,, +search-aggregations-metrics-cartesian-bounds-aggregation,https://www.elastic.co/docs/reference/aggregations/search-aggregations-metrics-cartesian-bounds-aggregation,, +search-aggregations-metrics-cartesian-centroid-aggregation,https://www.elastic.co/docs/reference/aggregations/search-aggregations-metrics-cartesian-centroid-aggregation,, +search-aggregations-change-point-aggregation,https://www.elastic.co/docs/reference/aggregations/search-aggregations-change-point-aggregation,, search-aggregations-metrics-extendedstats-aggregation,https://www.elastic.co/docs/reference/aggregations/search-aggregations-metrics-extendedstats-aggregation,, search-aggregations-pipeline-avg-bucket-aggregation,https://www.elastic.co/docs/reference/aggregations/search-aggregations-pipeline-avg-bucket-aggregation,, search-aggregations-pipeline-bucket-path,https://www.elastic.co/docs/reference/aggregations/pipeline#buckets-path-syntax,, diff --git a/specification/_types/Geo.ts b/specification/_types/Geo.ts index a3995dc248..d5f8c5db53 100644 --- a/specification/_types/Geo.ts +++ b/specification/_types/Geo.ts @@ -95,12 +95,6 @@ export type GeoTile = string /** A map hex cell (H3) reference */ export type GeoHexCell = string - -export class LatLon { - lat: double - lon: double -} - /** * A latitude/longitude as a 2 dimensional point. It can be represented in various ways: * - as a `{lat, long}` object @@ -128,6 +122,11 @@ export class LatLonGeoLocation { lon: double } +export class CartesianPoint { + x: double + y: double +} + export class GeoHashLocation { geohash: GeoHash } diff --git a/specification/_types/aggregations/Aggregate.ts b/specification/_types/aggregations/Aggregate.ts index d71ec3a8c6..38b9c7b5e2 100644 --- a/specification/_types/aggregations/Aggregate.ts +++ b/specification/_types/aggregations/Aggregate.ts @@ -20,12 +20,14 @@ import { CompositeAggregateKey } from '@_types/aggregations/bucket' import { AggregateName, Field, FieldValue, Metadata } from '@_types/common' import { + CartesianPoint, GeoBounds, GeoHash, GeoHexCell, GeoLine, GeoLocation, - GeoTile + GeoTile, + TopLeftBottomRightGeoBounds } from '@_types/Geo' import { double, integer, long } from '@_types/Numeric' import { DurationLarge, EpochTime, UnitMillis } from '@_types/Time' @@ -59,11 +61,14 @@ export type Aggregate = | SimpleValueAggregate | DerivativeAggregate | BucketMetricValueAggregate + | ChangePointAggregate // Multi value | StatsAggregate | StatsBucketAggregate | ExtendedStatsAggregate | ExtendedStatsBucketAggregate + | CartesianBoundsAggregate + | CartesianCentroidAggregate // Geo | GeoBoundsAggregate | GeoCentroidAggregate @@ -322,6 +327,17 @@ export class ExtendedStatsAggregate extends StatsAggregate { /** @variant name=extended_stats_bucket */ export class ExtendedStatsBucketAggregate extends ExtendedStatsAggregate {} +/** @variant name=cartesian_bounds */ +export class CartesianBoundsAggregate extends AggregateBase { + bounds?: TopLeftBottomRightGeoBounds +} + +/** @variant name=cartesian_centroid */ +export class CartesianCentroidAggregate extends AggregateBase { + count: long + location?: CartesianPoint +} + //----- Geo /** @@ -369,6 +385,68 @@ export class MultiBucketBase doc_count: long } +/** @variant name=change_point */ +export class ChangePointAggregate extends MultiBucketAggregateBase { + type: ChangeType + bucket?: ChangePointBucket +} + +export class ChangePointBucket extends MultiBucketBase { + key: FieldValue +} + +/** + * @variants typed_keys_quirk + */ +export type ChangeType = + | Dip + | DistributionChange + | Indeterminable + | NonStationary + | Spike + | Stationary + | StepChange + | TrendChange + +export class AbstractChangePoint { + p_value: double + change_point: integer +} + +/** @variant name=dip */ +export class Dip extends AbstractChangePoint {} + +/** @variant name=distribution_change */ +export class DistributionChange extends AbstractChangePoint {} + +/** @variant name=spike */ +export class Spike extends AbstractChangePoint {} + +/** @variant name=step_change */ +export class StepChange extends AbstractChangePoint {} + +/** @variant name=indeterminable */ +export class Indeterminable { + reason: string +} + +/** @variant name=non_stationary */ +export class NonStationary { + p_value: double + r_value: double + trend: string +} + +/** @variant name=stationary */ +export class Stationary {} + +/** @variant name=trend_change */ +export class TrendChange { + p_value: double + r_value: double + change_point: integer +} + /** * @variant name=histogram * @ext_doc_id search-aggregations-bucket-histogram-aggregation diff --git a/specification/_types/aggregations/AggregationContainer.ts b/specification/_types/aggregations/AggregationContainer.ts index 0a907f0ff7..b874786a71 100644 --- a/specification/_types/aggregations/AggregationContainer.ts +++ b/specification/_types/aggregations/AggregationContainer.ts @@ -60,6 +60,8 @@ import { AverageAggregation, BoxplotAggregation, CardinalityAggregation, + CartesianBoundsAggregation, + CartesianCentroidAggregation, ExtendedStatsAggregation, GeoBoundsAggregation, GeoCentroidAggregation, @@ -87,6 +89,7 @@ import { BucketScriptAggregation, BucketSelectorAggregation, BucketSortAggregation, + ChangePointAggregation, CumulativeCardinalityAggregation, CumulativeSumAggregation, DerivativeAggregation, @@ -183,6 +186,16 @@ export class AggregationContainer { * @ext_doc_id search-aggregations-metrics-cardinality-aggregation */ cardinality?: CardinalityAggregation + /** + * A metric aggregation that computes the spatial bounding box containing all values for a Point or Shape field. + * @ext_doc_id search-aggregations-metrics-cartesian-bounds-aggregation + */ + cartesian_bounds?: CartesianBoundsAggregation + /** + * A metric aggregation that computes the weighted centroid from all coordinate values for point and shape fields. + * @ext_doc_id search-aggregations-metrics-cartesian-centroid-aggregation + */ + cartesian_centroid?: CartesianCentroidAggregation /** * A multi-bucket aggregation that groups semi-structured text into buckets. * @ext_doc_id search-aggregations-bucket-categorize-text-aggregation @@ -190,6 +203,15 @@ export class AggregationContainer { * @availability serverless stability=experimental */ categorize_text?: CategorizeTextAggregation + /** + * A sibling pipeline that detects, spikes, dips, and change points in a metric. + * Given a distribution of values provided by the sibling multi-bucket aggregation, + * this aggregation indicates the bucket of any spike or dip and/or the bucket at which + * the largest change in the distribution of values, if they are statistically significant. + * There must be at least 22 bucketed values. Fewer than 1,000 is preferred. + * @ext_doc_id search-aggregations-change-point-aggregation + */ + change_point?: ChangePointAggregation /** * A single bucket aggregation that selects child documents that have the specified type, as defined in a `join` field. * @ext_doc_id search-aggregations-bucket-children-aggregation @@ -245,6 +267,7 @@ export class AggregationContainer { /** * A bucket aggregation which finds frequent item sets, a form of association rules mining that identifies items that often occur together. * @ext_doc_id search-aggregations-bucket-frequent-item-sets-aggregation + * @aliases frequent_items */ frequent_item_sets?: FrequentItemSetsAggregation /** diff --git a/specification/_types/aggregations/metric.ts b/specification/_types/aggregations/metric.ts index 28abf6486a..fb6a9b6775 100644 --- a/specification/_types/aggregations/metric.ts +++ b/specification/_types/aggregations/metric.ts @@ -111,6 +111,10 @@ export class ExtendedStatsAggregation extends FormatMetricAggregationBase { sigma?: double } +export class CartesianBoundsAggregation extends MetricAggregationBase {} + +export class CartesianCentroidAggregation extends MetricAggregationBase {} + /** * @ext_doc_id search-aggregations-metrics-geobounds-aggregation */ diff --git a/specification/_types/aggregations/pipeline.ts b/specification/_types/aggregations/pipeline.ts index e454708de8..5b2d296c75 100644 --- a/specification/_types/aggregations/pipeline.ts +++ b/specification/_types/aggregations/pipeline.ts @@ -203,6 +203,8 @@ export class BucketSortAggregation extends Aggregation { sort?: Sort } +export class ChangePointAggregation extends PipelineAggregationBase {} + /** * @ext_doc_id search-aggregations-pipeline-cumulative-cardinality-aggregation */