New

The executive guide to generative AI

Read more
About usPartnersSupport|Login

WARNING: Version 5.x has passed its EOL date.

This documentation is no longer being maintained and may be removed. If you are running this version, we strongly advise you to upgrade. For the latest information, see the current release documentation.

« Filter Aggregation Usage Geo Distance Aggregation Usage »
Elastic Docs ›Elasticsearch.Net and NEST: the .NET clients [5.x] ›Aggregations ›Bucket Aggregations

Filters Aggregation Usage

edit

Filters Aggregation Usage

edit

Defines a multi bucket aggregations where each bucket is associated with a filter. Each bucket will collect all documents that match its associated filter. For documents that do not match any filter, these will be collected in the other bucket.

Be sure to read the Elasticsearch documentation Filters Aggregation

Named filters

edit

Fluent DSL example

edit
s => s
.Aggregations(aggs => aggs
    .Filters("projects_by_state", agg => agg
        .OtherBucket()
        .OtherBucketKey("other_states_of_being")
        .NamedFilters(filters => filters
            .Filter("belly_up", f => f.Term(p => p.State, StateOfBeing.BellyUp))
            .Filter("stable", f => f.Term(p => p.State, StateOfBeing.Stable))
            .Filter("very_active", f => f.Term(p => p.State, StateOfBeing.VeryActive))
        )
        .Aggregations(childAggs => childAggs
            .Terms("project_tags", avg => avg.Field(p => p.CuratedTags.First().Name.Suffix("keyword")))
        )
    )
)

Object Initializer syntax example

edit
new SearchRequest<Project>
{
    Aggregations = new FiltersAggregation("projects_by_state")
    {
        OtherBucket = true,
        OtherBucketKey = "other_states_of_being",
        Filters = new NamedFiltersContainer
        {
            { "belly_up", Query<Project>.Term(p => p.State, StateOfBeing.BellyUp) },
            { "stable", Query<Project>.Term(p => p.State, StateOfBeing.Stable) },
            { "very_active", Query<Project>.Term(p => p.State, StateOfBeing.VeryActive) }
        },
        Aggregations =
            new TermsAggregation("project_tags") { Field = Field<Project>(p => p.CuratedTags.First().Name.Suffix("keyword")) }
    }
}

Example json output.

{
  "aggs": {
    "projects_by_state": {
      "filters": {
        "other_bucket": true,
        "other_bucket_key": "other_states_of_being",
        "filters": {
          "belly_up": {
            "term": {
              "state": {
                "value": "BellyUp"
              }
            }
          },
          "stable": {
            "term": {
              "state": {
                "value": "Stable"
              }
            }
          },
          "very_active": {
            "term": {
              "state": {
                "value": "VeryActive"
              }
            }
          }
        }
      },
      "aggs": {
        "project_tags": {
          "terms": {
            "field": "curatedTags.name.keyword"
          }
        }
      }
    }
  }
}

Handling Responses

edit

Using the .Agg aggregation helper we can fetch our aggregation results easily in the correct type. Be sure to read more about .Aggs vs .Aggregations

response.ShouldBeValid();

var filterAgg = response.Aggs.Filters("projects_by_state");
filterAgg.Should().NotBeNull();

var namedResult = filterAgg.NamedBucket("belly_up");
namedResult.Should().NotBeNull();
namedResult.DocCount.Should().BeGreaterThan(0);

namedResult = filterAgg.NamedBucket("stable");
namedResult.Should().NotBeNull();
namedResult.DocCount.Should().BeGreaterThan(0);

namedResult = filterAgg.NamedBucket("very_active");
namedResult.Should().NotBeNull();
namedResult.DocCount.Should().BeGreaterThan(0);

namedResult = filterAgg.NamedBucket("other_states_of_being");
namedResult.Should().NotBeNull();
namedResult.DocCount.Should().Be(0);

Anonymous filters

edit

Fluent DSL example

edit
s => s
.Aggregations(aggs => aggs
    .Filters("projects_by_state", agg => agg
        .OtherBucket()
        .AnonymousFilters(
            f => f.Term(p => p.State, StateOfBeing.BellyUp),
            f => f.Term(p => p.State, StateOfBeing.Stable),
            f => f.Term(p => p.State, StateOfBeing.VeryActive)
        )
        .Aggregations(childAggs => childAggs
            .Terms("project_tags", avg => avg.Field(p => p.CuratedTags.First().Name.Suffix("keyword")))
        )
    )
)

Object Initializer syntax example

edit
new SearchRequest<Project>
{
    Aggregations = new FiltersAggregation("projects_by_state")
    {
        OtherBucket = true,
        Filters = new List<QueryContainer>
        {
            Query<Project>.Term(p => p.State, StateOfBeing.BellyUp),
            Query<Project>.Term(p => p.State, StateOfBeing.Stable),
            Query<Project>.Term(p => p.State, StateOfBeing.VeryActive)
        },
        Aggregations =
            new TermsAggregation("project_tags") { Field = Field<Project>(p => p.CuratedTags.First().Name.Suffix("keyword")) }
    }
}

Example json output.

{
  "aggs": {
    "projects_by_state": {
      "filters": {
        "other_bucket": true,
        "filters": [
          {
            "term": {
              "state": {
                "value": "BellyUp"
              }
            }
          },
          {
            "term": {
              "state": {
                "value": "Stable"
              }
            }
          },
          {
            "term": {
              "state": {
                "value": "VeryActive"
              }
            }
          }
        ]
      },
      "aggs": {
        "project_tags": {
          "terms": {
            "field": "curatedTags.name.keyword"
          }
        }
      }
    }
  }
}

Handling Responses

edit

Using the .Agg aggregation helper we can fetch our aggregation results easily in the correct type. Be sure to read more about .Aggs vs .Aggregations

response.ShouldBeValid();

var filterAgg = response.Aggs.Filters("projects_by_state");
filterAgg.Should().NotBeNull();
var results = filterAgg.AnonymousBuckets();
results.Count.Should().Be(4);

foreach (var singleBucket in results.Take(3)) singleBucket.DocCount.Should().BeGreaterThan(0);

results.Last().DocCount.Should().Be(0);

The last bucket is the other bucket

Empty Filters

edit

Fluent DSL example

edit
s => s
.Aggregations(aggs => aggs
    .Filters("empty_filters", agg => agg
        .AnonymousFilters()
    )
)

Object Initializer syntax example

edit
new SearchRequest<Project>
{
    Aggregations = new FiltersAggregation("empty_filters")
    {
        Filters = new List<QueryContainer>()
    }
}

Example json output.

{
  "aggs": {
    "empty_filters": {
      "filters": {
        "filters": []
      }
    }
  }
}

Handling Responses

edit
response.ShouldBeValid();
response.Aggs.Filters("empty_filters").Buckets.Should().BeEmpty();

Conditionless Filters

edit

Fluent DSL example

edit
s => s
.Aggregations(aggs => aggs
    .Filters("conditionless_filters", agg => agg
        .AnonymousFilters(
            q => new QueryContainer()
        )
    )
)

Object Initializer syntax example

edit
new SearchRequest<Project>
{
    Aggregations = new FiltersAggregation("conditionless_filters")
    {
        Filters = new List<QueryContainer>
        {
            new QueryContainer()
        }
    }
}

Example json output.

{
  "aggs": {
    "conditionless_filters": {
      "filters": {
        "filters": []
      }
    }
  }
}

Handling Responses

edit
response.ShouldBeValid();
response.Aggs.Filters("conditionless_filters").Buckets.Should().BeEmpty();
« Filter Aggregation Usage Geo Distance Aggregation Usage »