Execution hint documentation added to cardinality agg (#9224)

* Execution hint documentation added to cardinality agg

Signed-off-by: Siddharth Rayabharam <[email protected]>

* Add expert level warning to cardinality execution_hint paramter

Signed-off-by: Asim Mahmood <[email protected]>

* Doc review

Signed-off-by: Fanit Kolchina <[email protected]>

* Update _aggregations/metric/cardinality.md

Co-authored-by: Nathan Bower <[email protected]>
Signed-off-by: Asim M <[email protected]>

---------

Signed-off-by: Siddharth Rayabharam <[email protected]>
Signed-off-by: Asim Mahmood <[email protected]>
Signed-off-by: Fanit Kolchina <[email protected]>
Signed-off-by: Asim M <[email protected]>
Co-authored-by: Siddharth Rayabharam <[email protected]>
Co-authored-by: Fanit Kolchina <[email protected]>
Co-authored-by: kolchfa-aws <[email protected]>
Co-authored-by: Nathan Bower <[email protected]>
(cherry picked from commit 2d39e1c)
Signed-off-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

Author: 4 people

_aggregations/metric/cardinality.md

@@ -58,4 +58,40 @@ GET opensearch_dashboards_sample_data_ecommerce/_search
     }
   }
 }
-```
+```
+{% include copy-curl.html %}
+
+## Configuring aggregation execution  
+
+You can control how an aggregation runs using the `execution_hint` setting. This setting supports two options:  
+
+- `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.  
+
+Setting `ordinals` on a non-ordinal field has no effect. Similarly, `direct` has no effect on ordinal fields.  
+{: .note}
+
+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}
+
+### Example  
+
+The following request runs a cardinality aggregation using ordinals:  
+
+```json
+GET opensearch_dashboards_sample_data_ecommerce/_search
+{
+  "size": 0,
+  "aggs": {
+    "unique_products": {
+      "cardinality": {
+        "field": "products.product_id",
+        "execution_hint": "ordinals"
+      }
+    }
+  }
+}
+```  
+{% include copy-curl.html %}