Skip to main content

Aggregations

Aggregations provide analytics capabilities, allowing you to group and compute metrics on your data.

Metric Aggregations​

Calculate numerical metrics from document field values. These single-value aggregations compute statistics like averages, sums, counts, and other mathematical operations.

Basic Metric Aggregations​

Request:

{
  "aggs": {
    "avg_response_time": {
      "avg": {"field": "response_time"}
    },
    "max_cpu_usage": {
      "max": {"field": "cpu_usage"}
    },
    "unique_users": {
      "cardinality": {"field": "user_id"}
    }
  },
  "size": 0
}

Response:

{
  "took": 12,
  "hits": {
    "total": {"value": 10000}
  },
  "aggregations": {
    "avg_response_time": {
      "value": 245.7
    },
    "max_cpu_usage": {
      "value": 89.5
    },
    "unique_users": {
      "value": 1523
    }
  }
}

Stats Aggregation​

Returns a comprehensive set of statistics (count, min, max, avg, sum) for a numeric field in a single aggregation, saving multiple requests.

{
  "aggs": {
    "response_time_stats": {
      "stats": {"field": "response_time"}
    }
  }
}

Returns: count, min, max, avg, sum

Extended Stats Aggregation​

Provides advanced statistical measures including variance, standard deviation, and sum of squares, in addition to basic statistics.

{
  "aggs": {
    "detailed_stats": {
      "extended_stats": {"field": "response_time"}
    }
  }
}

Percentiles Aggregation​

Calculates percentile values for a numeric field, showing distribution characteristics. Useful for SLA monitoring and performance analysis.

{
  "aggs": {
    "response_time_percentiles": {
      "percentiles": {
        "field": "response_time",
        "percents": [50, 95, 99]
      }
    }
  }
}

Top Hits Aggregation​

Returns sample documents from each bucket, typically the highest-scoring or most recent documents. Useful for retrieving representative examples from grouped data.

{
  "aggs": {
    "sample_documents": {
      "top_hits": {
        "size": 3,
        "_source": ["message", "@timestamp"]
      }
    }
  }
}

Bucket Aggregations​

Group documents into buckets based on field values, ranges, or other criteria.

Terms Aggregation​

Creates buckets for each unique term in a field, showing document counts for each value. Essential for building facets, top-N analyses, and categorical breakdowns.

Request:

{
  "aggs": {
    "status_codes": {
      "terms": {
        "field": "status_code",
        "size": 5
      }
    }
  },
  "size": 0
}

Response:

{
  "aggregations": {
    "status_codes": {
      "buckets": [
        {
          "key": 200,
          "doc_count": 8542
        },
        {
          "key": 404,
          "doc_count": 1123
        },
        {
          "key": 500,
          "doc_count": 234
        },
        {
          "key": 403,
          "doc_count": 89
        },
        {
          "key": 302,
          "doc_count": 67
        }
      ]
    }
  }
}

Advanced terms aggregation:

{
  "aggs": {
    "top_errors": {
      "terms": {
        "field": "error_type",
        "size": 5,
        "min_doc_count": 1,
        "order": {"_count": "desc"}
      }
    }
  }
}

Date Histogram Aggregation​

Creates time-based buckets for documents based on date/time fields. Perfect for time series analysis, trend visualization, and monitoring dashboards.

{
  "aggs": {
    "requests_over_time": {
      "date_histogram": {
        "field": "@timestamp",
        "calendar_interval": "1h",
        "min_doc_count": 0
      }
    }
  }
}

Fixed interval example:

{
  "aggs": {
    "metrics_per_minute": {
      "date_histogram": {
        "field": "@timestamp",
        "fixed_interval": "60s",
        "time_zone": "America/New_York"
      }
    }
  }
}

Range Aggregation​

Group documents by numeric or date ranges:

{
  "aggs": {
    "response_time_ranges": {
      "range": {
        "field": "response_time",
        "ranges": [
          {"to": 100},
          {"from": 100, "to": 500},
          {"from": 500}
        ]
      }
    }
  }
}

Filters Aggregation​

Group documents using multiple filter criteria:

{
  "aggs": {
    "log_levels": {
      "filters": {
        "filters": {
          "errors": {"term": {"level": "error"}},
          "warnings": {"term": {"level": "warning"}},
          "info": {"term": {"level": "info"}}
        }
      }
    }
  }
}

Multi-Terms Aggregation​

Group by multiple fields:

{
  "aggs": {
    "status_and_method": {
      "multi_terms": {
        "terms": [
          {"field": "status_code"},
          {"field": "http_method"}
        ]
      }
    }
  }
}

Composite Aggregation​

Paginate through all possible combinations of terms:

{
  "aggs": {
    "composite_agg": {
      "composite": {
        "sources": [
          {"status": {"terms": {"field": "status_code"}}},
          {"method": {"terms": {"field": "http_method"}}}
        ],
        "size": 100
      }
    }
  }
}

Nested Aggregations​

Combine bucket and metric aggregations:

{
  "aggs": {
    "status_codes": {
      "terms": {"field": "status_code"},
      "aggs": {
        "avg_response_time": {
          "avg": {"field": "response_time"}
        },
        "unique_users": {
          "cardinality": {"field": "user_id"}
        }
      }
    }
  }
}

Performance Tips​

  1. Limit aggregation cardinality to avoid memory issues
  2. Use composite aggregations for large cardinality groupings
  3. Pre-filter with range queries before expensive operations