From 776c35514bff43702c5ee35a7d9b08628a7eefc6 Mon Sep 17 00:00:00 2001 From: Siddharth Rayabharam Date: Fri, 13 Sep 2024 16:41:27 -0400 Subject: [PATCH 1/4] Execution hint documentation added to cardinality agg Signed-off-by: Siddharth Rayabharam --- _aggregations/metric/cardinality.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/_aggregations/metric/cardinality.md b/_aggregations/metric/cardinality.md index e03a561adb2..096eaaa9d53 100644 --- a/_aggregations/metric/cardinality.md +++ b/_aggregations/metric/cardinality.md @@ -58,4 +58,26 @@ GET opensearch_dashboards_sample_data_ecommerce/_search } } } +``` + +You can choose the mechanism by which the aggregation is executed with the `execution_hint` setting. This setting accepts two values: + +1. `direct`: Use field values directly. +2. `ordinals`: Use ordinals of the field. + +If not specified, mechanism that is appropriate for the field is selected. Note that specifying `ordinals` on a non-ordinal field will have no effect. Similarly, `direct` will have no effect on ordinal fields. + +```json +GET opensearch_dashboards_sample_data_ecommerce/_search +{ + "size": 0, + "aggs": { + "unique_products": { + "cardinality": { + "field": "products.product_id", + "execution_hint": "ordinals" + } + } + } +} ``` \ No newline at end of file From 59f966b2322e2b7b51e63ea84a7fd498273e15a7 Mon Sep 17 00:00:00 2001 From: Asim Mahmood Date: Mon, 17 Feb 2025 18:57:59 +0000 Subject: [PATCH 2/4] Add expert level warning to cardinality execution_hint paramter Signed-off-by: Asim Mahmood --- _aggregations/metric/cardinality.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/_aggregations/metric/cardinality.md b/_aggregations/metric/cardinality.md index 096eaaa9d53..906ccaf5aa4 100644 --- a/_aggregations/metric/cardinality.md +++ b/_aggregations/metric/cardinality.md @@ -65,7 +65,13 @@ You can choose the mechanism by which the aggregation is executed with the `exec 1. `direct`: Use field values directly. 2. `ordinals`: Use ordinals of the field. -If not specified, mechanism that is appropriate for the field is selected. Note that specifying `ordinals` on a non-ordinal field will have no effect. Similarly, `direct` will have no effect on ordinal fields. + +If not specified, OpenSearch automatically selects the appropriate mechanism for the field. Note: + + * Specifying ordinals on a non-ordinal field will have no effect. + * Similarly, direct will have no effect on ordinal fields. + +This is an expert-level setting. Ordinals use byte arrays, where the size of the array will be as large as the cardinality value. For high-cardinality fields, this can lead to significant heap memory usage and risk of out-of-memory errors. {: .warning} ```json GET opensearch_dashboards_sample_data_ecommerce/_search @@ -80,4 +86,4 @@ GET opensearch_dashboards_sample_data_ecommerce/_search } } } -``` \ No newline at end of file +``` From 18665c8b24c899f1e785ab4b2ae1bd67fc3bb990 Mon Sep 17 00:00:00 2001 From: Fanit Kolchina Date: Mon, 24 Feb 2025 16:37:30 -0500 Subject: [PATCH 3/4] Doc review Signed-off-by: Fanit Kolchina --- _aggregations/metric/cardinality.md | 24 ++++++++++++++++-------- 1 file changed, 16 insertions(+), 8 deletions(-) diff --git a/_aggregations/metric/cardinality.md b/_aggregations/metric/cardinality.md index 906ccaf5aa4..53cea6b5bee 100644 --- a/_aggregations/metric/cardinality.md +++ b/_aggregations/metric/cardinality.md @@ -59,19 +59,26 @@ GET opensearch_dashboards_sample_data_ecommerce/_search } } ``` +{% include copy-curl.html %} + +## Configuring aggregation execution -You can choose the mechanism by which the aggregation is executed with the `execution_hint` setting. This setting accepts two values: +You can control how an aggregation runs using the `execution_hint` setting. This setting supports two options: -1. `direct`: Use field values directly. -2. `ordinals`: Use ordinals of the field. +- `direct` – Uses field values directly. +- `ordinals` – Uses ordinals of the field. +If you don’t specify `execution_hint`, OpenSearch automatically chooses the best option for the field. -If not specified, OpenSearch automatically selects the appropriate mechanism for the field. Note: +Setting `ordinals` on a non-ordinal field has no effect. Similarly, `direct` has no effect on ordinal fields. +{: .note} - * Specifying ordinals on a non-ordinal field will have no effect. - * Similarly, direct will have no effect on ordinal fields. +This is an expert-level setting. Ordinals use byte arrays, where the array size depends on the field's cardinality. High-cardinality fields can consume significant heap memory, increasing the risk of out-of-memory errors. +{: .warning} -This is an expert-level setting. Ordinals use byte arrays, where the size of the array will be as large as the cardinality value. For high-cardinality fields, this can lead to significant heap memory usage and risk of out-of-memory errors. {: .warning} +### Example + +The following request runs a cardinality aggregation using ordinals: ```json GET opensearch_dashboards_sample_data_ecommerce/_search @@ -86,4 +93,5 @@ GET opensearch_dashboards_sample_data_ecommerce/_search } } } -``` +``` +{% include copy-curl.html %} \ No newline at end of file From 81cb3679f4452a74c9609df965e27bce9baa480d Mon Sep 17 00:00:00 2001 From: Asim M Date: Tue, 25 Feb 2025 11:44:56 -0800 Subject: [PATCH 4/4] Update _aggregations/metric/cardinality.md Co-authored-by: Nathan Bower Signed-off-by: Asim M --- _aggregations/metric/cardinality.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_aggregations/metric/cardinality.md b/_aggregations/metric/cardinality.md index 53cea6b5bee..3b0892c8661 100644 --- a/_aggregations/metric/cardinality.md +++ b/_aggregations/metric/cardinality.md @@ -68,7 +68,7 @@ You can control how an aggregation runs using the `execution_hint` setting. This - `direct` – Uses field values directly. - `ordinals` – Uses ordinals of the field. -If you don’t specify `execution_hint`, OpenSearch automatically chooses the best option for the field. +If you don't specify `execution_hint`, OpenSearch automatically chooses the best option for the field. Setting `ordinals` on a non-ordinal field has no effect. Similarly, `direct` has no effect on ordinal fields. {: .note}