[Star-tree] Support for nested aggs & Removing experimental flag.

_search-plugins/star-tree-index.md

@@ -7,7 +7,7 @@
 
 # Star-tree index
 
 A _star-tree index_ is a specialized index structure designed to improve aggregation performance by precomputing and storing aggregated values at different levels of granularity. This indexing technique enables faster aggregation execution, especially for multi-field aggregations.
 
 Once you enable star-tree indexes, OpenSearch automatically builds and uses star-tree indexes to optimize supported aggregations if the filter fields match the defined dimensions and the aggregation fields match the defined metrics in the star-tree mapping configuration. No changes to your query syntax or request parameters are required.
 
@@ -95,7 +95,7 @@
 
 ## Limitations
 
 Note the following limiations of star-tree indexes:
 
 - Star-tree indexes do not support updates or deletions. To use a star-tree index, data should be append-only. See [Enabling a star-tree index](#enabling-a-star-tree-index).
 - A star-tree index only works for aggregation queries that filter on dimension fields and aggregate metric fields defined in the index's star-tree configuration.
@@ -106,18 +106,20 @@
 
 ## Enabling a star-tree index
 
-A star-tree index is controlled by cluster-level and index-level settings.
+Star-tree indexing behavior is controlled by the following cluster-level and index-level settings. Index-level settings take precedence over cluster settings.
 
-### Cluster-level setting
-
-The cluster-level `indices.composite_index.star_tree.enabled` setting is enabled by default. To disable star-tree indexes, set it to `false`. For more information, see [Dynamic settings]({{site.url}}{{site.baseurl}}/install-and-configure/configuring-opensearch/index/#dynamic-settings).
+| Setting                                     | Scope   | Default | Purpose                                                                                                                              |
+| ------------------------------------------- | ------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `indices.composite_index.star_tree.enabled` | Cluster | `true`  | Enables or disables star-tree search optimization across the cluster.  |
+| `index.composite_index`                     | Index   | None       | Enables star-tree indexing for a specific index. Must be set when creating the index.                                                |
+| `index.append_only.enabled`                 | Index   | None      | Required for star-tree indexes. Prevents updates and deletions. Must be `true`.                                                      |
+| `index.search.star_tree_index.enabled`      | Index   | `true`  | Enables or disables use of the star-tree index for search queries on this index.                                                 |
 
 Setting `indices.composite_index.star_tree.enabled` to `false` prevents OpenSearch from using star-tree optimization during searches, but the star-tree index structures are still created. To completely remove star-tree structures, you must reindex your data without the star-tree mapping.
 {: .note}
 
-### Index-level settings
 
-Configure the following settings when creating your index. Star-tree indexes do not support updates or deletions. To enforce this policy, set `index.append_only.enabled` to `true`:
+To create an index that uses a star-tree index, send the following request:
 
 ```json
 PUT /logs
@@ -132,6 +134,10 @@
 
 Ensure that the `doc_values` parameter is enabled for the dimension and metric fields used in your star-tree mapping. This is enabled by default for most field types. For more information, see [Doc values]({{site.url}}{{site.baseurl}}/field-types/mapping-parameters/doc-values/).
 
+### Disabling star-tree usage
+
+By default, both the `indices.composite_index.star_tree.enabled` cluster setting and the `index.search.star_tree_index.enabled` index setting are set to `true`. To disable search using star-tree indexes, set both of these settings to `false`. Note that index settings take precedence over cluster settings. 
+
 ## Example mapping
 
 The following example shows how to create a star-tree index that precomputes aggregations in the `logs` index. The `sum` and `average` aggregations are calculated on the `size` and `latency` fields , respectively, for all combinations of values in the dimension fields. The dimensions are ordered by `status`, then `port`, and finally `method`, which determines how the data is organized in the tree structure:
@@ -490,10 +496,6 @@
 
 You can combine multiple supported bucket aggregations (such as `terms` and `range`) in a nested structure, and the star-tree index will optimize these nested aggregations. For more information about nested aggregations, see [Nested aggregations]({{site.url}}{{site.baseurl}}/aggregations/#nested-aggregations).
 
-## Disable search using a star-tree index
-
-By default, both the cluster setting `indices.composite_index.star_tree.enabled` and index setting `index.search.star_tree_index.enabled` are set to `true`. In case a user wants to disable search using star-tree, they can set these cluster or index settings as `false`. Please note that the index settings will take a precedence over cluster settings. 
-
 ## Next steps
 
 - [Star-tree field type]({{site.url}}{{site.baseurl}}/field-types/supported-field-types/star-tree/)