Skip to content

Fix AggregationContainer for all bucket aggregations so that aggs/aggregations are siblings of the aggregation type#1069

Merged
lucy66hw merged 3 commits intoopensearch-project:mainfrom
karenyrx:subargs
Mar 12, 2026
Merged

Fix AggregationContainer for all bucket aggregations so that aggs/aggregations are siblings of the aggregation type#1069
lucy66hw merged 3 commits intoopensearch-project:mainfrom
karenyrx:subargs

Conversation

@karenyrx
Copy link
Copy Markdown
Collaborator

Description

The correct REST request format is:

{
  "size": 0,
  "aggs": {
    "by_category": {
      "terms": {
        "field": "category.keyword"
      },
      "aggs": {
        "avg_price": {
          "avg": { "field": "price" }
        }
      }
    }
  }
}

but current spec supports something like this instead  ("aggs" is incorrectly nested inside "terms")

{
  "size": 0,
  "aggs": {
    "by_category": {
      "terms": {
        "field": "category.keyword", 
        "aggs": {
           "avg_price": {
             "avg": { "field": "price" }
           }
         }
      }
    }
  }
}

Fix this for 26 aggregation types that have a base of BucketAggregationBase (which is where subaggregations live)

Issues Resolved

List any issues this PR will resolve, e.g. Closes [...].

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.
For more information on following Developer Certificate of Origin and signing off your commits, please check here.

…/`aggregations` are siblings of the aggregation type

Signed-off-by: Karen X <karenxyr@gmail.com>
@github-actions
Copy link
Copy Markdown
Contributor

Proto Compatibility Report

Merge Report

No changes detected.


Generated by Proto Compatibility Check

@github-actions
Copy link
Copy Markdown
Contributor

github-actions bot commented Mar 11, 2026

Changes Analysis

Commit SHA: 43a4c4e
Comparing To SHA: fccf8eb

API Changes

Summary

└─┬Components
  ├──[➕] schemas/_common.aggregations___CompositeAggregationFields (42308:7)
  ├──[➕] schemas/_common.aggregations___MissingAggregationFields (43389:7)
  ├──[➕] schemas/_common.aggregations___GlobalAggregationFields (42964:7)
  ├──[➕] schemas/_common.aggregations___MultiTermsAggregationFields (43726:7)
  ├──[➕] schemas/_common.aggregations___RangeAggregationFields (43942:7)
  ├──[➕] schemas/_common.aggregations___GeoHashGridAggregationFields (42882:7)
  ├──[➕] schemas/_common.aggregations___GeoTileGridAggregationFields (42923:7)
  ├──[➕] schemas/_common.aggregations___TermsAggregationFields (44669:7)
  ├──[➕] schemas/_common.aggregations___AutoDateHistogramAggregationFields (41968:7)
  ├──[➕] schemas/_common.aggregations___FiltersAggregationFields (42763:7)
  ├──[➕] schemas/_common.aggregations___SamplerAggregationFields (44078:7)
  ├──[➕] schemas/_common.aggregations___AdjacencyMatrixAggregationFields (41479:7)
  ├──[➕] schemas/_common.aggregations___FilterAggregationFields (42748:7)
  ├──[➕] schemas/_common.aggregations___RareTermsAggregationFields (43992:7)
  ├──[➕] schemas/_common.aggregations___ParentAggregationFields (43834:7)
  ├──[➕] schemas/_common.aggregations___FilterAggregation (42738:7)
  ├──[➕] schemas/_common.aggregations___IpRangeAggregationFields (43138:7)
  ├──[➕] schemas/_common.aggregations___DateHistogramAggregationFields (42433:7)
  ├──[➕] schemas/_common.aggregations___NestedAggregationFields (43800:7)
  ├──[➕] schemas/_common.aggregations___GeoDistanceAggregationFields (42853:7)
  ├──[➕] schemas/_common.aggregations___SignificantTermsAggregationFields (44224:7)
  ├──[➕] schemas/_common.aggregations___HistogramAggregationFields (43000:7)
  ├──[➕] schemas/_common.aggregations___ChildrenAggregationFields (42271:7)
  ├──[➕] schemas/_common.aggregations___DateRangeAggregationFields (42499:7)
  ├──[➕] schemas/_common.aggregations___SignificantTextAggregationFields (44292:7)
  ├──[➕] schemas/_common.aggregations___DiversifiedSamplerAggregationFields (42552:7)
  ├──[➕] schemas/_common.aggregations___ReverseNestedAggregationFields (44054:7)
  └─┬Schemas
    ├─┬_common.aggregations___TermsAggregation
    │ ├──[➖] allOf (44643:11)❌ 
    │ └─┬ALLOF
    │   ├──[➕] required (44655:15)❌ 
    │   ├──[➖] properties/collect_mode (44605:13)❌ 
    │   ├──[➖] properties/exclude (44607:13)❌ 
    │   ├──[➖] properties/execution_hint (44609:13)❌ 
    │   ├──[➖] properties/format (44641:13)❌ 
    │   ├──[➖] properties/include (44611:13)❌ 
    │   ├──[➖] properties/min_doc_count (44613:13)❌ 
    │   ├──[➖] properties/missing (44617:13)❌ 
    │   ├──[➖] properties/order (44622:13)❌ 
    │   ├──[➖] properties/shard_min_doc_count (44630:13)❌ 
    │   ├──[➖] properties/shard_size (44624:13)❌ 
    │   ├──[➖] properties/show_term_doc_count_error (44634:13)❌ 
    │   ├──[➖] properties/size (44637:13)❌ 
    │   ├──[➖] properties/value_type (44619:13)❌ 
    │   └──[➕] properties/terms (44652:13)
    ├─┬_common.aggregations___SignificantTermsAggregation
    │ └─┬ALLOF
    │   ├──[➕] required (44222:15)❌ 
    │   ├──[➖] properties/background_filter (44186:13)❌ 
    │   ├──[➖] properties/chi_square (44188:13)❌ 
    │   ├──[➖] properties/exclude (44190:13)❌ 
    │   ├──[➖] properties/execution_hint (44192:13)❌ 
    │   ├──[➖] properties/field (44194:13)❌ 
    │   ├──[➖] properties/gnd (44196:13)❌ 
    │   ├──[➖] properties/include (44198:13)❌ 
    │   ├──[➖] properties/jlh (44200:13)❌ 
    │   ├──[➖] properties/min_doc_count (44202:13)❌ 
    │   ├──[➖] properties/mutual_information (44206:13)❌ 
    │   ├──[➖] properties/percentage (44208:13)❌ 
    │   ├──[➖] properties/script_heuristic (44210:13)❌ 
    │   ├──[➖] properties/shard_min_doc_count (44212:13)❌ 
    │   ├──[➖] properties/shard_size (44218:13)❌ 
    │   ├──[➖] properties/size (44224:13)❌ 
    │   └──[➕] properties/significant_terms (44219:13)
    ├─┬_common.aggregations___MissingAggregation
    │ └─┬ALLOF
    │   ├──[➕] required (43387:15)❌ 
    │   ├──[➖] properties/field (43407:13)❌ 
    │   └─┬Properties
    │     └──missing
    ├─┬_common.aggregations___RangeAggregation
    │ └─┬ALLOF
    │   ├──[➕] required (43940:15)❌ 
    │   ├──[➖] properties/field (43932:13)❌ 
    │   ├──[➖] properties/format (43950:13)❌ 
    │   ├──[➖] properties/keyed (43947:13)❌ 
    │   ├──[➖] properties/missing (43934:13)❌ 
    │   ├──[➖] properties/ranges (43940:13)❌ 
    │   ├──[➖] properties/script (43945:13)❌ 
    │   └──[➕] properties/range (43937:13)
    ├─┬_common.aggregations___ChildrenAggregation
    │ └─┬ALLOF
    │   ├──[➕] required (42269:15)❌ 
    │   ├──[➕] properties/children (42266:13)
    │   └──[➖] properties/type (42385:13)❌ 
    ├─┬_common.aggregations___DateHistogramAggregation
    │ └─┬ALLOF
    │   ├──[➕] required (42431:15)❌ 
    │   ├──[➖] properties/calendar_interval (42533:13)❌ 
    │   ├──[➖] properties/extended_bounds (42535:13)❌ 
    │   ├──[➖] properties/field (42539:13)❌ 
    │   ├──[➖] properties/fixed_interval (42541:13)❌ 
    │   ├──[➖] properties/format (42543:13)❌ 
    │   ├──[➖] properties/hard_bounds (42537:13)❌ 
    │   ├──[➖] properties/interval (42548:13)❌ 
    │   ├──[➖] properties/keyed (42569:13)❌ 
    │   ├──[➖] properties/min_doc_count (42550:13)❌ 
    │   ├──[➖] properties/missing (42556:13)❌ 
    │   ├──[➖] properties/offset (42558:13)❌ 
    │   ├──[➖] properties/order (42560:13)❌ 
    │   ├──[➖] properties/params (42562:13)❌ 
    │   ├──[➖] properties/script (42565:13)❌ 
    │   ├──[➖] properties/time_zone (42567:13)❌ 
    │   └──[➕] properties/date_histogram (42428:13)
    ├─┬_common.aggregations___FiltersAggregation
    │ └─┬ALLOF
    │   ├──[➕] required (42761:15)❌ 
    │   ├──[➖] properties/keyed (42838:13)❌ 
    │   ├──[➖] properties/other_bucket (42832:13)❌ 
    │   ├──[➖] properties/other_bucket_key (42835:13)❌ 
    │   └─┬Properties
    │     └──filters
    ├─┬_common.aggregations___GeoDistanceAggregation
    │ └─┬ALLOF
    │   ├──[➕] required (42851:15)❌ 
    │   ├──[➖] properties/distance_type (42913:13)❌ 
    │   ├──[➖] properties/field (42915:13)❌ 
    │   ├──[➖] properties/origin (42917:13)❌ 
    │   ├──[➖] properties/ranges (42919:13)❌ 
    │   ├──[➖] properties/unit (42924:13)❌ 
    │   └──[➕] properties/geo_distance (42848:13)
    ├─┬_common.aggregations___DateRangeAggregation
    │ └─┬ALLOF
    │   ├──[➕] required (42497:15)❌ 
    │   ├──[➖] properties/field (42592:13)❌ 
    │   ├──[➖] properties/format (42594:13)❌ 
    │   ├──[➖] properties/keyed (42606:13)❌ 
    │   ├──[➖] properties/missing (42597:13)❌ 
    │   ├──[➖] properties/ranges (42599:13)❌ 
    │   ├──[➖] properties/time_zone (42604:13)❌ 
    │   └──[➕] properties/date_range (42494:13)
    ├─┬_common.aggregations___SamplerAggregation
    │ └─┬ALLOF
    │   ├──[➕] required (44070:15)❌ 
    │   ├──[➕] properties/sampler (44067:13)
    │   └──[➖] properties/shard_size (44041:13)❌ 
    ├─┬_common.aggregations___GeoTileGridAggregation
    │ └─┬ALLOF
    │   ├──[➕] required (42921:15)❌ 
    │   ├──[➖] properties/bounds (42983:13)❌ 
    │   ├──[➖] properties/field (42969:13)❌ 
    │   ├──[➖] properties/precision (42971:13)❌ 
    │   ├──[➖] properties/shard_size (42973:13)❌ 
    │   ├──[➖] properties/size (42979:13)❌ 
    │   └──[➕] properties/geotile_grid (42918:13)
    ├─┬_common.aggregations___SignificantTextAggregation
    │ └─┬ALLOF
    │   ├──[➕] required (44290:15)❌ 
    │   ├──[➖] properties/background_filter (44247:13)❌ 
    │   ├──[➖] properties/chi_square (44249:13)❌ 
    │   ├──[➖] properties/exclude (44251:13)❌ 
    │   ├──[➖] properties/execution_hint (44253:13)❌ 
    │   ├──[➖] properties/field (44255:13)❌ 
    │   ├──[➖] properties/filter_duplicate_text (44257:13)❌ 
    │   ├──[➖] properties/gnd (44260:13)❌ 
    │   ├──[➖] properties/include (44262:13)❌ 
    │   ├──[➖] properties/jlh (44264:13)❌ 
    │   ├──[➖] properties/min_doc_count (44266:13)❌ 
    │   ├──[➖] properties/mutual_information (44270:13)❌ 
    │   ├──[➖] properties/percentage (44272:13)❌ 
    │   ├──[➖] properties/script_heuristic (44274:13)❌ 
    │   ├──[➖] properties/shard_min_doc_count (44276:13)❌ 
    │   ├──[➖] properties/shard_size (44282:13)❌ 
    │   ├──[➖] properties/size (44288:13)❌ 
    │   ├──[➖] properties/source_fields (44292:13)❌ 
    │   └──[➕] properties/significant_text (44287:13)
    ├─┬_common.aggregations___AdjacencyMatrixAggregation
    │ └─┬ALLOF
    │   ├──[➕] required (41477:15)❌ 
    │   ├──[➕] properties/adjacency_matrix (41474:13)
    │   └──[➖] properties/filters (41474:13)❌ 
    ├─┬_common.aggregations___IpRangeAggregation
    │ └─┬ALLOF
    │   ├──[➕] required (43136:15)❌ 
    │   ├──[➖] properties/field (43163:13)❌ 
    │   ├──[➖] properties/ranges (43165:13)❌ 
    │   └──[➕] properties/ip_range (43133:13)
    ├─┬_common.aggregations___AutoDateHistogramAggregation
    │ └─┬ALLOF
    │   ├──[➕] required (41966:15)❌ 
    │   ├──[➖] properties/buckets (42089:13)❌ 
    │   ├──[➖] properties/field (42093:13)❌ 
    │   ├──[➖] properties/format (42095:13)❌ 
    │   ├──[➖] properties/minimum_interval (42100:13)❌ 
    │   ├──[➖] properties/missing (42102:13)❌ 
    │   ├──[➖] properties/offset (42104:13)❌ 
    │   ├──[➖] properties/params (42107:13)❌ 
    │   ├──[➖] properties/script (42110:13)❌ 
    │   ├──[➖] properties/time_zone (42112:13)❌ 
    │   └──[➕] properties/auto_date_histogram (41963:13)
    ├─┬_common.aggregations___CompositeAggregation
    │ └─┬ALLOF
    │   ├──[➕] required (42306:15)❌ 
    │   ├──[➖] properties/after (42415:13)❌ 
    │   ├──[➖] properties/size (42417:13)❌ 
    │   ├──[➖] properties/sources (42421:13)❌ 
    │   └──[➕] properties/composite (42303:13)
    ├─┬_common.aggregations___HistogramAggregation
    │ └─┬ALLOF
    │   ├──[➕] required (42998:15)❌ 
    │   ├──[➖] properties/extended_bounds (43032:13)❌ 
    │   ├──[➖] properties/field (43036:13)❌ 
    │   ├──[➖] properties/format (43066:13)❌ 
    │   ├──[➖] properties/hard_bounds (43034:13)❌ 
    │   ├──[➖] properties/interval (43038:13)❌ 
    │   ├──[➖] properties/keyed (43068:13)❌ 
    │   ├──[➖] properties/min_doc_count (43044:13)❌ 
    │   ├──[➖] properties/missing (43050:13)❌ 
    │   ├──[➖] properties/offset (43056:13)❌ 
    │   ├──[➖] properties/order (43062:13)❌ 
    │   ├──[➖] properties/script (43064:13)❌ 
    │   └──[➕] properties/histogram (42995:13)
    ├─┬_common.aggregations___GeoHashGridAggregation
    │ └─┬ALLOF
    │   ├──[➕] required (42880:15)❌ 
    │   ├──[➖] properties/bounds (42935:13)❌ 
    │   ├──[➖] properties/field (42937:13)❌ 
    │   ├──[➖] properties/precision (42939:13)❌ 
    │   ├──[➖] properties/shard_size (42941:13)❌ 
    │   ├──[➖] properties/size (42947:13)❌ 
    │   └──[➕] properties/geohash_grid (42877:13)
    ├─┬_common.aggregations___NestedAggregation
    │ └─┬ALLOF
    │   ├──[➕] required (43798:15)❌ 
    │   ├──[➕] properties/nested (43795:13)
    │   └──[➖] properties/path (43804:13)❌ 
    ├─┬_common.aggregations___DiversifiedSamplerAggregation
    │ └─┬ALLOF
    │   ├──[➕] required (42550:15)❌ 
    │   ├──[➖] properties/execution_hint (42638:13)❌ 
    │   ├──[➖] properties/field (42650:13)❌ 
    │   ├──[➖] properties/max_docs_per_value (42640:13)❌ 
    │   ├──[➖] properties/script (42644:13)❌ 
    │   ├──[➖] properties/shard_size (42646:13)❌ 
    │   └──[➕] properties/diversified_sampler (42547:13)
    ├─┬_common.aggregations___RareTermsAggregation
    │ └─┬ALLOF
    │   ├──[➕] required (43990:15)❌ 
    │   ├──[➖] properties/exclude (43975:13)❌ 
    │   ├──[➖] properties/field (43977:13)❌ 
    │   ├──[➖] properties/include (43979:13)❌ 
    │   ├──[➖] properties/max_doc_count (43981:13)❌ 
    │   ├──[➖] properties/missing (43985:13)❌ 
    │   ├──[➖] properties/precision (43987:13)❌ 
    │   ├──[➖] properties/value_type (43993:13)❌ 
    │   └──[➕] properties/rare_terms (43987:13)
    ├─┬_common.aggregations___ParentAggregation
    │ └─┬ALLOF
    │   ├──[➕] required (43832:15)❌ 
    │   ├──[➕] properties/parent (43829:13)
    │   └──[➖] properties/type (43831:13)❌ 
    ├─┬_common.aggregations___ReverseNestedAggregation
    │ └─┬ALLOF
    │   ├──[➕] required (44052:15)❌ 
    │   ├──[➕] properties/reverse_nested (44049:13)
    │   └──[➖] properties/path (44030:13)❌ 
    ├─┬_common.aggregations___MultiTermsAggregation
    │ └─┬ALLOF
    │   ├──[➕] required (43724:15)❌ 
    │   ├──[➖] required (43768:15)❌ 
    │   ├──[➖] properties/collect_mode (43737:13)❌ 
    │   ├──[➖] properties/min_doc_count (43741:13)❌ 
    │   ├──[➖] properties/order (43739:13)❌ 
    │   ├──[➖] properties/shard_min_doc_count (43745:13)❌ 
    │   ├──[➖] properties/shard_size (43749:13)❌ 
    │   ├──[➖] properties/show_term_doc_count_error (43755:13)❌ 
    │   ├──[➖] properties/size (43758:13)❌ 
    │   ├──[➖] properties/terms (43762:13)❌ 
    │   └──[➕] properties/multi_terms (43721:13)
    └─┬_common.aggregations___GlobalAggregation
      └─┬ALLOF
        ├──[➕] required (42962:15)❌ 
        └──[➕] properties/global (42959:13)

Document Element Total Changes Breaking Changes
components 219 337
  • BREAKING Changes: 337 out of 219
  • Removals: 144
  • Additions: 75
  • Breaking Removals: 144
  • Breaking Additions: 25

Report

The full API changes report is available at: https://github.com/opensearch-project/opensearch-api-specification/actions/runs/22982009615/artifacts/5882563013

API Coverage

Before After Δ
Covered (%) 666 (65.23 %) 666 (65.23 %) 0 (0 %)
Uncovered (%) 355 (34.77 %) 355 (34.77 %) 0 (0 %)
Unknown 149 149 0

$ref: '#/components/schemas/AutoDateHistogramAggregation'
required: [auto_date_histogram]
unevaluatedProperties: true
- $ref: '#/components/schemas/AdjacencyMatrixAggregation'
Copy link
Copy Markdown
Collaborator

@lucy66hw lucy66hw Mar 11, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

will properties: adjacency_matrix lost by this change?

Copy link
Copy Markdown
Collaborator Author

@karenyrx karenyrx Mar 11, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

no, adjacency_matrix is now defined in AdjacencyMatrixAggregation

AdjacencyMatrixAggregation:
      allOf:
        - $ref: '#/components/schemas/BucketAggregationBase'
        - type: object
          properties:
            adjacency_matrix:
              type: object
              properties:
                filters:
                  description: |-
                    Filters used to create buckets.
                    At least one filter is required.
                  type: object
                  additionalProperties:
                    $ref: '_common.query_dsl.yaml#/components/schemas/QueryContainer'
          required: [adjacency_matrix]

Signed-off-by: Karen X <karenxyr@gmail.com>
@karenyrx karenyrx marked this pull request as ready for review March 12, 2026 00:17
This reverts commit 63bb8f5.

Signed-off-by: Karen X <karenxyr@gmail.com>
@lucy66hw lucy66hw merged commit ba9329c into opensearch-project:main Mar 12, 2026
34 of 35 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants