Module tantivy::aggregation

source ·
Expand description

§Aggregations

An aggregation summarizes your data as statistics on buckets or metrics.

Aggregations can provide answer to questions like:

  • What is the average price of all sold articles?
  • How many errors with status code 500 do we have per day?
  • What is the average listing price of cars grouped by color?

There are two categories: Metrics and Buckets.

§Prerequisite

Currently aggregations work only on fast fields. Fast fields of type u64, f64, i64, date and fast fields on text fields.

§Usage

To use aggregations, build an aggregation request by constructing Aggregations. Create an AggregationCollector from this request. AggregationCollector implements the Collector trait and can be passed as collector into Searcher::search().

§JSON Format

Aggregations request and result structures de/serialize into elasticsearch compatible JSON.

Notice: Intermediate aggregation results should not be de/serialized via JSON format. Postcard is a good choice.

let agg_req: Aggregations = serde_json::from_str(json_request_string).unwrap();
let collector = AggregationCollector::from_aggs(agg_req, None);
let searcher = reader.searcher();
let agg_res = searcher.search(&term_query, &collector).unwrap_err();
let json_response_string: String = &serde_json::to_string(&agg_res)?;

§Supported Aggregations

§Example

Compute the average metric, by building agg_req::Aggregations, which is built from an (String, agg_req::Aggregation) iterator.

Requests are compatible with the elasticsearch JSON request format.

use tantivy::aggregation::agg_req::Aggregations;

let elasticsearch_compatible_json_req = r#"
{
  "average": {
    "avg": { "field": "score" }
  },
  "range": {
    "range": {
      "field": "score",
      "ranges": [
        { "to": 3.0 },
        { "from": 3.0, "to": 7.0 },
        { "from": 7.0, "to": 20.0 },
        { "from": 20.0 }
      ]
    },
    "aggs": {
      "average_in_range": { "avg": { "field": "score" } }
    }
  }
}
"#;
let agg_req: Aggregations =
    serde_json::from_str(elasticsearch_compatible_json_req).unwrap();

§Code Organization

Check the README on github to see how the code is organized.

§Nested Aggregation

Buckets can contain sub-aggregations. In this example we create buckets with the range aggregation and then calculate the average on each bucket.

use tantivy::aggregation::agg_req::*;
use serde_json::json;

let agg_req_1: Aggregations = serde_json::from_value(json!({
    "rangef64": {
        "range": {
            "field": "score",
            "ranges": [
                { "from": 3, "to": 7000 },
                { "from": 7000, "to": 20000 },
                { "from": 50000, "to": 60000 }
            ]
        },
        "aggs": {
            "average_in_range": { "avg": { "field": "score" } }
        }
    },
}))
.unwrap();

§Distributed Aggregation

When the data is distributed on different Index instances, the DistributedAggregationCollector provides functionality to merge data between independent search calls by returning IntermediateAggregationResults. IntermediateAggregationResults provides the merge_fruits method to merge multiple results. The merged result can then be converted into AggregationResults via the into_final_result method.

Modules§

  • agg_req
    Contains the aggregation request tree. Used to build an AggregationCollector.
  • agg_result
    Contains the final aggregation tree. This tree can be converted via the into() method from IntermediateAggregationResults. This conversion computes the final result. For example: The intermediate result contains intermediate average results, which is the sum and the number of values. The actual average is calculated on the step from intermediate to final aggregation result tree.
  • bucket
    Module for all bucket aggregations.
  • intermediate_agg_result
    Contains the intermediate aggregation tree, that can be merged. Intermediate aggregation results can be used to merge results between segments or between indices.
  • metric
    Module for all metric aggregations.

Structs§

Enums§

Constants§

Type Aliases§