Skip to content

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:

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

Lucene Query:

# 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):

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

Represents a KQL (Kibana Query Language) query configuration.

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

Attributes:

Name Type Description
kql str

The Kibana Query Language (KQL) query string to apply.
Show JSON schema: 
{
  "additionalProperties": false,
  "description": "Represents a KQL (Kibana Query Language) query configuration.\n\nKQL is the default query language in Kibana and provides a simplified syntax for filtering data.",
  "properties": {
    "kql": {
      "description": "The Kibana Query Language (KQL) query string to apply.",
      "title": "Kql",
      "type": "string"
    }
  },
  "required": [
    "kql"
  ],
  "title": "KqlQuery",
  "type": "object"
}

Usage Example (Dashboard Level):

dashboards:
- # ...
  query:
    kql: 'event.action:"user_login" AND event.outcome:success'

Lucene Query

Filters documents using the more expressive, but complex, Lucene query syntax.

Represents a Lucene query configuration.

Lucene provides a more powerful and flexible, but less friendly, syntax for querying data compared to KQL.

Attributes:

Name Type Description
lucene str

The Lucene query string to apply.
Show JSON schema: 
{
  "additionalProperties": false,
  "description": "Represents a Lucene query configuration.\n\nLucene provides a more powerful and flexible, but less friendly, syntax for querying data compared to KQL.",
  "properties": {
    "lucene": {
      "description": "The Lucene query string to apply.",
      "title": "Lucene",
      "type": "string"
    }
  },
  "required": [
    "lucene"
  ],
  "title": "LuceneQuery",
  "type": "object"
}

Usage Example (Dashboard Level):

dashboards:
- # ...
  query:
    lucene: '(geo.src:"US" OR geo.src:"CA") AND tags:"production"'

ESQL Query

Uses Elasticsearch Query Language (ESQL) for data retrieval and aggregation. ESQL queries are typically used by specific panel types that are designed to work with ESQL's tabular results (e.g., ESQL-driven charts or tables).

Represents an ESQL (Elasticsearch Query Language) query configuration.

ESQL is a powerful query language for Elasticsearch that provides a flexible syntax for filtering data.

The query can be provided as either: - A string: The complete ESQL query - A list of strings: Query parts that will be concatenated with pipe characters (|)

The list format supports YAML anchors for query reuse. When anchors reference arrays, they create nested lists which are automatically flattened before concatenation.

Example with YAML anchors

.base: &base_query - FROM logs-* - WHERE @timestamp > NOW() - 1h

query: - *base_query - STATS count = COUNT()

Results in:

FROM logs-*

| WHERE @timestamp > NOW() - 1h

| STATS count = COUNT()

Attributes:

Name Type Description
root str

Usage Example (Panel Level - String Format):

panels:
  - type: esql_backed_chart
    title: "Top User Agents by Count"
    query: |
      FROM "web-logs-*"
      | STATS count = COUNT(user_agent.name) BY user_agent.name
      | SORT count DESC
      | LIMIT 10

Usage Example (Panel Level - Array Format):

panels:
  - type: esql_backed_chart
    title: "Top User Agents by Count"
    query:
      - FROM "web-logs-*"
      - STATS count = COUNT(user_agent.name) BY user_agent.name
      - SORT count DESC
      - LIMIT 10

When using the array format, query parts are automatically joined with the ES|QL pipe operator (|). Nested arrays produced by YAML anchor expansion are automatically flattened before joining, allowing flexible composition of query components. This enables powerful query reuse patterns with YAML anchors.

Advanced: ES|QL Query Reuse with YAML Anchors

You can use YAML anchors (& and *) to create reusable ES|QL query components, reducing duplication when multiple panels query similar data. This pattern lets you define base queries, filters, or complete "view-like" abstractions once and reference them across panels. See ES|QL Query Reuse with YAML Anchors for detailed patterns and examples.

Query Scope

  • Dashboard Level Query: Defined under dashboard.query. This query is applied globally to all panels that do not explicitly override it or ignore global queries. KQL and Lucene are supported at this level.
  • Panel Level Query: Defined under panel.query (for panels that support it, e.g., Lens panels, ESQL panels). This query is specific to the panel and is often combined with (or can override) the dashboard-level query, depending on the panel's behavior.
  • Lens panels typically use KQL for their panel-specific query.
  • ESQL-specific panels will use an ESQL query string.