Terms Aggregation Usage
editTerms Aggregation Usage
editA multi-bucket value source based aggregation where buckets are dynamically built - one per unique value.
See the Elasticsearch documentation on terms aggregation for more detail.
Fluent DSL example
edita => a .Terms("states", st => st .Field(p => p.State) .MinimumDocumentCount(2) .Size(5) .ShardSize(100) .ExecutionHint(TermsAggregationExecutionHint.Map) .Missing("n/a") .Script(ss => ss.Source("'State of Being: '+_value")) .Order(o => o .KeyAscending() .CountDescending() ) .Meta(m => m .Add("foo", "bar") ) )
Object Initializer syntax example
editnew TermsAggregation("states") { Field = Field<Project>(p => p.State), MinimumDocumentCount = 2, Size = 5, ShardSize = 100, ExecutionHint = TermsAggregationExecutionHint.Map, Missing = "n/a", Script = new InlineScript("'State of Being: '+_value"), Order = new List<TermsOrder> { TermsOrder.KeyAscending, TermsOrder.CountDescending }, Meta = new Dictionary<string, object> { { "foo", "bar" } } }
Example json output.
{ "states": { "meta": { "foo": "bar" }, "terms": { "field": "state", "min_doc_count": 2, "size": 5, "shard_size": 100, "execution_hint": "map", "missing": "n/a", "script": { "source": "'State of Being: '+_value" }, "order": [ { "_key": "asc" }, { "_count": "desc" } ] } } }
Handling Responses
editresponse.ShouldBeValid(); var states = response.Aggregations.Terms("states"); states.Should().NotBeNull(); states.DocCountErrorUpperBound.Should().HaveValue(); states.SumOtherDocCount.Should().HaveValue(); states.Buckets.Should().NotBeNull(); states.Buckets.Count.Should().BeGreaterThan(0); foreach (var item in states.Buckets) { item.Key.Should().NotBeNullOrEmpty(); item.DocCount.Should().BeGreaterOrEqualTo(1); } states.Meta.Should().NotBeNull().And.HaveCount(1); states.Meta["foo"].Should().Be("bar");
Filtering with a regular expression pattern
editUsing terms aggregation with filtering to include values using a regular expression pattern
Fluent DSL example
edita => a .Terms("states", st => st .Field(p => p.State.Suffix("keyword")) .MinimumDocumentCount(2) .Size(5) .ShardSize(100) .ExecutionHint(TermsAggregationExecutionHint.Map) .Missing("n/a") .Include("(Stable|VeryActive)") .Order(o => o .KeyAscending() .CountDescending() ) .Meta(m => m .Add("foo", "bar") ) )
Object Initializer syntax example
editnew TermsAggregation("states") { Field = Field<Project>(p => p.State.Suffix("keyword")), MinimumDocumentCount = 2, Size = 5, ShardSize = 100, ExecutionHint = TermsAggregationExecutionHint.Map, Missing = "n/a", Include = new TermsInclude("(Stable|VeryActive)"), Order = new List<TermsOrder> { TermsOrder.KeyAscending, TermsOrder.CountDescending }, Meta = new Dictionary<string, object> { { "foo", "bar" } } }
Example json output.
{ "states": { "meta": { "foo": "bar" }, "terms": { "field": "state.keyword", "min_doc_count": 2, "size": 5, "shard_size": 100, "execution_hint": "map", "missing": "n/a", "include": "(Stable|VeryActive)", "order": [ { "_key": "asc" }, { "_count": "desc" } ] } } }
Handling Responses
editresponse.ShouldBeValid(); var states = response.Aggregations.Terms<StateOfBeing>("states"); states.Should().NotBeNull(); states.DocCountErrorUpperBound.Should().HaveValue(); states.SumOtherDocCount.Should().HaveValue(); states.Buckets.Should().NotBeNull(); states.Buckets.Count.Should().BeGreaterThan(0); foreach (var item in states.Buckets) { item.Key.Should().BeOfType<StateOfBeing>(); item.DocCount.Should().BeGreaterOrEqualTo(1); } states.Meta.Should().NotBeNull().And.HaveCount(1); states.Meta["foo"].Should().Be("bar");
Filtering with exact values
editUsing terms aggregation with filtering to include only specific values
Fluent DSL example
edita => a .Terms("states", st => st .Field(p => p.State.Suffix("keyword")) .MinimumDocumentCount(2) .Size(5) .ShardSize(100) .ExecutionHint(TermsAggregationExecutionHint.Map) .Missing("n/a") .Include(new[] { StateOfBeing.Stable.ToString(), StateOfBeing.VeryActive.ToString() }) .Order(o => o .KeyAscending() .CountDescending() ) .Meta(m => m .Add("foo", "bar") ) )
Object Initializer syntax example
editnew TermsAggregation("states") { Field = Field<Project>(p => p.State.Suffix("keyword")), MinimumDocumentCount = 2, Size = 5, ShardSize = 100, ExecutionHint = TermsAggregationExecutionHint.Map, Missing = "n/a", Include = new TermsInclude(new[] { StateOfBeing.Stable.ToString(), StateOfBeing.VeryActive.ToString() }), Order = new List<TermsOrder> { TermsOrder.KeyAscending, TermsOrder.CountDescending }, Meta = new Dictionary<string, object> { { "foo", "bar" } } }
Example json output.
{ "states": { "meta": { "foo": "bar" }, "terms": { "field": "state.keyword", "min_doc_count": 2, "size": 5, "shard_size": 100, "execution_hint": "map", "missing": "n/a", "include": [ "Stable", "VeryActive" ], "order": [ { "_key": "asc" }, { "_count": "desc" } ] } } }
Handling Responses
editresponse.ShouldBeValid(); var states = response.Aggregations.Terms("states"); states.Should().NotBeNull(); states.DocCountErrorUpperBound.Should().HaveValue(); states.SumOtherDocCount.Should().HaveValue(); states.Buckets.Should().NotBeNull(); states.Buckets.Count.Should().BeGreaterThan(0); foreach (var item in states.Buckets) { item.Key.Should().NotBeNullOrEmpty(); item.DocCount.Should().BeGreaterOrEqualTo(1); } states.Meta.Should().NotBeNull().And.HaveCount(1); states.Meta["foo"].Should().Be("bar");
Filtering with partitions
editA terms aggregation that uses partitioning to filter the terms that are returned in the response. Further terms
can be returned by issuing additional requests with an incrementing partition
number.
Partitioning is available only in Elasticsearch 5.2.0+
Fluent DSL example
edita => a .Terms("commits", st => st .Field(p => p.NumberOfCommits) .Include(0, 10) .Size(5) )
Object Initializer syntax example
editnew TermsAggregation("commits") { Field = Field<Project>(p => p.NumberOfCommits), Include = new TermsInclude(0, 10), Size = 5 }
Example json output.
{ "commits": { "terms": { "field": "numberOfCommits", "size": 5, "include": { "partition": 0, "num_partitions": 10 } } } }
Handling Responses
editresponse.ShouldBeValid(); var commits = response.Aggregations.Terms<int>("commits"); commits.Should().NotBeNull(); commits.DocCountErrorUpperBound.Should().HaveValue(); commits.SumOtherDocCount.Should().HaveValue(); commits.Buckets.Should().NotBeNull(); commits.Buckets.Count.Should().BeGreaterThan(0); foreach (var item in commits.Buckets) { item.Key.Should().BeGreaterThan(0); item.DocCount.Should().BeGreaterOrEqualTo(1); }
Numeric fields
editA terms aggregation on a numeric field
Fluent DSL example
edita => a .Terms("commits", st => st .Field(p => p.NumberOfCommits) .Missing(-1) .ShowTermDocCountError() )
Object Initializer syntax example
editnew TermsAggregation("commits") { Field = Field<Project>(p => p.NumberOfCommits), ShowTermDocCountError = true, Missing = -1 }
Example json output.
{ "commits": { "terms": { "field": "numberOfCommits", "missing": -1, "show_term_doc_count_error": true } } }
Handling Responses
editresponse.ShouldBeValid(); var commits = response.Aggregations.Terms<int>("commits"); commits.Should().NotBeNull(); commits.DocCountErrorUpperBound.Should().HaveValue(); commits.SumOtherDocCount.Should().HaveValue(); commits.Buckets.Should().NotBeNull(); commits.Buckets.Count.Should().BeGreaterThan(0); foreach (var item in commits.Buckets) { item.Key.Should().BeGreaterThan(0); item.DocCount.Should().BeGreaterOrEqualTo(1); } commits.Buckets.Should().Contain(b => b.DocCountErrorUpperBound.HasValue);
Nested terms aggregations
editA terms aggregation returns buckets that can contain more aggregations
Fluent DSL example
edita => a .Terms("commits", st => st .Field(p => p.NumberOfCommits) .Aggregations(aggs => aggs .Terms("state", t => t .Meta(m => m.Add("x", "y")) .Field(p => p.State) ) ) )
Object Initializer syntax example
editnew TermsAggregation("commits") { Field = Field<Project>(p => p.NumberOfCommits), Aggregations = new TermsAggregation("state") { Meta = new Dictionary<string, object> { { "x", "y" } }, Field = Field<Project>(p => p.State), } }
Example json output.
{ "commits": { "terms": { "field": "numberOfCommits" }, "aggs": { "state": { "meta": { "x": "y" }, "terms": { "field": "state" } } } } }
Handling Responses
editresponse.ShouldBeValid(); var commits = response.Aggregations.Terms<int>("commits"); commits.Should().NotBeNull(); commits.DocCountErrorUpperBound.Should().HaveValue(); commits.SumOtherDocCount.Should().HaveValue(); commits.Buckets.Should().NotBeNull(); commits.Buckets.Count.Should().BeGreaterThan(0); foreach (var item in commits.Buckets) { item.Key.Should().BeGreaterThan(0); item.DocCount.Should().BeGreaterOrEqualTo(1); var states = item.Terms("state"); states.Should().NotBeNull(); states.Buckets.Should().NotBeEmpty(); states.Meta.Should().NotBeEmpty("meta").And.ContainKey("x"); foreach (var b in states.Buckets) { b.DocCount.Should().BeGreaterThan(0); b.Key.Should().NotBeNullOrEmpty(); } }
Typed Keys aggregations
editStarting with Elasticsearch 6.x you can provide a typed_keys
parameter which will prefix all the aggregation names
with the type of aggregation that is returned. The following modifies the previous nested terms aggregation and sends it again
but this time with the typed_keys
option set. The client should treat this in a an opaque fashion so let’s assert that it does.
Fluent DSL example
editf => base.Fluent(f.TypedKeys())
Object Initializer syntax example
editvar r = base.Initializer; r.TypedKeys = true; return r;