From 542fe02e1f0d72d7238d8b02680099de0d24f4f2 Mon Sep 17 00:00:00 2001
From: Wylie Conlon <william.conlon@elastic.co>
Date: Thu, 10 Jun 2021 13:42:55 -0400
Subject: [PATCH] Update aggregation reference docs for 7.13 (#101913)

* Update aggregation reference docs for 7.13

* Add more reference about filtered metrics
---
 .../dashboard/aggregation-reference.asciidoc   | 18 ++++++++++++------
 docs/user/dashboard/lens.asciidoc              | 14 ++++++++++++--
 2 files changed, 24 insertions(+), 8 deletions(-)

diff --git a/docs/user/dashboard/aggregation-reference.asciidoc b/docs/user/dashboard/aggregation-reference.asciidoc
index 7d5547fe3c3c5..39e596df4af34 100644
--- a/docs/user/dashboard/aggregation-reference.asciidoc
+++ b/docs/user/dashboard/aggregation-reference.asciidoc
@@ -188,6 +188,12 @@ For information about {es} metrics aggregations, refer to {ref}/search-aggregati
 
 | Type | Agg-based | Markdown | Lens | TSVB
 
+| Metrics with filters
+|
+^| X
+|
+|
+
 | Average
 ^| X
 ^| X
@@ -221,7 +227,7 @@ For information about {es} metrics aggregations, refer to {ref}/search-aggregati
 | Percentiles
 ^| X
 ^| X
-| 
+^| X
 ^| X
 
 | Percentiles Rank
@@ -230,10 +236,10 @@ For information about {es} metrics aggregations, refer to {ref}/search-aggregati
 | 
 ^| X
 
-| Top hit 
+| Top hit (Last value)
+^| X
 ^| X
 ^| X
-| 
 ^| X
 
 | Value count 
@@ -266,7 +272,7 @@ For information about {es} pipeline aggregations, refer to {ref}/search-aggregat
 | Derivative  
 ^| X
 ^| X
-| 
+^| X
 ^| X
 
 | Max bucket   
@@ -290,13 +296,13 @@ For information about {es} pipeline aggregations, refer to {ref}/search-aggregat
 | Moving average  
 ^| X
 ^| X
-| 
+^| X
 ^| X
 
 | Cumulative sum 
 ^| X
 ^| X
-| 
+^| X
 ^| X
 
 | Bucket script 
diff --git a/docs/user/dashboard/lens.asciidoc b/docs/user/dashboard/lens.asciidoc
index 3b3a7a9ee527d..9f17a380bc209 100644
--- a/docs/user/dashboard/lens.asciidoc
+++ b/docs/user/dashboard/lens.asciidoc
@@ -147,14 +147,24 @@ For the answers to common *Lens* questions, review the following.
 
 [float]
 [[kql-]]
-===== When should I use the Filter function instead of KQL filters?
+===== When should I use the top filter bar, filters function, or "Filter by"?
 
-The easiest way to apply KQL filters is to use <<semi-structured-search>>, but you can also use the *Filters* function in the following scenarios:
+Using the top <<semi-structured-search>> bar is best when you want to focus on a known set of
+data for all the visualization results. These top level filters are combined with other filters
+using AND logic.
+
+Use the *Filters* function in the following scenarios:
 
 * When you want to apply more than one KQL filter to the visualization.
 
 * When you want to apply the KQL filter to a single layer, which allows you to visualize filtered and unfiltered data.
 
+Use the *Filter by* advanced option in the following scenarios:
+
+* When you want to assign a custom color to each filter in a bar, line or area chart.
+
+* When you want to build a complex table, such as showing both failure rate and overall.
+
 [float]
 [[when-should-i-normalize-the-data-by-unit-or-use-a-custom-interval]]
 ===== When should I normalize the data by unit or use a custom interval?