docs: add multi-layer ES|QL charts section (#8681)

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

@@ -97,6 +97,8 @@ To build the chart:
 
 The chart preview shows how the volume of transferred data changes over time.
 
+{applies_to}`serverless: ga` {applies_to}`stack: ga 9.6+` To compare this area with the results of another query, add a layer to the chart. Refer to [Add multiple layers to {{esql}} charts](../esorql.md#esql-viz-multi-layer).
+
 ## Apply area chart best practices [area-chart-best-practices]
 
 After building the chart with the point-and-click editor or an {{esql}} query, customize its appearance for your data and audience:

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

@@ -96,6 +96,8 @@ To build the chart:
 
 The chart preview shows one bar for each response code. The request count determines the height of each bar.
 
+{applies_to}`serverless: ga` {applies_to}`stack: ga 9.6+` To compare these bars with the results of another query, add a layer to the chart. Refer to [Add multiple layers to {{esql}} charts](../esorql.md#esql-viz-multi-layer).
+
 ## Apply bar chart best practices [bar-chart-best-practices]
 
 After building the chart with the point-and-click editor or an {{esql}} query, customize its appearance for your data and audience:

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

@@ -96,6 +96,8 @@ To build the chart:
 
 The chart preview shows how the request count changes over time.
 
+{applies_to}`serverless: ga` {applies_to}`stack: ga 9.6+` To compare this line with the results of another query, add a layer to the chart. Refer to [Add multiple layers to {{esql}} charts](../esorql.md#esql-viz-multi-layer).
+
 ## Apply line chart best practices [line-chart-best-practices]
 
 After building the chart with the point-and-click editor or an {{esql}} query, customize its appearance for your data and audience:

explore-analyze/visualize/esorql.md

@@ -103,6 +103,83 @@ In the resulting chart, the time buckets are placed on the **Horizontal axis**,
 
 To add another field to the breakdown, select **Add a field** under **Breakdown** and choose a column from your query. You can also drag the fields inside the **Breakdown** dimension to change the order in which their values appear in the combined label.
 
+### Add multiple layers to {{esql}} charts [esql-viz-multi-layer]
+```{applies_to}
+stack: ga 9.6
+serverless: ga
+```
+
+If the series you want to compare come from different queries, you can plot each query in its own layer on the same chart. You can also add annotations and reference lines on top of the data. Layers are available on bar, line, and area charts. Other chart types, such as pie or metric, use a single query.
+
+Every {{esql}} data layer has its own query and its own dimensions, so you can change one query without touching the others. To split the results of a single query into several series instead, use the [**Breakdown** dimension](#esql-viz-multi-field-breakdown).
+
+To add a layer, select {icon}`plus` **Add layer** in the editor, then select the type of layer. The new layer opens in its own tab. When a chart has more than one layer, each layer has a tab, and you select a tab to edit that layer's query and dimensions.
+
+![The ES|QL visualization editor with the Add layer button next to the layer tabs](/explore-analyze/images/esql-visualization-add-layer.png)
+
+The layer types work a little differently from the same layers in a point-and-click visualization, as the following sections describe.
+
+#### Plot another query in its own layer
+
+To compare two sets of results on one chart, add a layer with its own query. For example, start from the [time series chart](#esql-time-series-charts) that counts requests, then add a layer for the requests that ended in a server error (response codes that start with 5):
+
+```esql
+FROM kibana_sample_data_logs
+| WHERE @timestamp <= ?_tend AND @timestamp > ?_tstart AND response.keyword LIKE "5*"
+| STATS server_errors = COUNT(*) BY time_bucket = BUCKET(@timestamp, 50, ?_tstart, ?_tend)
+```
+
+To add it:
+
+1. Select {icon}`plus` **Add layer** → **Visualization**.
+2. If you're asked, select the chart type for the layer. Each layer can use a different type, for example a line over bars.
+3. In the new layer's tab, enter the query and run it.
+4. Assign `time_bucket` to the **Horizontal axis** and `server_errors` to the **Vertical axis**.
+
+Check that both dimensions are set before you look at the chart. If the **Horizontal axis** of a layer is empty, the values of that layer don't follow time and stack at a single position.
+
+Use the same time-bucket column on the **Horizontal axis** of each layer so the layers line up in time. To compare client errors (response codes that start with 4) as well, add a third layer the same way, with this query:
+
+```esql
+FROM kibana_sample_data_logs
+| WHERE @timestamp <= ?_tend AND @timestamp > ?_tstart AND response.keyword LIKE "4*"
+| STATS client_errors = COUNT(*) BY time_bucket = BUCKET(@timestamp, 50, ?_tstart, ?_tend)
+```
+
+If you edit a layer's query and its results no longer contain a compatible column for every dimension of that layer, {{kib}} rejects the query and shows an error. Remove the incompatible dimensions, then run the query again.
+
+#### Mark events with annotations
+
+Annotations mark an event or a period on a time chart, such as a deployment or an outage. The chart needs a time axis, so **Annotations** stays unavailable until the horizontal axis shows time.
+
+Select {icon}`plus` **Add layer** → **Annotations**. {{kib}} creates a new annotation straight away. In a point-and-click visualization, you choose between a new annotation and one from the annotation library, and an annotation can be based on a query. {{esql}} charts offer neither. Each annotation is placed manually: set **Annotation date**, or turn on **Apply as range** and set **From** and **To**.
+
+#### Add reference lines
+
+A reference line shows a threshold, such as a target or a budget, so you can see at a glance where your data crosses it. How you add one depends on your version:
+
+- {applies_to}`serverless: ga` {applies_to}`stack: ga 9.7+` Select {icon}`plus` **Add layer** → **Reference lines**, then select the source of the values:
+
+    - **Static reference lines**: Enter fixed values. This layer has no query.
+    - **ES|QL reference lines**: Calculate the thresholds with a separate query, independent of the queries of your data layers. Each column of numbers that the query returns can become a line.
+
+- {applies_to}`stack: ga 9.6` Select {icon}`plus` **Add layer** → **Reference lines**, then enter fixed values.
+
+In a point-and-click visualization, you add a reference line first, then choose in its settings how to calculate it, for example with a formula. On an {{esql}} chart, you choose the source when you add the layer.
+
+{applies_to}`serverless: ga` {applies_to}`stack: ga 9.7+` For example, to draw a line at the average number of requests per time bucket, add an **ES|QL reference lines** layer with this query. It reuses the time-bucket query and averages its results:
+
+```esql
+FROM kibana_sample_data_logs
+| WHERE @timestamp <= ?_tend AND @timestamp > ?_tstart
+| STATS requests = COUNT(*) BY time_bucket = BUCKET(@timestamp, 50, ?_tstart, ?_tend)
+| STATS average_requests = AVG(requests)
+```
+
+#### Suggestions with several layers
+
+The **Suggestions** panel is hidden while the chart has more than one layer, because applying a suggestion would replace the other layers.
+
 ### Chart configuration persistence over {{esql}} query update [chart-config-persist]
 ```{applies_to}
 stack: ga 9.1