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:

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:

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:

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.

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

Attributes:

Name	Type	Description
`label_position`	`Literal['inline', 'above'] \| None`	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.

Show JSON schema:

{
  "additionalProperties": false,
  "description": "Settings for controls in a dashboard, defining their behavior and appearance.",
  "properties": {
    "label_position": {
      "anyOf": [
        {
          "enum": [
            "inline",
            "above"
          ],
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The position of the control label, either 'inline' or 'above'. Defaults to 'inline' if not set.",
      "title": "Label Position"
    },
    "apply_global_filters": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Whether to apply global filters to the control. Defaults to true if not set.",
      "title": "Apply Global Filters"
    },
    "apply_global_timerange": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Whether to apply the global time range to the control. Defaults to true if not set.",
      "title": "Apply Global Timerange"
    },
    "ignore_zero_results": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Whether to ignore controls that return zero results. Defaults to true if not set.",
      "title": "Ignore Zero Results"
    },
    "chain_controls": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Whether to chain controls together, allowing one control's selection to filter the next. Defaults to true if not set.",
      "title": "Chain Controls"
    },
    "click_to_apply": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Whether to require users to click the apply button before applying changes. Defaults to false if not set.",
      "title": "Click To Apply"
    }
  },
  "title": "ControlSettings",
  "type": "object"
}

Options List Control¶

Allows users to select one or more values from a list to filter data.

Represents an Options List control.

This control allows users to select one or more values from a list to filter data.

Attributes:

Name	Type	Description
`type`	`Literal['options']`
`field`	`str`	The name of the field within the data view that the control is associated with.
`fill_width`	`bool`	If true, the control will automatically adjust its width to fill available space.
`match_technique`	`MatchTechnique \| None`	The search technique used for filtering options (e.g., 'prefix', 'contains', 'exact').
`wait_for_results`	`bool \| None`	If set to true, delay the display of the list of values until the results are fully loaded.
`preselected`	`list[str]`	A list of options that are preselected when the control is initialized.
`multiple`	`bool \| None`	If true, allow multiple selection.
`data_view`	`str`	The ID or title of the data view (index pattern) the control operates on.

Show JSON schema:

{
  "$defs": {
    "MatchTechnique": {
      "description": "Enumeration for match techniques used in options list controls.",
      "enum": [
        "prefix",
        "contains",
        "exact"
      ],
      "title": "MatchTechnique",
      "type": "string"
    }
  },
  "additionalProperties": false,
  "description": "Represents an Options List control.\n\nThis control allows users to select one or more values from a list\nto filter data.",
  "properties": {
    "id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "A unique identifier. If not provided, one will be generated automatically.",
      "title": "Id"
    },
    "width": {
      "anyOf": [
        {
          "enum": [
            "small",
            "medium",
            "large"
          ],
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The width of the control in the dashboard layout. If not set, defaults to 'medium'.",
      "title": "Width"
    },
    "label": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The display label for the control. If not provided, a label may be inferred.",
      "title": "Label"
    },
    "type": {
      "const": "options",
      "default": "options",
      "title": "Type",
      "type": "string"
    },
    "field": {
      "description": "The name of the field within the data view that the control is associated with.",
      "title": "Field",
      "type": "string"
    },
    "fill_width": {
      "default": false,
      "description": "If true, the control will automatically adjust its width to fill available space.",
      "title": "Fill Width",
      "type": "boolean"
    },
    "match_technique": {
      "anyOf": [
        {
          "$ref": "#/$defs/MatchTechnique"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The search technique used for filtering options (e.g., 'prefix', 'contains', 'exact')."
    },
    "wait_for_results": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "If set to true, delay the display of the list of values until the results are fully loaded.",
      "title": "Wait For Results"
    },
    "preselected": {
      "description": "A list of options that are preselected when the control is initialized.",
      "items": {
        "type": "string"
      },
      "title": "Preselected",
      "type": "array"
    },
    "multiple": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "If true, allow multiple selection.",
      "title": "Multiple"
    },
    "data_view": {
      "description": "The ID or title of the data view (index pattern) the control operates on.",
      "title": "Data View",
      "type": "string"
    }
  },
  "required": [
    "field",
    "data_view"
  ],
  "title": "OptionsListControl",
  "type": "object"
}

Match Technique Options¶

Enumeration for match techniques used in options list controls.

PREFIX `class-attribute` `instance-attribute` ¶

PREFIX = 'prefix'

Match technique that filters options starting with the input text.

CONTAINS `class-attribute` `instance-attribute` ¶

CONTAINS = 'contains'

Match technique that filters options containing the input text.

EXACT `class-attribute` `instance-attribute` ¶

EXACT = 'exact'

Match technique that filters options matching the input text exactly.

Range Slider Control¶

Allows users to select a range of numeric values to filter data.

Represents a Range Slider control.

This control allows users to select a range of numeric or date values to filter data.

Attributes:

Name	Type	Description
`type`	`Literal['range']`
`fill_width`	`bool`	If true, the control will automatically adjust its width to fill available space.
`field`	`str`	The name of the field within the data view that the control is associated with.
`step`	`int \| float \| None`	The step value for the range, defining the granularity of selections.
`data_view`	`str`	The ID or title of the data view (index pattern) the control operates on.

Show JSON schema:

{
  "additionalProperties": false,
  "description": "Represents a Range Slider control.\n\nThis control allows users to select a range of numeric or date values\nto filter data.",
  "properties": {
    "id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "A unique identifier. If not provided, one will be generated automatically.",
      "title": "Id"
    },
    "width": {
      "anyOf": [
        {
          "enum": [
            "small",
            "medium",
            "large"
          ],
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The width of the control in the dashboard layout. If not set, defaults to 'medium'.",
      "title": "Width"
    },
    "label": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The display label for the control. If not provided, a label may be inferred.",
      "title": "Label"
    },
    "type": {
      "const": "range",
      "default": "range",
      "title": "Type",
      "type": "string"
    },
    "fill_width": {
      "default": false,
      "description": "If true, the control will automatically adjust its width to fill available space.",
      "title": "Fill Width",
      "type": "boolean"
    },
    "field": {
      "description": "The name of the field within the data view that the control is associated with.",
      "title": "Field",
      "type": "string"
    },
    "step": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The step value for the range, defining the granularity of selections.",
      "title": "Step"
    },
    "data_view": {
      "description": "The ID or title of the data view (index pattern) the control operates on.",
      "title": "Data View",
      "type": "string"
    }
  },
  "required": [
    "field",
    "data_view"
  ],
  "title": "RangeSliderControl",
  "type": "object"
}

Time Slider Control¶

Allows users to select a sub-section of the dashboard's current time range. This control does not use a data_view or field as it operates on the global time context.

Represents a Time Slider control.

This control allows users to select a time range to filter data by adjusting start and end offsets within the global time range.

Attributes:

Name	Type	Description
`type`	`Literal['time']`
`start_offset`	`float \| None`	The start offset for the time range as a %, defining the beginning of the selection.
`end_offset`	`float \| None`	The end offset for the time range as a %, defining the end of the selection.

Show JSON schema:

{
  "additionalProperties": false,
  "description": "Represents a Time Slider control.\n\nThis control allows users to select a time range to filter data\nby adjusting start and end offsets within the global time range.",
  "properties": {
    "id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "A unique identifier. If not provided, one will be generated automatically.",
      "title": "Id"
    },
    "width": {
      "anyOf": [
        {
          "enum": [
            "small",
            "medium",
            "large"
          ],
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The width of the control in the dashboard layout. If not set, defaults to 'medium'.",
      "title": "Width"
    },
    "label": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The display label for the control. If not provided, a label may be inferred.",
      "title": "Label"
    },
    "type": {
      "const": "time",
      "default": "time",
      "title": "Type",
      "type": "string"
    },
    "start_offset": {
      "anyOf": [
        {
          "maximum": 1,
          "minimum": 0,
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The start offset for the time range as a %, defining the beginning of the selection.",
      "title": "Start Offset"
    },
    "end_offset": {
      "anyOf": [
        {
          "maximum": 1,
          "minimum": 0,
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The end offset for the time range as a %, defining the end of the selection.",
      "title": "End Offset"
    }
  },
  "title": "TimeSliderControl",
  "type": "object"
}

Validators:

validate_offsets

validate_offsets `pydantic-validator` ¶

validate_offsets()

Ensure that start_offset is less than end_offset.

Note on Time Slider Offsets: The YAML configuration expects start_offset and end_offset as float values between 0.0 (0%) and 1.0 (100%). Kibana internally represents these as percentages from 0.0 to 100.0. If not provided, Kibana defaults to 0.0 for start and 100.0 for end.

ES|QL Controls¶

ES|QL controls allow users to filter ES|QL visualizations via variables. There are two main types:

ES|QL Field/Function Controls - For field/function selection (FIELDS, FUNCTIONS variable types)
ES|QL Value Controls - For value selection (VALUES, MULTI_VALUES, TIME_LITERAL variable types)

ES|QL Field Control¶

For field selection in ES|QL visualizations. Only supports static values via choices.

ES|QL control for single field selection from static list.

Attributes:

Name	Type	Description
`type`	`Literal['esql']`
`variable_name`	`str`	The name of the ES\|QL variable.
`variable_type`	`Literal[<ESQLVariableType.FIELDS: 'fields'>]`	The type of variable ('fields').
`choices`	`list[str]`	The static list of available fields for this control.
`default`	`str \| None`	Default selected field.

Show JSON schema:

{
  "additionalProperties": false,
  "description": "ES|QL control for single field selection from static list.",
  "properties": {
    "id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "A unique identifier. If not provided, one will be generated automatically.",
      "title": "Id"
    },
    "width": {
      "anyOf": [
        {
          "enum": [
            "small",
            "medium",
            "large"
          ],
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The width of the control in the dashboard layout. If not set, defaults to 'medium'.",
      "title": "Width"
    },
    "label": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The display label for the control. If not provided, a label may be inferred.",
      "title": "Label"
    },
    "type": {
      "const": "esql",
      "default": "esql",
      "title": "Type",
      "type": "string"
    },
    "variable_name": {
      "description": "The name of the ES|QL variable.",
      "title": "Variable Name",
      "type": "string"
    },
    "variable_type": {
      "const": "fields",
      "default": "fields",
      "description": "The type of variable ('fields').",
      "title": "Variable Type",
      "type": "string"
    },
    "choices": {
      "description": "The static list of available fields for this control.",
      "items": {
        "type": "string"
      },
      "title": "Choices",
      "type": "array"
    },
    "default": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Default selected field.",
      "title": "Default"
    }
  },
  "required": [
    "variable_name",
    "choices"
  ],
  "title": "ESQLFieldControl",
  "type": "object"
}

Validators:

validate_default

validate_default `pydantic-validator` ¶

validate_default()

Validate that default value exists in choices.

ES|QL Function Control¶

For function selection in ES|QL visualizations. Only supports static values via choices.

ES|QL control for single function selection from static list.

Attributes:

Name	Type	Description
`type`	`Literal['esql']`
`variable_name`	`str`	The name of the ES\|QL variable.
`variable_type`	`Literal[<ESQLVariableType.FUNCTIONS: 'functions'>]`	The type of variable ('functions').
`choices`	`list[str]`	The static list of available functions for this control.
`default`	`str \| None`	Default selected function.

Show JSON schema:

{
  "additionalProperties": false,
  "description": "ES|QL control for single function selection from static list.",
  "properties": {
    "id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "A unique identifier. If not provided, one will be generated automatically.",
      "title": "Id"
    },
    "width": {
      "anyOf": [
        {
          "enum": [
            "small",
            "medium",
            "large"
          ],
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The width of the control in the dashboard layout. If not set, defaults to 'medium'.",
      "title": "Width"
    },
    "label": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The display label for the control. If not provided, a label may be inferred.",
      "title": "Label"
    },
    "type": {
      "const": "esql",
      "default": "esql",
      "title": "Type",
      "type": "string"
    },
    "variable_name": {
      "description": "The name of the ES|QL variable.",
      "title": "Variable Name",
      "type": "string"
    },
    "variable_type": {
      "const": "functions",
      "default": "functions",
      "description": "The type of variable ('functions').",
      "title": "Variable Type",
      "type": "string"
    },
    "choices": {
      "description": "The static list of available functions for this control.",
      "items": {
        "type": "string"
      },
      "title": "Choices",
      "type": "array"
    },
    "default": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Default selected function.",
      "title": "Default"
    }
  },
  "required": [
    "variable_name",
    "choices"
  ],
  "title": "ESQLFunctionControl",
  "type": "object"
}

Validators:

validate_default

validate_default `pydantic-validator` ¶

validate_default()

Validate that default value exists in choices.

Field/Function Control Examples¶

controls:
  # Field selection control
  - type: esql
    variable_name: selected_field
    variable_type: fields
    choices: ["@timestamp", "host.name", "message", "log.level"]
    label: Select Field
    default: "@timestamp"

  # Function selection control
  - type: esql
    variable_name: aggregate_fn
    variable_type: functions
    choices: ["COUNT", "AVG", "SUM", "MAX", "MIN"]
    label: Aggregate Function
    default: "COUNT"

Using ES|QL Variables in Panels:

ES|QL control variables can be referenced in ES|QL panel queries:

Value variables (VALUES, MULTI_VALUES, TIME_LITERAL) use single ? prefix: ?variable_name
Field/function variables (FIELDS, FUNCTIONS) use double ?? prefix: ??variable_name

panels:
  # Using value variable
  - title: Filtered Requests
    esql:
      type: metric
      query:
        - FROM logs-*
        - WHERE http.response.status_code == ?status_code
        - STATS total = COUNT(*)

  # Using field variable
  - title: Dynamic Field Display
    esql:
      type: datatable
      query:
        - FROM logs-*
        - KEEP ??selected_field
        - LIMIT 100

ES|QL Static Single-Select Control (DEPRECATED)¶

Represents an ES|QL control with static values for single selection.

This control allows users to select a single value from a predefined list to filter ES|QL visualizations via variables.

Attributes:

Name	Type	Description
`type`	`Literal['esql']`
`variable_name`	`str`	The name of the ES\|QL variable (e.g., 'status_code').
`variable_type`	`ESQLVariableType`	The type of variable ('time_literal', 'fields', 'values', 'multi_values', 'functions').
`choices`	`list[str]`	The static list of available values for this control.
`default`	`str \| None`	Default selected value.
`multiple`	`Literal[False] \| None`	If true, allow multiple selection. Must be None or False for this control type.

Show JSON schema:

{
  "$defs": {
    "ESQLVariableType": {
      "description": "Types of ES|QL variables.\n\nThese match the ESQLVariableType enum from Kibana's kbn-esql-types package.",
      "enum": [
        "time_literal",
        "fields",
        "values",
        "multi_values",
        "functions"
      ],
      "title": "ESQLVariableType",
      "type": "string"
    }
  },
  "additionalProperties": false,
  "description": "Represents an ES|QL control with static values for single selection.\n\nThis control allows users to select a single value from a predefined list\nto filter ES|QL visualizations via variables.",
  "properties": {
    "id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "A unique identifier. If not provided, one will be generated automatically.",
      "title": "Id"
    },
    "width": {
      "anyOf": [
        {
          "enum": [
            "small",
            "medium",
            "large"
          ],
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The width of the control in the dashboard layout. If not set, defaults to 'medium'.",
      "title": "Width"
    },
    "label": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The display label for the control. If not provided, a label may be inferred.",
      "title": "Label"
    },
    "type": {
      "const": "esql",
      "default": "esql",
      "title": "Type",
      "type": "string"
    },
    "variable_name": {
      "description": "The name of the ES|QL variable (e.g., 'status_code').",
      "title": "Variable Name",
      "type": "string"
    },
    "variable_type": {
      "$ref": "#/$defs/ESQLVariableType",
      "default": "values",
      "description": "The type of variable ('time_literal', 'fields', 'values', 'multi_values', 'functions')."
    },
    "choices": {
      "description": "The static list of available values for this control.",
      "items": {
        "type": "string"
      },
      "title": "Choices",
      "type": "array"
    },
    "default": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Default selected value.",
      "title": "Default"
    },
    "multiple": {
      "anyOf": [
        {
          "const": false,
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "If true, allow multiple selection. Must be None or False for this control type.",
      "title": "Multiple"
    }
  },
  "required": [
    "variable_name",
    "choices"
  ],
  "title": "ESQLStaticSingleSelectControl",
  "type": "object"
}

Validators:

validate_defaults

validate_defaults `pydantic-validator` ¶

validate_defaults()

Validate that default value exists in choices.

Static Values Example¶

controls:
  # Multi-select with explicit multiple property
  - type: esql
    variable_name: environment
    variable_type: values
    choices: ["production", "staging", "development"]
    label: Environment
    multiple: true
    default: ["production", "staging"]

  # Single-select with string default (auto-infers multiple: false)
  - type: esql
    variable_name: status
    variable_type: values
    choices: ["200", "404", "500"]
    label: HTTP Status
    default: "200"

ES|QL Static Multi-Select Control (DEPRECATED)¶

Represents an ES|QL control with static values for multiple selection.

This control allows users to select multiple values from a predefined list to filter ES|QL visualizations via variables.

Attributes:

Name	Type	Description
`type`	`Literal['esql']`
`variable_name`	`str`	The name of the ES\|QL variable (e.g., 'status_code').
`variable_type`	`ESQLVariableType`	The type of variable ('time_literal', 'fields', 'values', 'multi_values', 'functions').
`choices`	`list[str]`	The static list of available values for this control.
`default`	`list[str] \| None`	Default selected values.
`multiple`	`Literal[True]`	Must be True for this control type.

Show JSON schema:

{
  "$defs": {
    "ESQLVariableType": {
      "description": "Types of ES|QL variables.\n\nThese match the ESQLVariableType enum from Kibana's kbn-esql-types package.",
      "enum": [
        "time_literal",
        "fields",
        "values",
        "multi_values",
        "functions"
      ],
      "title": "ESQLVariableType",
      "type": "string"
    }
  },
  "additionalProperties": false,
  "description": "Represents an ES|QL control with static values for multiple selection.\n\nThis control allows users to select multiple values from a predefined list\nto filter ES|QL visualizations via variables.",
  "properties": {
    "id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "A unique identifier. If not provided, one will be generated automatically.",
      "title": "Id"
    },
    "width": {
      "anyOf": [
        {
          "enum": [
            "small",
            "medium",
            "large"
          ],
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The width of the control in the dashboard layout. If not set, defaults to 'medium'.",
      "title": "Width"
    },
    "label": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The display label for the control. If not provided, a label may be inferred.",
      "title": "Label"
    },
    "type": {
      "const": "esql",
      "default": "esql",
      "title": "Type",
      "type": "string"
    },
    "variable_name": {
      "description": "The name of the ES|QL variable (e.g., 'status_code').",
      "title": "Variable Name",
      "type": "string"
    },
    "variable_type": {
      "$ref": "#/$defs/ESQLVariableType",
      "default": "values",
      "description": "The type of variable ('time_literal', 'fields', 'values', 'multi_values', 'functions')."
    },
    "choices": {
      "description": "The static list of available values for this control.",
      "items": {
        "type": "string"
      },
      "title": "Choices",
      "type": "array"
    },
    "default": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Default selected values.",
      "title": "Default"
    },
    "multiple": {
      "const": true,
      "default": true,
      "description": "Must be True for this control type.",
      "title": "Multiple",
      "type": "boolean"
    }
  },
  "required": [
    "variable_name",
    "choices"
  ],
  "title": "ESQLStaticMultiSelectControl",
  "type": "object"
}

Validators:

validate_defaults

validate_defaults `pydantic-validator` ¶

validate_defaults()

Validate that default values exist in choices.

ES|QL Query-Driven Single-Select Control (DEPRECATED)¶

Represents an ES|QL control with query-driven values for single selection.

This control dynamically fetches available values from an ES|QL query to filter ES|QL visualizations via variables.

Attributes:

Name	Type	Description
`type`	`Literal['esql']`
`variable_name`	`str`	The name of the ES\|QL variable (e.g., 'status_code').
`variable_type`	`ESQLVariableType`	The type of variable ('time_literal', 'fields', 'values', 'multi_values', 'functions').
`query`	`str`	The ES\|QL query that returns the available values for this control.
`multiple`	`Literal[False] \| None`	Must be None or False for single-select.
`default`	`str \| None`	Default selected value.

Show JSON schema:

{
  "$defs": {
    "ESQLVariableType": {
      "description": "Types of ES|QL variables.\n\nThese match the ESQLVariableType enum from Kibana's kbn-esql-types package.",
      "enum": [
        "time_literal",
        "fields",
        "values",
        "multi_values",
        "functions"
      ],
      "title": "ESQLVariableType",
      "type": "string"
    }
  },
  "additionalProperties": false,
  "description": "Represents an ES|QL control with query-driven values for single selection.\n\nThis control dynamically fetches available values from an ES|QL query\nto filter ES|QL visualizations via variables.",
  "properties": {
    "id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "A unique identifier. If not provided, one will be generated automatically.",
      "title": "Id"
    },
    "width": {
      "anyOf": [
        {
          "enum": [
            "small",
            "medium",
            "large"
          ],
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The width of the control in the dashboard layout. If not set, defaults to 'medium'.",
      "title": "Width"
    },
    "label": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The display label for the control. If not provided, a label may be inferred.",
      "title": "Label"
    },
    "type": {
      "const": "esql",
      "default": "esql",
      "title": "Type",
      "type": "string"
    },
    "variable_name": {
      "description": "The name of the ES|QL variable (e.g., 'status_code').",
      "title": "Variable Name",
      "type": "string"
    },
    "variable_type": {
      "$ref": "#/$defs/ESQLVariableType",
      "default": "values",
      "description": "The type of variable ('time_literal', 'fields', 'values', 'multi_values', 'functions')."
    },
    "query": {
      "description": "The ES|QL query that returns the available values for this control.",
      "minLength": 1,
      "title": "Query",
      "type": "string"
    },
    "multiple": {
      "anyOf": [
        {
          "const": false,
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Must be None or False for single-select.",
      "title": "Multiple"
    },
    "default": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Default selected value.",
      "title": "Default"
    }
  },
  "required": [
    "variable_name",
    "query"
  ],
  "title": "ESQLQuerySingleSelectControl",
  "type": "object"
}

ES|QL Query-Driven Multi-Select Control (DEPRECATED)¶

Represents an ES|QL control with query-driven values for multiple selection.

This control dynamically fetches available values from an ES|QL query to filter ES|QL visualizations via variables.

Attributes:

Name	Type	Description
`type`	`Literal['esql']`
`variable_name`	`str`	The name of the ES\|QL variable (e.g., 'status_code').
`variable_type`	`ESQLVariableType`	The type of variable ('time_literal', 'fields', 'values', 'multi_values', 'functions').
`query`	`str`	The ES\|QL query that returns the available values for this control.
`multiple`	`Literal[True]`	Must be True for multi-select.
`default`	`list[str] \| None`	Default selected values.

Show JSON schema:

{
  "$defs": {
    "ESQLVariableType": {
      "description": "Types of ES|QL variables.\n\nThese match the ESQLVariableType enum from Kibana's kbn-esql-types package.",
      "enum": [
        "time_literal",
        "fields",
        "values",
        "multi_values",
        "functions"
      ],
      "title": "ESQLVariableType",
      "type": "string"
    }
  },
  "additionalProperties": false,
  "description": "Represents an ES|QL control with query-driven values for multiple selection.\n\nThis control dynamically fetches available values from an ES|QL query\nto filter ES|QL visualizations via variables.",
  "properties": {
    "id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "A unique identifier. If not provided, one will be generated automatically.",
      "title": "Id"
    },
    "width": {
      "anyOf": [
        {
          "enum": [
            "small",
            "medium",
            "large"
          ],
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The width of the control in the dashboard layout. If not set, defaults to 'medium'.",
      "title": "Width"
    },
    "label": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The display label for the control. If not provided, a label may be inferred.",
      "title": "Label"
    },
    "type": {
      "const": "esql",
      "default": "esql",
      "title": "Type",
      "type": "string"
    },
    "variable_name": {
      "description": "The name of the ES|QL variable (e.g., 'status_code').",
      "title": "Variable Name",
      "type": "string"
    },
    "variable_type": {
      "$ref": "#/$defs/ESQLVariableType",
      "default": "values",
      "description": "The type of variable ('time_literal', 'fields', 'values', 'multi_values', 'functions')."
    },
    "query": {
      "description": "The ES|QL query that returns the available values for this control.",
      "minLength": 1,
      "title": "Query",
      "type": "string"
    },
    "multiple": {
      "const": true,
      "default": true,
      "description": "Must be True for multi-select.",
      "title": "Multiple",
      "type": "boolean"
    },
    "default": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Default selected values.",
      "title": "Default"
    }
  },
  "required": [
    "variable_name",
    "query"
  ],
  "title": "ESQLQueryMultiSelectControl",
  "type": "object"
}

Query-Driven Example¶

controls:
  # Query-driven single-select
  - type: esql
    variable_name: status_code
    variable_type: values
    query: FROM logs-* | STATS count BY http.response.status_code | KEEP http.response.status_code | LIMIT 20
    label: HTTP Status Code
    multiple: false

  # Query-driven multi-select
  - type: esql
    variable_name: host_names
    variable_type: values
    query: FROM logs-* | STATS count BY host.name | KEEP host.name
    label: Host Names
    multiple: true

  # Query-driven single-select with default value
  - type: esql
    variable_name: region
    variable_type: values
    query: FROM logs-* | STATS count BY cloud.region | KEEP cloud.region
    label: Cloud Region
    multiple: false
    default: us-east-1

  # Query-driven multi-select with default values
  - type: esql
    variable_name: services
    variable_type: values
    query: FROM logs-* | STATS count BY service.name | KEEP service.name
    label: Services
    multiple: true
    default: ["api-gateway", "auth-service"]

Note: Default values for query-driven controls are not validated against query results since the values are fetched dynamically at runtime.

Important: ES|QL control queries must return exactly one column containing the values to display in the control. Use KEEP to select only the field column after aggregation.

ES|QL Variable Types¶

Types of ES|QL variables.

These match the ESQLVariableType enum from Kibana's kbn-esql-types package.

TIME_LITERAL `class-attribute` `instance-attribute` ¶

TIME_LITERAL = 'time_literal'

Time literal variable type.

FIELDS `class-attribute` `instance-attribute` ¶

FIELDS = 'fields'

Fields variable type.

VALUES `class-attribute` `instance-attribute` ¶

VALUES = 'values'

Values variable type.

MULTI_VALUES `class-attribute` `instance-attribute` ¶

MULTI_VALUES = 'multi_values'

Multi-values variable type.

FUNCTIONS `class-attribute` `instance-attribute` ¶

FUNCTIONS = 'functions'

Functions variable type.

Dashboard Configuration

Controls Configuration¶

Minimal Configuration Examples¶

Complex Configuration Example¶

Full Configuration Options¶

Control Settings (settings.controls)¶

Options List Control¶

Match Technique Options¶

PREFIX class-attribute instance-attribute ¶

CONTAINS class-attribute instance-attribute ¶

EXACT class-attribute instance-attribute ¶

Range Slider Control¶

Time Slider Control¶

validate_offsets pydantic-validator ¶

ES|QL Controls¶

ES|QL Field Control¶

validate_default pydantic-validator ¶

ES|QL Function Control¶

validate_default pydantic-validator ¶

Field/Function Control Examples¶

ES|QL Static Single-Select Control (DEPRECATED)¶

validate_defaults pydantic-validator ¶

Static Values Example¶

ES|QL Static Multi-Select Control (DEPRECATED)¶

validate_defaults pydantic-validator ¶

ES|QL Query-Driven Single-Select Control (DEPRECATED)¶

ES|QL Query-Driven Multi-Select Control (DEPRECATED)¶

Query-Driven Example¶

ES|QL Variable Types¶

TIME_LITERAL class-attribute instance-attribute ¶

FIELDS class-attribute instance-attribute ¶

VALUES class-attribute instance-attribute ¶

MULTI_VALUES class-attribute instance-attribute ¶

FUNCTIONS class-attribute instance-attribute ¶

Related Documentation¶

Control Settings (`settings.controls`)¶

PREFIX `class-attribute` `instance-attribute` ¶

CONTAINS `class-attribute` `instance-attribute` ¶

EXACT `class-attribute` `instance-attribute` ¶

validate_offsets `pydantic-validator` ¶

validate_default `pydantic-validator` ¶

validate_default `pydantic-validator` ¶

validate_defaults `pydantic-validator` ¶

validate_defaults `pydantic-validator` ¶

TIME_LITERAL `class-attribute` `instance-attribute` ¶

FIELDS `class-attribute` `instance-attribute` ¶

VALUES `class-attribute` `instance-attribute` ¶

MULTI_VALUES `class-attribute` `instance-attribute` ¶

FUNCTIONS `class-attribute` `instance-attribute` ¶