Documentation Plugins OpenSearch Query editor

OpenSearch query editor

This document explains how to use the OpenSearch query editor to build queries for metrics, logs, and traces.

The query editor supports two query languages:

• Lucene: The default query language with support for metric aggregations, bucket aggregations, logs, raw data, and trace analytics.
• PPL (Piped Processing Language): An alternative query language that uses a pipe syntax for data exploration. PPL must be enabled in the data source configuration.

Select the query language from the Query type drop-down at the top of the query editor.

Lucene queries

Lucene is the default query language. When using Lucene, select a query type from the Lucene Query Type drop-down to control the kind of data returned.

The following Lucene query types are available:

Metric queries

Metric queries combine metric aggregations with bucket aggregations to produce time-series or tabular data. Use the plus and minus icons to add or remove metrics and group-by clauses. Click on an aggregation to expand its options.

Metric aggregations

The following metric aggregations are available:

Bucket aggregations

Bucket aggregations group documents into buckets for metric calculation:

Each bucket aggregation has additional settings you can expand by clicking on the aggregation row:

• Date Histogram: Interval (auto, 10s, 1m, 5m, 10m, 20m, 1h, 1d, or custom), Min Doc Count, Trim Edges, Offset.
• Terms: Order (Top/Bottom), Size, Min Doc Count, Order By (Term value, Doc Count, or a metric), Missing, Execution Hint.
• Histogram: Interval (numeric), Min Doc Count.
• Filters: Custom Lucene queries per filter, each with an optional Label.
• Geo Hash Grid: Precision.

Pipeline metrics

Pipeline aggregations compute values from the output of other aggregations rather than from documents directly. Use the eye icon next to a metric to hide it from the visualization while keeping it available as input for a pipeline metric.

The following pipeline aggregations are available:

Series naming and alias patterns

You can control the name of time series using the Alias field. This field only appears for time-series queries where the last bucket aggregation is a Date Histogram.

The following patterns are supported:

Log queries

Select Logs as the Lucene query type to query log data. Enter a Lucene query to filter log messages.

The fields used for log messages and log levels are configured in the data source settings.

When using Explore, Grafana automatically generates a logs volume histogram alongside log results, showing the distribution of log entries over time.

Lucene query examples

The following examples show common Lucene query patterns:

Raw Data and Raw Document queries

Raw Data returns documents in a tabular format suitable for the table panel. Raw Document returns the full document JSON. Both types accept a Lucene query string to filter results.

Each type has the following settings:

Trace queries

Select Traces as the Lucene query type to query distributed trace data. Traces are only available using Lucene queries.

The trace query type has the following additional settings:

View all traces

To view a list of traces:

1. Leave the Query field blank or enter a Lucene query to filter.
2. Set Lucene Query Type to Traces.
3. Run the query.
4. Select the Table visualization if needed.

Click a trace ID in the table to open that trace in the Explore trace view.

View a single trace

To view a specific trace:

1. Enter traceId: <YOUR_TRACE_ID> in the Query field.
2. Set Lucene Query Type to Traces.
3. Run the query.
4. Select the Traces visualization if needed.

Service map

Toggle Service Map to visualize the relationships between services in your traced application as a node graph.

Each service is represented as a node showing:

• Average latency
• Average throughput per minute
• Error and success rates (shown as the node border)

Click any node to view all metrics for that service. Arrows between nodes represent requests between services — click an arrow to see the operations involved.

You can view the service map for all traces in the current time range or for a single trace by querying a specific traceId.

PPL queries

Piped Processing Language (PPL) is an alternative query language that uses a pipe (|) syntax to chain commands for data exploration and transformation.

To use PPL, ensure it’s enabled in the data source configuration.

Write PPL queries

The PPL query editor provides:

• Syntax highlighting and auto-completion for PPL keywords and index fields
• Press Shift+Enter to run the query
• Click Kickstart your query to open a modal with sample queries you can use as starting points

To narrow down field suggestions, specify an index name in the data source settings.

PPL format options

Select a format from the Format drop-down to control how results are displayed. The default format is Table.

PPL query examples

The following examples show common PPL query patterns:

Filter logs by a field value:

Copy

source = opensearch_dashboards_sample_data_logs | where geo.src = "US"

Search flights with conditions:

Copy

search source=opensearch_dashboards_sample_data_flights | where AvgTicketPrice > 1150 | where FlightDelay = true

Find documents where a field contains a specific word:

Copy

SOURCE = my_index | WHERE LIKE(title, '%wind%') LIMIT 10

Aggregate data for time-series visualization (use with Time series format):

Copy

source = my_index | eval dateValue = timestamp(timestamp) | stats count(response) by dateValue

For more information about PPL syntax and supported commands, refer to the OpenSearch PPL documentation.

Ad hoc filters

The OpenSearch data source supports ad hoc filters for both Lucene and PPL queries. Ad hoc filters let you add key-value filters from the dashboard without modifying the query. Add an ad hoc filter variable to your dashboard, select the OpenSearch data source, and use it to dynamically filter query results.

For more information about ad hoc filters, refer to the Grafana ad hoc filters documentation.

Query language references

For detailed syntax and command documentation, refer to the official OpenSearch documentation:

• Lucene query syntax
• PPL commands reference
• PPL functions reference
• Metric aggregations
• Bucket aggregations
• Pipeline aggregations
• Trace analytics with Data Prepper