# Dashboard Compiler - Complete Documentation

> This file contains all documentation for the Dashboard Compiler project.

---



---
# Source: index.md
---

# YAML ➤ Lens Dashboard Compiler

Convert human-friendly YAML dashboard definitions into Kibana NDJSON format.

![The Chameleon mascot](./images/project-banner-smaller.png)

This tool simplifies the process of creating and managing Kibana dashboards by
allowing you to define them in a clean, maintainable YAML format instead of
hand-crafting complex JSON.

## Getting Started

### VS Code Extension (Recommended)

**Best for interactive development** - Live preview, visual editing, built-in snippets

**No Python installation required!** The extension includes a bundled LSP server binary.

**Installation:**

1. **Install the extension:**
   - **OpenVSX Registry** (Cursor, VS Code forks): Search "Kibana Dashboard Compiler"
   - **Manual**: Download `.vsix` from [releases](https://github.com/strawgate/kb-yaml-to-lens/releases)

2. **Create your first dashboard:**

   Create a new file called `my-dashboard.yaml` and add the following content:

   ```yaml
   dashboards:
   - name: My First Dashboard
     description: A simple dashboard with markdown
     panels:
       - title: Hello Panel
         markdown:
           content: |
             # Hello, Kibana!

             This is my first markdown panel.
         size: {w: 24, h: 15}
   ```

   Or use snippets: type `dashboard` and press Tab to insert a template.

3. **Preview your dashboard:**
   - Save the file (Ctrl+S) to auto-compile
   - Open Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
   - Run **"YAML Dashboard: Preview Dashboard"**

4. **Upload to Kibana:**
   - Configure Kibana URL in VS Code settings
   - Run **"YAML Dashboard: Open in Kibana"**

**Full guide:** [VS Code Extension Documentation](vscode-extension.md)

---

### CLI (For Automation & Scripting)

**Best for:** CI/CD pipelines, batch processing, programmatic usage

**Requirements:** [uv](https://github.com/astral-sh/uv) (recommended) or Python 3.12+

**Installation:** No clone or setup required! Run directly with uvx:

```bash
uvx kb-dashboard-cli compile --help
```

**Your First Dashboard:**

1. Create `inputs/my-dashboard.yaml`:

   ```yaml
   dashboards:
   - name: My First Dashboard
     description: A simple dashboard
     panels:
       - title: Welcome
         size: {w: 24, h: 15}
         markdown:
           content: |
             # Welcome to Kibana!
   ```

2. Compile:

   ```bash
   uvx kb-dashboard-cli compile --input-file inputs/my-dashboard.yaml
   ```

3. Upload to Kibana:

   ```bash
   uvx kb-dashboard-cli compile --input-file inputs/my-dashboard.yaml --upload --kibana-url http://localhost:5601
   ```

**Full guide:** [CLI Documentation](CLI.md)

---

## Features

- **YAML-based Definition** – Define dashboards, panels, filters, and queries in simple, readable YAML.
- **Kibana Integration** – Compile to NDJSON format compatible with Kibana 8+.
- **Rich Panel Support** – Support for Lens (metric, pie, XY charts), Markdown, Links, Image, and Search panels.
- **Color Palettes** – Choose from color-blind safe, brand, and other built-in color palettes.
- **Interactive Controls** – Add options lists, range sliders, and time sliders with chaining support.
- **Flexible Filtering** – Use a comprehensive filter DSL (exists, phrase, range) or raw KQL/Lucene/ESQL queries.
- **Direct Upload** – Compile and upload to Kibana in one step, with support for authentication and API keys.
- **Screenshot Export** – Generate high-quality PNG screenshots of your dashboards programmatically.

## More Examples

### Lens Metric Panel

Here's a dashboard with a Lens metric panel displaying a count:

```yaml
dashboards:
- name: Metric Dashboard
  description: A dashboard with a single metric panel
  panels:
    - title: Document Count
      type: lens
      size: {w: 24, h: 15}
      data_view: your-index-pattern-*
      chart:
        type: metric
        metrics:
          - type: count
            label: Total Documents
```

### Programmatic Alternative

While this guide focuses on YAML, you can also create dashboards entirely in Python code. This approach offers:

- Dynamic dashboard generation based on runtime data
- Type safety with Pydantic models
- Reusable dashboard templates and components
- Integration with existing Python workflows

See the [Programmatic Usage Guide](programmatic-usage.md) for examples and patterns.

## Next Steps

### Enhance Your Workflow

- **[VS Code Extension Features](vscode-extension.md)** - Visual grid editor, code snippets, keyboard shortcuts
- **[CLI Advanced Usage](CLI.md)** - Environment variables, API keys, CI/CD integration
- **[Dashboard Decompiling Guide](guides/dashboard-decompiling-guide.md)** - Convert existing Kibana JSON dashboards to YAML
- **[Complete Examples](examples/index.md)** - Production-ready dashboard templates

### User Guide

Reference documentation for YAML dashboard syntax:

- **[Dashboard Configuration](dashboard/dashboard.md)** - Dashboard-level settings and options.
- **[Panel Types](panels/base.md)** - Available panel types (Markdown, Charts, Images, Links, etc.).
- **[Dashboard Controls](controls/config.md)** - Interactive filtering controls.
- **[Filters & Queries](filters/config.md)** - Data filtering and query configuration.

### Developer Guide

Advanced documentation for contributors and programmatic usage:

- **[Programmatic Usage](programmatic-usage.md)** - Using the Python API directly to generate dashboards.
- **[API Reference](api/index.md)** - Auto-generated Python API documentation.
- **[Contributing Guide](https://github.com/strawgate/kb-yaml-to-lens/blob/main/CONTRIBUTING.md)** - How to contribute and add new capabilities.

## How It Works

```mermaid
graph TB
    YAML[YAML Definition]
    KIBANA[Kibana]

    subgraph "Interactive Development"
        EXT[VS Code Extension]
        EXT --> PREVIEW[Live Preview]
    end

    subgraph "Automation/CI"
        CLI[CLI Compiler]
        CLI --> NDJSON[NDJSON Files]
    end

    YAML --> EXT
    YAML --> CLI
    EXT --> KIBANA
    NDJSON --> KIBANA
```

## License

MIT

### Third-Party Content

Some example dashboards in `packages/kb-dashboard-docs/content/examples/` are derived from the [Elastic integrations repository](https://github.com/elastic/integrations) and are licensed under the [Elastic License 2.0](https://github.com/strawgate/kb-yaml-to-lens/blob/main/licenses/ELASTIC-LICENSE-2.0.txt). Specifically:

- `packages/kb-dashboard-docs/content/examples/system_otel/` - System monitoring dashboards for OpenTelemetry
- `packages/kb-dashboard-docs/content/examples/docker_otel/` - Docker container monitoring dashboards for OpenTelemetry

See [licenses/README.md](https://github.com/strawgate/kb-yaml-to-lens/blob/main/licenses/README.md) for the complete list of affected files.

## Support

For issues and feature requests, please refer to the repository's issue tracker.


---
# Source: CLI.md
---

# Dashboard Compiler CLI

The `kb-dashboard` CLI tool allows you to compile YAML dashboard configurations to Kibana's NDJSON format and optionally upload them directly to Kibana.

## Prerequisites

- **[uv](https://github.com/astral-sh/uv)** (recommended) - Enables running the CLI via `uvx` with zero setup
- Or **Python 3.12+** with pip for traditional installation

**Note:** When using `uvx`, Python and all dependencies are handled automatically. The VS Code Extension does not require Python either - it includes a bundled binary. See [VS Code Extension Documentation](vscode-extension.md) for zero-configuration setup.

## When to Use the CLI

**Use the CLI when:**

- ✅ Building CI/CD pipelines for dashboard deployment
- ✅ Batch processing multiple dashboards
- ✅ Scripting dashboard generation (e.g., templates, dynamic data)
- ✅ Integrating with other automation tools
- ✅ Running in headless/server environments without GUI
- ✅ Using Docker containers or serverless functions

**Use the VS Code Extension when:**

- ✅ Developing dashboards interactively
- ✅ Learning the YAML schema
- ✅ Making frequent visual adjustments
- ✅ Needing live preview and validation

**See:** [VS Code Extension Documentation](vscode-extension.md) for interactive development workflow.

---

## Installation

### Using uvx (Recommended)

Run the CLI directly without cloning or installing anything:

```bash
uvx kb-dashboard-cli compile --help
```

This downloads and runs the published package automatically. No Python environment setup required!

### Development Installation

For contributors or development workflows, clone the repository:

```bash
git clone https://github.com/strawgate/kb-yaml-to-lens
cd kb-yaml-to-lens
just cli install
```

See [DEVELOPING.md](https://github.com/strawgate/kb-yaml-to-lens/blob/main/DEVELOPING.md) for full development setup.

## Basic Usage

### Compile Dashboards

Compile YAML dashboards to NDJSON format:

```bash
uvx kb-dashboard-cli compile
```

This will:

- Find all YAML files in `inputs/` (by default)
- Compile them to Kibana JSON format
- Output NDJSON files to `output/` directory
- Create individual NDJSON files per scenario
- Create a combined `compiled_dashboards.ndjson` file

### Compile a Single File

Compile a specific YAML file without scanning a directory:

```bash
uvx kb-dashboard-cli compile --input-file ./dashboards/example.yaml
```

When `--input-file` is provided, `--input-dir` is ignored.

### Export Individual JSON Files

For workflows that require individual JSON files per dashboard (e.g., Fleet integration):

```bash
uvx kb-dashboard-cli compile --format json --output-dir ./output
```

This will:

- Create one pretty-printed JSON file per dashboard
- Name files based on the dashboard ID (sanitized for filesystem safety)

### CI Sync Detection

Use the `--exit-non-zero-on-change` flag to detect when YAML and JSON files are out of sync in CI pipelines:

```bash
uvx kb-dashboard-cli compile --format json --output-dir ./dashboards --exit-non-zero-on-change
if [ $? -ne 0 ]; then
    echo "Dashboard JSON files are out of sync with YAML sources"
    exit 1
fi
```

When this flag is enabled, the exit code equals the number of files that changed (capped at 125). By default, the command exits with code 0 on success regardless of whether files changed.

### Compile and Upload to Kibana

Compile dashboards and upload them directly to Kibana:

```bash
uvx kb-dashboard-cli compile --upload
```

This will compile the dashboards and upload them to a local Kibana instance.

### Screenshot Dashboards

Generate a PNG screenshot of a dashboard:

```bash
uvx kb-dashboard-cli screenshot --dashboard-id <id> --output <file.png>
```

This will use Kibana's Reporting API to take a screenshot.

### Export Dashboard for Issue

Export a dashboard from Kibana and create a pre-filled GitHub issue:

```bash
uvx kb-dashboard-cli export-for-issue --dashboard-id <id>
```

This will export the dashboard and open your browser with a pre-filled GitHub issue containing the dashboard NDJSON export.

### Disassemble Dashboards

Break down a Kibana dashboard JSON into components for easier LLM-based conversion:

```bash
uvx kb-dashboard-cli disassemble dashboard.ndjson -o output_dir
```

This will extract the dashboard into separate files:

- `metadata.json` - Dashboard metadata (id, title, description, version)
- `options.json` - Dashboard display options
- `controls.json` - Control group configuration
- `filters.json` - Dashboard-level filters
- `references.json` - Data view references
- `panels/` - Individual panel JSON files

For a comprehensive guide on using this tool to convert dashboards from JSON to YAML, see the [Dashboard Decompiling Guide](guides/dashboard-decompiling-guide.md).

### Decompile Dashboards

Generate a YAML dashboard stub from Kibana NDJSON output:

```bash
uvx kb-dashboard-cli decompile dashboard.ndjson -o dashboard.yaml
```

This command emits:

- Dashboard metadata (name/id/description where available)
- Panel stubs with `id`, `title`, `size`, and `position`
- TODO comments containing original panel JSON for non-trivial manual conversion

### Upgrade Legacy YAML Schema

Upgrade legacy dashboard YAML from `0.2.7` format to canonical `0.4.0` schema:

```bash
uvx kb-dashboard-cli upgrade --input-dir ./dashboards --write
```

Run in check mode (no writes) and fail CI if upgrades are needed:

```bash
uvx kb-dashboard-cli upgrade --input-dir ./dashboards --fail-on-change
```

`kb-dashboard upgrade` targets `0.2.7 -> 0.4.0` only; `0.3.x` compatibility is intentionally not preserved.

## Configuration

### Environment Variables

The CLI supports configuration via environment variables:

```bash
export KIBANA_URL=http://localhost:5601
export KIBANA_USERNAME=elastic
export KIBANA_PASSWORD=changeme
export KIBANA_SPACE_ID=my-space  # Optional: target a specific Kibana space
# OR use API key instead
export KIBANA_API_KEY=your-api-key-here
```

Then simply run:

```bash
uvx kb-dashboard-cli compile --upload
```

### Command-Line Options

All options can also be specified on the command line:

```bash
uvx kb-dashboard-cli compile \
  --upload \
  --kibana-url http://localhost:5601 \
  --kibana-username elastic \
  --kibana-password changeme
```

To upload to a specific Kibana space:

```bash
uvx kb-dashboard-cli compile --upload --kibana-space-id production
```

Or with environment variables:

```bash
export KIBANA_SPACE_ID=staging
uvx kb-dashboard-cli compile --upload
```

## Command Reference

The following commands are available in the `kb-dashboard` CLI. For detailed information about each command and its options, see the auto-generated reference below.



---
# Source: examples/index.md
---

# Complete Examples

This section provides real-world YAML dashboard examples demonstrating various features and capabilities of the Dashboard Compiler.

## How to Use These Examples

1. **Browse:** Click on any example bundle below to view its README with complete documentation
2. **Copy:** Each bundle contains YAML files you can copy to your local directory
3. **Compile:** Run the compiler using uvx (no clone required):

   ```bash
   uvx kb-dashboard-cli compile --input-file my-dashboard.yaml
   ```

4. **Upload (Optional):** To upload directly to Kibana:

   ```bash
   uvx kb-dashboard-cli compile --input-file my-dashboard.yaml --upload
   ```

**For contributors:** If you've cloned the repository, you can compile examples from the repo:

```bash
uvx kb-dashboard-cli compile --input-dir packages/kb-dashboard-docs/content/examples --output-dir output
```

## Standalone Examples

These single-file examples demonstrate specific features:

### Controls Example

Demonstrates dashboard controls including options list, range slider, time slider, control chaining, and custom label positions.


??? example "Dashboard Definition (controls-example.yaml)"

    ```yaml
    ```


### Dimensions Example

Shows how to configure dimensions in Lens visualizations including multiple dimension types, custom formatting, and breakdown configurations.


??? example "Dashboard Definition (dimensions-example.yaml)"

    ```yaml
    ```


### Color Palette Example

Demonstrates color customization for charts including custom palettes, manual color assignments, and per-chart configuration.

**Note:** Manual color assignments are an advanced topic. See the [Custom Color Assignments](../guides/color-assignments.md) guide.


??? example "Dashboard Definition (color-palette-examples.yaml)"

    ```yaml
    ```


### Filters Example

Comprehensive filter demonstrations including field existence, phrase filters, range filters, custom DSL, and combined filters.


??? example "Dashboard Definition (filters-example.yaml)"

    ```yaml
    ```


### Multi-Panel Showcase

A complete dashboard featuring multiple panel types: markdown, metrics, pie charts, XY charts, images, links, and grid layouts.


??? example "Dashboard Definition (multi-panel-showcase.yaml)"

    ```yaml
    ```


### Navigation Example

Demonstrates dashboard navigation features including links panels, dashboard linking patterns, and URL parameter passing.


??? example "Dashboard Definition (navigation-example.yaml)"

    ```yaml
    ```


### Drilldowns Example

Demonstrates panel drilldowns including dashboard-to-dashboard navigation and URL drilldowns with template variables. See the [Drilldowns Example](drilldowns/README.md) for complete documentation.


??? example "Dashboard Definition (drilldowns/01-drilldowns-demo.yaml)"

    ```yaml
    ```


### Heatmap Examples

Examples of heatmap visualizations.


??? example "Dashboard Definition (heatmap-examples.yaml)"

    ```yaml
    ```


### Metric Formatting Examples

Examples of metric formatting options.


??? example "Dashboard Definition (metric-formatting-examples.yaml)"

    ```yaml
    ```


## Integration Bundles

Complete dashboard bundles for monitoring various technologies. Each bundle includes multiple dashboards with navigation links and comprehensive documentation.

### OpenTelemetry Integrations

| Bundle | Description |
| ------ | ----------- |
| [Aerospike](aerospike/README.md) | Aerospike NoSQL database monitoring (3 dashboards) |
| [Apache HTTP Server](apache_otel/README.md) | Apache web server metrics and logs (1 dashboard) |
| [AWS CloudTrail](aws_cloudtrail_otel/README.md) | AWS API activity monitoring with ES\|QL (1 dashboard) |
| [AWS VPC Flow Logs](aws_vpcflow_otel/README.md) | VPC network traffic analysis (3 dashboards) |
| [Docker](docker_otel/README.md) | Container monitoring with Docker Stats receiver (2 dashboards) |
| [Elasticsearch](elasticsearch_otel/README.md) | Elasticsearch cluster monitoring (7 dashboards) |
| [Kubernetes Cluster](k8s_cluster_otel/README.md) | K8s cluster health and workload monitoring (5 dashboards) |
| [Memcached](memcached_otel/README.md) | Memcached cache monitoring (1 dashboard) |
| [MySQL](mysql_otel/README.md) | MySQL database metrics (2 dashboards) |
| [PostgreSQL](postgresql_otel/README.md) | PostgreSQL database monitoring (2 dashboards) |
| [Redis](redis_otel/README.md) | Redis instance and database monitoring (3 dashboards) |
| [System (OTel)](system_otel/README.md) | Host metrics with Host Metrics receiver (5 dashboards) |

### Elastic Agent Integrations

| Bundle | Description |
| ------ | ----------- |
| [CrowdStrike](crowdstrike/README.md) | CrowdStrike EDR security dashboards (6 dashboards) |
| [CrowdStrike Modern](crowdstrike-modern/README.md) | Workflow-centric SOC dashboards (4 dashboards) |
| [System (Classic)](system/README.md) | Elastic System integration dashboards (14 dashboards) |
| [System (Modern)](system_modern/README.md) | Modern System dashboards with style guide patterns (14 dashboards) |

## Viewing Example Source Code

All example files are located in the `packages/kb-dashboard-docs/content/examples/` directory of the repository. You can:

1. **View README:** Click the bundle link to see complete setup instructions and dashboard descriptions
2. **Clone locally:** Download the repository to experiment with examples
3. **Compile examples:** Run `uvx kb-dashboard-cli compile --input-dir packages/kb-dashboard-docs/content/examples --output-dir output` to generate NDJSON files

## Using Examples as Templates

To use an example as a starting point for your own dashboard:

1. Copy the example YAML file to your `inputs/` directory
2. Modify the dashboard name, description, and ID
3. Adjust panels, filters, and controls to match your data views
4. Compile and upload to Kibana

## Related Documentation

- [Dashboard Configuration](../dashboard/dashboard.md) - Dashboard-level settings
- [Panel Types](../panels/base.md) - Available panel types and configurations


---
# Source: dashboard/dashboard.md
---

# Dashboard Configuration

The `dashboards` array is the root element in your YAML configuration file. Each dashboard defines the overall structure, content, and global settings for a Kibana dashboard.

## Minimal Configuration Example

A minimal dashboard requires a `name` and at least one panel.

```yaml
dashboards:
  - name: "Simple Log Dashboard"
    panels:
      - markdown:
          content: "Welcome to the dashboard!"
        size: {w: 6, h: 3}
```

## Complex Configuration Example

This example showcases a dashboard with various settings, a global query, filters, controls, and multiple panels.

```yaml
dashboards:
  - name: "Comprehensive Application Overview"
    description: "An overview of application performance and logs, with interactive filtering."
    settings:
      margins: true
      titles: true
      sync:
        cursor: true
        tooltips: true
        colors: false # Use distinct color palettes per panel
      controls:
        label_position: "above"
        chain_controls: true
    query:
      kql: "NOT response_code:500" # Global KQL query
    filters:
      - field: "geo.country_iso_code"
        equals: "US"
      - exists: resource.attributes.host.name
    controls:
      - type: options
        label: "Filter by Host"
        data_view: "metrics-*"
        field: "resource.attributes.host.name"
    panels:
      - markdown:
          content: "### Key Performance Indicators"
        size: {w: 12, h: 2}
      - lens:
          type: metric
          primary:
            aggregation: unique_count
            field: resource.attributes.host.name
          data_view: "metrics-*"
        title: "Total Hosts"
        size: {w: 4, h: 4}
        position: {x: 0, y: 2}
      - lens:
          type: bar
          dimension:
            type: values
            field: "resource.attributes.os.type"
          metrics:
            - aggregation: unique_count
              field: resource.attributes.host.name
          data_view: "metrics-*"
        title: "Hosts by OS Type"
        size: {w: 8, h: 4}
        position: {x: 4, y: 2}
```

## Full Configuration Options

### Dashboard Object

The main object defining the dashboard.

| YAML Key | Data Type | Description | Compiler Default | Required |
| ------------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------- | ---------------- | -------- |
| `name` | `string` | The title of the dashboard displayed in Kibana. | N/A | Yes |
| `id` | `string` | An optional unique identifier for the dashboard. If not provided, one will be generated based on the name. | Generated ID | No |
| `description` | `string` | A brief description of the dashboard's purpose or content. | `""` (empty string) | No |
| `minimum_kibana_version` | `string` | Optional minimum Kibana version required by this dashboard. Use this when the dashboard intentionally relies on newer Kibana features such as `TS`-based ES\|QL queries. | `None` | No |
| `time_range` | `TimeRange` object | A default time range to apply when opening the dashboard. See [Time Range](#time-range-time_range). | `None` | No |
| `settings` | `DashboardSettings` object | Global settings for the dashboard. See [Dashboard Settings](#dashboard-settings-settings). | See defaults below | No |
| `query` | `Query` object | A global query (KQL or Lucene) applied to the dashboard. See [Queries Documentation](../queries/config.md). | `None` | No |
| `filters` | `list of Filter objects` | A list of global filters applied to the dashboard. See [Filters Documentation](../filters/config.md). | `[]` (empty list) | No |
| `controls` | `list of Control objects` | A list of control panels for the dashboard. See [Controls Documentation](../controls/config.md). | `[]` (empty list) | No |
| `panels` | `list of Panel objects` | A list of Panel objects defining the content and layout. See [Panels Documentation](../panels/base.md). | `[]` (empty list) | Yes |

### Time Range (`time_range`)

Configure a default time range that will be restored when opening the dashboard. When `time_range` is set, Kibana will automatically apply the specified time range instead of using the global time picker value.

| YAML Key | Data Type | Description | Compiler Default | Required |
| -------- | --------- | ----------- | ------- | -------- |
| `from` | `string` | The start of the time range. Supports relative time expressions like `now-30d/d`, `now-1h`, etc. | N/A | Yes |
| `to` | `string` | The end of the time range. Supports relative time expressions. | `now` | No |

**Example:**

```yaml
dashboards:
  - name: "Last 30 Days Overview"
    time_range:
      from: "now-30d/d"
      to: "now"
    panels:
      - markdown:
          content: "This dashboard defaults to the last 30 days."
        size: {w: 12, h: 3}
```

### Minimum Kibana Version (`minimum_kibana_version`)

Use `minimum_kibana_version` when a dashboard depends on features that are unavailable on older Kibana versions.
For example, `section` panels require Kibana 9.1+, and `TS`-based ES|QL queries require Kibana 9.2+.

**Example:**

```yaml
dashboards:
  - name: "TS-Based Metrics Dashboard"
    minimum_kibana_version: "9.2.0"
    panels:
      - title: "Request Rate"
        esql:
          type: line
          query: |
            TS metrics-*
            | STATS request_rate = SUM(RATE(http.requests))
              BY time_bucket = BUCKET(@timestamp, 20, ?_tstart, ?_tend)
            | SORT time_bucket ASC
          dimension:
            field: "time_bucket"
          metrics:
            - field: "request_rate"
```

**Example with collapsible sections:**

```yaml
dashboards:
  - name: "Operations Overview"
    minimum_kibana_version: "9.1.0"
    panels:
      - title: "Expanded Details"
        section:
          collapsed: true
          panels:
            - title: "CPU Usage"
              size: { w: half, h: 8 }
              lens:
                type: metric
                data_view: "metrics-*"
                primary:
                  aggregation: average
                  field: system.cpu.total.pct
```

### Dashboard Settings (`settings`)

Global settings for the dashboard, configured under the `dashboard.settings` path.

| YAML Key | Data Type | Description | Compiler Default | Required |
| ------------------ | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------- | ---------------- | -------- |
| `margins` | `boolean` | Whether to put space (margins) between panels in the dashboard. | `true` | No |
| `sync` | `DashboardSyncSettings` object | Configures synchronization of cursor, tooltips, and colors across panels. See [Dashboard Sync Settings](#dashboard-sync-settings-settingssync). | See defaults below | No |
| `controls` | `ControlSettings` object | Global settings for controls on the dashboard. See [Controls Documentation](../controls/config.md#control-settings-settingscontrols). | See defaults in Controls docs | No |
| `titles` | `boolean` | Whether to display the titles in the panel headers. | `true` | No |
| `layout_algorithm` | `string` | The auto-layout algorithm for positioning panels without explicit coordinates. Valid values: `up-left`, `left-right`, `blocked`, `first-available-gap`. | `up-left` | No |

### Dashboard Sync Settings (`settings.sync`)

Configure whether cursor, tooltips, and colors should synchronize across panels.

> **Note:** The compiler applies different defaults than Kibana's native defaults. Kibana's native defaults are all `true`, but the compiler intentionally defaults `tooltips` and `colors` to `false` for a cleaner dashboard experience.

| YAML Key | Data Type | Description | Compiler Default | Required |
| ---------- | --------- | ---------------------------------------------------------------------------------------------------------- | ---------------- | -------- |
| `cursor` | `boolean` | Whether to synchronize the cursor across related panels. | `true` | No |
| `tooltips` | `boolean` | Whether to synchronize tooltips across related panels. | `false` | No |
| `colors` | `boolean` | Whether to apply the same color palette to all panels on the dashboard. | `false` | No |

## Methods (for programmatic generation)

While primarily declarative, the underlying Pydantic models for `Dashboard` support methods for adding components if you are generating configurations programmatically (not directly used in YAML):

* `add_filter(filter: FilterTypes)`: Adds a filter to the `filters` list.
* `add_control(control: ControlTypes)`: Adds a control to the `controls` list.
* `add_panel(panel: PanelTypes)`: Adds a panel to the `panels` list.

## Related Documentation

* [Controls Configuration](../controls/config.md)
* [Filters Configuration](../filters/config.md)
* [Queries Configuration](../queries/config.md)
* [Panels Overview](../panels/base.md)


---
# Source: panels/base.md
---

# Base Panel Configuration

All panel types used within a dashboard (e.g., Markdown, Lens charts, Search panels) share a common set of base configuration fields. These fields define fundamental properties like the panel's title, its position and size on the dashboard grid, and an optional description.

When defining a panel in your YAML, you must specify the configuration block for that specific panel type (e.g., `markdown`, `lens`) which serves as the key to identify the panel type.


---

## Minimal Example (Illustrating Base Fields within a Specific Panel Type)

This example shows how base panel fields are used within a `markdown` panel:

```yaml
dashboards:
- name: "Example Dashboard"
  panels:
    - markdown:
        content: "System is **operational**." # MarkdownPanel specific config
      title: "Status Overview"
      description: "A quick look at system status." # BasePanel field
      hide_title: false                             # BasePanel field
      size:                                         # BasePanel field (recommended)
        w: quarter  # or numeric value like 12
        h: 8
      position:                                     # BasePanel field (optional)
        x: 0
        y: 0
```

**Note:** See [Auto-Layout Guide](./auto-layout.md) for details on automatic panel positioning.

## Full Configuration Options

### Base Panel Fields

These fields are available for all panel types and are inherited from the `BasePanel` configuration.

| YAML Key | Data Type | Description | Kibana Default | Required |
| ------------ | --------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------- | -------- |
| `id` | `string` | A unique identifier for the panel. If not provided, one may be generated during compilation. | Generated ID | No |
| `title` | `string` | The title displayed on the panel header. Can be an empty string if you wish for no visible title. | `""` (empty string) | No |
| `hide_title` | `boolean` | If `true`, the panel title (even if defined) will be hidden. | `false` (title is shown) | No |
| `description` | `string` | A brief description of the panel's content or purpose. This is often shown on hover or in panel information. | `""` (empty string, if `None`) | No |
| `size` | `Size` object | Defines the panel's width and height. See [Size Object Configuration](#size-object-configuration-size) below. | `w: 12, h: 8` | No |
| `position` | `Position` object | **Optional:** Defines the panel's x/y coordinates. Omit for automatic positioning. See [Position Object Configuration](#position-object-configuration-position) below. | Auto-calculated | No |
| `drilldowns` | `list[Drilldown]` | **Optional:** List of drilldowns for interactive navigation. See [Drilldowns Configuration](./drilldowns.md). | `None` | No |

**Note on Panel Types**: Each panel must have exactly one key identifying its type (e.g., `markdown`, `lens`, `search`, `links`, `image`, `esql`). This key contains the type-specific configuration.

**Note on Auto-Layout**: For automatic panel positioning without manual coordinate calculation, use the `size` field and omit the `position` field. See the [Auto-Layout Guide](./auto-layout.md) for details.

### Size Object Configuration (`size`)

The `size` object defines the panel's width and height on the dashboard grid. This is the **recommended** approach for new dashboards.

Both shorthand and verbose parameter names are supported for improved readability.

| YAML Key | Verbose Alternative | Data Type | Description | Default | Required |
| -------- | ------------------- | --------- | ------------------------------------------------------------ | ------- | -------- |
| `w` | `width` | `integer` or `SemanticWidth` | The width of the panel. Accepts semantic values (`whole`, `half`, `third`, `quarter`, `sixth`, `eighth`) or numeric values (1-48). | `12` (quarter) | No |
| `h` | `height` | `integer` | The height of the panel in grid units. | `8` | No |

**Semantic Width Values:**

| Value | Grid Units | Description |
| ----- | ---------- | ----------- |
| `whole` | 48 | Full dashboard width |
| `half` | 24 | Half width |
| `third` | 16 | One-third width |
| `quarter` | 12 | Quarter width |
| `sixth` | 8 | One-sixth width |
| `eighth` | 6 | One-eighth width |

**Example:**

```yaml
size:
  w: quarter  # Semantic value
  h: 8

# Or with numeric value:
size:
  width: 24   # Numeric value
  height: 12
```

### Position Object Configuration (`position`)

The `position` object defines the panel's x/y coordinates on the dashboard grid. This field is **optional** - when omitted, the panel will be automatically positioned using the dashboard's layout algorithm.

| YAML Key | Verbose Alternative | Data Type | Description | Default | Required |
| -------- | ------------------- | --------- | ------------------------------------------------------------ | ------- | -------- |
| `x` | `from_left` | `integer` or `None` | The horizontal starting position (0-based, 0-48). If `None`, position is auto-calculated. | `None` | No |
| `y` | `from_top` | `integer` or `None` | The vertical starting position (0-based). If `None`, position is auto-calculated. | `None` | No |

**Example with fixed position:**

```yaml
position:
  x: 0
  y: 0

# Or verbose:
position:
  from_left: 24
  from_top: 10
```

**Example with auto-positioning (omit position entirely):**

```yaml
# No position field - will be auto-positioned
size:
  w: quarter
  h: 8
```

## Panel Types (Specific Configurations)

The `BasePanel` fields are common to all panel types. For details on the specific configuration fields available for each panel `type`, refer to their individual documentation pages:

* [Markdown Panel](./markdown.md)
* [Links Panel](./links.md)
* [Search Panel](./search.md)
* [Image Panel](./image.md)
* [Section Panel](./section.md) (collapsible sections)
* [XY Chart Panel](./xy.md)
* [Pie Chart Panel](./pie.md)
* [Metric Panel](./metric.md)
* [Tagcloud Panel](./tagcloud.md)
* [Lens Panel](./lens.md)
* [ESQL Panel](./esql.md)

## Color Mapping Configuration

> **Quick Reference**: Want to customize chart colors? See [Color Mapping Examples](#color-mapping-examples) below for palette selection, or the [Custom Color Assignments](../guides/color-assignments.md) guide for manual color assignments.

Many chart panel types (Pie, XY, Metric) support color customization through the `color` field. You can select from built-in color palettes or manually assign specific colors to data values.

### ColorValueMapping Object

**kb_dashboard_core.panels.charts.base.config.ColorValueMapping**

Categorical color mapping for charts keyed by exact values.

Fields:
- `palette` (`<class 'str'>`): The palette ID to use for unassigned colors.

Available palettes:
- 'default' - Standard EUI palette
- 'eui_amsterdam_color_blind' - Color-blind safe palette (default)
- 'kibana_palette' or 'legacy' - Legacy Kibana colors
- 'elastic_brand' - Elastic brand colors
- 'gray' - Grayscale palette
- `assignments` (`list[kb_dashboard_core.panels.charts.base.config.ColorValueAssignment]`): Manual color assignments to specific data values.


---
# Source: panels/auto-layout.md
---

# Auto-Layout Guide

This guide explains how to use the automatic panel layout system to position panels on your dashboard without manually specifying coordinates.

## Overview

Instead of manually calculating x and y coordinates for every panel, you can use auto-layout to automatically position panels on the dashboard grid. Auto-layout works by:

1. Defining panel **size** (width and height) without position
2. Choosing a **layout algorithm** to determine how panels are arranged
3. Letting the compiler calculate optimal positions for all panels

## Quick Start

### Basic Auto-Layout Example

```yaml
dashboards:
  - name: "Auto-Layout Dashboard"
    settings:
      layout_algorithm: up-left  # Optional, defaults to 'up-left'
    panels:
      # Panel 1: Quarter-width panel (12 units wide)
      - markdown:
          content: "First panel"
        title: "Panel 1"
        size:
          w: quarter  # Semantic width - 12 units
          h: 8        # Height in grid units
        # No position specified - will be auto-positioned

      # Panel 2: Another quarter-width panel
      - markdown:
          content: "Second panel"
        title: "Panel 2"
        size:
          w: quarter
          h: 8

      # Panel 3: Half-width panel
      - markdown:
          content: "Third panel"
        title: "Panel 3"
        size:
          w: half  # Semantic width - 24 units
          h: 8
```

This creates a dashboard where panels are automatically arranged in a 2x2 grid pattern.

## Panel Size Configuration

### The `size` Field

Instead of specifying a `grid` object with x, y, w, h coordinates, you can use separate `size` and `position` fields:

```yaml
panels:
  - markdown:
      content: "My content"
    title: "My Panel"
    size:
      w: 24     # Width (or use semantic values)
      h: 8      # Height
    position:   # Optional - omit for auto-layout
      x: 0
      y: 0
```

### Semantic Width Values

The `w` (width) field accepts semantic values for common panel widths:

| Semantic Value | Grid Units | Description |
| -------------- | ---------- | ----------- |
| `whole` | 48 | Full dashboard width |
| `half` | 24 | Half width (2 panels per row) |
| `third` | 16 | One-third width (3 panels per row) |
| `quarter` | 12 | Quarter width (4 panels per row) |
| `sixth` | 8 | One-sixth width (6 panels per row) |
| `eighth` | 6 | One-eighth width (8 panels per row) |

You can also specify numeric values from 1 to 48.

### Default Size

If you omit the `size` field entirely, panels default to:

- Width: 12 units (quarter width)
- Height: 8 units

```yaml
panels:
  - markdown:
      content: "Uses default size"
    title: "Default Panel"
    # No size specified - uses w=12, h=8
```

## Layout Algorithms

The `layout_algorithm` setting in dashboard `settings` controls how panels are automatically positioned. Choose the algorithm that best fits your dashboard's content flow.

### `up-left` (Default)

Floats panels up first, then left. Creates compact, grid-like layouts.

**Best for:** Dashboards where you want panels to form neat grids.

```yaml
dashboards:
  - name: "Up-Left Example"
    settings:
      layout_algorithm: up-left
    panels:
      - markdown: { content: "A" }
        title: "Panel A"
        size: { w: quarter, h: 8 }

      - markdown: { content: "B" }
        title: "Panel B"
        size: { w: quarter, h: 8 }

      - markdown: { content: "C" }
        title: "Panel C"
        size: { w: quarter, h: 8 }

      - markdown: { content: "D" }
        title: "Panel D"
        size: { w: quarter, h: 8 }
```

**Result:** Forms a 2x2 grid with panels arranged like:

```text
[A][B]
[C][D]
```

### `left-right`

Fills rows from left to right before moving to the next row. Row height is determined by the tallest panel in that row.

**Best for:** Dashboards where you want panels to appear in reading order (left-to-right, top-to-bottom).

```yaml
dashboards:
  - name: "Left-Right Example"
    settings:
      layout_algorithm: left-right
    panels:
      - markdown: { content: "A" }
        size: { w: half, h: 8 }

      - markdown: { content: "B" }
        size: { w: half, h: 12 }  # Taller panel

      - markdown: { content: "C" }
        size: { w: third, h: 8 }

      - markdown: { content: "D" }
        size: { w: third, h: 8 }
```

**Result:**

```text
Row 1: [A (h=8)][B (h=12)]  <- Row height = 12
Row 2: [C (h=8)][D (h=8)]   <- Row height = 8
```

### `blocked`

Never fills gaps above the current bottom. Maintains strict top-to-bottom flow.

**Best for:** Dashboards where vertical ordering matters more than space efficiency.

```yaml
dashboards:
  - name: "Blocked Example"
    settings:
      layout_algorithm: blocked
    panels:
      - markdown: { content: "Tall panel" }
        size: { w: half, h: 20 }
        position: { x: 0, y: 0 }  # Locked position

      - markdown: { content: "Auto panel 1" }
        size: { w: half, h: 8 }
        # Will go to x=24, y=0 (right of tall panel)

      - markdown: { content: "Auto panel 2" }
        size: { w: half, h: 8 }
        # Will go to y=20 (below the tall panel, not filling the gap)
```

### `first-available-gap`

Scans the entire grid from top-left to find the first available gap. Maximizes space utilization.

**Best for:** Dashboards where minimizing vertical height is important.

```yaml
dashboards:
  - name: "First Available Gap Example"
    settings:
      layout_algorithm: first-available-gap
    panels:
      - markdown: { content: "Tall panel" }
        size: { w: half, h: 20 }
        position: { x: 0, y: 0 }

      - markdown: { content: "Small panel 1" }
        size: { w: half, h: 8 }
        # Will fill the gap at x=24, y=0

      - markdown: { content: "Small panel 2" }
        size: { w: half, h: 8 }
        # Will fill the gap at x=24, y=8
```

## Mixing Auto-Layout and Fixed Positions

You can mix panels with auto-layout and panels with fixed positions (called "locked panels"):

```yaml
dashboards:
  - name: "Mixed Layout"
    panels:
      # Locked panel - fixed position
      - markdown:
          content: "This stays at the top"
        title: "Header"
        size: { w: whole, h: 4 }
        position: { x: 0, y: 0 }

      # Auto-positioned panels will flow around the locked panel
      - markdown:
          content: "Auto panel 1"
        title: "Panel 1"
        size: { w: half, h: 8 }
        # No position - will be auto-positioned below the header

      - markdown:
          content: "Auto panel 2"
        title: "Panel 2"
        size: { w: half, h: 8 }
```

The auto-layout algorithm respects locked panels and positions auto panels around them.

## Field Aliases

Both `size` and `position` support verbose aliases for readability:

```yaml
size:
  width: 24   # Same as 'w'
  height: 12  # Same as 'h'

position:
  from_left: 0  # Same as 'x'
  from_top: 10  # Same as 'y'
```

## Common Patterns

### Full-Width Header with Grid Below

```yaml
panels:
  # Header
  - markdown: { content: "Dashboard Title" }
    title: "Header"
    size: { w: whole, h: 4 }

  # Grid of metrics (will auto-arrange in 2x2 grid)
  - lens: { type: metric, ... }
    size: { w: quarter }

  - lens: { type: metric, ... }
    size: { w: quarter }

  - lens: { type: metric, ... }
    size: { w: quarter }

  - lens: { type: metric, ... }
    size: { w: quarter }
```

### Two-Column Layout

```yaml
settings:
  layout_algorithm: left-right

panels:
  - markdown: { content: "Left column content" }
    size: { w: half, h: 20 }

  - markdown: { content: "Right column content" }
    size: { w: half, h: 20 }

  # These will form the second row
  - markdown: { content: "Bottom left" }
    size: { w: half, h: 10 }

  - markdown: { content: "Bottom right" }
    size: { w: half, h: 10 }
```

### Dashboard with Sidebar

```yaml
panels:
  # Fixed sidebar
  - links: { ... }
    title: "Navigation"
    size: { w: eighth, h: 40 }
    position: { x: 0, y: 0 }  # Lock to left side

  # Main content area (auto-positioned to the right)
  - lens: { type: xy, ... }
    title: "Main Chart"
    size: { w: 42, h: 20 }  # 48 - 6 = 42 remaining width

  - lens: { type: metric, ... }
    size: { w: 42, h: 20 }
```

## Related Documentation

- [Base Panel Configuration](./base.md) - Common panel fields
- [Dashboard Configuration](../dashboard/dashboard.md) - Dashboard settings


---
# Source: panels/drilldowns.md
---

# Drilldowns Configuration

Drilldowns enable interactive navigation from dashboard panels. When users click on chart elements, they can either navigate to another dashboard or open an external URL with context from the clicked element.


---

## Overview

Drilldowns can be added to any Lens or ESQL panel by specifying the `drilldowns` field in the panel configuration. There are two types of drilldowns:

| Type | Description | Use Case |
| ---- | ----------- | -------- |
| **Dashboard Drilldown** | Navigate to another Kibana dashboard | Deep-dive analysis, related dashboards |
| **URL Drilldown** | Open an external URL | Documentation, external systems, tickets |

## Quick Example

```yaml
panels:
  - title: Events by Status
    size: { w: half, h: 12 }
    lens:
      type: bar
      data_view: logs-*
      dimension:
        type: values
        field: http.response.status_code
        id: status
      metrics:
        - aggregation: count
          id: count
    drilldowns:
      # Navigate to another dashboard
      - name: View Status Details
        dashboard: status-details-dashboard
        with_filters: true
        with_time: true
      # Open external documentation
      - name: HTTP Status Reference
        url: "https://httpstatuses.com/{{event.value}}"
        new_tab: true
```

## Drilldown Types

### Dashboard Drilldown

**kb_dashboard_core.panels.drilldowns.config.DashboardDrilldown**

Dashboard-to-dashboard drilldown configuration.

Fields:
- `id` (`str | None`): Optional unique identifier for the drilldown. If not provided, one will be generated.
- `name` (`<class 'str'>`): Display name for the drilldown.
- `triggers` (`list[Annotated[kb_dashboard_core.panels.drilldowns.config.DrilldownTrigger, FieldInfo(annotation=NoneType, required=True, metadata=[Strict(strict=False)])]]`): List of triggers that activate this drilldown. Defaults to ['click'].
- `dashboard` (`<class 'str'>`): Target dashboard ID or friendly identifier.
- `with_filters` (`<class 'bool'>`): Whether to carry over current filters to the target dashboard. Defaults to True.
- `with_time` (`<class 'bool'>`): Whether to carry over current time range to the target dashboard. Defaults to True.


---
# Source: panels/links.md
---

# Links Panel Configuration

The `links` panel type is used to display a collection of hyperlinks on your dashboard. These links can point to other Kibana dashboards or external web URLs. This panel is useful for creating navigation hubs or providing quick access to related resources.


---

## Links Panel

**kb_dashboard_core.panels.links.config.LinksPanel**

Represents a Links panel configuration.

Links panels are used to display a collection of links to other dashboards,
saved objects, or external URLs.

Examples:
    Linking to another Dashboard:
    ```yaml
    dashboards:
      - name: "Main Overview"
        panels:
          - title: "Navigate to User Details"
            size: { w: 24, h: 2 }
            links:
              items:
                - label: "View User Activity Dashboard"
                  dashboard: "user-activity-dashboard-id"
    ```

    Linking to an External URL:
    ```yaml
    dashboards:
      - name: "Main Overview"
        panels:
          - title: "External Resources"
            size: { w: 24, h: 2 }
            links:
              items:
                - label: "Project Documentation"
                  url: "https://docs.example.com/project-alpha"
                  new_tab: true
    ```

    Complex configuration with multiple link types:
    ```yaml
    dashboards:
      - name: "Operations Hub"
        panels:
          - title: "Quick Access"
            size: { w: 48, h: 3 }
            links:
              layout: "vertical"
              items:
              - label: "Service Health Dashboard"
                dashboard: "service-health-monitor-v2"
              - label: "Runbook Wiki"
                url: "https://internal.wiki/ops/runbooks"
                new_tab: true
    ```

Fields:
- `id` (`str | None`): A unique identifier for the panel. If not provided, one may be generated during compilation.
- `title` (`<class 'str'>`): The title displayed on the panel header. Can be an empty string.
- `hide_title` (`bool | None`): If `true`, the panel title will be hidden. Defaults to `false` (title is shown).
- `description` (`str | None`): A brief description of the panel's content or purpose. Defaults to an empty string.
- `size` (`<class 'kb_dashboard_core.panels.config.Size'>`): Defines the panel's size on the dashboard grid.
- `position` (`<class 'kb_dashboard_core.panels.config.Position'>`): Defines the panel's position on the dashboard grid. If not specified, position will be auto-calculated.
- `drilldowns` (`list[DrilldownTypes] | None`): Optional list of drilldowns to attach to this panel.
- `links_config` (`<class 'kb_dashboard_core.panels.links.config.LinksPanelConfig'>`): Links panel configuration.


---
# Source: panels/markdown.md
---

# Markdown Panel Configuration

The `markdown` panel type is used to display rich text content, formatted using Markdown syntax, directly on your dashboard. This is equivalent to the "Text" visualization in Kibana.


---

## Markdown Panel

**kb_dashboard_core.panels.markdown.config.MarkdownPanel**

Represents a Markdown panel configuration.

Markdown panels are used to display rich text content using Markdown syntax.

Examples:
    Minimal Markdown panel:
    ```yaml
    dashboards:
      - name: "Dashboard with Markdown"
        panels:
          - title: "Welcome Note"
            size: { w: 48, h: 3 }
            markdown:
              content: |
                ## Welcome to the Dashboard!
                This panel provides an overview of the key metrics and reports available.

                - Item 1
                - Item 2
    ```

    Markdown panel with custom font size:
    ```yaml
    dashboards:
      - name: "Informational Dashboard"
        panels:
          - title: "Important Instructions"
            size: { w: 32, h: 5 }
            markdown:
              content: |
                # Setup Guide

                Please follow the [official documentation](https://strawgate.github.io/kb-yaml-to-lens/) for setup instructions.

                Key steps:
                1. **Download** the installer.
                2. **Configure** the `config.yaml` file.
                3. **Run** the start script.
              font_size: 14
    ```

Fields:
- `id` (`str | None`): A unique identifier for the panel. If not provided, one may be generated during compilation.
- `title` (`<class 'str'>`): The title displayed on the panel header. Can be an empty string.
- `hide_title` (`bool | None`): If `true`, the panel title will be hidden. Defaults to `false` (title is shown).
- `description` (`str | None`): A brief description of the panel's content or purpose. Defaults to an empty string.
- `size` (`<class 'kb_dashboard_core.panels.config.Size'>`): Defines the panel's size on the dashboard grid.
- `position` (`<class 'kb_dashboard_core.panels.config.Position'>`): Defines the panel's position on the dashboard grid. If not specified, position will be auto-calculated.
- `drilldowns` (`list[DrilldownTypes] | None`): Optional list of drilldowns to attach to this panel.
- `markdown` (`<class 'kb_dashboard_core.panels.markdown.config.MarkdownPanelConfig'>`): Markdown panel configuration.


---
# Source: panels/section.md
---

# Section Panel Configuration

The `section` panel type creates a collapsible section that groups panels under a named, expandable header. This is useful for organizing complex dashboards by allowing users to collapse groups of related panels to focus on specific areas.

> **Requires Kibana 9.1+.** Collapsible sections are not supported on Kibana 8.x. Dashboards containing `section:` panels will fail to import on older versions.


---

## Collapsible Panel

**kb_dashboard_core.panels.collapsible.CollapsiblePanel**

A collapsible section that groups panels under a named, expandable header.

In the outer dashboard grid, a collapsible panel occupies a single full-width row
(the section header). Its inner panels are laid out in a separate coordinate space
relative to the section.

Examples:
    ```yaml
    dashboards:
      - name: "Dashboard with Sections"
        panels:
          - title: "Overview"
            size: { w: 48, h: 6 }
            markdown:
              content: "# Overview"
          - title: "Details"
            section:
              collapsed: true
              panels:
                - title: "CPU Usage"
                  size: { w: 48, h: 12 }
                  markdown:
                    content: "# CPU"
    ```

Fields:
- `id` (`str | None`): A unique identifier for the panel. If not provided, one may be generated during compilation.
- `title` (`<class 'str'>`): The title displayed on the panel header. Can be an empty string.
- `hide_title` (`bool | None`): If `true`, the panel title will be hidden. Defaults to `false` (title is shown).
- `description` (`str | None`): A brief description of the panel's content or purpose. Defaults to an empty string.
- `size` (`<class 'kb_dashboard_core.panels.config.Size'>`): Section header size. Defaults to full width (48) and 1 row tall.
- `position` (`<class 'kb_dashboard_core.panels.config.Position'>`): Defines the panel's position on the dashboard grid. If not specified, position will be auto-calculated.
- `drilldowns` (`list[DrilldownTypes] | None`): Optional list of drilldowns to attach to this panel.
- `section` (`<class 'kb_dashboard_core.panels.collapsible.SectionConfig'>`): Section configuration including collapsed state and inner panels.


---
# Source: panels/lens.md
---

# Lens Panel Configuration

Lens panels in Kibana provide a flexible and user-friendly way to create various types of visualizations, such as metric displays, pie charts, bar charts, line charts, and more. This document covers the YAML configuration for Lens panels using this compiler.

The `LensPanel` is the primary container. Its `lens` field contains the specific visualization configuration (for example `metric`, `pie`, `line`, or `datatable`).


---

## Minimal Configuration Examples

**Minimal Lens Metric Chart:**

```yaml
dashboards:
  - name: "Key Metrics Dashboard"
    panels:
      - title: "Total Users"
        size: {w: 16, h: 3}
        lens:
          type: metric # Specifies a LensMetricChart
          data_view: "logs-*"
          query: # Optional panel-specific query
            kql: "event.dataset:website.visits"
          primary:
            aggregation: "unique_count"
            field: "user.id"
            label: "Unique Visitors"
```

**Minimal Lens Pie Chart:**

```yaml
dashboards:
  - name: "Traffic Analysis"
    panels:
      - title: "Traffic by Source"
        size: {w: 32, h: 3}
        position: {x: 16, y: 0}
        lens:
          type: pie # Specifies a LensPieChart
          data_view: "weblogs-*"
          metrics:
            - aggregation: "count"
              label: "Sessions"
          breakdowns:
            - type: values
              field: "source.medium"
              label: "Traffic Source"
              size: 5 # Top 5 sources
```

## Full Configuration Options

### Lens Panel (panel with a `lens:` field)

This is the main object for a Lens-based visualization. It inherits from the [Base Panel Configuration](base.md).

| 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](base.md#size-object-configuration-size). | `w: 12, h: 8` | No |
| `position` | `Position` object | Defines the panel's x/y coordinates. Inherited from BasePanel. See [Position Object Configuration](base.md#position-object-configuration-position). | Auto-calculated | No |
| `query` | `LegacyQueryTypes` object (KQL or Lucene) | A panel-specific query to filter data for this Lens visualization. See [Queries Documentation](../queries/config.md). | `None` (uses dashboard query) | No |
| `filters` | `list of FilterTypes` | A list of panel-specific filters. See [Filters Documentation](../filters/config.md). | `[]` (empty list) | No |
| `lens` | `LensPanelConfig` object | Defines the actual Lens visualization configuration. This includes the inner `type` plus chart-specific fields. | N/A | Yes |

**Note**: For XY charts (line, bar, area), a `layers` field is available to add reference lines and additional data layers. See the [XY Chart Panel Configuration](xy.md#reference-lines) documentation for details.

---

## Lens Metric Chart (`lens.type: metric`)

Displays a single primary metric, optionally with a secondary metric, a maximum value, and a breakdown dimension.

| YAML Key | Data Type | Description | Kibana Default | Required |
| ----------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------- | ---------------- | -------- |
| `type` | `Literal['metric']` | Specifies the chart type as a Lens Metric visualization. | `metric` | Yes |
| `id` | `string` | An optional unique identifier for this specific chart layer. | Generated ID | No |
| `primary` | `LensMetricTypes` object | The primary metric to display. This is the main value shown. See [Lens Metrics](#lens-metrics-primary-secondary-maximum-for-metric-metrics-for-pie). | N/A | Yes |
| `secondary` | `LensMetricTypes` object | An optional secondary metric to display alongside the primary. See [Lens Metrics](#lens-metrics-primary-secondary-maximum-for-metric-metrics-for-pie). | `None` | No |
| `maximum` | `LensMetricTypes` object | An optional maximum metric, used for progress bar scale or context. See [Lens Metrics](#lens-metrics-primary-secondary-maximum-for-metric-metrics-for-pie). | `None` | No |
| `breakdown` | `LensDimensionTypes` object | An optional dimension to break down the metric by (e.g., showing primary metric per country). See [Lens Dimensions](#lens-dimensions-breakdown-for-metric-breakdowns-for-pie). | `None` | No |
| `appearance` | `MetricAppearance` object | Visual appearance configuration. See [Metric Appearance](#metric-appearance). | `None` | No |
| `titles_and_text` | `MetricTitlesAndText` object | Titles and text formatting options. See [Metric Titles and Text](#metric-titles-and-text). | `None` | No |

### Metric Appearance

| YAML Key | Data Type | Description | Kibana Default | Required |
| ----------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------- | ---------------- | -------- |
| `primary.icon` | `string` | Icon identifier to display alongside the primary metric value. | `None` | No |
| `primary.icon_position` | `Literal['left', 'right']` | Horizontal alignment of the icon. | `None` | No |
| `primary.background_chart.type` | `Literal['line', 'bar', 'none']` | Background chart mode for the primary metric. | `None` | No |
| `primary.background_chart.direction` | `Literal['horizontal', 'vertical']` | Direction for bar background charts (`type: bar`). | `None` | No |
| `primary.font_size` | `Literal['default', 'fit', 'custom']` | Font size mode for the primary metric value. | `None` | No |
| `primary.position` | `Literal['top', 'bottom']` | Vertical position of the primary metric value. | `None` | No |
| `primary.alignment` | `Literal['left', 'center', 'right']` | Text alignment for the primary metric value. | `None` | No |
| `secondary.alignment` | `Literal['left', 'center', 'right']` | Text alignment for the secondary metric value. | `None` | No |
| `secondary.label.text` | `string` | Custom label for the secondary metric. | `None` | No |
| `secondary.label.position` | `Literal['before', 'after']` | Position for the secondary label. | `None` | No |
| `breakdown.column_count` | `int` | Maximum breakdown columns (minimum `1`). | `None` | No |

### Metric Titles and Text

| YAML Key | Data Type | Description | Kibana Default | Required |
| ----------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------- | ---------------- | -------- |
| `subtitle` | `string` | Custom subtitle text displayed below the metric title. | `None` | No |
| `alignment` | `Literal['left', 'center', 'right']` | Text alignment for the metric title and subtitle. | `None` | No |
| `weight` | `Literal['bold', 'normal', 'lighter']` | Font weight for the metric title. | `None` | No |

**Example (Lens Metric Chart with Styling):**

```yaml
dashboards:
  - name: "Lens Metric Example"
    description: "Example of Lens metric panel with primary, secondary, and breakdown"
    panels:
      - title: "Data Transfer Metrics"
        size: {w: 24, h: 15}
        lens:
          type: metric
          data_view: "logs-*"
          primary:
            aggregation: "sum"
            field: "bytes_transferred"
            label: "Total Data"
            format: { type: "bytes" }
          secondary:
            aggregation: "average"
            field: "response_time_ms"
            label: "Avg Response"
            format: { type: "duration", suffix: " ms" }
          breakdown:
            type: values
            field: "host.name"
            size: 3
            label: "Top Hosts"
          appearance:
            primary:
              background_chart:
                type: bar
                direction: horizontal
              icon: sortUp
              icon_position: right
          titles_and_text:
            subtitle: "Last 24 hours"
            alignment: center
            weight: bold
```

---

## Lens Pie Chart (`lens.type: pie`)

Visualizes proportions of categories using slices of a pie or a donut chart.

| YAML Key | Data Type | Description | Kibana Default | Required |
| ----------------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------- | ---------------- | -------- |
| `type` | `Literal['pie']` | Specifies the chart type as a Lens Pie visualization. | `pie` | Yes |
| `id` | `string` | An optional unique identifier for this specific chart layer. | Generated ID | No |
| `data_view` | `string` | The ID or title of the data view (index pattern) for this pie chart. | N/A | Yes |
| `metrics` | `LensMetricTypes \| list[LensMetricTypes]` object | A single metric or list of metrics that determine the size of each slice. See [Lens Metrics](#lens-metrics-primary-secondary-maximum-for-metric-metrics-for-pie). | N/A | Yes |
| `breakdowns` | `list of LensBreakdownTypes` objects | One or more breakdowns that determine how the pie is sliced. See [Lens Dimensions](#lens-dimensions-breakdown-for-metric-breakdowns-for-pie). | N/A | Yes |
| `appearance` | `PieChartAppearance` object | Formatting options for the chart appearance. See [Pie Chart Appearance](#pie-chart-appearance-appearance-field). | `None` | No |
| `legend` | `PieLegend` object | Formatting options for the chart legend. See [Pie Legend](#pie-legend-legend-field). | `None` | No |
| `color` | `ColorValueMapping` object | Formatting options for the chart color palette. See [Color Mapping](#color-mapping-color-field). | `None` | No |

**Example (Lens Pie Chart):**

```yaml
dashboards:
  - name: "Lens Pie Chart Example"
    description: "Example of Lens pie chart with appearance and legend options"
    panels:
      - title: "Disk Operations by Device"
        size: {w: 24, h: 15}
        lens:
          type: pie
          data_view: "metrics-*"
          metrics:
            - aggregation: "average"
              field: "metrics.system.disk.operations"
              label: "Avg Disk Operations"
          breakdowns:
            - type: values
              field: "resource.attributes.device"
              size: 5
              label: "Device"
          appearance:
            donut: "medium"
            categories:
              position: "inside"
            values:
              format: "percent"
          legend:
            visible: "show"
            width: "large"
```

---

## Lens Dimensions (`breakdown` for Metric, `breakdowns` for Pie)

Dimensions define how data is grouped or bucketed in Lens visualizations.

### Common Dimension Fields (`BaseLensDimension`)

All specific dimension types below can include:

| YAML Key | Data Type | Description | Kibana Default | Required |
| -------- | --------- | ---------------------------------------------------------------------------------------------------------- | ---------------- | -------- |
| `id` | `string` | An optional unique identifier for the dimension. | Generated ID | No |
| `label` | `string` | A custom display label for the dimension. If not provided, a label is inferred. | Inferred | No |

When these shapes are used in chart fields that accept `LensBreakdownTypes` instead of `LensDimensionTypes` (for example pie `breakdowns` or other breakdown-specific configs), the breakdown variant may also allow `collapse`. Plain XY `dimension` / `breakdown` axes do not support `collapse`.

### Top Values Dimension (`type: values`)

Groups data by the most frequent unique values of one or more fields. Supports both single-field and multi-field (multi-term) aggregations.

| YAML Key | Data Type | Description | Kibana Default | Required |
| ------------------ | ----------------- | ---------------------------------------------------------------------------------------------------------- | ---------------- | -------- |
| `type` | `Literal['values']` | Specifies the dimension type. | N/A | Yes |
| `field` | `string` | Single field to get top values from. Mutually exclusive with `fields`. | N/A | One of `field` or `fields` |
| `fields` | `list of strings` | Multiple fields for multi-term aggregation (minimum 2 fields). Mutually exclusive with `field`. | N/A | One of `field` or `fields` |
| `size` | `integer` | The number of top values to display. | `3` | No |
| `sort` | `Sort` object | How to sort the terms. `by` can be a metric label or `_term` (alphabetical). `direction` is `asc` or `desc`. | Sort by metric, `desc` | No |
| `show_other_bucket` | `boolean` | If `true`, groups remaining values into an "Other" bucket. | `true` | No |
| `include_missing_values` | `boolean` | If `true`, creates a bucket for documents where the field is missing. | `false` | No |
| `include` | `list of strings` | A list of specific terms to include. When `include_is_regex` is `true`, must contain exactly one entry. | `None` | No |
| `exclude` | `list of strings` | A list of specific terms to exclude. When `exclude_is_regex` is `true`, must contain exactly one entry. | `None` | No |
| `include_is_regex` | `boolean` | If `true`, treats the single `include` value as a regex pattern. `include` must contain exactly one entry. | `false` | No |
| `exclude_is_regex` | `boolean` | If `true`, treats the single `exclude` value as a regex pattern. `exclude` must contain exactly one entry. | `false` | No |

**Example - Single Field:**

```yaml
breakdowns:
  - type: values
    field: agent.name
    size: 5
```

**Example - Multi-Field:**

```yaml
breakdowns:
  - type: values
    fields:
      - agent.name
      - agent.type
    size: 10
    label: "Agent Name + Type"
```

**Example - Regex Include/Exclude:**

```yaml
breakdowns:
  - type: values
    field: log.level
    include:
      - "^err(or)?$"
    include_is_regex: true
    exclude:
      - "^debug$"
    exclude_is_regex: true
```

### Date Histogram Dimension (`type: date_histogram`)

Groups data into time-based buckets (e.g., per hour, day).

| YAML Key | Data Type | Description | Kibana Default | Required |
| ------------------- | ------------------------------- | ---------------------------------------------------------------------------------------------------------- | ---------------- | -------- |
| `type` | `Literal['date_histogram']` | Specifies the dimension type. | N/A | Yes |
| `field` | `string` | The date field to use for the histogram. | N/A | Yes |
| `minimum_interval` | `string` | The time interval (e.g., `auto`, `1h`, `1d`, `1w`). | `auto` | No |
| `partial_intervals` | `boolean` | If `true`, includes buckets for time periods that are only partially covered by the data. | `true` | No |

### Filters Dimension (`type: filters`)

Creates buckets based on a list of custom KQL/Lucene queries.

| YAML Key | Data Type | Description | Kibana Default | Required |
| --------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------- | ---------------- | -------- |
| `type` | `Literal['filters']` | Specifies the dimension type. | N/A | Yes |
| `filters` | `list of LensFiltersDimensionFilter` objects | A list of filter definitions. Each filter object has `query` (KQL/Lucene) and an optional `label`. | N/A | Yes |

**`LensFiltersDimensionFilter` Object:**

| YAML Key | Data Type | Description | Kibana Default | Required |
| -------- | ------------------------- | ------------------------------------------------ | ---------------- | -------- |
| `query` | `LegacyQueryTypes` object | The KQL or Lucene query for this filter bucket. | N/A | Yes |
| `label` | `string` | A display label for this filter bucket. | Query string | No |

### Intervals Dimension (`type: intervals`)

Groups data into numeric ranges (buckets).

| YAML Key | Data Type | Description | Kibana Default | Required |
| ------------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------- | ---------------- | -------- |
| `type` | `Literal['intervals']` | Specifies the dimension type. | N/A | Yes |
| `field` | `string` | The numeric field to create intervals from. | N/A | Yes |
| `intervals` | `list of LensIntervalsDimensionInterval` objects | A list of custom interval ranges. If not provided, `granularity` is used. | `None` | No |
| `granularity` | `integer` (1-7) | Divides the field into evenly spaced intervals. 1 is coarsest, 7 is finest. | `4` | No |
| `include_empty_intervals` | `boolean` | If `true`, shows a bucket for documents with missing values for the field. | `false` | No |

**`LensIntervalsDimensionInterval` Object:**

| YAML Key | Data Type | Description | Kibana Default | Required |
| -------- | --------- | ------------------------------------------------ | ---------------- | -------- |
| `from` | `integer` | The start of the interval (inclusive). | `None` | No |
| `to` | `integer` | The end of the interval (exclusive). | `None` | No |
| `label` | `string` | A display label for this interval bucket. | Auto-generated | No |

---

## Lens Metrics (`primary`, `secondary`, `maximum` for Metric; `metrics` for Pie)

Metrics define the calculations performed on your data (e.g., count, sum, average).

### Common Metric Fields (`BaseLensMetric`)

All specific metric types below can include:

| YAML Key | Data Type | Description | Kibana Default | Required |
| -------- | ------------------------- | ---------------------------------------------------------------------------------------------------------- | ---------------- | -------- |
| `id` | `string` | An optional unique identifier for the metric. | Generated ID | No |
| `label` | `string` | A custom display label for the metric. If not provided, a label is inferred. | Inferred | No |
| `format` | `LensMetricFormatTypes` object | How to format the metric's value (e.g., number, bytes, percent). See [Metric Formatting](#metric-formatting-format-field-within-a-metric). | Default for type | No |
| `filter` | `LegacyQueryTypes` object | A KQL or Lucene query to filter data _before_ this metric is calculated. | `None` | No |

### Aggregated Metric Types

These metrics perform an aggregation on a field.

**Count / Unique Count (`aggregation: count` or `aggregation: unique_count`)**

| YAML Key | Data Type | Description | Kibana Default | Required |
| --------------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------- | ---------------- | -------- |
| `aggregation` | `Literal['count', 'unique_count']` | Type of count. | N/A | Yes |
| `field` | `string` | For `unique_count`, the field whose unique values are counted. For `count`, optional (counts all documents if `None`). | `None` for `count` | No (Yes for `unique_count`) |
| `exclude_zeros` | `boolean` | If `true`, zero values are excluded from the aggregation. | `true` | No |

**Sum (`aggregation: sum`)**

| YAML Key | Data Type | Description | Kibana Default | Required |
| --------------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------- | ---------------- | -------- |
| `aggregation` | `Literal['sum']` | Specifies sum aggregation. | `sum` | Yes |
| `field` | `string` | The numeric field to sum. | N/A | Yes |
| `exclude_zeros` | `boolean` | If `true`, zero values are excluded from the sum. | `true` | No |

**Min, Max, Average, Median (`aggregation: min` / `max` / `average` / `median`)**

| YAML Key | Data Type | Description | Kibana Default | Required |
| ------------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------- | ---------------- | -------- |
| `aggregation` | `Literal['min', 'max', 'average', 'median']` | The aggregation type. | N/A | Yes |
| `field` | `string` | The numeric field for the aggregation. | N/A | Yes |

**Last Value (`aggregation: last_value`)**

| YAML Key | Data Type | Description | Kibana Default | Required |
| ------------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------- | ---------------- | -------- |
| `aggregation` | `Literal['last_value']` | Retrieves the most recent value of a field. | `last_value` | Yes |
| `field` | `string` | The field whose last value is retrieved. | N/A | Yes |
| `date_field` | `string` | The date field used to determine the "last" value. | `@timestamp` | No |

**Percentile (`aggregation: percentile`)**

| YAML Key | Data Type | Description | Kibana Default | Required |
| ------------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------- | ---------------- | -------- |
| `aggregation` | `Literal['percentile']` | Calculates the value at a specific percentile. | `percentile` | Yes |
| `field` | `string` | The numeric field for percentile calculation. | N/A | Yes |
| `percentile` | `integer` | The percentile to calculate (e.g., `95` for 95th percentile). | N/A | Yes |

**Percentile Rank (`aggregation: percentile_rank`)**

| YAML Key | Data Type | Description | Kibana Default | Required |
| ------------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------- | ---------------- | -------- |
| `aggregation` | `Literal['percentile_rank']` | Determines the rank of a specific value within the dataset. | `percentile_rank` | Yes |
| `field` | `string` | The numeric field for percentile rank calculation. | N/A | Yes |
| `rank` | `integer` | The value for which to find the percentile rank. | N/A | Yes |

### Formula Metric

Allows custom calculations using Kibana's native formula syntax. Formulas enable complex calculations that combine multiple aggregations, field operations, and mathematical expressions.

| YAML Key | Data Type | Description | Kibana Default | Required |
| --------- | ------------------------- | ------------------------------------------------ | ---------------- | -------- |
| `formula` | `string` | The formula string using Kibana formula syntax. | N/A | Yes |
| `label` | `string` | A custom display label for the metric. | `"Formula"` | No |
| `format` | `LensMetricFormatTypes` object | How to format the metric's value. | Default number format | No |

**Example Formulas:**

Simple arithmetic:

```yaml
primary:
  formula: "count() / 100"
  label: "Count Percentage"
```

Field aggregations:

```yaml
primary:
  formula: "max(response.time) - min(response.time)"
  label: "Response Time Range"
  format:
    type: duration
```

With filters:

```yaml
primary:
  formula: "count(kql='status:error') / count() * 100"
  label: "Error Rate %"
  format:
    type: percent
```

Number formatting:

```yaml
primary:
  formula: "average(bytes)"
  label: "Avg Bytes"
  format:
    type: bytes
    compact: true
```

---

## Metric Formatting (`format` field within a metric)

Defines how metric values are displayed in visualizations.

### Standard Format

**kb_dashboard_core.panels.charts.lens.metrics.config.LensMetricFormat**

Standard format configuration for displaying metric values.

Supports common numeric formats with optional suffix and compact notation.

Fields:
- `type` (`Literal['number', 'bytes', 'bits', 'percent', 'duration']`): The format type for the metric value.

Available formats:
- **number**: Plain numeric value with optional decimal places
- **bytes**: Byte size formatting (B, KB, MB, GB, TB)
- **bits**: Bit size formatting (b, Kb, Mb, Gb, Tb)
- **percent**: Percentage formatting with % symbol
- **duration**: Time duration formatting (ms, s, m, h, d)
- `decimals` (`int | None`): The number of decimal places to display. If not specified, defaults to 2 for number/bytes/percent, 0 for bits/duration.
- `suffix` (`str | None`): Optional suffix to display after the formatted number (e.g., " requests", " users").
- `compact` (`bool | None`): Whether to use compact notation (e.g., 1.2K instead of 1200). Defaults to Kibana's behavior.


---
# Source: panels/esql.md
---

# 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`).


---

## Minimal Configuration Examples

**Minimal ESQL Metric Chart:**

```yaml
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"
```

!!! tip "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](../guides/esql-views.md) for detailed patterns and examples.

**Minimal ESQL Pie Chart:**

```yaml
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](base.md). 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](base.md#size-object-configuration-size). | `w: 12, h: 8` | No |
| `position` | `Position` object | Defines the panel's x/y coordinates. Inherited from BasePanel. See [Position Object Configuration](base.md#position-object-configuration-position). | 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](../queries/config.md#esql-query). | 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:**

```yaml
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](#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](#esql-metric-column). | `None` | No |
| `maximum` | `ESQLMetric` object | An optional maximum metric. Its `field` refers to an ESQL result column. See [ESQL Metric Column](#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](#esql-dimension-column). | `None` | No |

**Example (ESQL Metric Chart):**

```yaml
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](#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](#esql-dimension-column). | N/A | Yes |
| `appearance` | `PieChartAppearance` object | Formatting options for the chart appearance. See [Pie Chart Appearance](#pie-chart-appearance-formatting-appearance-field) (shared with Lens). | `None` | No |
| `legend` | `PieLegend` object | Formatting options for the chart legend. See [Pie Legend](#pie-legend-formatting-legend-field) (shared with Lens). | `None` | No |
| `color` | `ColorValueMapping` object | Formatting options for the chart color palette. See [Color Mapping](#color-mapping-formatting-color-field) (shared with Lens). | `None` | No |

**Example (ESQL Pie Chart):**

```yaml
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](#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](#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](#esql-dimension-column). | `None` | No |
| `appearance` | `XYAppearance` object | Formatting options for chart appearance. See [XY Chart Appearance](#xy-chart-appearance-formatting-appearance-field). | `None` | No |
| `legend` | `XYLegend` object | Formatting options for the chart legend. See [XY Legend](#xy-legend-formatting-legend-field). | `None` | No |
| `color` | `ColorValueMapping` object | Formatting options for the chart color palette. See [Color Mapping](#color-mapping-formatting-color-field) (shared with other chart types). | `None` | No |

**Example (ESQL Bar Chart):**

```yaml
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](#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](#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](#esql-dimension-column). | `None` | No |
| `appearance` | `XYAppearance` object | Formatting options for chart appearance. See [XY Chart Appearance](#xy-chart-appearance-formatting-appearance-field). | `None` | No |
| `legend` | `XYLegend` object | Formatting options for the chart legend. See [XY Legend](#xy-legend-formatting-legend-field). | `None` | No |
| `color` | `ColorValueMapping` object | Formatting options for the chart color palette. See [Color Mapping](#color-mapping-formatting-color-field) (shared with other chart types). | `None` | No |

**Example (ESQL Line Chart):**

```yaml
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](#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](#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](#esql-dimension-column). | `None` | No |
| `appearance` | `XYAppearance` object | Formatting options for chart appearance. See [XY Chart Appearance](#xy-chart-appearance-formatting-appearance-field). | `None` | No |
| `legend` | `XYLegend` object | Formatting options for the chart legend. See [XY Legend](#xy-legend-formatting-legend-field). | `None` | No |
| `color` | `ColorValueMapping` object | Formatting options for the chart color palette. See [Color Mapping](#color-mapping-formatting-color-field) (shared with other chart types). | `None` | No |

**Example (ESQL Area Chart):**

```yaml
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**.

!!! note "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:

```yaml
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](#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):**

```yaml
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:**

```yaml
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](base.md#colorvaluemapping-object) 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](base.md#colorvalueassignment-object). | `[]` | 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 |

---

## Related Documentation

- [Base Panel Configuration](base.md)
- [Dashboard Configuration](../dashboard/dashboard.md)
- [Queries Configuration](../queries/config.md#esql-query)
- Elasticsearch ESQL Reference (external)


---
# Source: panels/datatable.md
---

# Datatable Chart Panel Configuration

The Datatable chart panel displays tabular data with customizable columns, sorting, pagination, and formatting options. Perfect for displaying detailed records and performing quick data analysis.


---

## Lens Datatable Charts

**kb_dashboard_core.panels.charts.datatable.config.LensDatatableChart**

Represents a Datatable chart configuration within a Lens panel.

Datatable charts display tabular data with customizable columns, sorting,
pagination, and formatting options.

Examples:
    Simple datatable with metrics and breakdowns:
    ```yaml
    lens:
      type: datatable
      data_view: "metrics-*"
      metrics:
        - id: "service-count"
          field: "service.name"
          aggregation: count
      breakdowns:
        - id: "service-breakdown"
          type: values
          field: "service.name"
    ```

    Datatable with sorting and pagination:
    ```yaml
    lens:
      type: datatable
      data_view: "logs-*"
      metrics:
        - id: "error-count"
          aggregation: count
          filter:
            kql: "log.level:error"
      breakdowns:
        - id: "service"
          type: values
          field: "service.name"
      sorting:
        column_id: "error-count"
        direction: desc
      paging:
        enabled: true
        page_size: 25
    ```

Fields:
- `id` (`str | None`): A unique identifier. If not provided, one will be generated automatically.
- `type` (`Literal['datatable']`): The type of chart, which is 'datatable' for this visualization.
- `data_view` (`<class 'str'>`): The data view that determines the data for the datatable chart.
- `metrics` (`list[LensDatatableMetricTypes | LensMetricTypes]`): List of metrics to display as columns.
- `breakdowns` (`list[LensDatatableBreakdownTypes | LensBreakdownTypes]`): List of breakdowns to use as row groupings.
- `metrics_split_by` (`list[LensDatatableDimensionTypes | LensDimensionTypes] | None`): Optional split-metrics-by dimensions (creates separate metric columns for each dimension value).
- `appearance` (`kb_dashboard_core.panels.charts.datatable.config.DatatableAppearance | None`): Appearance settings for the datatable.
- `sorting` (`kb_dashboard_core.panels.charts.datatable.config.DatatableSortingConfig | None`): Optional sorting configuration.
- `paging` (`kb_dashboard_core.panels.charts.datatable.config.DatatablePagingConfig | None`): Optional pagination configuration.


---
# Source: panels/gauge.md
---

# Gauge Chart Panel Configuration

The Gauge chart panel displays a single metric value with optional min/max ranges and goal indicators, typically used for KPIs and progress tracking toward targets or thresholds.


---

## Lens Gauge Charts

**kb_dashboard_core.panels.charts.gauge.config.LensGaugeChart**

Represents a Gauge chart configuration within a Lens panel.

Gauge charts display a single metric value with optional min/max ranges and goal indicators,
typically used to show progress toward a target or threshold.

Examples:
    Minimal gauge with static values:
    ```yaml
    lens:
      type: gauge
      data_view: "metrics-*"
      metric:
        aggregation: average
        field: system.cpu.total.pct
      minimum: 0
      maximum: 100
      goal: 80
    ```

    Gauge with custom appearance and color:
    ```yaml
    lens:
      type: gauge
      data_view: "logs-*"
      metric:
        aggregation: average
        field: response_time_ms
      minimum: 0
      maximum: 1000
      goal: 500
      color:
        range_type: percent
        thresholds:
          - up_to: 0
            color: "#00BF6F"
          - up_to: 80
            color: "#FFA500"
      appearance:
        shape: arc
    ```

Fields:
- `type` (`Literal['gauge']`): The type of chart, which is 'gauge' for this visualization.
- `color` (`kb_dashboard_core.panels.charts.base.config.ColorRangeMapping | None`): Range-based palette configuration for gauge thresholds. When set, enables palette color mode.
- `appearance` (`kb_dashboard_core.panels.charts.gauge.config.GaugeAppearance | None`): Visual appearance configuration for the gauge.
- `titles_and_text` (`kb_dashboard_core.panels.charts.gauge.config.GaugeTitlesAndText | None`): Title and subtitle options mapped to gauge `label_major` and `label_minor`.
- `id` (`str | None`): A unique identifier. If not provided, one will be generated automatically.
- `data_view` (`<class 'str'>`): The data view that determines the data for the gauge chart.
- `metric` (`LensMetricTypes`): The primary metric to display in the gauge. This is the main value shown.
- `minimum` (`LensMetricTypes | int | float | None`): An optional minimum value for the gauge range. Can be a metric (field-based) or a static numeric value.
- `maximum` (`LensMetricTypes | int | float | None`): An optional maximum value for the gauge range. Can be a metric (field-based) or a static numeric value.
- `goal` (`LensMetricTypes | int | float | None`): An optional goal/target value to display as a reference. Can be a metric (field-based) or a static numeric value.


---
# Source: panels/heatmap.md
---

# Heatmap Chart Panel Configuration

The Heatmap chart panel displays data as a matrix where cell colors represent metric values, typically used for visualizing patterns across two categorical dimensions or time-based intensity analysis.


---

## Minimal Configuration Example

```yaml
dashboards:
  - name: "Server Activity Dashboard"
    panels:
      - title: "Activity by Hour and Day"
        size: {w: 24, h: 15}
        lens:
          type: heatmap
          data_view: "logs-*"
          x_axis:
            field: "@timestamp"
            type: date_histogram
            label: "Hour of Day"
          y_axis:
            field: "host.name"
            type: values
            label: "Server"
          value:
            aggregation: count
            label: "Request Count"
```

## Grid and Legend Configuration Example

Customize the appearance of your heatmap with grid and legend options:

```yaml
dashboards:
  - name: "Customized Heatmap"
    panels:
      - title: "Response Time Heatmap"
        size: {w: 24, h: 15}
        lens:
          type: heatmap
          data_view: "logs-*"
          x_axis:
            field: "@timestamp"
            type: date_histogram
          y_axis:
            field: "service.name"
            type: values
          value:
            aggregation: average
            field: "response.time"
            format:
              type: duration
          appearance:
            values:
              visible: true
            x_axis:
              labels:
                visible: true
              title:
                visible: true
            y_axis:
              labels:
                visible: true
              title:
                visible: true
            legend:
              visible: show
              position: right
```

## One-Dimensional Heatmap Example

Create a 1D heatmap by omitting the Y-axis:

```yaml
dashboards:
  - name: "Hourly Traffic Pattern"
    panels:
      - title: "Traffic Intensity by Hour"
        size: {w: 48, h: 8}
        lens:
          type: heatmap
          data_view: "logs-*"
          x_axis:
            field: "@timestamp"
            type: date_histogram
            label: "Hour"
          value:
            aggregation: count
            label: "Events"
```

## Lens Heatmap Chart

**kb_dashboard_core.panels.charts.heatmap.config.LensHeatmapChart**

Represents a Heatmap chart configuration within a Lens panel.

Heatmap charts display data as a matrix where cell colors represent metric values,
typically used for visualizing patterns across two categorical dimensions.

Fields:
- `type` (`Literal['heatmap']`): The type of chart, which is 'heatmap' for this visualization.
- `appearance` (`kb_dashboard_core.panels.charts.heatmap.config.HeatmapAppearance | None`): Formatting options for the chart appearance.
- `color` (`kb_dashboard_core.panels.charts.base.config.ColorRangeMapping | None`): Optional range-based palette configuration for heatmap cell coloring.
- `id` (`str | None`): A unique identifier. If not provided, one will be generated automatically.
- `data_view` (`<class 'str'>`): The data view that determines the data for the heatmap chart.
- `x_axis` (`LensDimensionTypes`): The dimension to display on the X-axis (horizontal).
- `y_axis` (`LensDimensionTypes | None`): The dimension to display on the Y-axis (vertical). Optional for 1D heatmaps.
- `value` (`LensMetricTypes`): The metric that determines cell color intensity.


---
# Source: panels/metric.md
---

# Metric Chart Panel Configuration

The Metric chart panel displays a single value or a small set of key metrics, often used for KPIs or summary statistics.


---

## Minimal Configuration Example

```yaml
dashboards:
  - name: "KPI Dashboard"
    panels:
      - title: "Total Hosts"
        size: {w: 12, h: 2}
        lens:
          type: metric
          data_view: "metrics-*"
          primary:
            aggregation: unique_count
            field: resource.attributes.host.name
```

## Formula Metric Example

Formula metrics allow you to create custom calculations using Kibana's formula syntax:

```yaml
dashboards:
  - name: "Error Monitoring"
    panels:
      - title: "Error Rate"
        size: {w: 12, h: 2}
        lens:
          type: metric
          data_view: "logs-*"
          primary:
            formula: "count(kql='status:error') / count() * 100"
            label: "Error Rate %"
            format:
              type: percent
```

## Full Configuration Options

### Lens Metric Chart

| YAML Key | Data Type | Description | Default | Required |
| ----------- | -------------------------------- | ------------------------------------------------------------- | ---------- | -------- |
| `type` | `Literal['metric']` | Specifies the chart type as metric. | `'metric'` | No |
| `data_view` | `string` | The data view that determines the data for the metric chart. | N/A | Yes |
| `primary` | `LensMetricTypes` | The primary metric to display (main value). | N/A | Yes |
| `secondary` | `LensMetricTypes \| None` | Optional secondary metric to display alongside the primary. | `None` | No |
| `maximum` | `LensMetricTypes \| None` | Optional maximum metric for comparison or progress bar scale. | `None` | No |
| `breakdown` | `LensDimensionTypes \| None` | Optional breakdown dimension for splitting the metric. | `None` | No |
| `appearance` | `MetricAppearance \| None` | Visual appearance configuration. See [Metric Appearance](#metric-appearance). | `None` | No |
| `titles_and_text` | `MetricTitlesAndText \| None` | Titles and text formatting options. See [Metric Titles and Text](#metric-titles-and-text). | `None` | No |

Color thresholds and `apply_to` are configured on the primary metric's `color` field (e.g., `primary.color.thresholds`, `primary.color.apply_to`). Legacy chart-level `color` and `apply_to` are not accepted in `0.4.0`; run `kb-dashboard upgrade` to migrate old files.

#### Metric Appearance

| YAML Key | Data Type | Description | Default | Required |
| ----------- | -------------------------------- | ------------------------------------------------------------- | ---------- | -------- |
| `primary.icon` | `string \| None` | Icon identifier to display alongside the primary metric value. | `None` | No |
| `primary.icon_position` | `Literal['left', 'right'] \| None` | Horizontal alignment of the icon relative to the primary metric value. | `None` | No |
| `primary.background_chart.type` | `Literal['line', 'bar', 'none'] \| None` | Background chart mode for the primary metric. | `None` | No |
| `primary.background_chart.direction` | `Literal['horizontal', 'vertical'] \| None` | Direction for bar background charts. Only valid when type is `bar`. | `None` | No |
| `primary.font_size` | `Literal['default', 'fit', 'custom'] \| None` | Font size mode for the primary metric value. | `None` | No |
| `primary.position` | `Literal['top', 'bottom'] \| None` | Vertical position of the primary metric value within the panel. | `None` | No |
| `primary.alignment` | `Literal['left', 'center', 'right'] \| None` | Text alignment for the primary metric value. | `None` | No |
| `secondary.alignment` | `Literal['left', 'center', 'right'] \| None` | Text alignment for the secondary metric value. | `None` | No |
| `secondary.label.text` | `string \| None` | Custom label text for the secondary metric. | `None` | No |
| `secondary.label.position` | `Literal['before', 'after'] \| None` | Position of the secondary label relative to the value. | `None` | No |
| `breakdown.column_count` | `int \| None` | Maximum number of columns when displaying broken-down metrics. Minimum value is `1`. | `None` | No |

#### Metric Titles and Text

| YAML Key | Data Type | Description | Default | Required |
| ----------- | -------------------------------- | ------------------------------------------------------------- | ---------- | -------- |
| `subtitle` | `string \| None` | Custom subtitle text displayed below the metric title. | `None` | No |
| `alignment` | `Literal['left', 'center', 'right'] \| None` | Text alignment for the metric title and subtitle. | `None` | No |
| `weight` | `Literal['bold', 'normal', 'lighter'] \| None` | Font weight for the metric title. | `None` | No |

#### Lens Metric Types

The `primary`, `secondary`, and `maximum` fields accept these metric configurations:

| Metric Type | Description | Key Fields | Example Use Case |
| ----------- | ----------- | ---------- | ---------------- |
| **Count** | Count documents or unique values | `aggregation: 'count' \| 'unique_count'`, `field` (optional) | Count total requests or unique users |
| **Sum** | Sum numeric field values | `aggregation: 'sum'`, `field` | Total revenue or bytes transferred |
| **Aggregation** | Other aggregations (avg, min, max, median, etc.) | `aggregation`, `field` | Average response time or max CPU usage |
| **Last Value** | Most recent value of a field | `aggregation: 'last_value'`, `field` | Latest status or most recent reading |
| **Percentile** | Calculate percentile of values | `aggregation: 'percentile'`, `field`, `percentile` | 95th percentile latency |
| **Percentile Rank** | Calculate rank of a value | `aggregation: 'percentile_rank'`, `field`, `rank` | What % of requests are faster than 500ms |
| **Formula** | Custom calculation using Kibana formula syntax | `formula`, `label` (optional), `format` (optional) | `count(kql='status:error') / count() * 100` |
| **Static Value** | Fixed numeric value | `value`, `label` (optional) | Target threshold or goal value |

**Common Fields:**

All metric types except Static Value support:

- `label`: Custom display label
- `format`: Number formatting (see [Format Configuration Options](#format-configuration-options) for details)
- `filter`: KQL filter to apply before aggregation

**Additional Field Details:**

- **Count**: Optional `field` (for counting specific field values), optional `exclude_zeros` (exclude zero values from count)
- **Sum**: Required `field`, optional `exclude_zeros` (exclude zero values from sum)
- **Last Value**: Required `field`, optional `date_field` (determines sort order for finding the most recent value)

**Examples:**

```yaml
# Count metric
primary:
  aggregation: count
  label: "Total Requests"

# Average metric
primary:
  aggregation: average
  field: response_time_ms
  label: "Avg Response Time"
  format:
    type: duration

# Formula metric
primary:
  formula: "count(kql='status:error') / count() * 100"
  label: "Error Rate %"
  format:
    type: percent
```

### ESQL Metric Chart

| YAML Key | Data Type | Description | Default | Required |
| ----------- | -------------------------------- | ------------------------------------------------------------- | ---------- | -------- |
| `type` | `Literal['metric']` | Specifies the chart type as metric. | `'metric'` | No |
| `primary` | `ESQLMetricTypes` | The primary metric to display (main value). | N/A | Yes |
| `secondary` | `ESQLMetricTypes \| None` | Optional secondary metric to display alongside the primary. | `None` | No |
| `maximum` | `ESQLMetricTypes \| None` | Optional maximum metric for comparison or progress bar scale. | `None` | No |
| `breakdown` | `ESQLDimensionTypes \| None` | Optional breakdown dimension for splitting the metric. | `None` | No |
| `appearance` | `MetricAppearance \| None` | Visual appearance configuration. See [Metric Appearance](#metric-appearance). | `None` | No |
| `titles_and_text` | `MetricTitlesAndText \| None` | Titles and text formatting options. See [Metric Titles and Text](#metric-titles-and-text). | `None` | No |

Color thresholds and `apply_to` are configured on the primary metric's `color` field (e.g., `primary.color.thresholds`, `primary.color.apply_to`). Legacy chart-level `color` and `apply_to` are not accepted in `0.4.0`; run `kb-dashboard upgrade` to migrate old files.

#### ESQL Metric Types

The `primary`, `secondary`, and `maximum` fields accept these metric configurations:

| Metric Type | Description | Key Fields | Example Use Case |
| ----------- | ----------- | ---------- | ---------------- |
| **ESQL Metric** | Reference a column from your ESQL query result | `field` | Any aggregated value from STATS clause |
| **Static Value** | Fixed numeric value | `value`, `label` (optional) | Target threshold or goal value |

**ESQL metrics** reference columns produced by your ESQL query. The `field` must match a column name in your query result.

**Example:**

```yaml
# ESQL metric referencing query result column
esql:
  type: metric
  query: |
    FROM logs-*
    | STATS
        total_requests = COUNT(*),
        avg_duration = AVG(event.duration),
        error_rate = COUNT(kql='event.outcome:failure') / COUNT(*) * 100
  primary:
    field: "total_requests"  # References column from STATS
  secondary:
    field: "avg_duration"    # References column from STATS
  maximum:
    field: "error_rate"      # References column from STATS
```

The ESQL query determines what metrics are available - each column in your STATS clause becomes a metric you can reference.

## Color Mode

Use `primary.color.apply_to` to control how metric colors are applied:

- `value`: apply colors to metric value text
- `background`: apply colors to metric background (default)

```yaml
dashboards:
  - name: "Metric Color Modes"
    panels:
      - title: "Error Rate (Value Colors)"
        size: {w: 8, h: 4}
        lens:
          type: metric
          data_view: "logs-*"
          primary:
            formula: "count(kql='event.outcome:failure') / count() * 100"
            label: "Error Rate"
            color:
              apply_to: value
            format:
              type: percent

      - title: "Availability (Background Colors)"
        size: {w: 8, h: 4}
        position: {x: 8, y: 0}
        lens:
          type: metric
          data_view: "logs-*"
          primary:
            formula: "count(kql='event.outcome:success') / count() * 100"
            label: "Availability"
            color:
              apply_to: background
            format:
              type: percent
```

## Styling Options

Metric panels support a variety of styling options to control layout, alignment, and typography.

### Subtitle and Secondary Label

Add contextual information with custom subtitles and secondary metric labels:

```yaml
dashboards:
  - name: "Styled Metrics"
    panels:
      - title: "CPU Usage"
        size: {w: 12, h: 4}
        lens:
          type: metric
          data_view: "metrics-*"
          appearance:
            secondary:
              label:
                text: "vs. previous day"
                position: after
          titles_and_text:
            subtitle: "Last 24 hours"
          primary:
            aggregation: average
            field: system.cpu.total.norm.pct
            format:
              type: percent
          secondary:
            aggregation: average
            field: system.cpu.total.norm.pct
            filter:
              kql: "@timestamp < now-1d"
```

### Progress Bar

Display a progress bar below the metric value to show progress toward a maximum:

```yaml
dashboards:
  - name: "Progress Metrics"
    panels:
      - title: "Disk Usage"
        size: {w: 12, h: 4}
        lens:
          type: metric
          data_view: "metrics-*"
          appearance:
            primary:
              background_chart:
                type: bar
                direction: horizontal
          primary:
            aggregation: average
            field: system.filesystem.used.pct
            format:
              type: percent
          maximum:
            value: 1
```

### Icon

Add an icon alongside the metric value:

```yaml
dashboards:
  - name: "Icon Metrics"
    panels:
      - title: "Uptrend Indicator"
        size: {w: 12, h: 4}
        lens:
          type: metric
          data_view: "metrics-*"
          appearance:
            primary:
              icon: sortUp
              icon_position: right
          primary:
            aggregation: count
```

### Text Alignment and Typography

Control alignment and font properties for different parts of the metric:

```yaml
dashboards:
  - name: "Aligned Metrics"
    panels:
      - title: "Centered KPI"
        size: {w: 12, h: 4}
        lens:
          type: metric
          data_view: "metrics-*"
          appearance:
            primary:
              font_size: fit
              position: top
              alignment: center
            secondary:
              alignment: center
          titles_and_text:
            alignment: center
            weight: bold
          primary:
            aggregation: count
            label: "Total Events"
```

### Breakdown Columns

Control the number of columns when using breakdown dimensions:

```yaml
dashboards:
  - name: "Multi-Column Metrics"
    panels:
      - title: "Events by Host"
        size: {w: 24, h: 8}
        lens:
          type: metric
          data_view: "metrics-*"
          appearance:
            breakdown:
              column_count: 4
          primary:
            aggregation: count
          breakdown:
            type: values
            field: host.name
```

## Programmatic Usage (Python)

You can create Metric chart panels programmatically using Python:

### Count Metric Example

```python
from kb_dashboard_core.panels.charts.config import (
    LensMetricPanelConfig,
    LensPanel,
)
from kb_dashboard_core.panels.charts.metric.metrics import (
    MetricLensCountAggregatedMetric,
)
from kb_dashboard_core.panels.config import Position, Size

panel = LensPanel(
    title='Total Documents',
    position=Position(x=0, y=0),
    size=Size(w=24, h=15),
    lens=LensMetricPanelConfig(
        type='metric',
        data_view='logs-*',
        primary=MetricLensCountAggregatedMetric(),
    ),
)
```

### Average Metric Example

```python
from kb_dashboard_core.panels.charts.config import (
    LensMetricPanelConfig,
    LensPanel,
)
from kb_dashboard_core.panels.charts.metric.metrics import (
    MetricLensOtherAggregatedMetric,
)
from kb_dashboard_core.panels.config import Position, Size

panel = LensPanel(
    title='Avg Response Time',
    position=Position(x=0, y=0),
    size=Size(w=24, h=15),
    lens=LensMetricPanelConfig(
        type='metric',
        data_view='logs-*',
        primary=MetricLensOtherAggregatedMetric(
            aggregation='average', field='response_time'
        ),
    ),
)
```

### Formula Metric Example

```python
from kb_dashboard_core.panels.charts.config import (
    LensMetricPanelConfig,
    LensPanel,
)
from kb_dashboard_core.panels.charts.lens.metrics.config import LensMetricFormat
from kb_dashboard_core.panels.charts.metric.metrics import MetricLensFormulaMetric
from kb_dashboard_core.panels.config import Position, Size

panel = LensPanel(
    title='Error Rate',
    position=Position(x=0, y=0),
    size=Size(w=24, h=15),
    lens=LensMetricPanelConfig(
        type='metric',
        data_view='logs-*',
        primary=MetricLensFormulaMetric(
            formula="count(kql='status:error') / count() * 100",
            label='Error Rate %',
            format=LensMetricFormat(type='percent'),
        ),
    ),
)
```

## Number Formatting

Metric charts support various number formatting options to display values in a user-friendly way. You can add suffixes, use compact notation, or apply custom number patterns.

### Format Configuration Options

The `format` field accepts an object with the following properties:

| YAML Key | Data Type | Description | Default | Required |
| -------- | --------- | ----------- | ------- | -------- |
| `type` | `string` | Format type: `'number'`, `'bytes'`, `'bits'`, `'percent'`, `'duration'` | `'number'` | No |
| `suffix` | `string` | Custom text appended to the formatted value | `''` | No |
| `prefix` | `string` | Custom text prepended to the formatted value | `''` | No |
| `compact` | `boolean` | Enable compact notation (e.g., 1.2K instead of 1200) | `false` | No |
| `pattern` | `string` | Custom numeral.js format pattern (e.g., `'0,0.00'`) | `null` | No |

### Suffix Formatting

Add custom text after metric values to provide context:

```yaml
dashboards:
  - name: "Metrics with Suffixes"
    panels:
      - title: "Request Rate"
        size: {w: 12, h: 4}
        lens:
          type: metric
          data_view: "logs-*"
          primary:
            aggregation: count
            label: "Requests"
            format:
              type: number
              suffix: " req/sec"

      - title: "Active Users"
        size: {w: 12, h: 4}
        position: {x: 12, y: 0}
        lens:
          type: metric
          data_view: "logs-*"
          primary:
            aggregation: unique_count
            field: "user.id"
            label: "Users"
            format:
              type: number
              suffix: " users"
```

### Compact Notation

Use compact notation to display large numbers in a more readable format (e.g., 1.2K instead of 1200):

```yaml
dashboards:
  - name: "Compact Metrics"
    panels:
      - title: "Total Events (Compact)"
        size: {w: 12, h: 4}
        lens:
          type: metric
          data_view: "logs-*"
          primary:
            aggregation: count
            label: "Events"
            format:
              type: number
              compact: true  # Displays as 1.2M, 500K, etc.
```

### Custom Number Patterns

Apply custom formatting patterns using numeral.js syntax:

```yaml
dashboards:
  - name: "Formatted Metrics"
    panels:
      - title: "Revenue (Currency)"
        size: {w: 12, h: 4}
        lens:
          type: metric
          data_view: "sales-*"
          primary:
            aggregation: sum
            field: "transaction.amount"
            label: "Total Revenue"
            format:
              type: custom
              pattern: "0,0.00"  # Comma separators, 2 decimals

      - title: "Success Rate"
        size: {w: 12, h: 4}
        position: {x: 12, y: 0}
        lens:
          type: metric
          data_view: "logs-*"
          primary:
            formula: "count(kql='status:success') / count() * 100"
            label: "Success Rate"
            format:
              type: custom
              pattern: "0.0a"    # 1 decimal + suffix (K, M, etc.)
              suffix: "%"
```

### Combining Format Options

You can combine multiple formatting options for maximum flexibility:

```yaml
dashboards:
  - name: "Combined Formatting"
    panels:
      - title: "Bandwidth Usage"
        size: {w: 12, h: 4}
        lens:
          type: metric
          data_view: "network-*"
          primary:
            aggregation: sum
            field: "network.bytes"
            label: "Total Bandwidth"
            format:
              type: bytes       # Built-in bytes format
              compact: true     # Use compact notation (MB, GB)
              suffix: "/day"    # Add custom suffix
```

For more examples of metric formatting, see [metric-formatting-examples.yaml](../examples/metric-formatting-examples.yaml).

## Related

- [Base Panel Configuration](./base.md)
- [Dashboard Configuration](../dashboard/dashboard.md)
- [Metric Formatting Examples](../examples/metric-formatting-examples.yaml)


---
# Source: panels/mosaic.md
---

# Mosaic Chart Panel Configuration

The Mosaic chart panel visualizes categorical data as proportional rectangles, showing category distributions at a glance. Mosaic charts support exactly one metric, one dimension, and an optional breakdown.

---

## Lens Mosaic Charts

**kb_dashboard_core.panels.charts.mosaic.config.LensMosaicChart**

Represents a Mosaic chart configuration within a Lens panel.

Mosaic charts visualize categorical data as proportional rectangles,
where each rectangle's area represents its proportion of the whole.
Mosaic charts support exactly one metric, one dimension, and an optional breakdown.

Examples:
    Simple mosaic chart showing request distribution:
    ```yaml
    lens:
      type: mosaic
      data_view: "logs-*"
      dimension:
        field: "http.request.method"
        type: values
      metric:
        aggregation: count
    ```

    Mosaic chart with breakdown:
    ```yaml
    lens:
      type: mosaic
      data_view: "logs-*"
      dimension:
        field: "http.request.method"
        type: values
      breakdown:
        field: "service.name"
        type: values
      metric:
        aggregation: count
    ```

    Mosaic chart with custom colors:
    ```yaml
    lens:
      type: mosaic
      data_view: "metrics-*"
      dimension:
        field: "service.name"
        type: values
      metric:
        aggregation: count
      color:
        palette: 'eui_amsterdam_color_blind'
        assignments:
          - values: ['api-gateway']
            color: '#00BF6F'
          - values: ['database']
            color: '#006BB4'
    ```

    Mosaic chart with legend options:
    ```yaml
    lens:
      type: mosaic
      data_view: "logs-*"
      dimension:
        field: "http.request.method"
        type: values
      metric:
        aggregation: count
      legend:
        visible: show
        position: bottom
    ```

Fields:
- `id` (`str | None`): A unique identifier. If not provided, one will be generated automatically.
- `type` (`Literal['mosaic']`)
- `appearance` (`kb_dashboard_core.panels.charts.mosaic.config.MosaicAppearance | None`): Formatting options for the chart appearance.
- `legend` (`kb_dashboard_core.panels.charts.mosaic.config.MosaicLegend | None`): Formatting options for the chart legend.
- `color` (`kb_dashboard_core.panels.charts.base.config.ColorValueMapping | None`): Formatting options for the chart color.
- `data_view` (`<class 'str'>`): The data view that determines the data for the mosaic chart.
- `metric` (`LensMetricTypes`): Metric that determines the size of rectangles. Mosaic charts support only one metric.
- `dimension` (`LensDimensionTypes`): Primary dimension for grouping data. Mosaic charts support only one dimension.
- `breakdown` (`LensBreakdownTypes | None`): Optional secondary breakdown for splitting the mosaic into sub-groups.


---
# Source: panels/pie.md
---

# Pie Chart Panel Configuration

The Pie chart panel visualizes data as a pie or donut chart, useful for showing proportions of a whole.


---

## Lens Pie Charts

**kb_dashboard_core.panels.charts.pie.config.LensPieChart**

Represents a Pie chart configuration within a Lens panel.

Pie charts are used to visualize the proportion of categories.

Examples:
    Simple pie chart showing traffic sources:
    ```yaml
    lens:
      type: pie
      data_view: "logs-*"
      breakdowns:
        - field: "source.geo.country_name"
          type: values
      metrics:
        - aggregation: count
    ```

    Pie chart with custom colors:
    ```yaml
    lens:
      type: pie
      data_view: "metrics-*"
      breakdowns:
        - field: "resource.attributes.os.type"
          type: values
      metrics:
        - aggregation: unique_count
          field: resource.attributes.host.name
      color:
        palette: 'eui_amsterdam_color_blind'
        assignments:
          - values: ['linux']
            color: '#00BF6F'
          - values: ['windows']
            color: '#006BB4'
    ```

Fields:
- `id` (`str | None`): A unique identifier. If not provided, one will be generated automatically.
- `type` (`Literal['pie']`)
- `appearance` (`kb_dashboard_core.panels.charts.pie.config.PieChartAppearance | None`): Formatting options for the chart appearance, including donut size.
- `legend` (`kb_dashboard_core.panels.charts.pie.config.PieLegend | None`): Formatting options for the chart legend.
- `color` (`kb_dashboard_core.panels.charts.base.config.ColorValueMapping | None`): Formatting options for the chart color.
- `data_view` (`<class 'str'>`): The data view that determines the data for the pie chart.
- `metrics` (`list[LensMetricTypes]`): Metrics that determine the size of slices.
- `breakdowns` (`list[LensBreakdownTypes]`): The breakdowns that determine the slices of the pie chart. First breakdown is primary, additional breakdowns are secondary.


---
# Source: panels/tagcloud.md
---

# Tag Cloud Chart Panel Configuration

The Tag Cloud chart panel visualizes term frequency as a word cloud, where the size of each tag is proportional to its metric value. This is useful for showing the most common or significant terms in your data.


---

## Lens Tagcloud Charts

**kb_dashboard_core.panels.charts.tagcloud.config.LensTagcloudChart**

Represents a Tagcloud chart configuration within a Lens panel.

Tagcloud charts are used to visualize term frequency as word/tag clouds.

Examples:
    Minimal tagcloud:
    ```yaml
    dashboards:
    - name: "Log Analysis"
      panels:
        - title: "Top Error Messages"
          size: { w: 48, h: 6 }
          lens:
            type: tagcloud
            data_view: "logs-*"
            dimension:
              type: values
              field: "error.message"
            metric:
              aggregation: count
    ```

    Advanced tagcloud with appearance customization:
    ```yaml
    dashboards:
    - name: "Advanced Tag Cloud"
      panels:
        - title: "Service Labels"
          size: { w: 48, h: 8 }
          lens:
            type: tagcloud
            data_view: "logs-*"
            dimension:
              type: values
              field: "service.name"
            metric:
              aggregation: count
            appearance:
              min_font_size: 12
              max_font_size: 96
              orientation: "multiple"
              labels:
                visible: false
            color:
              palette: "kibana_palette"
    ```

Fields:
- `id` (`str | None`): A unique identifier. If not provided, one will be generated automatically.
- `type` (`Literal['tagcloud']`)
- `appearance` (`kb_dashboard_core.panels.charts.tagcloud.config.TagcloudAppearance | None`): Formatting options for the chart appearance.
- `color` (`kb_dashboard_core.panels.charts.base.config.ColorValueMapping | None`): Formatting options for the chart colors.
- `data_view` (`<class 'str'>`): The data view that determines the data for the tagcloud chart.
- `dimension` (`LensDimensionTypes`): The dimension for grouping (terms). This determines the tags shown in the cloud.
- `metric` (`LensMetricTypes`): The metric for sizing. This determines the size of each tag.


---
# Source: panels/xy.md
---

# XY Chart Panel Configuration

The XY chart panel creates line, bar, and area charts for time series and other data visualizations.


---

## Lens Bar Charts

**kb_dashboard_core.panels.charts.xy.config.LensBarChart**

Represents a Bar chart configuration within a Lens panel.

Examples:
    Simple bar chart with time series:
    ```yaml
    lens:
      type: bar
      data_view: "logs-*"
      dimension:
        type: date_histogram
        field: "@timestamp"
      metrics:
        - aggregation: count
    ```

    Stacked bar chart with breakdown:
    ```yaml
    lens:
      type: bar
      mode: stacked
      data_view: "logs-*"
      dimension:
        type: date_histogram
        field: "@timestamp"
      breakdown:
        type: values
        field: "service.name"
      metrics:
        - aggregation: count
    ```

Fields:
- `data_view` (`<class 'str'>`): The data view to use for the chart.
- `dimension` (`LensDimensionTypes | None`): Defines the X-axis dimension for the chart. XY charts support 0 or 1 dimension.
- `metrics` (`list[LensXYMetricTypes]`): Defines the metrics for the chart. At least one metric is required.
- `breakdown` (`LensDimensionTypes | None`): An optional dimension to split the series by. If provided, it will be used to break down the data into multiple series.
- `id` (`str | None`): A unique identifier. If not provided, one will be generated automatically.
- `legend` (`kb_dashboard_core.panels.charts.xy.config.XYLegend | None`): Formatting options for the chart legend.
- `color` (`kb_dashboard_core.panels.charts.base.config.ColorValueMapping | None`): Formatting options for the chart color palette.
- `type` (`Literal['bar']`): The type of XY chart to display. Defaults to 'bar'.
- `appearance` (`kb_dashboard_core.panels.charts.xy.config.BarChartAppearance | None`): Formatting options for the chart appearance.
- `mode` (`Literal['stacked', 'unstacked', 'percentage']`): The stacking mode for bar and area charts. Defaults to 'stacked'.


---
# Source: panels/image.md
---

# Image Panel Configuration

The `image` panel type is used to display an image directly on your dashboard. This can be useful for branding, diagrams, or other visual elements.


---

## Image Panel

**kb_dashboard_core.panels.images.config.ImagePanel**

Represents an Image panel configuration.

Image panels are used to display images.

Examples:
    Minimal image panel:
    ```yaml
    dashboards:
      - name: "Branded Dashboard"
        panels:
          - title: "Company Logo"
            size: { w: 16, h: 3 }
            image:
              from_url: "https://example.com/path/to/your/logo.png"
    ```

    Image panel with custom fit and background:
    ```yaml
    dashboards:
      - name: "Dashboard with Diagram"
        panels:
          - title: "System Architecture Diagram"
            size: { w: 48, h: 6 }
            image:
              from_url: "https://example.com/path/to/architecture.svg"
              fit: "contain"
              background_color: "#f0f0f0"
    ```

Fields:
- `id` (`str | None`): A unique identifier for the panel. If not provided, one may be generated during compilation.
- `title` (`<class 'str'>`): The title displayed on the panel header. Can be an empty string.
- `hide_title` (`bool | None`): If `true`, the panel title will be hidden. Defaults to `false` (title is shown).
- `description` (`str | None`): A brief description of the panel's content or purpose. Defaults to an empty string.
- `size` (`<class 'kb_dashboard_core.panels.config.Size'>`): Defines the panel's size on the dashboard grid.
- `position` (`<class 'kb_dashboard_core.panels.config.Position'>`): Defines the panel's position on the dashboard grid. If not specified, position will be auto-calculated.
- `drilldowns` (`list[DrilldownTypes] | None`): Optional list of drilldowns to attach to this panel.
- `image` (`<class 'kb_dashboard_core.panels.images.config.ImagePanelConfig'>`): Image panel configuration.


---
# Source: panels/search.md
---

# Search Panel Configuration

The `search` panel type is used to embed the results of a pre-existing, saved Kibana search directly onto your dashboard. This allows you to display dynamic log views, event lists, or any other data set defined by a saved search in Discover.


---

## Search Panel

**kb_dashboard_core.panels.search.config.SearchPanel**

Represents a Search panel configuration.

Search panels are used to display the results of a saved Kibana search.

Examples:
    Minimal search panel:
    ```yaml
    dashboards:
      - name: "Log Monitoring Dashboard"
        panels:
          - title: "All System Logs"
            size: { w: 48, h: 10 }
            search:
              saved_search_id: "a1b2c3d4-e5f6-7890-1234-567890abcdef"
    ```

    Search panel with hidden title:
    ```yaml
    dashboards:
      - name: "Security Incidents Overview"
        panels:
          - hide_title: true
            description: "Critical security alerts from the last 24 hours"
            size: { w: 48, h: 8 }
            search:
              saved_search_id: "critical-security-alerts-saved-search"
    ```

Fields:
- `id` (`str | None`): A unique identifier for the panel. If not provided, one may be generated during compilation.
- `title` (`<class 'str'>`): The title displayed on the panel header. Can be an empty string.
- `hide_title` (`bool | None`): If `true`, the panel title will be hidden. Defaults to `false` (title is shown).
- `description` (`str | None`): A brief description of the panel's content or purpose. Defaults to an empty string.
- `size` (`<class 'kb_dashboard_core.panels.config.Size'>`): Defines the panel's size on the dashboard grid.
- `position` (`<class 'kb_dashboard_core.panels.config.Position'>`): Defines the panel's position on the dashboard grid. If not specified, position will be auto-calculated.
- `drilldowns` (`list[DrilldownTypes] | None`): Optional list of drilldowns to attach to this panel.
- `search` (`<class 'kb_dashboard_core.panels.search.config.SearchPanelConfig'>`): Search panel configuration.


---
# Source: controls/config.md
---

# Controls Configuration

Controls are interactive elements that can be added to a dashboard, allowing users to filter data or adjust visualization settings dynamically. They are defined as a list of control objects within each dashboard's `controls` field in the `dashboards:` array. Global behavior of controls can be managed via the `settings.controls` object.

## Minimal Configuration Examples

Here's a minimal example of an `options` list control:

```yaml
dashboards:
  - name: "Example Dashboard"
    controls:
      - type: options
        label: "Filter by OS Type"
        data_view: "metrics-*"
        field: "resource.attributes.os.type"
```

Here's a minimal example of a `range` slider control:

```yaml
dashboards:
  - name: "Example Dashboard"
    controls:
      - type: range
        label: "CPU Load Average (1m)"
        data_view: "metrics-*"
        field: "metrics.system.cpu.load_average.1m"
```

## Complex Configuration Example

This example demonstrates multiple controls with custom widths and global control settings:

```yaml
dashboards:
  - name: "Application Monitoring Dashboard"
    description: "Dashboard with interactive controls."
    settings:
      controls:
        label_position: "above"
        chain_controls: true
        click_to_apply: false
    controls:
      - type: options
        label: "Host Name"
        width: "medium"
        data_view: "metrics-*"
        field: "resource.attributes.host.name"
        multiple: true
        match_technique: "contains"
      - type: range
        label: "CPU Utilization"
        width: "large"
        data_view: "metrics-*"
        field: "metrics.system.cpu.utilization"
        step: 0.01
      - type: time
        label: "Custom Time Slice"
        width: "small"
        start_offset: 0.1  # 10% from the start of the global time range
        end_offset: 0.9    # 90% from the start of the global time range
```

## Full Configuration Options

### Control Settings (`settings.controls`)

Global settings for all controls on the dashboard. These are configured under the `settings.controls` path in your main dashboard YAML.

**kb_dashboard_core.controls.config.ControlSettings**

Settings for controls in a dashboard, defining their behavior and appearance.

Fields:
- `label_position` (`Optional[Literal['inline', 'above']]`): The position of the control label, either 'inline' or 'above'. Defaults to 'inline' if not set.
- `apply_global_filters` (`bool | None`): Whether to apply global filters to the control. Defaults to true if not set.
- `apply_global_timerange` (`bool | None`): Whether to apply the global time range to the control. Defaults to true if not set.
- `ignore_zero_results` (`bool | None`): Whether to ignore controls that return zero results. Defaults to true if not set.
- `chain_controls` (`bool | None`): Whether to chain controls together, allowing one control's selection to filter the next. Defaults to true if not set.
- `click_to_apply` (`bool | None`): Whether to require users to click the apply button before applying changes. Defaults to false if not set.


---
# Source: filters/config.md
---

# Filters Configuration

Filters are used to narrow down the data displayed on a dashboard or within individual panels. They are defined as a list of filter objects, typically under the `filters` key of a `dashboard` object or a panel that supports filtering.

## Minimal Configuration Examples

**Exists Filter:** Check if the `error.message` field exists.

```yaml
filters:
  - exists: "error.message"
```

**Phrase Filter:** Find documents where `status.keyword` is exactly "active".

```yaml
filters:
  - field: "status.keyword"
    equals: "active"
```

**Phrases Filter (using `in` alias):** Find documents where `event.category` is "authentication" OR "network".

```yaml
filters:
  - field: "event.category"
    in: ["authentication", "network"]
```

**Range Filter:** Find documents where `response_time` is between 100 (inclusive) and 500 (exclusive).

```yaml
filters:
  - field: "response_time"
    gte: "100" # Values are typically strings, Kibana handles conversion
    lt: "500"
```

## Complex Configuration Example

This example demonstrates a combination of filter types, including logical junctions (`and`, `or`) and a modifier (`not`).

```yaml
filters:
  - alias: "Successful Logins from US or CA"
    and: # `and_filters` in Pydantic, `and` in YAML
      - field: "event.action"
        equals: "user_login"
      - field: "event.outcome"
        equals: "success"
      - or: # `or_filters` in Pydantic, `or` in YAML
          - field: "source.geo.country_iso_code"
            equals: "US"
          - field: "source.geo.country_iso_code"
            equals: "CA"
  - alias: "Exclude test users"
    not: # `not_filter` in Pydantic, `not` in YAML
      field: "user.name"
      in: ["test_user_01", "qa_bot"]
  - exists: "transaction.id"
    disabled: true # This filter is defined but currently disabled
  - dsl:
      query_string:
        query: "message:(*error* OR *exception*) AND NOT logger_name:debug"
```

## Full Configuration Options

### Exists Filter

Checks for the existence of a specific field.

**kb_dashboard_core.filters.config.ExistsFilter**

Represents an 'exists' filter configuration in the Config schema.

This filter checks for the existence or non-existence of a specific field.

Fields:
- `alias` (`str | None`): An optional alias for the filter, used for display purposes.
- `disabled` (`bool | None`): Indicates whether the filter is disabled. If `true`, the filter will not be applied.
- `exists` (`<class 'str'>`): The field name to check for existence. If the field exists in a document, it will match that document.


---
# Source: queries/config.md
---

# Queries Configuration

Queries are used to define the search criteria for retrieving data. They can be applied globally at the dashboard level or specifically to individual panels that support them. This compiler supports KQL (Kibana Query Language), Lucene, and ESQL (Elasticsearch Query Language).

## Minimal Configuration Examples

**KQL Query:**

```yaml
# Applied at the dashboard level
dashboards:
- # ...
  query:
    kql: 'response_code:200 AND "user.id": "test-user"'
```

**Lucene Query:**

```yaml
# Applied at the dashboard level
dashboards:
- # ...
  query:
    lucene: 'event.module:nginx AND event.dataset:nginx.access'
```

**ESQL Query (typically for specific panel types like ESQL-backed charts):**

```yaml
# Example within a panel configuration that supports ESQL
panels:
  - type: some_esql_panel # Hypothetical panel type
    # ... other panel config
    query: |
      FROM my_index
      | STATS RARE(clientip)
```

## Full Configuration Options

Queries are typically defined under a `query` key, either at the root of the `dashboard` object or within a specific panel's configuration. The structure of the `query` object determines the language.

### KQL Query

Filters documents using the Kibana Query Language (KQL). This is often the default query language in Kibana.

**kb_dashboard_core.queries.config.KqlQuery**

Represents a KQL (Kibana Query Language) query configuration.

KQL is the default query language in Kibana and provides a simplified syntax for filtering data.

Fields:
- `kql` (`<class 'str'>`): The Kibana Query Language (KQL) query string to apply.


---
# Source: guides/index.md
---

# Advanced Guides

Use the CLI to access bundled guide content:

- `kb-dashboard docs list-guides`
- `kb-dashboard docs guide <guide-id>`

## Recommended Workflow Guides

| Guide | Use it for |
| ----- | ---------- |
| [Dashboard Decompiling Guide](dashboard-decompiling-guide.md) | Converting existing Kibana JSON dashboards into YAML |
| [Creating Dashboards from OpenTelemetry Receivers](otel-dashboard-guide.md) | Building new dashboards for OpenTelemetry receivers from scratch |
| [ES\|QL Language Reference](esql-language-reference.md) | Writing production-ready ES\|QL for dashboard panels |
| [Kibana Dashboard Style Guide](dashboard-style-guide.md) | Applying layout, hierarchy, and readability patterns across dashboards |
| [Breaking Changes](breaking-changes.md) | Migration checklist for version upgrades |
| [Color Assignments](color-assignments.md) | Configuring chart color assignments |
| [Legend Configuration](legend-configuration.md) | Legend placement and sizing |
| [ES\|QL Views](esql-views.md) | Reusable ES\|QL view definitions |


---
# Source: guides/breaking-changes.md
---

Guide content is available via the CLI and intentionally excluded from llms-full.txt.

Use:
- `kb-dashboard docs list-guides`
- `kb-dashboard docs guide breaking-changes`

---
# Source: guides/dashboard-decompiling-guide.md
---

Guide content is available via the CLI and intentionally excluded from llms-full.txt.

Use:
- `kb-dashboard docs list-guides`
- `kb-dashboard docs guide dashboard-decompiling-guide`

---
# Source: guides/dashboard-style-guide.md
---

Guide content is available via the CLI and intentionally excluded from llms-full.txt.

Use:
- `kb-dashboard docs list-guides`
- `kb-dashboard docs guide dashboard-style-guide`

---
# Source: guides/esql-language-reference.md
---

Guide content is available via the CLI and intentionally excluded from llms-full.txt.

Use:
- `kb-dashboard docs list-guides`
- `kb-dashboard docs guide esql-language-reference`

---
# Source: guides/otel-dashboard-guide.md
---

Guide content is available via the CLI and intentionally excluded from llms-full.txt.

Use:
- `kb-dashboard docs list-guides`
- `kb-dashboard docs guide otel-dashboard-guide`

---
# Source: guides/color-assignments.md
---

Guide content is available via the CLI and intentionally excluded from llms-full.txt.

Use:
- `kb-dashboard docs list-guides`
- `kb-dashboard docs guide color-assignments`

---
# Source: guides/legend-configuration.md
---

Guide content is available via the CLI and intentionally excluded from llms-full.txt.

Use:
- `kb-dashboard docs list-guides`
- `kb-dashboard docs guide legend-configuration`

---
# Source: guides/esql-views.md
---

Guide content is available via the CLI and intentionally excluded from llms-full.txt.

Use:
- `kb-dashboard docs list-guides`
- `kb-dashboard docs guide esql-views`