ESQL Panel Configuration¶

ESQL panels leverage the power of Elasticsearch Query Language (ESQL) to create visualizations. This allows for more complex data transformations and aggregations directly within the query that feeds the chart.

The ESQLPanel is the primary container. Its esql field holds both the ESQL query and the specific visualization type configuration (for example metric, pie, bar, or datatable).

A Poem for the Query Wizards¶

For those who wield the power of Elasticsearch Query Language:

FROM the indexes, data flows,
WHERE the data goes, nobody knows.
STATS works on numbers, SORT shows the best,
LIMIT lets the engine rest.

ESQL queries, powerful and clean,
Transforming data never seen!
Complex aggregations, custom math,
Your query blazes the perfect path.

No need for pre-defined fields to bind,
You shape your metrics, well-defined.
FROM, BY, and STATS aligned,
Column names thoughtfully designed.

So here's to those who love to query,
With ESQL power, never weary!
Direct from Elasticsearch's core,
Your visualizations are never a bore!

Minimal Configuration Examples¶

Minimal ESQL Metric Chart:

dashboards:
  - name: "ESQL Metrics Dashboard"
    panels:
      - title: "Total Processed Events"
        size: {w: 16, h: 3}
        esql:
          type: metric
          query: |
            FROM logs-*
            | STATS total_events = COUNT(*)
          primary:
            field: "total_events"

Advanced: Query Reuse with YAML Anchors

ES|QL queries can also be defined as arrays, enabling reuse patterns with YAML anchors. This lets you define base queries once and extend them across multiple panels. See ES|QL Query Reuse with YAML Anchors for detailed patterns and examples.

Minimal ESQL Pie Chart:

dashboards:
  - name: "ESQL Event Analysis"
    panels:
      - title: "Events by Type (ESQL)"
        size: {w: 32, h: 3}
        position: {x: 16, y: 0}
        esql:
          type: pie # Specifies an ESQLPieChart
          query: |
            FROM logs-*
            | STATS event_count = COUNT(*) BY event.category
            | SORT event_count DESC
            | LIMIT 5
          metrics:
            - field: "event_count"
          breakdowns:
            - field: "event.category"

Full Configuration Options¶

ESQL Panel (panel with an `esql:` field)¶

This is the main object for an ESQL-based visualization. It inherits from the Base Panel Configuration. The presence of the esql field distinguishes it from a Lens panel.

YAML Key	Data Type	Description	Kibana Default	Required
`id`	`string`	A unique identifier for the panel. Inherited from BasePanel.	Generated ID	No
`title`	`string`	The title displayed on the panel header. Inherited from BasePanel.	`""` (empty string)	No
`hide_title`	`boolean`	If `true`, the panel title will be hidden. Inherited from BasePanel.	`false`	No
`description`	`string`	A brief description of the panel. Inherited from BasePanel.	`""` (empty string, if `None`)	No
`size`	`Size` object	Defines the panel's width and height. Inherited from BasePanel. See Size Object Configuration.	`w: 12, h: 8`	No
`position`	`Position` object	Defines the panel's x/y coordinates. Inherited from BasePanel. See Position Object Configuration.	Auto-calculated	No
`esql`	`ESQLPanelConfig` object	Defines the actual ESQL visualization configuration. Contains the query, time_field, inner `type`, and chart-specific fields.	N/A	Yes

ESQL Chart Configuration Fields¶

All ESQL chart types share these common panel-level fields:

YAML Key	Data Type	Description	Default	Required
`query`	`string` or `ESQLQuery` object	The ESQL query string. See Queries Documentation.	N/A	Yes
`time_field`	`string`	The time field to use for the dashboard time picker. This connects the panel to the dashboard's global time range controls.	`'@timestamp'`	No
`type`	Chart type literal	The specific chart type (metric, pie, bar, line, area, etc.). See chart-specific sections below.	N/A	Yes

Example using custom time field:

dashboards:
  - name: "Custom Time Field Example"
    panels:
      - title: "Events Over Time"
        size: {w: 48, h: 20}
        esql:
          type: bar
          query: |
            FROM logs-*
            | STATS event_count = COUNT(*) BY timestamp_bucket = BUCKET(event.created, 20, ?_tstart, ?_tend)
            | SORT timestamp_bucket ASC
          time_field: "event.created"  # Use event.created instead of @timestamp
          dimension:
            field: "timestamp_bucket"
          metrics:
            - field: "event_count"

Note: The BUCKET(@timestamp, 20, ?_tstart, ?_tend) syntax creates ~20 buckets that automatically adapt to the dashboard time range. The ?_tstart and ?_tend parameters are auto-populated by Kibana.

ESQL Metric Chart (`esql.type: metric`)¶

Displays a single primary metric derived from an ESQL query, optionally with a secondary metric, a maximum value, and a breakdown dimension. The field names in the chart configuration must correspond to column names produced by the ESQL query.

YAML Key	Data Type	Description	Kibana Default	Required
`type`	`Literal['metric']`	Specifies the chart type as an ESQL Metric visualization.	`metric`	Yes
`id`	`string`	An optional unique identifier for this specific chart layer.	Generated ID	No
`primary`	`ESQLMetric` object	The primary metric to display. Its `field` refers to an ESQL result column. See ESQL Metric Column.	N/A	Yes
`secondary`	`ESQLMetric` object	An optional secondary metric. Its `field` refers to an ESQL result column. See ESQL Metric Column.	`None`	No
`maximum`	`ESQLMetric` object	An optional maximum metric. Its `field` refers to an ESQL result column. See ESQL Metric Column.	`None`	No
`breakdown`	`ESQLDimension` object	An optional dimension to break down the metric by. Its `field` refers to an ESQL result column. See ESQL Dimension Column.	`None`	No

Example (ESQL Metric Chart):

dashboards:
  - name: "ESQL Metric Example"
    description: "Example of ESQL metric panel with primary, secondary, and breakdown"
    panels:
      - title: "Service Performance Metrics"
        size: {w: 24, h: 15}
        esql:
          type: metric
          query: |
            FROM logs-*
            | STATS avg_response_time = AVG(response.time),
                    p95_response_time = PERCENTILE(response.time, 95.0) BY service_name
          primary:
            field: "avg_response_time"
          secondary:
            field: "p95_response_time"
          breakdown:
            field: "service_name"

ESQL Pie Chart (`esql.type: pie`)¶

Visualizes proportions of categories using slices of a pie or a donut chart, with data sourced from an ESQL query. The field names in the chart configuration must correspond to column names produced by the ESQL query.

YAML Key	Data Type	Description	Kibana Default	Required
`type`	`Literal['pie']`	Specifies the chart type as an ESQL Pie visualization.	`pie`	Yes
`id`	`string`	An optional unique identifier for this specific chart layer.	Generated ID	No
`metrics`	`ESQLMetric \\| list[ESQLMetric]` object	A single metric or list of metrics that determine the size of each slice. Each `field` refers to an ESQL result column. See ESQL Metric Column.	N/A	Yes
`breakdowns`	`list of ESQLDimension` objects	One or more breakdowns that determine how the pie is sliced. Each `field` refers to an ESQL result column. See ESQL Dimension Column.	N/A	Yes
`appearance`	`PieChartAppearance` object	Formatting options for the chart appearance. See Pie Chart Appearance (shared with Lens).	`None`	No
`legend`	`PieLegend` object	Formatting options for the chart legend. See Pie Legend (shared with Lens).	`None`	No
`color`	`ColorValueMapping` object	Formatting options for the chart color palette. See Color Mapping (shared with Lens).	`None`	No

Example (ESQL Pie Chart):

dashboards:
  - name: "ESQL Pie Chart Example"
    description: "Example of ESQL pie chart with donut appearance"
    panels:
      - title: "Error Types Distribution"
        size: {w: 24, h: 15}
        esql:
          type: pie
          query: |
            FROM logs-*
            | STATS error_count = COUNT(error.code) BY error_type
            | SORT error_count DESC
            | LIMIT 10
          metrics:
            - field: "error_count"
          breakdowns:
            - field: "error_type"
          appearance:
            donut: "small"

ESQL Bar Chart (`esql.type: bar`)¶

Displays bar chart visualizations with data sourced from an ESQL query. Supports stacked, unstacked, and percentage modes. The field names in the chart configuration must correspond to column names produced by the ESQL query.

YAML Key	Data Type	Description	Kibana Default	Required
`type`	`Literal['bar']`	Specifies the chart type as an ESQL Bar visualization.	`bar`	Yes
`id`	`string`	An optional unique identifier for this specific chart layer.	Generated ID	No
`mode`	`Literal['stacked', 'unstacked', 'percentage']`	Stacking mode for bar charts.	`'stacked'`	No
`dimension`	`ESQLDimension` object	A single dimension that determines the X-axis (0 or 1 dimension allowed). The `field` refers to an ESQL result column. See ESQL Dimension Column.	`None`	No
`metrics`	`list of ESQLMetric` objects	One or more metrics that determine the Y-axis values. Each `field` refers to an ESQL result column. See ESQL Metric Column.	N/A	Yes
`breakdown`	`ESQLDimension` object	An optional dimension to split the series by. Its `field` refers to an ESQL result column. See ESQL Dimension Column.	`None`	No
`appearance`	`XYAppearance` object	Formatting options for chart appearance. See XY Chart Appearance.	`None`	No
`legend`	`XYLegend` object	Formatting options for the chart legend. See XY Legend.	`None`	No
`color`	`ColorValueMapping` object	Formatting options for the chart color palette. See Color Mapping (shared with other chart types).	`None`	No

Example (ESQL Bar Chart):

dashboards:
  - name: "ESQL Bar Chart Example"
    description: "Example of ESQL bar chart with stacked mode"
    panels:
      - title: "Events Over Time by Category"
        size: {w: 48, h: 20}
        esql:
          type: bar
          query: |
            FROM logs-*
            | STATS event_count = COUNT(*) BY timestamp_bucket = BUCKET(@timestamp, 20, ?_tstart, ?_tend), event.category
            | SORT timestamp_bucket ASC
          mode: stacked
          dimension:
            field: "timestamp_bucket"
          metrics:
            - field: "event_count"
          breakdown:
            field: "event.category"

ESQL Line Chart (`esql.type: line`)¶

Displays line chart visualizations with data sourced from an ESQL query. The field names in the chart configuration must correspond to column names produced by the ESQL query.

YAML Key	Data Type	Description	Kibana Default	Required
`type`	`Literal['line']`	Specifies the chart type as an ESQL Line visualization.	`line`	Yes
`id`	`string`	An optional unique identifier for this specific chart layer.	Generated ID	No
`dimension`	`ESQLDimension` object	A single dimension that determines the X-axis (0 or 1 dimension allowed). The `field` refers to an ESQL result column. See ESQL Dimension Column.	`None`	No
`metrics`	`list of ESQLMetric` objects	One or more metrics that determine the Y-axis values. Each `field` refers to an ESQL result column. See ESQL Metric Column.	N/A	Yes
`breakdown`	`ESQLDimension` object	An optional dimension to split the series by. Its `field` refers to an ESQL result column. See ESQL Dimension Column.	`None`	No
`appearance`	`XYAppearance` object	Formatting options for chart appearance. See XY Chart Appearance.	`None`	No
`legend`	`XYLegend` object	Formatting options for the chart legend. See XY Legend.	`None`	No
`color`	`ColorValueMapping` object	Formatting options for the chart color palette. See Color Mapping (shared with other chart types).	`None`	No

Example (ESQL Line Chart):

dashboards:
  - name: "ESQL Line Chart Example"
    description: "Example of ESQL line chart with breakdown"
    panels:
      - title: "Average Response Time by Service"
        size: {w: 48, h: 20}
        esql:
          type: line
          query: |
            FROM logs-*
            | STATS avg_response_time = AVG(response.time) BY timestamp_bucket = BUCKET(@timestamp, 20, ?_tstart, ?_tend), service.name
            | SORT timestamp_bucket ASC
          dimension:
            field: "timestamp_bucket"
          metrics:
            - field: "avg_response_time"
          breakdown:
            field: "service.name"

ESQL Area Chart (`esql.type: area`)¶

Displays area chart visualizations with data sourced from an ESQL query. Supports stacked, unstacked, and percentage modes. The field names in the chart configuration must correspond to column names produced by the ESQL query.

YAML Key	Data Type	Description	Kibana Default	Required
`type`	`Literal['area']`	Specifies the chart type as an ESQL Area visualization.	`area`	Yes
`id`	`string`	An optional unique identifier for this specific chart layer.	Generated ID	No
`mode`	`Literal['stacked', 'unstacked', 'percentage']`	Stacking mode for area charts.	`'stacked'`	No
`dimension`	`ESQLDimension` object	A single dimension that determines the X-axis (0 or 1 dimension allowed). The `field` refers to an ESQL result column. See ESQL Dimension Column.	`None`	No
`metrics`	`list of ESQLMetric` objects	One or more metrics that determine the Y-axis values. Each `field` refers to an ESQL result column. See ESQL Metric Column.	N/A	Yes
`breakdown`	`ESQLDimension` object	An optional dimension to split the series by. Its `field` refers to an ESQL result column. See ESQL Dimension Column.	`None`	No
`appearance`	`XYAppearance` object	Formatting options for chart appearance. See XY Chart Appearance.	`None`	No
`legend`	`XYLegend` object	Formatting options for the chart legend. See XY Legend.	`None`	No
`color`	`ColorValueMapping` object	Formatting options for the chart color palette. See Color Mapping (shared with other chart types).	`None`	No

Example (ESQL Area Chart):

dashboards:
  - name: "ESQL Area Chart Example"
    description: "Example of ESQL area chart with stacked mode"
    panels:
      - title: "Total Bytes by Host"
        size: {w: 48, h: 20}
        esql:
          type: area
          query: |
            FROM logs-*
            | STATS bytes_total = SUM(bytes) BY timestamp_bucket = BUCKET(@timestamp, 20, ?_tstart, ?_tend), host.name
            | SORT timestamp_bucket ASC
          mode: stacked
          dimension:
            field: "timestamp_bucket"
          metrics:
            - field: "bytes_total"
          breakdown:
            field: "host.name"

ESQL Columns¶

For ESQL panels, the primary, secondary, maximum (in metric charts) and metrics, breakdowns (in pie charts) fields refer to columns that must be present in the output of your ESQL query.

Static values in ES|QL charts

ES|QL chart metric fields must reference query result columns. If you need a constant value (for example, a gauge goal), add it in the query with EVAL, then reference that field in your chart config.

Example:

esql:
  type: gauge
  query: |
    FROM metrics-*
    | STATS avg_cpu = AVG(system.cpu.total.pct)
    | EVAL goal_cpu = 80
  metric:
    field: "avg_cpu"
  goal:
    field: "goal_cpu"

ESQL Metric Column¶

Used to specify a metric column from your ESQL query result.

YAML Key	Data Type	Description	Kibana Default	Required
`id`	`string`	An optional unique identifier for this metric column definition.	Generated ID	No
`field`	`string`	The name of the column in your ESQL query result that represents the metric value.	N/A	Yes
`label`	`string`	An optional display label for the metric.	`None`	No
`format`	`ESQLMetricFormat` object	Optional format configuration for the metric. See ESQL Metric Format.	`None`	No

ESQL Metric Format¶

Configure how metric values are displayed (number format, suffix, decimal places, etc.).

Standard Format Types:

YAML Key	Data Type	Description	Kibana Default	Required
`type`	`Literal['number', 'bytes', 'bits', 'percent', 'duration']`	The format type for the metric.	N/A	Yes
`decimals`	`integer`	Number of decimal places to display. If not specified, defaults to 2 for number/bytes/percent/duration, 0 for bits.	Type-dependent	No
`suffix`	`string`	Optional suffix to display after the number (e.g., 'KB', 'ms').	`None`	No
`compact`	`boolean`	Whether to display the number in a compact format (e.g., '1.2K' instead of '1200').	`None`	No
`pattern`	`string`	Optional Numeral.js pattern for custom formatting. Controls decimal places, thousands separators, and more (e.g., '0,0.00' for 2 decimals with comma separator, '0.0000' for 4 decimals). Note: `decimals` provides a simpler way to control decimal places without a pattern.	`None`	No

Custom Format Type:

For completely custom number formatting, use:

YAML Key	Data Type	Description	Kibana Default	Required
`type`	`Literal['custom']`	Indicates a custom format pattern.	`'custom'`	Yes
`pattern`	`string`	Numeral.js pattern for custom formatting (e.g., '0,0.[0000]', '0.00%').	N/A	Yes

Example (Metric with Format):

dashboards:
  - name: "ESQL Metric Formatting Example"
    description: "Example showing various metric formatting options"
    panels:
      - title: "Formatted Metrics"
        size: {w: 48, h: 20}
        esql:
          type: bar
          query: |
            FROM logs-*
            | STATS total_bytes = SUM(bytes),
                    event_count = COUNT(*),
                    avg_response_time = AVG(response.time),
                    success_rate = COUNT(status == 200) / COUNT(*) * 100,
                    precise_value = AVG(bytes) BY timestamp_bucket = BUCKET(@timestamp, 20, ?_tstart, ?_tend)
            | SORT timestamp_bucket ASC
          dimension:
            field: "timestamp_bucket"
          metrics:
            - field: "total_bytes"
              label: "Total Data"
              format:
                type: bytes
                decimals: 1
            - field: "event_count"
              label: "Events"
              format:
                type: number
                decimals: 0
            - field: "avg_response_time"
              label: "Avg Response Time"
              format:
                type: number
                decimals: 2
                suffix: "ms"
            - field: "success_rate"
              label: "Success Rate"
              format:
                type: percent
                decimals: 1
            - field: "precise_value"
              label: "Precise Value"
              format:
                type: number
                pattern: "0,0.0000"

ESQL Dimension Column¶

Used to specify a dimension/grouping column from your ESQL query result.

YAML Key	Data Type	Description	Kibana Default	Required
`id`	`string`	An optional unique identifier for this dimension column definition.	Generated ID	No
`field`	`string`	The name of the column in your ESQL query result that represents the dimension.	N/A	Yes
`label`	`string`	An optional display label for the dimension. If not provided, the field name is used.	`None`	No
`data_type`	`Literal['date'] \\| None`	The data type of the field. Set to `'date'` for time/date fields to enable proper sorting and formatting in Kibana. This is particularly useful when using `BUCKET()` to create time series.	`None`	No

When used as a breakdown field (on XY, metric, mosaic, or waffle charts), the dimension also supports:

YAML Key	Data Type	Description	Kibana Default	Required
`collapse`	`CollapseAggregationEnum \\| None`	The collapse function to apply to this breakdown (`sum`, `avg`, `min`, `max`). Used to aggregate values when multiple series exist. Only valid on breakdown fields, not plain dimensions.	`None`	No

Example using label and data_type for time series:

dashboards:
  - name: "Time Series with BUCKET Example"
    panels:
      - title: "Events Over Time (Adaptive Buckets)"
        size: {w: 48, h: 20}
        esql:
          type: bar
          query: |
            FROM logs-*
            | STATS event_count = COUNT(*) BY time_bucket = BUCKET(@timestamp, 20, ?_tstart, ?_tend)
            | SORT time_bucket ASC
          dimension:
            field: "time_bucket"
            label: "Time"  # Friendly display name instead of 'time_bucket'
            data_type: "date"  # Tells Kibana this is a date field for proper formatting
          metrics:
            - field: "event_count"

When to use data_type: date:

Use data_type: 'date' when your dimension field contains date/time values, especially when using ES|QL's BUCKET() function to create time series. This ensures:

Proper date formatting in tooltips and axis labels
Correct chronological sorting
Time-based zoom and pan interactions
Dashboard time picker integration (via time_field)

Pie Chart Specific Formatting (Shared with Lens)¶

ESQL Pie Charts share the same formatting options for appearance, titles/text, legend, and colors as Lens Pie Charts.

Pie Chart Appearance Formatting (`appearance` field)¶

YAML Key	Data Type	Description	Kibana Default	Required
`donut`	`Literal['small', 'medium', 'large']`	If set, creates a donut chart with the specified hole size. If not specified, Kibana displays as a pie chart (no donut hole).	`None`	No

Pie Labels and Values Formatting (`appearance.categories` and `appearance.values`)¶

YAML Key	Data Type	Description	Kibana Default	Required
`appearance.categories.position`	`Literal['hide', 'inside', 'auto']`	How to display labels for each slice.	`None`	No
`appearance.values.format`	`Literal['hide', 'integer', 'percent']`	How to display the value for each slice.	`None`	No
`appearance.values.decimal_places`	`integer` (0-10)	Number of decimal places for slice values.	`None`	No

titles_and_text is not accepted in 0.4.0; use appearance.categories and appearance.values fields instead (or run kb-dashboard upgrade).

Pie Legend Formatting (`legend` field)¶

YAML Key	Data Type	Description	Kibana Default	Required
`visible`	`Literal['show', 'hide', 'auto']`	Controls legend visibility.	`None`	No
`width`	`Literal['small', 'medium', 'large', 'extra_large']`	Width of the legend area.	`None`	No
`truncate_labels`	`integer` (0-5)	Max number of lines for legend labels before truncating. `0` disables truncation.	`None`	No

Color Mapping Formatting (`color` field)¶

See ColorValueMapping for full details on color customization options.

YAML Key	Data Type	Description	Kibana Default	Required
`palette`	`string`	The ID of the color palette to use (e.g., `eui_amsterdam_color_blind`, `elastic_brand`).	`eui_amsterdam_color_blind`	No
`assignments`	`list[ColorValueAssignment]`	Manual color assignments to specific data values. See ColorValueAssignment.	`[]`	No

XY Chart Specific Formatting (Shared with Lens)¶

ESQL XY Charts (bar, line, area) share the same formatting options for appearance and legend as Lens XY Charts.

XY Chart Appearance Formatting (`appearance` field)¶

YAML Key	Data Type	Description	Kibana Default	Required
`x_axis`	`AxisConfig \\| None`	Configuration for the X-axis (horizontal axis).	`None`	No
`y_left_axis`	`AxisConfig \\| None`	Configuration for the left Y-axis (primary vertical axis).	`None`	No
`y_right_axis`	`AxisConfig \\| None`	Configuration for the right Y-axis (secondary vertical axis).	`None`	No
`series`	`list[XYSeries] \\| None`	Per-series visual configuration (axis assignment, colors).	`None`	No

AxisConfig Options¶

YAML Key	Data Type	Description	Kibana Default	Required
`title`	`str \\| None`	Custom title for the axis.	`None`	No
`scale`	`Literal['linear', 'log', 'sqrt', 'time'] \\| None`	Scale type for the axis.	`None`	No
`extent`	`AxisExtent \\| None`	Axis bounds/range configuration.	`None`	No

AxisExtent Options¶

YAML Key	Data Type	Description	Kibana Default	Required
`mode`	`Literal['full', 'data_bounds', 'custom']`	Extent mode: 'full' (entire range), 'data_bounds' (fit to data), 'custom' (manual bounds).	N/A	Yes
`min`	`float \\| None`	Minimum bound (required when mode is 'custom').	`None`	Conditional
`max`	`float \\| None`	Maximum bound (required when mode is 'custom').	`None`	Conditional
`enforce`	`bool \\| None`	Whether to enforce the bounds strictly.	`None`	No
`nice_values`	`bool \\| None`	Whether to round bounds to nice values.	`None`	No

XYSeries Options¶

YAML Key	Data Type	Description	Kibana Default	Required
`metric_id`	`str`	ID of the metric this series configuration applies to.	N/A	Yes
`axis`	`Literal['left', 'right'] \\| None`	Which Y-axis this series is assigned to (for dual-axis charts).	`None`	No
`color`	`str \\| None`	Hex color code for the series (e.g., '#2196F3').	`None`	No

XY Legend Formatting (`legend` field)¶

YAML Key	Data Type	Description	Kibana Default	Required
`visible`	`bool \\| None`	Whether the legend is visible.	`None`	No
`position`	`Literal['top', 'bottom', 'left', 'right'] \\| None`	Position of the legend (Kibana defaults to 'right').	`None`	No

ESQL Panel Configuration¶

A Poem for the Query Wizards¶

Minimal Configuration Examples¶

Full Configuration Options¶

ESQL Panel (panel with an esql: field)¶

ESQL Chart Configuration Fields¶

ESQL Metric Chart (esql.type: metric)¶

ESQL Pie Chart (esql.type: pie)¶

ESQL Bar Chart (esql.type: bar)¶

ESQL Line Chart (esql.type: line)¶

ESQL Area Chart (esql.type: area)¶