New Pull Request

_aggregations/bucket/index.md

@@ -1,19 +1,6 @@
----
-layout: default
-title: Bucket aggregations
-has_children: true
-has_toc: false
-nav_order: 3
-redirect_from:
-  - /opensearch/bucket-agg/
-  - /query-dsl/aggregations/bucket-agg/
-  - /query-dsl/aggregations/bucket/
-  - /aggregations/bucket-agg/
----
-
 # Bucket aggregations
 
-Bucket aggregations categorize sets of documents as buckets. The type of bucket aggregation determines the bucket for a given document.
+Bucket aggregations categorize sets of documents into buckets. The type of bucket aggregation determines the bucket for a given document.
 
 You can use bucket aggregations to implement faceted navigation (usually placed as a sidebar on a search result landing page) to help your users filter the results.
 
@@ -22,7 +9,8 @@ You can use bucket aggregations to implement faceted navigation (usually placed
 OpenSearch supports the following bucket aggregations:
 
 - [Adjacency matrix]({{site.url}}{{site.baseurl}}/aggregations/bucket/adjacency-matrix/)
-- [Children]({{site.url}}{{site.baseurl}}/aggregations/bucket/children)
+- [Auto-interval date histogram]({{site.url}}{{site.baseurl}}/aggregations/bucket/auto-interval-date-histogram/)
+- [Children]({{site.url}}{{site.baseurl}}/aggregations/bucket/children/)
 - [Date histogram]({{site.url}}{{site.baseurl}}/aggregations/bucket/date-histogram/)
 - [Date range]({{site.url}}{{site.baseurl}}/aggregations/bucket/date-range/)
 - [Diversified sampler]({{site.url}}{{site.baseurl}}/aggregations/bucket/diversified-sampler/)
@@ -43,4 +31,68 @@ OpenSearch supports the following bucket aggregations:
 - [Sampler]({{site.url}}{{site.baseurl}}/aggregations/bucket/sampler/)
 - [Significant terms]({{site.url}}{{site.baseurl}}/aggregations/bucket/significant-terms/)
 - [Significant text]({{site.url}}{{site.baseurl}}/aggregations/bucket/significant-text/)
-- [Terms]({{site.url}}{{site.baseurl}}/aggregations/bucket/terms/)
+- [Terms]({{site.url}}{{site.baseurl}}/aggregations/bucket/terms/)
+
+## Usage
+
+To use a bucket aggregation, specify it in the `aggs` section of your search request:
+
+```json
+GET _search
+{
+  "aggs": {
+    "my_bucket_agg": {
+      "BUCKET_TYPE": {
+        ...
+      }
+    }
+  }
+}
+```
+
+Replace `BUCKET_TYPE` with the type of bucket aggregation you want to use.
+
+## Common parameters
+
+Most bucket aggregations support the following common parameters:
+
+- `field`: The field to aggregate on
+- `script`: A script to generate values to aggregate on
+- `missing`: A value to use for documents that are missing the field
+
+## Nesting aggregations
+
+You can nest bucket aggregations within other bucket aggregations to create more complex aggregations. For example:
+
+```json
+GET _search
+{
+  "aggs": {
+    "my_date_histo": {
+      "date_histogram": {
+        "field": "date",
+        "interval": "month"
+      },
+      "aggs": {
+        "my_terms": {
+          "terms": {
+            "field": "category"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+This creates date histogram buckets and then subdivides those buckets using a terms aggregation.
+
+## Performance considerations 
+
+Bucket aggregations can be computationally expensive, especially on large datasets. To improve performance:
+
+- Use filters to reduce the number of documents before aggregating
+- Set a reasonable `size` parameter to limit the number of buckets returned
+- Consider using sampling aggregations like `sampler` for approximate results on very large datasets
+
+For more details on each bucket aggregation type, refer to the individual documentation pages linked above.

_aggregations/bucket/reroute-service.md

@@ -0,0 +1,92 @@
+# RerouteService
+
+The `RerouteService` interface allows you to asynchronously perform cluster reroute operations in OpenSearch.
+
+## Overview
+
+The `RerouteService` provides methods to:
+
+- Schedule cluster reroute operations
+- Update shard states 
+- Rebalance the cluster if appropriate
+
+Reroute operations can be triggered with different priority levels to control when they are executed relative to other cluster state update tasks.
+
+## Usage
+
+To use the `RerouteService`, inject it as a dependency:
+
+```java
+public class MyClass {
+
+  private final RerouteService rerouteService;
+
+  @Inject
+  public MyClass(RerouteService rerouteService) {
+    this.rerouteService = rerouteService;
+  }
+
+  // Use rerouteService...
+}
+```
+
+## Methods
+
+### reroute
+
+```java
+void reroute(String reason, Priority priority, ActionListener<ClusterState> listener)
+```
+
+Schedules a cluster reroute operation.
+
+Parameters:
+- `reason` - A string describing the reason for the reroute
+- `priority` - The priority level for this reroute operation
+- `listener` - An `ActionListener` to be notified when the reroute completes
+
+The priority determines when this reroute will be executed relative to other cluster state update tasks. If there is already a pending reroute at a higher priority, this reroute will be batched with it. If there is a pending reroute at a lower priority, its priority will be raised to match this one.
+
+### newFunctionality
+
+```java 
+void newFunctionality()
+```
+
+This method provides new functionality added to the `RerouteService` interface. The specific behavior is not yet documented.
+
+## Priority Levels
+
+The `Priority` enum defines the available priority levels for reroute operations:
+
+- `IMMEDIATE` - Highest priority, executed as soon as possible
+- `HIGH` - High priority 
+- `NORMAL` - Normal priority
+- `LOW` - Low priority
+- `LANGUID` - Lowest priority
+
+Higher priority operations will be executed before lower priority ones.
+
+## Examples
+
+Scheduling a normal priority reroute:
+
+```java
+rerouteService.reroute("Rebalance cluster", Priority.NORMAL, new ActionListener<ClusterState>() {
+  @Override
+  public void onResponse(ClusterState clusterState) {
+    // Handle successful reroute
+  }
+
+  @Override
+  public void onFailure(Exception e) {
+    // Handle reroute failure  
+  }
+});
+```
+
+## Best Practices
+
+- Use an appropriate priority level based on the urgency of the reroute
+- Provide descriptive reason strings to aid debugging
+- Handle both success and failure cases in the listener