docs/sources/datasources/elasticsearch/query-editor/index.md
Grafana provides a query editor for Elasticsearch. Elasticsearch queries are in Lucene format. For more information about query syntax, refer to Lucene query syntax and Query string syntax.
{{< admonition type="note" >}}
When composing Lucene queries, ensure that you use uppercase boolean operators: AND, OR, and NOT. Lowercase versions of these operators are not supported by the Lucene query syntax.
{{< /admonition >}}
{{< figure src="/static/img/docs/elasticsearch/elastic-query-editor-10.1.png" max-width="800px" class="docs-image--no-shadow" caption="Elasticsearch query editor" >}}
For general documentation on querying data sources in Grafana, including options and functions common to all query editors, refer to Query and transform data.
Elasticsearch groups aggregations into three categories:
Bucket - Bucket aggregations don't calculate metrics, they create buckets of documents based on field values, ranges and a variety of other criteria. Refer to Bucket aggregations for additional information. Use bucket aggregations under Group by when creating a metrics query in the query builder.
Metrics - Metrics aggregations perform calculations such as sum, average, min, etc. They can be single-value or multi-value. Refer to Metrics aggregations for additional information. Use metrics aggregations in the metrics query type in the query builder.
Pipeline - Pipeline aggregations work on the output of other aggregations rather than on documents or fields. Refer to Pipeline aggregations for additional information.
There are two types of queries you can create with the Elasticsearch query builder. Each type is explained in detail below.
Metrics queries aggregate data and produce calculations such as count, min, max, and more. Click the metric box to view options in the drop-down menu. The default is count.
Alias - Aliasing only applies to time series queries, where the last group is date histogram. This is ignored for any other type of query.
Metric - Metrics aggregations include:
Pipeline aggregations - Pipeline aggregations work on the output of other aggregations rather than on documents. The following pipeline aggregations are available:
You can select multiple metrics and group by multiple terms or filters when using the Elasticsearch query editor.
Use the + sign to the right to add multiple metrics to your query. Click on the eye icon next to Metric to hide metrics, and the garbage can icon to remove metrics.
Each group by option will have a different subset of options to further narrow your query.
The following options are specific to the date histogram bucket aggregation option.
@timestamp.30d (30 days). The default is Auto.0.0.+) or negative (-) values. Examples: 1h, 5s, 1d.Coordinated Universal Time.Configure the following options for the terms bucket aggregation option:
top or bottom.no limit.0.term value, doc count or count.Configure the following options for the filters bucket aggregation option:
hostname:"hostname1", product:"widget5". Use the * wildcard to match any number of characters.Configure the following options for the geo hash grid bucket aggregation option:
Configure the following options for the histogram bucket aggregation option:
0.The nested group by option is currently experimental, you can select a field and then settings specific to that field.
Click the + sign to add multiple group by options. The data will grouped in order (first by, then by).
{{< figure src="/static/img/docs/elasticsearch/group-by-then-by-10.2.png" max-width="850px" class="docs-image--no-shadow" caption="Group by options" >}}
Logs queries analyze Elasticsearch log data. You can configure the following options:
500.{{< docs/experimental product="The raw query editor" featureFlag="elasticsearchRawDSLQuery" >}}
The raw query editor allows you to write Elasticsearch queries using the native Elasticsearch Query DSL.
To access the raw query editor, click the Code toggle in the top-right corner of the query editor. You can switch between Builder and Code modes:
When in Code mode, you can write complete Elasticsearch query DSL in JSON format. The editor provides:
Shift+Alt+F to format your queryCtrl+Enter (or Cmd+Enter on Mac) to run the queryIf you want to filter by time range in a dashboard, you need to use the $__from and $__to macros in your raw DSL.
An example query applying dashboard time range using the @timestamp field:
{
"query": {
"bool": {
"must": [
{
"range": {
"@timestamp": {
"gte": "$__from",
"lte": "$__to",
"format": "epoch_millis"
}
}
}
]
}
}
}
The raw query editor supports all query types:
{{< docs/experimental product="The ES|QL query editor" featureFlag="elasticsearchESQLQuery" >}}
Introduced in Grafana v13.0, the ES|QL query editor lets you query Elasticsearch using ES|QL (Elasticsearch Query Language), a pipe-based query language. Unlike Lucene queries that rely on aggregation configuration in the builder UI, ES|QL lets you express filtering, aggregation, and transformation in a single query string.
For an introduction to ES|QL syntax and concepts, refer to Get started with ES|QL queries in the Elasticsearch documentation.
How the editor handles index selection depends on your data source configuration:
FROM command directly in your ES|QL query. This lets you query any index without creating a separate data source for each one. FROM $__index when the ES|QL field receives focus. You can override this and query a different index if needed.The ES|QL code editor provides:
The following examples show common ES|QL query patterns.
Count documents grouped by a field:
FROM logs-*
| STATS count = COUNT(*) BY host.name
| SORT count DESC
| LIMIT 10
Filter by a field value and compute an average over time intervals:
FROM metrics-*
| WHERE service.name == "api-gateway"
| STATS avg_duration = AVG(transaction.duration.us) BY @timestamp = BUCKET(@timestamp, 1 minute)
| SORT @timestamp
Search for specific patterns in log data:
FROM logs-*
| WHERE message LIKE "*error*" AND log.level == "ERROR"
| KEEP @timestamp, message, host.name, log.level
| SORT @timestamp DESC
| LIMIT 100
For more information about ES|QL syntax, commands, and functions, refer to the following Elasticsearch documentation:
FROM, WHERE, STATS, EVAL, KEEP, SORT, LIMIT, and more)You can also augment queries by using template variables.
Queries of terms have a 500-result limit by default.
To set a custom limit, set the size property in your query.