Skip to content

Commit

Permalink
Docs: Improve aggregation handling section (closes #1219)
Browse files Browse the repository at this point in the history
  • Loading branch information
@gmarz
gmarz committed Jan 27, 2015
1 parent c7c89a6 commit 1d9ec08
Show file tree
Hide file tree
Showing 2 changed files with 55 additions and 40 deletions.
45 changes: 25 additions & 20 deletions docs/build/nest/aggregations/handling.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,8 @@
<script src="/scripts/html5shiv.js"></script><link rel="stylesheet" type="text/css" href="/styles/normalize.css"/><link rel="stylesheet" type="text/css" href="/styles/layout.css"/><link rel="stylesheet" type="text/css" href="/styles/pygments.css"/><link rel="stylesheet" type="text/css" href="/styles/pygments.css"/><link rel="stylesheet" type="text/css" href="//netdna.bootstrapcdn.com/font-awesome/4.0.3/css/font-awesome.css"/><link href="//fonts.googleapis.com/css?family=Ubuntu+Mono|Open+Sans" rel="stylesheet" type="text/css"/><link href="/prettify/prettify.css" type="text/css" rel="stylesheet"/><link href="/prettify/sunburst.css" type="text/css" rel="stylesheet"/><script src="//code.jquery.com/jquery.min.js" type="text/javascript"></script><script type="text/javascript" src="/prettify/prettify.js"></script><script type="text/javascript" src="/prettify/fix_code_tags.js"></script></head><body><div class="wrapper"><header class="header"><div class="actions"><iframe src="//ghbtns.com/github-btn.html?user=elasticsearch&amp;repo=elasticsearch-net&amp;type=fork&amp;count=true" allowtransparency="true" frameborder="0" scrolling="0" width="95" height="20"></iframe><iframe src="//ghbtns.com/github-btn.html?user=elasticsearch&amp;repo=elasticsearch-net&amp;type=watch&amp;count=true" allowtransparency="true" frameborder="0" scrolling="0" width="110" height="20"></iframe></div><img src="/images/nest-nuget-icon.png" width="48" height="48"/><h1 class="nest">NEST</h1><p>Documentation</p></header><div class="divide"></div><div class="middle"><div class="container"><main class="content"><h1 id="aggregations">Aggregations</h1>
<p>For a good overview of what aggregations are, refer the <a href="http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/search-aggregations.html">original Elasticsearch docs</a> on the subject.</p>
<h2 id="specifying-aggregations-during-search">Specifying Aggregations during Search</h2>
<p>Adding aggregations to a search request is as simple as</p>
<p>Adding aggregations to a search request is as simple as:</p>
<h4 id="fluent-syntax">Fluent Syntax</h4>
<pre><code>var result = client.Search&lt;ElasticsearchProject&gt;(s =&gt; s
.Aggregations(a =&gt; a
.Terms(&quot;my_agg&quot;, st =&gt; st
Expand All @@ -12,7 +13,7 @@ <h2 id="specifying-aggregations-during-search">Specifying Aggregations during Se
)
)
);
</code></pre><p>The above can also be accomplished using the object initializer syntax (OIS)...</p>
</code></pre><h4 id="object-initializer-syntax">Object Initializer Syntax</h4>
<pre><code>var searchRequest = new SearchRequest
{
Aggregations = new Dictionary&lt;string, IAggregationContainer&gt;
Expand All @@ -34,24 +35,25 @@ <h2 id="specifying-aggregations-during-search">Specifying Aggregations during Se
</code></pre><h3 id="getting-to-your-aggregation">Getting to your aggregation</h3>
<p>The result of the aggregations are accessed from the <code>Aggs</code> property of the response using the key that was specified on the request, <code>my_agg</code>, in the above examples:</p>
<pre><code>var myAgg = result.Aggs.Terms(&quot;my_agg&quot;);
</code></pre><p>Notice we executed a <a href="/nest/aggregations/terms.html">terms aggregation</a>, and on the response we had to retrieve our results from the <code>Terms</code> property of <code>Aggs</code>. All aggregations work like this in NEST. If <code>my_agg</code> was a <a href="/nest/aggregations/percentiles.html">percentiles aggregation</a> instead, we would have to extract the results from <code>Aggs.Percentiles</code></p>
</code></pre><p>Notice we executed a <a href="/nest/aggregations/terms.html">terms aggregation</a>, and on the response we had to retrieve our results from the <code>Terms</code> property of <code>Aggs</code>. All aggregations work like this in NEST.</p>
<p>If <code>my_agg</code> was a <a href="/nest/aggregations/percentiles.html">percentiles aggregation</a> instead, we would have to extract the results from <code>Aggs.Percentiles</code></p>
<pre><code>var myAgg = results.Aggs.Percentiles(&quot;my_agg&quot;);
</code></pre><p>Or if it were a <a href="/nest/aggregations/geohash-grid.html">geohash grid aggregation</a> we would retrieve it from <code>Aggs.GeoHash</code></p>
<pre><code>var myAgg = results.Aggs.GeoHash(&quot;my_agg&quot;)
</code></pre><p>etc...</p>
<p>Since aggregation response structures all fall into similar groups, each aggregation response in NEST is typed to a specific implementation of <code>IAggregationMetric</code>. This can be a <code>ValueMetric</code>, <code>SingleBucket</code>, <code>Bucket</code>, <code>BucketWithDocCount</code>, and the list goes on. The <code>Aggs</code> helper property of the response will automatically convert to the response from ES to the correct CLR type.</p>
<h2 id="sub-aggregations">Sub-aggregations</h2>
<p>NEST of course also supports sub-aggregations...</p>
<p>NEST of course also supports sub-aggregations.</p>
<p>In the following example we are executing a <a href="http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/search-aggregations-bucket-terms-aggregation.html">terms aggregation</a>, <code>names</code>, as a top-level aggregation, and then within it a <a href="http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/search-aggregations-metrics-max-aggregation.html">max aggregation</a>, <code>max_age</code>, as a sub-aggregation. This will produce a bucket per unique value of the <code>Name</code> field, and within each bucket find the max <code>Age</code> value for that particular name.</p>
<h4 id="fluent-syntax">Fluent Syntax</h4>
<pre><code>var result = client.Search&lt;ElasticsearchProject&gt;(s =&gt; s
<pre><code>var result = client.Search&lt;Person&gt;(s =&gt; s
.Aggregations(a =&gt; a
.Terms(&quot;my_agg&quot;, st =&gt; st
.Field(o =&gt; o.Content)
.Terms(&quot;names&quot;, st =&gt; st
.Field(o =&gt; o.Name)
.Size(10)
.ExecutionHint(TermsAggregationExecutionHint.Ordinals)
.Aggregations(aa =&gt; aa
.Max(&quot;my_sub_agg&quot;, m =&gt; m
.Field(o =&gt; o.LongValue)
.Max(&quot;max_age&quot;, m =&gt; m
.Field(o =&gt; o.Age)
)
)
)
Expand All @@ -62,21 +64,20 @@ <h4 id="fluent-syntax">Fluent Syntax</h4>
{
Aggregations = new Dictionary&lt;string, IAggregationContainer&gt;
{
{ &quot;my_agg&quot;, new AggregationContainer
{ &quot;names&quot;, new AggregationContainer
{
Terms = new TermsAggregator
{
Field = &quot;content&quot;,
Size = 10,
ExecutionHint = TermsAggregationExecutionHint.Ordinals
Field = &quot;name&quot;,
Size = 10
},
Aggregations = new Dictionary&lt;string, IAggregationContainer&gt;
{
{ &quot;my_sub_agg&quot;, new AggregationContainer
{ &quot;max_age&quot;, new AggregationContainer
{
Max = new MaxAggregator
{
Field = &quot;longValue&quot;
Field = &quot;age&quot;
}
}
}
Expand All @@ -87,8 +88,12 @@ <h4 id="fluent-syntax">Fluent Syntax</h4>
};

var result = client.Search&lt;ElasticsearchProject&gt;(searchRequest);
</code></pre><p>Accessing the top level aggregation and sub-aggregation is pretty straight-forward...</p>
<pre><code>var myAgg = result.Aggs.Terms(&quot;my_agg&quot;);
var mySubAgg = myAgg.Aggs.Max(&quot;my_sub_agg&quot;);
</code></pre><p>That&#39;s how NEST handles aggregations in a nutshell. Refer to the specific section on each aggregation type for more details.</p>
</code></pre><p>To access the <code>max_age</code> sub-aggregation, we first extract the top-level terms aggregation, <code>names</code>, from the response:</p>
<pre><code>var names = result.Aggs.Terms(&quot;names&quot;);
</code></pre><p>We can then iterate over each <code>name</code> bucket and extract our <code>max_age</code> result:</p>
<pre><code>foreach(var name in names.Items)
{
var maxAge = name.Aggs.Max(&quot;max_age&quot;);
}
</code></pre><p>That&#39;s aggregations in a nutshell. Refer to the specific section on each aggregation type for more details.</p>
</main></div><aside class="left-sidebar"><aside id="menu"><ul><li><h4><a href="/">Home</a><a href="/contributing.html">Contributing</a><a href="/building.html">Building</a><a href="/breaking-changes.html">1.0 Breaking Changes</a><a href="https://github.com/elasticsearch/elasticsearch-net/releases">Release Notes</a></h4></li></ul><ul id="elasticsearch-net"><h4 class="title">Elasticsearch.Net</h4><ul><li><a href="/elasticsearch-net/quick-start.html">Quick Start</a></li><li><a href="/elasticsearch-net/connecting.html">Connecting</a></li><li><a href="/elasticsearch-net/security.html">Security</a></li><li><a href="/elasticsearch-net/cluster-failover.html">Cluster failover</a></li><li><a href="/elasticsearch-net/building-requests.html">Building requests</a></li><li><a href="/elasticsearch-net/handling-responses.html">Handling responses</a></li><li><a href="/elasticsearch-net/errors.html">Errors</a></li></ul></ul><ul id="nest"><h4 class="title">NEST</h4><ul><li><a href="/nest/quick-start.html">Quick Start</a></li><li><a href="/nest/connecting.html">Connecting</a></li><li><a href="/nest/index-type-inference.html">Type/Index Inference</a></li><li><a href="/nest/handling-responses.html">Handling responses</a></li><li><a href="/nest/writing-queries.html">Writing queries</a></li><li><a href="/nest/tips-tricks.html">Tips & Tricks</a></li></ul><li><h4><a href="/nest/core/"><i class="fa fa-chevron-right"></i>Core</a></h4></li><li><h4><a href="/nest/indices/aliases.html"><i class="fa fa-chevron-right"></i>Indices</a></h4></li><li><h4><a href="/nest/cluster/health.html"><i class="fa fa-chevron-right"></i>Cluster</a></h4></li><li><h4><a href="/nest/search/basics.html"><i class="fa fa-chevron-right"></i>Search</a></h4></li><h4><a href="/nest/aggregations/handling.html"><i class="fa fa-chevron-down"></i>Aggregations</a></h4><ul><li class="sub"><a href="/nest/aggregations/avg.html">Avg</a></li><li class="sub"><a href="/nest/aggregations/cardinality.html">Cardinality</a></li><li class="sub"><a href="/nest/aggregations/date-histogram.html">Date Histogram</a></li><li class="sub"><a href="/nest/aggregations/date-range.html">Date Range</a></li><li class="sub"><a href="/nest/aggregations/extended-stats.html">Extended Stats</a></li><li class="sub"><a href="/nest/aggregations/filter.html">Filter</a></li><li class="sub"><a href="/nest/aggregations/geo-bounds.html">Geo Bounds</a></li><li class="sub"><a href="/nest/aggregations/geo-distance.html">Geo Distance</a></li><li class="sub"><a href="/nest/aggregations/geohash-grid.html">Geohash Grid</a></li><li class="sub"><a href="/nest/aggregations/global.html">Global</a></li><li class="sub"><a href="/nest/aggregations/histogram.html">Histogram</a></li><li class="sub"><a href="/nest/aggregations/ipv4.html">IPv4 Range</a></li><li class="sub"><a href="/nest/aggregations/max.html">Max</a></li><li class="sub"><a href="/nest/aggregations/min.html">Min</a></li><li class="sub"><a href="/nest/aggregations/missing.html">Missing</a></li><li class="sub"><a href="/nest/aggregations/percentiles.html">Percentiles</a></li><li class="sub"><a href="/nest/aggregations/percentile-ranks.html">Percentiles Ranks</a></li><li class="sub"><a href="/nest/aggregations/range.html">Range</a></li><li class="sub"><a href="/nest/aggregations/nested.html">Nested</a></li><li class="sub"><a href="/nest/aggregations/reverse-nested.html">Reverse Nested</a></li><li class="sub"><a href="/nest/aggregations/significant-terms.html">Significant Terms</a></li><li class="sub"><a href="/nest/aggregations/stats.html">Stats</a></li><li class="sub"><a href="/nest/aggregations/sum.html">Sum</a></li><li class="sub"><a href="/nest/aggregations/terms.html">Terms</a></li><li class="sub"><a href="/nest/aggregations/top-hits.html">Top Hits</a></li><li class="sub"><a href="/nest/aggregations/value-count.html">Value Count</a></li></ul><li><h4><a href="/nest/facets/handling.html" class="selected"><i class="fa fa-chevron-right"></i>Facets</a></h4></li></ul></aside></aside></div><footer class="footer"></footer></div></body></html>
50 changes: 30 additions & 20 deletions docs/contents/nest/aggregations/handling.markdown
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,9 @@ For a good overview of what aggregations are, refer the [original Elasticsearch

## Specifying Aggregations during Search

Adding aggregations to a search request is as simple as
Adding aggregations to a search request is as simple as:

#### Fluent Syntax

var result = client.Search<ElasticsearchProject>(s => s
.Aggregations(a => a
Expand All @@ -23,7 +25,7 @@ Adding aggregations to a search request is as simple as
)
);

The above can also be accomplished using the object initializer syntax (OIS)...
#### Object Initializer Syntax

var searchRequest = new SearchRequest
{
Expand All @@ -50,7 +52,9 @@ The result of the aggregations are accessed from the `Aggs` property of the resp

var myAgg = result.Aggs.Terms("my_agg");

Notice we executed a [terms aggregation](/nest/aggregations/terms.html), and on the response we had to retrieve our results from the `Terms` property of `Aggs`. All aggregations work like this in NEST. If `my_agg` was a [percentiles aggregation](/nest/aggregations/percentiles.html) instead, we would have to extract the results from `Aggs.Percentiles`
Notice we executed a [terms aggregation](/nest/aggregations/terms.html), and on the response we had to retrieve our results from the `Terms` property of `Aggs`. All aggregations work like this in NEST.

If `my_agg` was a [percentiles aggregation](/nest/aggregations/percentiles.html) instead, we would have to extract the results from `Aggs.Percentiles`

var myAgg = results.Aggs.Percentiles("my_agg");

Expand All @@ -64,19 +68,20 @@ Since aggregation response structures all fall into similar groups, each aggrega

## Sub-aggregations

NEST of course also supports sub-aggregations...
NEST of course also supports sub-aggregations.

In the following example we are executing a [terms aggregation](http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/search-aggregations-bucket-terms-aggregation.html), `names`, as a top-level aggregation, and then within it a [max aggregation](http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/search-aggregations-metrics-max-aggregation.html), `max_age`, as a sub-aggregation. This will produce a bucket per unique value of the `Name` field, and within each bucket find the max `Age` value for that particular name.

#### Fluent Syntax

var result = client.Search<ElasticsearchProject>(s => s
var result = client.Search<Person>(s => s
.Aggregations(a => a
.Terms("my_agg", st => st
.Field(o => o.Content)
.Terms("names", st => st
.Field(o => o.Name)
.Size(10)
.ExecutionHint(TermsAggregationExecutionHint.Ordinals)
.Aggregations(aa => aa
.Max("my_sub_agg", m => m
.Field(o => o.LongValue)
.Max("max_age", m => m
.Field(o => o.Age)
)
)
)
Expand All @@ -89,21 +94,20 @@ NEST of course also supports sub-aggregations...
{
Aggregations = new Dictionary<string, IAggregationContainer>
{
{ "my_agg", new AggregationContainer
{ "names", new AggregationContainer
{
Terms = new TermsAggregator
{
Field = "content",
Size = 10,
ExecutionHint = TermsAggregationExecutionHint.Ordinals
Field = "name",
Size = 10
},
Aggregations = new Dictionary<string, IAggregationContainer>
{
{ "my_sub_agg", new AggregationContainer
{ "max_age", new AggregationContainer
{
Max = new MaxAggregator
{
Field = "longValue"
Field = "age"
}
}
}
Expand All @@ -115,9 +119,15 @@ NEST of course also supports sub-aggregations...

var result = client.Search<ElasticsearchProject>(searchRequest);

Accessing the top level aggregation and sub-aggregation is pretty straight-forward...
To access the `max_age` sub-aggregation, we first extract the top-level terms aggregation, `names`, from the response:

var myAgg = result.Aggs.Terms("my_agg");
var mySubAgg = myAgg.Aggs.Max("my_sub_agg");
var names = result.Aggs.Terms("names");

We can then iterate over each `name` bucket and extract our `max_age` result:

foreach(var name in names.Items)
{
var maxAge = name.Aggs.Max("max_age");
}

That's how NEST handles aggregations in a nutshell. Refer to the specific section on each aggregation type for more details.
That's aggregations in a nutshell. Refer to the specific section on each aggregation type for more details.

0 comments on commit 1d9ec08

Please sign in to comment.