Elasticsearch Range Aggregation - Syntax, Example, and Tips

The Range Aggregation in Elasticsearch is a multi-bucket aggregation that groups documents into buckets based on specified ranges of values. It allows you to define custom ranges and see how many documents fall into each range.

Syntax

{
  "range": {
    "field": "field_name",
    "ranges": [
      {
        "to": 50
      },
      {
        "from": 50,
        "to": 100
      },
      {
        "from": 100
      }
    ]
  }
}

For more details, refer to the official Elasticsearch documentation.

Example Usage

GET /sales/_search
{
  "aggs": {
    "price_ranges": {
      "range": {
        "field": "price",
        "ranges": [
          { "to": 50 },
          { "from": 50, "to": 100 },
          { "from": 100 }
        ]
      }
    }
  }
}

This example groups sales documents into three buckets based on price ranges: less than 50, between 50 and 100, and 100 or more.

Common Issues

1. Missing field values: Documents without the specified field are not included in the results.
2. Incorrect field type: Ensure the field is of a numeric type for range aggregations.
3. Overlapping ranges: Be cautious with range definitions to avoid unintended overlaps.

Best Practices

1. Use meaningful range boundaries that align with your data analysis needs.
2. Consider using keyed response format for easier result parsing.
3. Combine with other aggregations for more complex analysis.
4. Use script parameter for custom range calculations when needed.

Frequently Asked Questions

Q: Can I use Range Aggregation on date fields?
A: Yes, Range Aggregation works with date fields. You can specify date ranges using date math expressions or milliseconds since the epoch.

Q: How does Range Aggregation handle documents with missing values?
A: By default, documents with missing values are not included in any bucket. You can use the missing parameter to assign these documents to a specific bucket.

Q: Can I customize the bucket keys in the response?
A: Yes, you can use the keyed parameter and provide custom key names for each range to make the response more readable and easier to work with.

Q: Is it possible to use Range Aggregation with nested fields?
A: Yes, you can use Range Aggregation with nested fields by wrapping it in a nested aggregation.

Q: How does Range Aggregation perform on large datasets?
A: Range Aggregation is generally efficient, but performance can be impacted by the number of documents and the complexity of ranges. Consider using filters or other optimizations for very large datasets.