Get started with ES|QL in Discover

Elasticsearch Query Language (ES|QL) lets you explore Elasticsearch data in Discover without a data view. You write a piped query that names the data, then filter and sort it in the same editor. This tutorial walks through a first session on the sample web logs: run a query, read the table and chart, then keep what you found.

It assumes you can open Kibana and have data in Elasticsearch. You do not need ES|QL experience.

By the end of this tutorial, you can:

  • Open Discover in ES|QL mode
  • Write a piped query that selects fields, filters rows, and sorts the results
  • Read the results table and the chart that Discover builds from the query
  • Keep the session so you can reopen it, or add the session, table, or chart to a dashboard

To follow this tutorial, you need the following:

  • The enableESQL setting enabled in Kibana Advanced Settings. It is enabled by default.
  • The Kibana sample web logs. Add them from Add sample data. You can use your own indices instead. Replace kibana_sample_data_logs in the examples with a data source you can query.

Discover has two query modes. This tutorial uses ES|QL, which does not require a data view. Classic mode uses data views with Kibana Query Language (KQL) or Lucene. For classic mode, refer to Explore fields and data with Discover.

  1. Find Discover in the navigation menu or use the global search field.

  2. If the editor is not already in ES|QL mode, switch to it from either location:

    • Query in ES|QL (ES|QL or Try ES|QL in earlier versions) in the application menu.
    • Switch to ES|QL in the contextual menu ( ) of the active Discover tab. This affects only that tab.

    If the editor already shows an ES|QL query, skip this step. If that tab already has a KQL or Lucene query, Discover converts it when you switch. Switching back to classic mode does not restore that query. Refer to Revert to Discover's classic mode.

  3. Set the time range to Last 7 days.

    Sample data timestamps are relative to when you installed the set. If you added the sample web logs earlier, widen the range until the table has rows.

Result: The query editor is in ES|QL mode, and the time range covers the sample web logs.

Start with the operating system and RAM fields from the sample web logs.

  1. Copy the following query. To make queries easier to read, put each processing command on a new line.

    FROM kibana_sample_data_logs
| KEEP machine.os, machine.ram
    1. Query the sample web logs you added earlier.
    2. Keep only the machine.os and machine.ram fields in the results table.
    Note

    ES|QL keywords are not case sensitive.

  2. Select Search (or ▶Run in earlier versions).

Result: The table lists operating systems and RAM values. Discover also draws a chart from the query.

You don't have to write the next change from memory. The editor suggests commands and fields as you type, and it includes in-app help. Refer to Write queries with the ES|QL editor for those tools, the editor search bar, and AI assistance.

If you are not sure which index or field names to use on your own data, the editor can browse data sources and fields for you. Refer to Browse data sources and fields from the editor.

Add the visit destination so you can see where the visits went. LIMIT sets how many rows the query returns. These examples use LIMIT 10 to keep the table short.

  1. Replace the query with the following:

    FROM kibana_sample_data_logs
| KEEP machine.os, machine.ram, geo.dest
| LIMIT 10

  2. Select Search (or ▶Run in earlier versions).

Result: The table shows 10 rows. The chart updates from the new query and breaks the data down for you.

Note

When you don't use KEEP to retain specific fields, Discover does not break the chart down automatically. An option appears above the visualization so you can select a field.

Sort by RAM, and drop visits whose destination is Great Britain.

  1. Replace the query with the following:

    FROM kibana_sample_data_logs
| KEEP machine.os, machine.ram, geo.dest
| SORT machine.ram desc
| WHERE geo.dest != "GB"
| LIMIT 10

  2. Select Search (or ▶Run in earlier versions).

Result: The table and chart no longer include rows where geo.dest is GB. The table is sorted by machine.ram in descending order.

You can also add a WHERE clause by interacting with a value in the results table. Refer to Refine an ES|QL query from the results table. Column-header sorting only reorders the rows already retrieved. To sort the full data set, keep using SORT in the query. Refer to Sort query results.

To reopen this query, the columns, and the tabs later, save the Discover session.

You can also add the session or the chart to a dashboard.

You can save the current table to a dashboard too.

Refer to Save a Discover session for reuse.

Result: The session is saved, and you can reopen it or put it on a dashboard.

There is much more you can do with ES|QL to explore data and investigate in Discover.