Support for aggregations in Security's Query API Key Information API (#2455) (#2459)

* Done

* Restrict aggs types

* types.ts

* make contrib

---------

Co-authored-by: Laurent Saint-Félix <[email protected]>
(cherry picked from commit 221884f)

Co-authored-by: Albert Zaharovits <[email protected]>

Author: github-actions[bot]

specification/security/query_api_keys/QueryApiKeysRequest.ts

@@ -17,6 +17,8 @@
  * under the License.
  */
 
+import { Dictionary } from '@spec_utils/Dictionary'
+import { APIKeyAggregationContainer } from './types'
 import { RequestBase } from '@_types/Base'
 import { integer } from '@_types/Numeric'
 import { QueryContainer } from '@_types/query_dsl/abstractions'
@@ -32,7 +34,7 @@ import { Sort, SortResults } from '@_types/sort'
 export interface Request extends RequestBase {
   query_parameters: {
     /**
-     * Return the snapshot of the owner user's role descriptors associated with the API key. 
+     * Return the snapshot of the owner user's role descriptors associated with the API key.
      * An API key's actual permission is the intersection of its assigned role descriptors and the owner user's role descriptors.
      * @availability stack since=8.5.0
      * @availability serverless
@@ -41,10 +43,21 @@ export interface Request extends RequestBase {
     with_limited_by?: boolean
   }
   body: {
+    /**
+     * Any aggregations to run over the corpus of returned API keys.
+     * Aggregations and queries work together. Aggregations are computed only on the API keys that match the query.
+     * This supports only a subset of aggregation types, namely: `terms`, `range`, `date_range`, `missing`,
+     * `cardinality`, `value_count`, `composite`, `filter`, and `filters`.
+     * Additionally, aggregations only run over the same subset of fields that query works with.
+     * @aliases aggs */
+    aggregations?: Dictionary<string, APIKeyAggregationContainer>
     /**
      * A query to filter which API keys to return.
-     * The query supports a subset of query types, including `match_all`, `bool`, `term`, `terms`, `ids`, `prefix`, `wildcard`, and `range`.
-     * You can query all public information associated with an API key.
+     * If the query parameter is missing, it is equivalent to a `match_all` query.
+     * The query supports a subset of query types, including `match_all`, `bool`, `term`, `terms`, `match`,
+     * `ids`, `prefix`, `wildcard`, `exists`, `range`, and `simple_query_string`.
+     * You can query the following public information associated with an API key: `id`, `type`, `name`,
+     * `creation`, `expiration`, `invalidated`, `invalidation`, `username`, `realm`, and `metadata`.
      */
     query?: QueryContainer
     /**

specification/security/query_api_keys/QueryApiKeysResponse.ts

@@ -19,6 +19,9 @@
 
 import { ApiKey } from '@security/_types/ApiKey'
 import { integer } from '@_types/Numeric'
+import { Dictionary } from '@spec_utils/Dictionary'
+import { AggregateName } from '@_types/common'
+import { APIKeyAggregate } from './types'
 
 export class Response {
   body: {
@@ -34,5 +37,9 @@ export class Response {
      * A list of API key information.
      */
     api_keys: ApiKey[]
+    /**
+     * The aggregations result, if requested.
+     */
+    aggregations?: Dictionary<AggregateName, APIKeyAggregate>
   }
 }

specification/security/query_api_keys/types.ts

@@ -0,0 +1,127 @@
+/*
+ * Licensed to Elasticsearch B.V. under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch B.V. licenses this file to you under
+ * the Apache License, Version 2.0 (the "License"); you may
+ * not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import { Dictionary } from '@spec_utils/Dictionary'
+import { Metadata } from '@_types/common'
+import { QueryContainer } from '@_types/query_dsl/abstractions'
+import {
+  CompositeAggregation,
+  DateRangeAggregation,
+  FiltersAggregation,
+  MissingAggregation,
+  RangeAggregation,
+  TermsAggregation
+} from '@_types/aggregations/bucket'
+import {
+  CardinalityAggregation,
+  ValueCountAggregation
+} from '@_types/aggregations/metric'
+import {
+  CardinalityAggregate,
+  ValueCountAggregate,
+  StringTermsAggregate,
+  LongTermsAggregate,
+  DoubleTermsAggregate,
+  UnmappedTermsAggregate,
+  MultiTermsAggregate,
+  MissingAggregate,
+  FilterAggregate,
+  RangeAggregate,
+  DateRangeAggregate,
+  FiltersAggregate,
+  CompositeAggregate
+} from '@_types/aggregations/Aggregate'
+
+/**
+ * @variants container
+ * @non_exhaustive
+ */
+export class APIKeyAggregationContainer {
+  /**
+   * Sub-aggregations for this aggregation.
+   * Only applies to bucket aggregations.
+   * @variant container_property
+   * @aliases aggs
+   */
+  aggregations?: Dictionary<string, APIKeyAggregationContainer>
+  /**
+   * @variant container_property
+   */
+  meta?: Metadata
+  /**
+   * A single-value metrics aggregation that calculates an approximate count of distinct values.
+   * @doc_id search-aggregations-metrics-cardinality-aggregation
+   */
+  cardinality?: CardinalityAggregation
+  /**
+   * A multi-bucket aggregation that creates composite buckets from different sources.
+   * Unlike the other multi-bucket aggregations, you can use the `composite` aggregation to paginate *all* buckets from a multi-level aggregation efficiently.
+   */
+  composite?: CompositeAggregation
+  /**
+   * A multi-bucket value source based aggregation that enables the user to define a set of date ranges - each representing a bucket.
+   * @doc_id search-aggregations-bucket-daterange-aggregation
+   */
+  date_range?: DateRangeAggregation
+  /**
+   * A single bucket aggregation that narrows the set of documents to those that match a query.
+   * @doc_id search-aggregations-bucket-filter-aggregation
+   */
+  filter?: QueryContainer
+  /**
+   * A multi-bucket aggregation where each bucket contains the documents that match a query.
+   * @doc_id search-aggregations-bucket-filters-aggregation
+   */
+  filters?: FiltersAggregation
+  missing?: MissingAggregation
+  /**
+   * A multi-bucket value source based aggregation that enables the user to define a set of ranges - each representing a bucket.
+   * @doc_id search-aggregations-bucket-range-aggregation
+   */
+  range?: RangeAggregation
+  /**
+   * A multi-bucket value source based aggregation where buckets are dynamically built - one per unique value.
+   * @doc_id search-aggregations-bucket-terms-aggregation
+   */
+  terms?: TermsAggregation
+  /**
+   * A single-value metrics aggregation that counts the number of values that are extracted from the aggregated documents.
+   * @doc_id search-aggregations-metrics-valuecount-aggregation
+   */
+  value_count?: ValueCountAggregation
+}
+
+/**
+ * @variants external
+ * @non_exhaustive
+ */
+export type APIKeyAggregate =
+  | CardinalityAggregate
+  | ValueCountAggregate
+  | StringTermsAggregate
+  | LongTermsAggregate
+  | DoubleTermsAggregate
+  | UnmappedTermsAggregate
+  | MultiTermsAggregate
+  | MissingAggregate
+  | FilterAggregate
+  | FiltersAggregate
+  | RangeAggregate
+  | DateRangeAggregate
+  | CompositeAggregate