1 files changed, 51 insertions, 0 deletions
diff --git a/docs/reference/aggregations/metrics/valuecount-aggregation.asciidoc b/docs/reference/aggregations/metrics/valuecount-aggregation.asciidoc
new file mode 100644
index 0000000000..ed5e23ee33
--- /dev/null
+++ b/docs/reference/aggregations/metrics/valuecount-aggregation.asciidoc
@@ -0,0 +1,51 @@
+[[search-aggregations-metrics-valuecount-aggregation]]
+=== Value Count Aggregation
+
+A `single-value` metrics aggregation that counts the number of values that are extracted from the aggregated documents.
+These values can be extracted either from specific fields in the documents, or be generated by a provided script. Typically,
+this aggregator will be used in conjunction with other single-value aggregations. For example, when computing the `avg`
+one might be interested in the number of values the average is computed over.
+
+[source,js]
+--------------------------------------------------
+{
+    "aggs" : {
+        "grades_count" : { "value_count" : { "field" : "grade" } }
+    }
+}
+--------------------------------------------------
+
+Response:
+
+[source,js]
+--------------------------------------------------
+{
+    ...
+
+    "aggregations": {
+        "grades_count": {
+            "value": 10
+        }
+    }
+}
+--------------------------------------------------
+
+The name of the aggregation (`grades_count` above) also serves as the key by which the aggregation result can be
+retrieved from the returned response.
+
+==== Script
+
+Counting the values generated by a script:
+
+[source,js]
+--------------------------------------------------
+{
+    ...,
+
+    "aggs" : {
+        "grades_count" : { "value_count" : { "script" : "doc['grade'].value" } }
+    }
+}
+--------------------------------------------------
+
+TIP: The `script` parameter expects an inline script. Use `script_id` for indexed scripts and `script_file` for scripts in the `config/scripts/` directory.