| <!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><meta name="generator" content="rustdoc"><meta name="description" content="Aggregations"><meta name="keywords" content="rust, rustlang, rust-lang, aggregation"><title>tantivy::aggregation - Rust</title><link rel="preload" as="font" type="font/woff2" crossorigin href="../../SourceSerif4-Regular.ttf.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../../FiraSans-Regular.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../../FiraSans-Medium.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../../SourceCodePro-Regular.ttf.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../../SourceSerif4-Bold.ttf.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../../SourceCodePro-Semibold.ttf.woff2"><link rel="stylesheet" href="../../normalize.css"><link rel="stylesheet" href="../../rustdoc.css" id="mainThemeStyle"><link rel="stylesheet" href="../../ayu.css" disabled><link rel="stylesheet" href="../../dark.css" disabled><link rel="stylesheet" href="../../light.css" id="themeStyle"><script id="default-settings" ></script><script src="../../storage.js"></script><script defer src="../../main.js"></script><noscript><link rel="stylesheet" href="../../noscript.css"></noscript><link rel="alternate icon" type="image/png" href="../../favicon-16x16.png"><link rel="alternate icon" type="image/png" href="../../favicon-32x32.png"><link rel="icon" type="image/svg+xml" href="../../favicon.svg"></head><body class="rustdoc mod"><!--[if lte IE 11]><div class="warning">This old browser is unsupported and will most likely display funky things.</div><![endif]--><nav class="mobile-topbar"><button class="sidebar-menu-toggle">☰</button><a class="sidebar-logo" href="../../tantivy/index.html"><div class="logo-container"><img src="http://fulmicoton.com/tantivy-logo/tantivy-logo.png" alt="logo"></div></a><h2></h2></nav><nav class="sidebar"><a class="sidebar-logo" href="../../tantivy/index.html"><div class="logo-container"> |
| <img src="http://fulmicoton.com/tantivy-logo/tantivy-logo.png" alt="logo"></div></a><h2 class="location"><a href="#">Module aggregation</a></h2><div class="sidebar-elems"><section><ul class="block"><li><a href="#modules">Modules</a></li><li><a href="#structs">Structs</a></li><li><a href="#enums">Enums</a></li><li><a href="#constants">Constants</a></li><li><a href="#types">Type Definitions</a></li></ul></section></div></nav><main><div class="width-limiter"><nav class="sub"><form class="search-form"><div class="search-container"><span></span><input class="search-input" name="search" autocomplete="off" spellcheck="false" placeholder="Click or press ‘S’ to search, ‘?’ for more options…" type="search"><div id="help-button" title="help" tabindex="-1"><a href="../../help.html">?</a></div><div id="settings-menu" tabindex="-1"><a href="../../settings.html" title="settings"><img width="22" height="22" alt="Change settings" src="../../wheel.svg"></a></div></div></form></nav><section id="main-content" class="content"><div class="main-heading"><h1 class="fqn">Module <a href="../index.html">tantivy</a>::<wbr><a class="mod" href="#">aggregation</a><button id="copy-path" onclick="copy_path(this)" title="Copy item path to clipboard"><img src="../../clipboard.svg" width="19" height="18" alt="Copy item path"></button></h1><span class="out-of-band"><a class="srclink" href="../../src/tantivy/aggregation/mod.rs.html#1-1617">source</a> · <a id="toggle-all-docs" href="javascript:void(0)" title="collapse all docs">[<span class="inner">−</span>]</a></span></div><details class="rustdoc-toggle top-doc" open><summary class="hideme"><span>Expand description</span></summary><div class="docblock"><h2 id="aggregations"><a href="#aggregations">Aggregations</a></h2> |
| <p>An aggregation summarizes your data as statistics on buckets or metrics.</p> |
| <p>Aggregations can provide answer to questions like:</p> |
| <ul> |
| <li>What is the average price of all sold articles?</li> |
| <li>How many errors with status code 500 do we have per day?</li> |
| <li>What is the average listing price of cars grouped by color?</li> |
| </ul> |
| <p>There are two categories: <a href="metric/index.html">Metrics</a> and <a href="bucket/index.html">Buckets</a>.</p> |
| <h3 id="prerequisite"><a href="#prerequisite">Prerequisite</a></h3> |
| <p>Currently aggregations work only on <a href="../fastfield/index.html">fast fields</a>. Single value fast fields |
| of type <code>u64</code>, <code>f64</code>, <code>i64</code>, <code>date</code> and fast fields on text fields.</p> |
| <h3 id="usage"><a href="#usage">Usage</a></h3> |
| <p>To use aggregations, build an aggregation request by constructing |
| <a href="agg_req/type.Aggregations.html"><code>Aggregations</code></a>. |
| Create an <a href="struct.AggregationCollector.html" title="AggregationCollector"><code>AggregationCollector</code></a> from this request. <code>AggregationCollector</code> implements the |
| <a href="../collector/trait.Collector.html"><code>Collector</code></a> trait and can be passed as collector into |
| <a href="../struct.Searcher.html#method.search"><code>Searcher::search()</code></a>.</p> |
| <h3 id="json-format"><a href="#json-format">JSON Format</a></h3> |
| <p>Aggregations request and result structures de/serialize into elasticsearch compatible JSON.</p> |
| <div class="example-wrap"><pre class="language-verbatim"><code>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)?;</code></pre></div><h3 id="supported-aggregations"><a href="#supported-aggregations">Supported Aggregations</a></h3> |
| <ul> |
| <li><a href="bucket/index.html">Bucket</a> |
| <ul> |
| <li><a href="bucket/struct.HistogramAggregation.html">Histogram</a></li> |
| <li><a href="agg_req/struct.RangeAggregation.html">Range</a></li> |
| <li><a href="bucket/struct.TermsAggregation.html">Terms</a></li> |
| </ul> |
| </li> |
| <li><a href="metric/index.html">Metric</a> |
| <ul> |
| <li><a href="metric/struct.AverageAggregation.html">Average</a></li> |
| <li><a href="metric/struct.StatsAggregation.html">Stats</a></li> |
| </ul> |
| </li> |
| </ul> |
| <h2 id="example"><a href="#example">Example</a></h2> |
| <p>Compute the average metric, by building <a href="agg_req/type.Aggregations.html" title="agg_req::Aggregations"><code>agg_req::Aggregations</code></a>, which is built from an |
| <code>(String, agg_req::Aggregation)</code> iterator.</p> |
| |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>tantivy::aggregation::agg_req::{Aggregations, Aggregation, MetricAggregation}; |
| <span class="kw">use </span>tantivy::aggregation::AggregationCollector; |
| <span class="kw">use </span>tantivy::aggregation::metric::AverageAggregation; |
| <span class="kw">use </span>tantivy::query::AllQuery; |
| <span class="kw">use </span>tantivy::aggregation::agg_result::AggregationResults; |
| <span class="kw">use </span>tantivy::IndexReader; |
| <span class="kw">use </span>tantivy::schema::Schema; |
| |
| <span class="kw">fn </span>aggregate_on_index(reader: <span class="kw-2">&</span>IndexReader, schema: Schema) { |
| <span class="kw">let </span>agg_req: Aggregations = <span class="macro">vec!</span>[ |
| ( |
| <span class="string">"average"</span>.to_string(), |
| Aggregation::Metric(MetricAggregation::Average( |
| AverageAggregation::from_field_name(<span class="string">"score"</span>.to_string()), |
| )), |
| ), |
| ] |
| .into_iter() |
| .collect(); |
| |
| <span class="kw">let </span>collector = AggregationCollector::from_aggs(agg_req, <span class="prelude-val">None</span>, schema); |
| |
| <span class="kw">let </span>searcher = reader.searcher(); |
| <span class="kw">let </span>agg_res: AggregationResults = searcher.search(<span class="kw-2">&</span>AllQuery, <span class="kw-2">&</span>collector).unwrap(); |
| }</code></pre></div> |
| <h2 id="example-json"><a href="#example-json">Example JSON</a></h2> |
| <p>Requests are compatible with the elasticsearch json request format.</p> |
| |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>tantivy::aggregation::agg_req::Aggregations; |
| |
| <span class="kw">let </span>elasticsearch_compatible_json_req = <span class="string">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" } } |
| } |
| } |
| } |
| "#</span>; |
| <span class="kw">let </span>agg_req: Aggregations = |
| serde_json::from_str(elasticsearch_compatible_json_req).unwrap();</code></pre></div> |
| <h2 id="code-organization"><a href="#code-organization">Code Organization</a></h2> |
| <p>Check the <a href="https://github.com/quickwit-oss/tantivy/tree/main/src/aggregation#readme">README</a> on github to see how the code is organized.</p> |
| <h2 id="nested-aggregation"><a href="#nested-aggregation">Nested Aggregation</a></h2> |
| <p>Buckets can contain sub-aggregations. In this example we create buckets with the range |
| aggregation and then calculate the average on each bucket.</p> |
| |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>tantivy::aggregation::agg_req::<span class="kw-2">*</span>; |
| <span class="kw">use </span>tantivy::aggregation::metric::AverageAggregation; |
| <span class="kw">use </span>tantivy::aggregation::bucket::RangeAggregation; |
| <span class="kw">let </span>sub_agg_req_1: Aggregations = <span class="macro">vec!</span>[( |
| <span class="string">"average_in_range"</span>.to_string(), |
| Aggregation::Metric(MetricAggregation::Average( |
| AverageAggregation::from_field_name(<span class="string">"score"</span>.to_string()), |
| )), |
| )] |
| .into_iter() |
| .collect(); |
| |
| <span class="kw">let </span>agg_req_1: Aggregations = <span class="macro">vec!</span>[ |
| ( |
| <span class="string">"range"</span>.to_string(), |
| Aggregation::Bucket(BucketAggregation { |
| bucket_agg: BucketAggregationType::Range(RangeAggregation{ |
| field: <span class="string">"score"</span>.to_string(), |
| ranges: <span class="macro">vec!</span>[(<span class="number">3f64</span>..<span class="number">7f64</span>).into(), (<span class="number">7f64</span>..<span class="number">20f64</span>).into()], |
| keyed: <span class="bool-val">false</span>, |
| }), |
| sub_aggregation: sub_agg_req_1.clone(), |
| }), |
| ), |
| ] |
| .into_iter() |
| .collect();</code></pre></div> |
| <h2 id="distributed-aggregation"><a href="#distributed-aggregation">Distributed Aggregation</a></h2> |
| <p>When the data is distributed on different <a href="../struct.Index.html"><code>Index</code></a> instances, the |
| <a href="struct.DistributedAggregationCollector.html" title="DistributedAggregationCollector"><code>DistributedAggregationCollector</code></a> provides functionality to merge data between independent |
| search calls by returning |
| <a href="intermediate_agg_result/struct.IntermediateAggregationResults.html"><code>IntermediateAggregationResults</code></a>. |
| <code>IntermediateAggregationResults</code> provides the |
| <a href="intermediate_agg_result/struct.IntermediateAggregationResults.html#method.merge_fruits"><code>merge_fruits</code></a> method |
| to merge multiple results. The merged result can then be converted into |
| <a href="agg_result/struct.AggregationResults.html"><code>AggregationResults</code></a> via the |
| <a href="intermediate_agg_result/struct.IntermediateAggregationResults.html#method.into_final_bucket_result"><code>into_final_bucket_result</code></a> method.</p> |
| </div></details><h2 id="modules" class="small-section-header"><a href="#modules">Modules</a></h2><div class="item-table"><div class="item-row"><div class="item-left module-item"><a class="mod" href="agg_req/index.html" title="tantivy::aggregation::agg_req mod">agg_req</a></div><div class="item-right docblock-short">Contains the aggregation request tree. Used to build an |
| <a href="struct.AggregationCollector.html"><code>AggregationCollector</code></a>.</div></div><div class="item-row"><div class="item-left module-item"><a class="mod" href="agg_result/index.html" title="tantivy::aggregation::agg_result mod">agg_result</a></div><div class="item-right docblock-short">Contains the final aggregation tree. |
| This tree can be converted via the <code>into()</code> method from <code>IntermediateAggregationResults</code>. |
| 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.</div></div><div class="item-row"><div class="item-left module-item"><a class="mod" href="bucket/index.html" title="tantivy::aggregation::bucket mod">bucket</a></div><div class="item-right docblock-short">Module for all bucket aggregations.</div></div><div class="item-row"><div class="item-left module-item"><a class="mod" href="intermediate_agg_result/index.html" title="tantivy::aggregation::intermediate_agg_result mod">intermediate_agg_result</a></div><div class="item-right docblock-short">Contains the intermediate aggregation tree, that can be merged. |
| Intermediate aggregation results can be used to merge results between segments or between |
| indices.</div></div><div class="item-row"><div class="item-left module-item"><a class="mod" href="metric/index.html" title="tantivy::aggregation::metric mod">metric</a></div><div class="item-right docblock-short">Module for all metric aggregations.</div></div></div><h2 id="structs" class="small-section-header"><a href="#structs">Structs</a></h2><div class="item-table"><div class="item-row"><div class="item-left module-item"><a class="struct" href="struct.AggregationCollector.html" title="tantivy::aggregation::AggregationCollector struct">AggregationCollector</a></div><div class="item-right docblock-short">Collector for aggregations.</div></div><div class="item-row"><div class="item-left module-item"><a class="struct" href="struct.AggregationSegmentCollector.html" title="tantivy::aggregation::AggregationSegmentCollector struct">AggregationSegmentCollector</a></div><div class="item-right docblock-short"><code>AggregationSegmentCollector</code> does the aggregation collection on a segment.</div></div><div class="item-row"><div class="item-left module-item"><a class="struct" href="struct.DistributedAggregationCollector.html" title="tantivy::aggregation::DistributedAggregationCollector struct">DistributedAggregationCollector</a></div><div class="item-right docblock-short">Collector for distributed aggregations.</div></div></div><h2 id="enums" class="small-section-header"><a href="#enums">Enums</a></h2><div class="item-table"><div class="item-row"><div class="item-left module-item"><a class="enum" href="enum.Key.html" title="tantivy::aggregation::Key enum">Key</a></div><div class="item-right docblock-short">The key to identify a bucket.</div></div></div><h2 id="constants" class="small-section-header"><a href="#constants">Constants</a></h2><div class="item-table"><div class="item-row"><div class="item-left module-item"><a class="constant" href="constant.MAX_BUCKET_COUNT.html" title="tantivy::aggregation::MAX_BUCKET_COUNT constant">MAX_BUCKET_COUNT</a></div><div class="item-right docblock-short">The default max bucket count, before the aggregation fails.</div></div></div><h2 id="types" class="small-section-header"><a href="#types">Type Definitions</a></h2><div class="item-table"><div class="item-row"><div class="item-left module-item"><a class="type" href="type.SerializedKey.html" title="tantivy::aggregation::SerializedKey type">SerializedKey</a></div><div class="item-right docblock-short">The serialized key is used in a <code>HashMap</code>.</div></div></div></section></div></main><div id="rustdoc-vars" data-root-path="../../" data-current-crate="tantivy" data-themes="ayu,dark,light" data-resource-suffix="" data-rustdoc-version="1.66.0-nightly (5c8bff74b 2022-10-21)" ></div></body></html> |
