[[search-aggregations-bucket-filters-aggregation]]
=== Filters aggregation
++++
<titleabbrev>Filters</titleabbrev>
++++

A multi-bucket aggregation where each bucket contains the documents
that match a <<query-dsl,query>>.

Example:

[source,console]
--------------------------------------------------
PUT /logs/_bulk?refresh
{ "index" : { "_id" : 1 } }
{ "body" : "warning: page could not be rendered" }
{ "index" : { "_id" : 2 } }
{ "body" : "authentication error" }
{ "index" : { "_id" : 3 } }
{ "body" : "warning: connection timed out" }

GET logs/_search
{
  "size": 0,
  "aggs" : {
    "messages" : {
      "filters" : {
        "filters" : {
          "errors" :   { "match" : { "body" : "error"   }},
          "warnings" : { "match" : { "body" : "warning" }}
        }
      }
    }
  }
}
--------------------------------------------------

In the above example, we analyze log messages. The aggregation will build two
collection (buckets) of log messages - one for all those containing an error,
and another for all those containing a warning.

Response:

[source,console-result]
--------------------------------------------------
{
  "took": 9,
  "timed_out": false,
  "_shards": ...,
  "hits": ...,
  "aggregations": {
    "messages": {
      "buckets": {
        "errors": {
          "doc_count": 1
        },
        "warnings": {
          "doc_count": 2
        }
      }
    }
  }
}
--------------------------------------------------
// TESTRESPONSE[s/"took": 9/"took": $body.took/]
// TESTRESPONSE[s/"_shards": \.\.\./"_shards": $body._shards/]
// TESTRESPONSE[s/"hits": \.\.\./"hits": $body.hits/]

==== Anonymous filters

The filters field can also be provided as an array of filters, as in the
following request:

[source,console]
--------------------------------------------------
GET logs/_search
{
  "size": 0,
  "aggs" : {
    "messages" : {
      "filters" : {
        "filters" : [
          { "match" : { "body" : "error"   }},
          { "match" : { "body" : "warning" }}
        ]
      }
    }
  }
}
--------------------------------------------------
// TEST[continued]

The filtered buckets are returned in the same order as provided in the
request. The response for this example would be:

[source,console-result]
--------------------------------------------------
{
  "took": 4,
  "timed_out": false,
  "_shards": ...,
  "hits": ...,
  "aggregations": {
    "messages": {
      "buckets": [
        {
          "doc_count": 1
        },
        {
          "doc_count": 2
        }
      ]
    }
  }
}
--------------------------------------------------
// TESTRESPONSE[s/"took": 4/"took": $body.took/]
// TESTRESPONSE[s/"_shards": \.\.\./"_shards": $body._shards/]
// TESTRESPONSE[s/"hits": \.\.\./"hits": $body.hits/]

[[other-bucket]]
==== `Other` Bucket

The `other_bucket` parameter can be set to add a bucket to the response which will contain all documents that do 
not match any of the given filters. The value of this parameter can be as follows:

`false`::         Does not compute the `other` bucket
`true`::          Returns the `other` bucket either in a bucket (named `_other_` by default) if named filters are being used, 
                  or as the last bucket if anonymous filters are being used

The `other_bucket_key` parameter can be used to set the key for the `other` bucket to a value other than the default `_other_`. Setting 
this parameter will implicitly set the `other_bucket` parameter to `true`.

The following snippet shows a response where the `other` bucket is requested to be named `other_messages`.

[source,console]
--------------------------------------------------
PUT logs/_doc/4?refresh
{
  "body": "info: user Bob logged out"
}

GET logs/_search
{
  "size": 0,
  "aggs" : {
    "messages" : {
      "filters" : {
        "other_bucket_key": "other_messages",
        "filters" : {
          "errors" :   { "match" : { "body" : "error"   }},
          "warnings" : { "match" : { "body" : "warning" }}
        }
      }
    }
  }
}
--------------------------------------------------
// TEST[continued]

The response would be something like the following:

[source,console-result]
--------------------------------------------------
{
  "took": 3,
  "timed_out": false,
  "_shards": ...,
  "hits": ...,
  "aggregations": {
    "messages": {
      "buckets": {
        "errors": {
          "doc_count": 1
        },
        "warnings": {
          "doc_count": 2
        },
        "other_messages": {
          "doc_count": 1
        }
      }
    }
  }
}
--------------------------------------------------
// TESTRESPONSE[s/"took": 3/"took": $body.took/]
// TESTRESPONSE[s/"_shards": \.\.\./"_shards": $body._shards/]
// TESTRESPONSE[s/"hits": \.\.\./"hits": $body.hits/]
