From b463ebfc03902a4dc8aac2c9226048289305c693 Mon Sep 17 00:00:00 2001 From: Laura Trotta Date: Mon, 6 Oct 2025 13:04:46 +0200 Subject: [PATCH 1/4] fix search validation --- specification/_types/Geo.ts | 11 ++- .../_types/aggregations/Aggregate.ts | 77 ++++++++++++++++++- .../aggregations/AggregationContainer.ts | 22 ++++++ specification/_types/aggregations/metric.ts | 4 + specification/_types/aggregations/pipeline.ts | 2 + 5 files changed, 109 insertions(+), 7 deletions(-) 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..3c1790c010 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,65 @@ 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 +} + +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..3447493b6f 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,14 @@ 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. + * @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 +266,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 */ From f314b53f066fcdf850988b491ee47b0263c030a5 Mon Sep 17 00:00:00 2001 From: Laura Trotta Date: Mon, 6 Oct 2025 16:10:25 +0200 Subject: [PATCH 2/4] add variants to changetype --- specification/_types/aggregations/Aggregate.ts | 3 +++ 1 file changed, 3 insertions(+) diff --git a/specification/_types/aggregations/Aggregate.ts b/specification/_types/aggregations/Aggregate.ts index 3c1790c010..38b9c7b5e2 100644 --- a/specification/_types/aggregations/Aggregate.ts +++ b/specification/_types/aggregations/Aggregate.ts @@ -395,6 +395,9 @@ export class ChangePointBucket extends MultiBucketBase { key: FieldValue } +/** + * @variants typed_keys_quirk + */ export type ChangeType = | Dip | DistributionChange From e4527447811209ec1ebc1defb6d096015303d65b Mon Sep 17 00:00:00 2001 From: Laura Trotta <153528055+l-trotta@users.noreply.github.com> Date: Tue, 7 Oct 2025 10:43:47 +0200 Subject: [PATCH 3/4] Update specification/_types/aggregations/AggregationContainer.ts Co-authored-by: Quentin Pradet --- specification/_types/aggregations/AggregationContainer.ts | 1 + 1 file changed, 1 insertion(+) diff --git a/specification/_types/aggregations/AggregationContainer.ts b/specification/_types/aggregations/AggregationContainer.ts index 3447493b6f..b874786a71 100644 --- a/specification/_types/aggregations/AggregationContainer.ts +++ b/specification/_types/aggregations/AggregationContainer.ts @@ -208,6 +208,7 @@ export class AggregationContainer { * 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 From cb6bc47c8d79a986ddfe7f599b68bebff48053f7 Mon Sep 17 00:00:00 2001 From: Laura Trotta Date: Tue, 7 Oct 2025 10:57:51 +0200 Subject: [PATCH 4/4] add ext docs to table csv --- specification/_doc_ids/table.csv | 3 +++ 1 file changed, 3 insertions(+) diff --git a/specification/_doc_ids/table.csv b/specification/_doc_ids/table.csv index 23941a5133..e8eabc0c4f 100644 --- a/specification/_doc_ids/table.csv +++ b/specification/_doc_ids/table.csv @@ -680,6 +680,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,,