Terms Aggregation Usageedit

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 exampleedit

s => s
.Size(0)
.Aggregations(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.Inline("'State of Being: '+_value").Lang("groovy"))
        .Order(TermsOrder.TermAscending)
        .Order(TermsOrder.CountDescending)
        .Meta(m => m
            .Add("foo", "bar")
        )
    )
)

Object Initializer syntax exampleedit

new SearchRequest<Project>
{
    Size = 0,
    Aggregations = 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") { Lang = "groovy" },
        Order = new List<TermsOrder>
        {
            TermsOrder.TermAscending,
            TermsOrder.CountDescending
        },
        Meta = new Dictionary<string, object>
        {
            { "foo", "bar" }
        }
    }
}

Example json output. 

{
  "size": 0,
  "aggs": {
    "states": {
      "meta": {
        "foo": "bar"
      },
      "terms": {
        "field": "state",
        "min_doc_count": 2,
        "size": 5,
        "shard_size": 100,
        "execution_hint": "map",
        "missing": "n/a",
        "script": {
          "inline": "'State of Being: '+_value",
          "lang": "groovy"
        },
        "order": [
          {
            "_term": "asc"
          },
          {
            "_count": "desc"
          }
        ]
      }
    }
  }
}

Handling Responsesedit

response.IsValid.Should().BeTrue();
var states = response.Aggs.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 patternedit

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

Fluent DSL exampleedit

s => s
.Size(0)
.Aggregations(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(TermsOrder.TermAscending)
        .Order(TermsOrder.CountDescending)
        .Meta(m => m
            .Add("foo", "bar")
        )
    )
)

Object Initializer syntax exampleedit

new SearchRequest<Project>
{
    Size = 0,
    Aggregations = 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 TermsIncludeExclude { Pattern = "(Stable|VeryActive)" },
        Order = new List<TermsOrder>
        {
            TermsOrder.TermAscending,
            TermsOrder.CountDescending
        },
        Meta = new Dictionary<string, object>
        {
            { "foo", "bar" }
        }
    }
}

Example json output. 

{
  "size": 0,
  "aggs": {
    "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": [
          {
            "_term": "asc"
          },
          {
            "_count": "desc"
          }
        ]
      }
    }
  }
}

Handling Responsesedit

response.IsValid.Should().BeTrue();
var states = response.Aggs.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 exact valuesedit

Using terms aggregation with filtering to include only specific values

Fluent DSL exampleedit

s => s
.Size(0)
.Aggregations(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(TermsOrder.TermAscending)
        .Order(TermsOrder.CountDescending)
        .Meta(m => m
            .Add("foo", "bar")
        )
    )
)

Object Initializer syntax exampleedit

new SearchRequest<Project>
{
    Size = 0,
    Aggregations = 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 TermsIncludeExclude { Values = new[] { StateOfBeing.Stable.ToString(), StateOfBeing.VeryActive.ToString() } },
        Order = new List<TermsOrder>
        {
            TermsOrder.TermAscending,
            TermsOrder.CountDescending
        },
        Meta = new Dictionary<string, object>
        {
            { "foo", "bar" }
        }
    }
}

Example json output. 

{
  "size": 0,
  "aggs": {
    "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": [
          {
            "_term": "asc"
          },
          {
            "_count": "desc"
          }
        ]
      }
    }
  }
}

Handling Responsesedit

response.IsValid.Should().BeTrue();
var states = response.Aggs.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 partitionsedit

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.

Note

Partitioning is available only in Elasticsearch 5.2.0+

Fluent DSL exampleedit

s => s
.Size(0)
.Aggregations(a => a
    .Terms("commits", st => st
        .Field(p => p.NumberOfCommits)
        .Include(partition: 0, numberOfPartitions: 10)
        .Size(5)
    )
)

Object Initializer syntax exampleedit

new SearchRequest<Project>
{
    Size = 0,
    Aggregations = new TermsAggregation("commits")
    {
        Field = Infer.Field<Project>(p => p.NumberOfCommits),
        Include = new TermsIncludeExclude
        {
            Partition = 0,
            NumberOfPartitions = 10
        },
        Size = 5
    }
}

Example json output. 

{
  "size": 0,
  "aggs": {
    "commits": {
      "terms": {
        "field": "numberOfCommits",
        "size": 5,
        "include": {
          "partition": 0,
          "num_partitions": 10
        }
      }
    }
  }
}

Handling Responsesedit

response.IsValid.Should().BeTrue();
var commits = response.Aggs.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 fieldsedit

A terms aggregation on a numeric field

Fluent DSL exampleedit

s => s
.Size(0)
.Aggregations(a => a
    .Terms("commits", st => st
        .Field(p => p.NumberOfCommits)
    )
)

Object Initializer syntax exampleedit

new SearchRequest<Project>
{
    Size = 0,
    Aggregations = new TermsAggregation("commits")
    {
        Field = Infer.Field<Project>(p => p.NumberOfCommits),
    }
}

Example json output. 

{
  "size": 0,
  "aggs": {
    "commits": {
      "terms": {
        "field": "numberOfCommits"
      }
    }
  }
}

Handling Responsesedit

response.IsValid.Should().BeTrue();
var commits = response.Aggs.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);
}