Kibana Query Language

The Kibana Query Language (KQL) is a simple syntax for filtering Elasticsearch data using free text search or field-based search. KQL is only used for filtering data, and has no role in sorting or aggregating the data.

KQL is able to suggest field names, values, and operators as you type. The performance of the suggestions is controlled by Kibana settings:

KQL has a different set of features than the Lucene query syntax. KQL is able to query nested fields and scripted fields. KQL does not support regular expressions or searching with fuzzy terms. To use the legacy Lucene syntax, click KQL next to the Search field, and then turn off KQL.

A terms query uses exact search terms. Spaces separate each search term, and only one term is required to match the document. Use quotation marks to indicate a phrase match.

To query using exact search terms, enter the field name followed by : and then the values separated by spaces:

http.response.status_code:400 401 404

For text fields, this will match any value regardless of order:

http.response.body.content.text:quick brown fox

To query for an exact phrase, use quotation marks around the values:

http.response.body.content.text:"quick brown fox"

Field names are not required by KQL. When a field name is not provided, terms will be matched by the default fields in your index settings. To search across fields:

"quick brown fox"

KQL supports or, and, and not. By default, and has a higher precedence than or. To override the default precedence, group operators in parentheses. These operators can be upper or lower case.

To match documents where response is 200, extension is php, or both:

response:200 or extension:php

To match documents where response is 200 and extension is php:

response:200 and extension:php

To match documents where response is 200 or 404.

response:(200 or 404)

To match documents where response is 200 and extension is either php or css:

response:200 and (extension:php or extension:css)

To match documents where response is 200 and extension is php or extension is css, and response is anything:

response:200 and extension:php or extension:css

To match documents where response is not 200:

not response:200

To match documents where response is 200 but extension is not php or css.

response:200 and not (extension:php or extension:css)

To match multi-value fields that contain a list of terms:

tags:(success and info and security)

KQL supports >, >=, <, and <= on numeric and date types.

account_number >= 100 and items_sold <= 200

Typically, Kibana’s time filter is sufficient for setting a time range, but in some cases you might need to search on dates. Include the date range in quotes.

@timestamp < "2021-01-02T21:55:59"

@timestamp < "2021-01"

@timestamp < "2021"

An exist query matches documents that contain any value for a field, in this case, response:

response:*

Existence is defined by Elasticsearch and includes all values, including empty text.

Wildcards queries can be used to search by a term prefix or to search multiple fields. The default settings of Kibana prevent leading wildcards for performance reasons, but this can be allowed with an advanced setting.

To match documents where machine.os starts with win, such as "windows 7" and "windows 10":

machine.os:win*

To match multiple fields:

machine.os*:windows 10

This syntax is handy when you have text and keyword versions of a field. The query checks machine.os and machine.os.keyword for the term windows 10.

A main consideration for querying nested fields is how to match parts of the nested query to the individual nested documents. You can:

In the following document, items is a nested field. Each document in the nested field contains a name, stock, and category.

{
  "grocery_name": "Elastic Eats",
  "items": [
    {
      "name": "banana",
      "stock": "12",
      "category": "fruit"
    },
    {
      "name": "peach",
      "stock": "10",
      "category": "fruit"
    },
    {
      "name": "carrot",
      "stock": "9",
      "category": "vegetable"
    },
    {
      "name": "broccoli",
      "stock": "5",
      "category": "vegetable"
    }
  ]
}

To match stores that have more than 10 bananas in stock:

items:{ name:banana and stock > 10 }

items is the nested path. Everything inside the curly braces (the nested group) must match a single nested document.

The following query does not return any matches because no single nested document has bananas with a stock of 9.

items:{ name:banana and stock:9 }

The following subqueries are in separate nested groups and can match different nested documents:

items:{ name:banana } and items:{ stock:9 }

name:banana matches the first document in the array and stock:9 matches the third document in the array.

To find a store with more than 10 bananas that also stocks vegetables:

items:{ name:banana and stock > 10 } and items:{ category:vegetable }

The first nested group (name:banana and stock > 10) must match a single document, but the category:vegetables subquery can match a different nested document because it is in a separate group.

KQL supports nested fields inside other nested fields—you have to specify the full path. In this document, level1 and level2 are nested fields:

{
  "level1": [
    {
      "level2": [
        {
          "prop1": "foo",
          "prop2": "bar"
        },
        {
          "prop1": "baz",
          "prop2": "qux"
        }
      ]
    }
  ]
}

To match on a single nested document:

level1.level2:{ prop1:foo and prop2:bar }