From 1d9ec08f8e38e5379eea83b6c2a6fb5df23c73b2 Mon Sep 17 00:00:00 2001 From: gmarz Date: Tue, 27 Jan 2015 13:39:53 -0500 Subject: [PATCH] Docs: Improve aggregation handling section (closes #1219) --- docs/build/nest/aggregations/handling.html | 45 +++++++++-------- .../nest/aggregations/handling.markdown | 50 +++++++++++-------- 2 files changed, 55 insertions(+), 40 deletions(-) diff --git a/docs/build/nest/aggregations/handling.html b/docs/build/nest/aggregations/handling.html index 2cb14a3e2d0..750f698a1be 100644 --- a/docs/build/nest/aggregations/handling.html +++ b/docs/build/nest/aggregations/handling.html @@ -2,7 +2,8 @@

NEST

Documentation

Aggregations

For a good overview of what aggregations are, refer the original Elasticsearch docs on the subject.

-

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
             .Terms("my_agg", st => st
@@ -12,7 +13,7 @@

The above can also be accomplished using the object initializer syntax (OIS)...

+

Object Initializer Syntax

var searchRequest = new SearchRequest
 {
     Aggregations = new Dictionary<string, IAggregationContainer>
@@ -34,24 +35,25 @@

Getting to your aggregation

The result of the aggregations are accessed from the Aggs property of the response using the key that was specified on the request, my_agg, in the above examples:

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

Notice we executed a terms aggregation, 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 instead, we would have to extract the results from Aggs.Percentiles

+

Notice we executed a terms aggregation, 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 instead, we would have to extract the results from Aggs.Percentiles

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

Or if it were a geohash grid aggregation we would retrieve it from Aggs.GeoHash

var myAgg = results.Aggs.GeoHash("my_agg")

etc...

Since aggregation response structures all fall into similar groups, each aggregation response in NEST is typed to a specific implementation of IAggregationMetric. This can be a ValueMetric, SingleBucket, Bucket, BucketWithDocCount, and the list goes on. The Aggs helper property of the response will automatically convert to the response from ES to the correct CLR type.

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, names, as a top-level aggregation, and then within it a max aggregation, 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)
                 )
             )
         )
@@ -62,21 +64,20 @@ 
Fluent Syntax

 {
     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"
                                     }
                                 }
                             }
@@ -87,8 +88,12 @@ 
Fluent Syntax

 };
 
 var result = client.Search<ElasticsearchProject>(searchRequest);
-
Accessing the top level aggregation and sub-aggregation is pretty straight-forward...

-
var myAgg = result.Aggs.Terms("my_agg");
-var mySubAgg = myAgg.Aggs.Max("my_sub_agg");
-
That's how NEST handles aggregations in a nutshell.  Refer to the specific section on each aggregation type for more details.

+

To access the max_age sub-aggregation, we first extract the top-level terms aggregation, names, from the response:

+
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 aggregations in a nutshell. Refer to the specific section on each aggregation type for more details.

\ No newline at end of file diff --git a/docs/contents/nest/aggregations/handling.markdown b/docs/contents/nest/aggregations/handling.markdown index c9c8fd7de96..8a07888eabb 100644 --- a/docs/contents/nest/aggregations/handling.markdown +++ b/docs/contents/nest/aggregations/handling.markdown @@ -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(s => s .Aggregations(a => a @@ -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 { @@ -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"); @@ -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(s => s + var result = client.Search(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) ) ) ) @@ -89,21 +94,20 @@ NEST of course also supports sub-aggregations... { Aggregations = new Dictionary { - { "my_agg", new AggregationContainer + { "names", new AggregationContainer { Terms = new TermsAggregator { - Field = "content", - Size = 10, - ExecutionHint = TermsAggregationExecutionHint.Ordinals + Field = "name", + Size = 10 }, Aggregations = new Dictionary { - { "my_sub_agg", new AggregationContainer + { "max_age", new AggregationContainer { Max = new MaxAggregator { - Field = "longValue" + Field = "age" } } } @@ -115,9 +119,15 @@ NEST of course also supports sub-aggregations... var result = client.Search(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. \ No newline at end of file