1 files changed, 128 insertions, 0 deletions
diff --git a/docs/reference/aggregations/bucket/filters-aggregation.asciidoc b/docs/reference/aggregations/bucket/filters-aggregation.asciidoc
new file mode 100644
index 0000000000..2553758d77
--- /dev/null
+++ b/docs/reference/aggregations/bucket/filters-aggregation.asciidoc
@@ -0,0 +1,128 @@
+[[search-aggregations-bucket-filters-aggregation]]
+=== Filters Aggregation
+
+Defines a multi bucket aggregations where each bucket is associated with a
+filter. Each bucket will collect all documents that match its associated
+filter.
+
+Example:
+
+[source,js]
+--------------------------------------------------
+{
+  "aggs" : {
+    "messages" : {
+      "filters" : {
+        "filters" : {
+          "errors" :   { "term" : { "body" : "error"   }},
+          "warnings" : { "term" : { "body" : "warning" }}
+        }
+      },
+      "aggs" : {
+        "monthly" : {
+          "histogram" : {
+            "field" : "timestamp",
+            "interval" : "1M"
+          }
+        }
+      }
+    }
+  }
+}
+--------------------------------------------------
+
+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. And for each of these buckets
+it will break them down by month.
+
+Response:
+
+[source,js]
+--------------------------------------------------
+...
+  "aggs" : {
+    "messages" : {
+      "buckets" : {
+        "errors" : {
+          "doc_count" : 34,
+            "monthly" : {
+              "buckets : [
+                ... // the histogram monthly breakdown
+              ]
+            }
+          },
+          "warnings" : {
+            "doc_count" : 439,
+            "monthly" : {
+              "buckets : [
+                 ... // the histogram monthly breakdown
+              ]
+            }
+          }
+        }
+      }
+    }
+  }
+...
+--------------------------------------------------
+
+==== Anonymous filters
+
+The filters field can also be provided as an array of filters, as in the
+following request:
+
+[source,js]
+--------------------------------------------------
+{
+  "aggs" : {
+    "messages" : {
+      "filters" : {
+        "filters" : [
+          { "term" : { "body" : "error"   }},
+          { "term" : { "body" : "warning" }}
+        ]
+      },
+      "aggs" : {
+        "monthly" : {
+          "histogram" : {
+            "field" : "timestamp",
+            "interval" : "1M"
+          }
+        }
+      }
+    }
+  }
+}
+--------------------------------------------------
+
+The filtered buckets are returned in the same order as provided in the
+request.  The response for this example would be:
+
+[source,js]
+--------------------------------------------------
+...
+  "aggs" : {
+    "messages" : {
+      "buckets" : [
+        {
+          "doc_count" : 34,
+          "monthly" : {
+            "buckets : [
+              ... // the histogram monthly breakdown
+            ]
+          }
+        },
+        {
+          "doc_count" : 439,
+          "monthly" : {
+            "buckets : [
+              ... // the histogram monthly breakdown
+            ]
+          }
+        }
+      ]
+    }
+  }
+...
+--------------------------------------------------
+\ No newline at end of file