The Aggregate stage computes statistical aggregations across your search results, including counts, sums, averages, min/max values, and custom metrics. This is useful for analytics, faceted search, and understanding result distributions.
Stage Category : REDUCE (Aggregates results)Transformation : N documents → aggregation results + optional documents
When to Use Use Case Description Faceted search Count documents by category Analytics Compute metrics across results Price ranges Min/max/avg calculations Distributions Understand result characteristics
When NOT to Use Scenario Recommended Alternative Grouping with full docs group_bySimple counting Use search facets Per-document stats code_executionLLM-based analysis summarize
Parameters Parameter Type Default Description aggregationsarray Required List of aggregation operations group_bystring none Field to group aggregations by include_documentsboolean falseInclude original documents in output
Aggregation Types Type Description Example countNumber of documents Total results sumSum of field values Total revenue avgAverage value Average price minMinimum value Lowest price maxMaximum value Highest price cardinalityUnique values count Unique authors percentilePercentile values P50, P95 histogramValue distribution Price buckets
Configuration Examples Basic Aggregations
Grouped Aggregations
Faceted Search
Percentile Analysis
Multi-Field Aggregations
{ "stage_type" : "reduce" , "stage_id" : "aggregate" , "parameters" : { "aggregations" : [ { "type" : "count" , "name" : "total" }, { "type" : "avg" , "field" : "metadata.price" , "name" : "avg_price" }, { "type" : "min" , "field" : "metadata.price" , "name" : "min_price" }, { "type" : "max" , "field" : "metadata.price" , "name" : "max_price" } ] } }
Output Schema Without Group By { "aggregations" : { "total" : 150 , "avg_price" : 49.99 , "min_price" : 9.99 , "max_price" : 199.99 }, "documents" : [] // if include_documents: false }
With Group By { "aggregations" : { "electronics" : { "count" : 45 , "avg_rating" : 4.2 }, "clothing" : { "count" : 62 , "avg_rating" : 4.5 }, "books" : { "count" : 43 , "avg_rating" : 4.7 } } }
Histogram Output { "aggregations" : { "price_ranges" : { "buckets" : [ { "key" : "0-50" , "count" : 45 }, { "key" : "50-100" , "count" : 62 }, { "key" : "100-150" , "count" : 28 }, { "key" : "150-200" , "count" : 15 } ] } } }
Metric Value Latency 5-50ms Memory O(groups × aggregations) Cost Free Scalability Efficient for large result sets
Common Pipeline Patterns Search with Facets [ { "stage_type" : "filter" , "stage_id" : "semantic_search" , "parameters" : { "query" : "{{INPUT.query}}" , "vector_index" : "text_extractor_v1_embedding" , "top_k" : 1000 } }, { "stage_type" : "reduce" , "stage_id" : "aggregate" , "parameters" : { "aggregations" : [ { "type" : "count" , "name" : "total" }, { "type" : "histogram" , "field" : "metadata.category" , "name" : "categories" }, { "type" : "histogram" , "field" : "metadata.price" , "interval" : 25 , "name" : "price_ranges" } ], "include_documents" : true } } ]
Analytics Pipeline [ { "stage_type" : "filter" , "stage_id" : "structured_filter" , "parameters" : { "conditions" : { "AND" : [ { "field" : "metadata.date" , "operator" : "gte" , "value" : "2024-01-01" }, { "field" : "metadata.status" , "operator" : "eq" , "value" : "published" } ] } } }, { "stage_type" : "reduce" , "stage_id" : "aggregate" , "parameters" : { "aggregations" : [ { "type" : "count" , "name" : "total_published" }, { "type" : "sum" , "field" : "metadata.views" , "name" : "total_views" }, { "type" : "avg" , "field" : "metadata.engagement" , "name" : "avg_engagement" }, { "type" : "percentile" , "field" : "metadata.views" , "percentiles" : [ 50 , 90 , 99 ], "name" : "view_distribution" } ], "group_by" : "metadata.author" } } ]
E-Commerce Product Analytics [ { "stage_type" : "filter" , "stage_id" : "hybrid_search" , "parameters" : { "query" : "{{INPUT.query}}" , "vector_index" : "product_embedding" , "top_k" : 500 } }, { "stage_type" : "filter" , "stage_id" : "structured_filter" , "parameters" : { "conditions" : { "field" : "metadata.in_stock" , "operator" : "eq" , "value" : true } } }, { "stage_type" : "reduce" , "stage_id" : "aggregate" , "parameters" : { "aggregations" : [ { "type" : "count" , "name" : "available_products" }, { "type" : "min" , "field" : "metadata.price" , "name" : "lowest_price" }, { "type" : "max" , "field" : "metadata.price" , "name" : "highest_price" }, { "type" : "avg" , "field" : "metadata.rating" , "name" : "avg_rating" }, { "type" : "cardinality" , "field" : "metadata.brand" , "name" : "brand_count" } ], "group_by" : "metadata.category" , "include_documents" : true } } ]
Aggregation Details Count { "type" : "count" , "name" : "total" }
Counts documents. No field required.
Sum / Avg / Min / Max { "type" : "avg" , "field" : "metadata.price" , "name" : "average_price" }
Requires numeric field.
Cardinality { "type" : "cardinality" , "field" : "metadata.author" , "name" : "unique_authors" }
Counts unique values (approximate for large sets).
Percentile { "type" : "percentile" , "field" : "score" , "percentiles" : [ 25 , 50 , 75 , 95 ], "name" : "score_percentiles" }
Returns specified percentile values.
Histogram { "type" : "histogram" , "field" : "metadata.price" , "interval" : 50 , "name" : "price_buckets" }
Groups values into buckets.
Error Handling Error Behavior Missing field Skip document for that aggregation Non-numeric field Error for numeric aggregations Empty results Return zero/empty aggregations Invalid type Stage fails
