New

The executive guide to generative AI

Read more
About usPartnersSupport|Login
A newer version is available. For the latest information, see the current release documentation.
« Significant Text Aggregation Usage Variable Width Histogram Usage »
Elastic Docs ›Elasticsearch .NET Clients [7.17] ›Aggregations ›Bucket Aggregations

Terms Aggregation Usage

edit

Terms Aggregation Usage

edit

A 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

edit
a => 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

edit
new 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

edit
response.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

edit

Using terms aggregation with filtering to include values using a regular expression pattern

Fluent DSL example

edit
a => 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

edit
new 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

edit
response.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

edit

Using terms aggregation with filtering to include only specific values

Fluent DSL example

edit
a => 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

edit
new 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

edit
response.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

edit

A 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

edit
a => a
.Terms("commits", st => st
    .Field(p => p.NumberOfCommits)
    .Include(0, 10)
    .Size(5)
)

Object Initializer syntax example

edit
new 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

edit
response.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

edit

A terms aggregation on a numeric field

Fluent DSL example

edit
a => a
.Terms("commits", st => st
    .Field(p => p.NumberOfCommits)
    .Missing(-1)
    .ShowTermDocCountError()
)

Object Initializer syntax example

edit
new 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

edit
response.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

edit

A terms aggregation returns buckets that can contain more aggregations

Fluent DSL example

edit
a => 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

edit
new 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

edit
response.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

edit

Starting 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

edit
f => base.Fluent(f.TypedKeys())

Object Initializer syntax example

edit
var r = base.Initializer;
r.TypedKeys = true;
return r;
« Significant Text Aggregation Usage Variable Width Histogram Usage »