docs: unify chart dimension settings into shared snippets (#4773)

explore-analyze/_snippets/lens-breakdown-advanced-settings.md

@@ -4,6 +4,6 @@ Several advanced options allow you to refine the behavior of the breakdown:
 - **Include documents without the selected field**: Off by default.
 - **Group remaining values as "Other"**: On by default.
 - **Enable accuracy mode**: This option improves results for high-cardinality data, but increases the load on the {{es}} cluster.
-- **Include values**: Values from the breakdown dimension to always show a tile for.
-- **Exclude values**: Values from the breakdown dimension to always exclude from the displayed tiles.
+- **Include values**: Values from the dimension to always include, even if they aren't among the top values. You can enter exact values or a regular expression.
+- **Exclude values**: Values from the dimension to always exclude. You can enter exact values or a regular expression.
 :::

explore-analyze/_snippets/lens-bucket-date-histogram.md

@@ -0,0 +1,2 @@
+- **Date histogram**: Group data into time-based buckets.
+  - **Field**: Select the date field to use for the time-based grouping.

explore-analyze/_snippets/lens-bucket-filters.md

@@ -0,0 +1 @@
+- **Filters**: Define custom KQL filters. Each filter creates one group from the documents that match its query.

explore-analyze/_snippets/lens-bucket-intervals.md

@@ -0,0 +1,5 @@
+- **Intervals**: Create numeric ranges for continuous data by grouping a numeric field into buckets.
+  - **Field**: Select the numeric field to create intervals from.
+  - **Intervals granularity**: Use the slider to control how many intervals to create. {{kib}} divides the field into evenly spaced intervals (incremented by 10, 5, or 2) between the field's minimum and maximum values. The minimum granularity is 1, and the maximum is set by the `histogram:maxBars` advanced setting.
+  - **Create custom ranges**: Define your own ranges with specific lower and upper bounds and optional labels, instead of using the automatic granularity.
+  - **Include empty rows**: Include intervals that contain no matching documents. On by default.

explore-analyze/_snippets/lens-bucket-top-values.md

@@ -0,0 +1,5 @@
+- **Top values**: Show the most common values of a field.
+  - **Field**: Select the field to group by. You can add up to 4 fields to create multi-term groups. When multiple fields are selected, each group represents a unique combination of values across those fields. You can reorder the fields by dragging them to change their priority.
+  - **Number of values**: How many top values to display. The default number of values depends on your environment:
+    - {applies_to}`serverless: ga` {applies_to}`stack: ga 9.4` Defaults to 9.
+    - {applies_to}`stack: ga 9.0-9.3` Defaults to 5 for the first Top values dimension added to the chart and 3 for each additional one.

explore-analyze/_snippets/lens-collapse-by.md

@@ -0,0 +1 @@
+- **Collapse by**: Aggregate all metric values that share the same value for this dimension into a single number, removing it as an independent grouping. Available aggregation methods: `Sum`, `Min`, `Max`, or `Average`.

explore-analyze/_snippets/lens-rank-by-options.md

@@ -1,7 +1,7 @@
 - **Rank by**: Specifies the dimension the top values are ranked by. Available options:
   - **Count of records**: Rank by the number of documents containing each value. This is the default when a metric is defined.
   - **Alphabetical**: Rank by the term key alphabetically. This is the default when no metric is defined.
-  - **Rarity**: Find terms that appear in very few documents, using a [rare terms aggregation](elasticsearch://reference/aggregations/search-aggregations-bucket-rare-terms-aggregation.md). You can configure the **Max doc count** to set the maximum number of documents a term can appear in to be considered rare (default: 1, max: 100). Only available for non-numeric fields and single-field terms.
+  - **Rarity**: Find terms that appear in very few documents, using a [rare terms aggregation](elasticsearch://reference/aggregations/search-aggregations-bucket-rare-terms-aggregation.md). You can configure the **Max doc count per term** to set the maximum number of documents a term can appear in to be considered rare (default: 1, max: 100). Available for single-field terms only, and not for floating-point numeric fields (`float`, `double`, `half_float`, and `scaled_float`).
   - **Significance**: Find statistically unusual terms compared to the overall data set, using a [significant terms aggregation](elasticsearch://reference/aggregations/search-aggregations-bucket-significantterms-aggregation.md). Only available for `keyword` fields and single-field terms.
   - **Custom**: Define a custom metric aggregation to rank by (for example, rank by the sum of a numeric field rather than by count).
 - **Rank direction**: Ascending or descending order. Disabled when **Rank by** is set to **Rarity** or **Significance**.

explore-analyze/visualize/charts/area-charts.md

@@ -126,22 +126,20 @@ Customize your area chart to match the information you need and how you want it
 **Data**
 :   
     - **Functions**:
-      - **Top values**: Create separate areas for the most common values in a field.
-        - **Field**: Select the field to group by. You can add up to 4 fields. When multiple fields are selected, each area represents a unique combination of values across those fields. You can reorder the fields by dragging them to change their priority.
-        - **Number of values**: How many top values to display. The default number of values depends on your environment:
-          - {applies_to}`serverless: ga` {applies_to}`stack: ga 9.4` Defaults to 9.
-          - {applies_to}`stack: ga 9.0-9.3` Defaults to 5.
+      :::{include} ../../_snippets/lens-bucket-top-values.md
+      :::
         :::{include} ../../_snippets/lens-rank-by-options.md
         :::
         :::{include} ../../_snippets/lens-breakdown-advanced-settings.md
         :::
-      - **Date histogram**: Group data points into time-based buckets (for example, hourly, daily, weekly). 
-        - **Field**: Select the date field to use for the time-based grouping.
+      :::{include} ../../_snippets/lens-bucket-date-histogram.md
+      :::
         :::{include} ../../_snippets/lens-histogram-settings.md
         :::
-      - **Intervals**: Create numeric ranges for continuous data. You can define the interval granularity or specify custom ranges.
-        - **Field**: Select the numeric field to create intervals from.
-      - **Filters**: Allow you to segment your data based on specific conditions, creating separate areas for each filter.
+      :::{include} ../../_snippets/lens-bucket-intervals.md
+      :::
+      :::{include} ../../_snippets/lens-bucket-filters.md
+      :::
 
 **Appearance**
 :   **Name**: By default, the chart uses the function or formula as title. It's a best practice to customize this with a meaningful title.
@@ -151,7 +149,7 @@ Customize your area chart to match the information you need and how you want it
 **Data**
 :   To represent the metrics or values you want to visualize, you can use quick functions like Average, Count, Percentile, Counter rate, or create custom calculations with formulas. Refer to [](/explore-analyze/visualize/lens.md#lens-formulas) for examples.
 
-    :::{include} ../../_snippets/area-vertical-axis-advanced-settings.md
+    :::{include} ../../_snippets/lens-value-advanced-settings.md
     :::
 
 **Appearance**
@@ -168,22 +166,23 @@ You can split your data by a categorical field to create multiple stacked or ove
 **Data**
 :   
     - **Functions**:
-      - **Top values**: Create separate areas for the most common values in a field.
-        - **Field**: Select the field to group by. You can add up to 4 fields. When multiple fields are selected, each area represents a unique combination of values across those fields. You can reorder the fields by dragging them to change their priority.
-        - **Number of values**: How many top values to display. The default number of values depends on your environment:
-          - {applies_to}`serverless: ga` {applies_to}`stack: ga 9.4` Defaults to 9.
-          - {applies_to}`stack: ga 9.0-9.3` Defaults to 3.
+      :::{include} ../../_snippets/lens-bucket-top-values.md
+      :::
         :::{include} ../../_snippets/lens-rank-by-options.md
         :::
         :::{include} ../../_snippets/lens-breakdown-advanced-settings.md
         :::
-      - **Date histogram**: Group data points into time-based buckets (for example, hourly, daily, weekly). 
-        - **Field**: Select the date field to use for the time-based grouping.
+      :::{include} ../../_snippets/lens-bucket-date-histogram.md
+      :::
         :::{include} ../../_snippets/lens-histogram-settings.md
         :::
-      - **Intervals**: Create numeric ranges for continuous data. You can define the interval granularity or specify custom ranges.
-        - **Field**: Select the numeric field to create intervals from.
-      - **Filters**: Create separate colored areas based on filter conditions.
+      :::{include} ../../_snippets/lens-bucket-intervals.md
+      :::
+      :::{include} ../../_snippets/lens-bucket-filters.md
+      :::
+
+    :::{include} ../../_snippets/lens-collapse-by.md
+    :::
 
 **Appearance**
 :   Allow you to customize how your breakdown data is displayed in line charts, including:

explore-analyze/visualize/charts/bar-charts.md

@@ -358,23 +358,22 @@ Customize your bar chart to display exactly the information you need, formatted
 ### Horizontal axis settings [horizontal-axis-options]
 
 **Data**
-:   The dimension that creates your individual bars. Common functions include:
-    - **Top values**: Create bars for the most common values in a field.
-      - **Field**: Select the field to group by. You can add up to 4 fields to create multi-term bars. When multiple fields are selected, each bar represents a unique combination of values across those fields. You can reorder the fields by dragging them to change their priority.
-      - **Number of values**: How many top values to display. The default number of values depends on your environment:
-        - {applies_to}`serverless: ga` {applies_to}`stack: ga 9.4` Defaults to 9.
-        - {applies_to}`stack: ga 9.0-9.3` Defaults to 5.
+:   The dimension that creates your individual bars. It supports the following functions:
+
+    :::{include} ../../_snippets/lens-bucket-top-values.md
+    :::
       :::{include} ../../_snippets/lens-rank-by-options.md
       :::
       :::{include} ../../_snippets/lens-breakdown-advanced-settings.md
       :::
-    - **Date histogram**: Create time-based bars with configurable intervals.
-      - **Field**: Select the date field to use for the time-based grouping.
+    :::{include} ../../_snippets/lens-bucket-date-histogram.md
+    :::
       :::{include} ../../_snippets/lens-histogram-settings.md
       :::
-    - **Intervals**: Group data into numerical ranges.
-      - **Field**: Select the numeric field to create intervals from.
-    - **Filters**: Define custom categories using KQL queries.
+    :::{include} ../../_snippets/lens-bucket-intervals.md
+    :::
+    :::{include} ../../_snippets/lens-bucket-filters.md
+    :::
 
 **Appearance**
 :   Define the formatting of the horizontal axis, including:
@@ -399,23 +398,25 @@ Customize your bar chart to display exactly the information you need, formatted
 ### Breakdown settings [breakdown-options]
 
 **Data**
-:   Split your bars into segments or groups based on another dimension. Each unique value creates its own segment or bar, allowing you to show composition or compare metrics across multiple dimensions. Common functions include:
-    - **Top values**: Create bar segments for the most common values in a field.
-      - **Field**: Select the field to group by. You can add up to 4 fields. When multiple fields are selected, each segment represents a unique combination of values across those fields. You can reorder the fields by dragging them to change their priority.
-      - **Number of values**: How many top values to display. The default number of values depends on your environment:
-        - {applies_to}`serverless: ga` {applies_to}`stack: ga 9.4` Defaults to 9.
-        - {applies_to}`stack: ga 9.0-9.3` Defaults to 3.
+:   Split your bars into segments or groups based on another dimension. Each unique value creates its own segment or bar, allowing you to show composition or compare metrics across multiple dimensions. It supports the following functions:
+
+    :::{include} ../../_snippets/lens-bucket-top-values.md
+    :::
       :::{include} ../../_snippets/lens-rank-by-options.md
       :::
       :::{include} ../../_snippets/lens-breakdown-advanced-settings.md
       :::
-    - **Date histogram**: Create time-based bars with configurable intervals.
-      - **Field**: Select the date field to use for the time-based grouping.
+    :::{include} ../../_snippets/lens-bucket-date-histogram.md
+    :::
       :::{include} ../../_snippets/lens-histogram-settings.md
       :::
-    - **Intervals**: Group data into numerical ranges.
-      - **Field**: Select the numeric field to create intervals from.
-    - **Filters**: Define custom categories using KQL queries.
+    :::{include} ../../_snippets/lens-bucket-intervals.md
+    :::
+    :::{include} ../../_snippets/lens-bucket-filters.md
+    :::
+
+    :::{include} ../../_snippets/lens-collapse-by.md
+    :::
 
 **Appearance**
 :   Define the formatting of the breakdown, including:

explore-analyze/visualize/charts/heat-map-charts.md

@@ -232,22 +232,20 @@ The **Horizontal axis** dimension defines the columns of the heat map.
 **Data**
 :   The **Horizontal axis** dimension supports the following functions:
 
-    - **Top values**: Create columns for the most common values in a field.
-      - **Field**: Select the field to group by. You can add up to 4 fields to create multi-term columns. When multiple fields are selected, each column represents a unique combination of values across those fields. You can reorder the fields by dragging them to change their priority.
-      - **Number of values**: How many top values to display. The default number of values depends on your environment:
-        - {applies_to}`serverless: ga` {applies_to}`stack: ga 9.4` Defaults to 9.
-        - {applies_to}`stack: ga 9.0-9.3` Defaults to 5.
+    :::{include} ../../_snippets/lens-bucket-top-values.md
+    :::
       :::{include} ../../_snippets/lens-rank-by-options.md
       :::
       :::{include} ../../_snippets/lens-breakdown-advanced-settings.md
       :::
-    - **Date histogram**: Group data into time-based buckets.
-      - **Field**: Select the date field to use for the time-based grouping.
+    :::{include} ../../_snippets/lens-bucket-date-histogram.md
+    :::
       :::{include} ../../_snippets/lens-histogram-settings.md
       :::
-    - **Intervals**: Create numeric ranges for continuous data.
-      - **Field**: Select the numeric field to create intervals from.
-      - **Include empty rows**: Include intervals with no matching documents.
+    :::{include} ../../_snippets/lens-bucket-intervals.md
+    :::
+    :::{include} ../../_snippets/lens-bucket-filters.md
+    :::
 
 **Appearance**
 :   - **Name**: Customize the axis label.
@@ -259,22 +257,20 @@ The **Vertical axis** dimension defines the rows of the heat map.
 **Data**
 :   The **Vertical axis** dimension supports the same functions as the horizontal axis:
 
-    - **Top values**: Create rows for the most common values in a field.
-      - **Field**: Select the field to group by. You can add up to 4 fields to create multi-term rows. When multiple fields are selected, each row represents a unique combination of values across those fields. You can reorder the fields by dragging them to change their priority.
-      - **Number of values**: How many top values to display. The default number of values depends on your environment:
-        - {applies_to}`serverless: ga` {applies_to}`stack: ga 9.4` Defaults to 9.
-        - {applies_to}`stack: ga 9.0-9.3` Defaults to 3.
+    :::{include} ../../_snippets/lens-bucket-top-values.md
+    :::
       :::{include} ../../_snippets/lens-rank-by-options.md
       :::
       :::{include} ../../_snippets/lens-breakdown-advanced-settings.md
       :::
-    - **Date histogram**: Group data into time-based buckets.
-      - **Field**: Select the date field to use for the time-based grouping.
+    :::{include} ../../_snippets/lens-bucket-date-histogram.md
+    :::
       :::{include} ../../_snippets/lens-histogram-settings.md
       :::
-    - **Intervals**: Create numeric ranges for continuous data.
-      - **Field**: Select the numeric field to create intervals from.
-      - **Include empty rows**: Include intervals with no matching documents.
+    :::{include} ../../_snippets/lens-bucket-intervals.md
+    :::
+    :::{include} ../../_snippets/lens-bucket-filters.md
+    :::
 
 **Appearance**
 :   - **Name**: Customize the axis label.