kibana/docs/concepts/kuery.asciidoc

[[kuery-query]]
=== Kibana Query Language

The Kibana Query Language (KQL) is a simple syntax for filtering {es} 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 <<settings, {kib} settings>>.

KQL has a different set of features than the <<lucene-query>>. KQL is able to query
nested fields and <<scripted-fields, 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.

[discrete]
=== Terms query

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:

[source,yaml]
-------------------
http.response.status_code:400 401 404
-------------------

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

[source,yaml]
-------------------
http.response.body.content.text:quick brown fox
-------------------

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

[source,yaml]
-------------------
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:

[source,yaml]
-------------------
"quick brown fox"
-------------------

[discrete]
=== Boolean queries

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:

[source,yaml]
-------------------
response:200 or extension:php
-------------------

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

[source,yaml]
-------------------
response:200 and extension:php
-------------------

To match documents where response is `200` or `404`.

[source,yaml]
-------------------
response:(200 or 404)
-------------------

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

[source,yaml]
-------------------
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:

[source,yaml]
-------------------
response:200 and extension:php or extension:css
-------------------

To match documents where response is not `200`:

[source,yaml]
-------------------
not response:200
-------------------

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

[source,yaml]
-------------------
response:200 and not (extension:php or extension:css)
-------------------

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

[source,yaml]
-------------------
tags:(success and info and security)
-------------------

[discrete]
=== Range queries

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

[source,yaml]
-------------------
account_number >= 100 and items_sold <= 200
-------------------

[discrete]
=== Date range queries

Typically, Kibana's <<set-time-filter,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.

[source,yaml]
-------------------
@timestamp < "2021-01-02T21:55:59"
-------------------

[source,yaml]
-------------------
@timestamp < "2021-01"
-------------------

[source,yaml]
-------------------
@timestamp < "2021"
-------------------


[discrete]
=== Exist queries

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

[source,yaml]
-------------------
response:*
-------------------

Existence is defined by {es} and includes all values, including empty text.

[discrete]
=== Wildcard queries

Wildcards queries can be used to *search by a term prefix* or to *search multiple fields*.
The default settings of {kib} *prevent leading wildcards* for performance reasons,
but this can be allowed with an <<query-allowleadingwildcards, advanced setting>>.

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

[source,yaml]
-------------------
machine.os:win*
-------------------

To match multiple fields:

[source,yaml]
-------------------
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`.


[discrete]
=== Nested field queries

A main consideration for querying {ref}/nested.html[nested fields] is how to
match parts of the nested query to the individual nested documents.
You can:

* *Match parts of the query to a single nested document only.* This is what most users want when querying on a nested field.
* *Match parts of the query to different nested documents.* This is how a regular object field works.
 This query is generally less useful than matching to a single document.

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

[source,json]
----------------------------------
{
  "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"
    }
  ]
}
----------------------------------

[discrete]
==== Match a single document

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

[source,yaml]
-------------------
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.

[source,yaml]
-------------------
items:{ name:banana and stock:9 }
-------------------

[discrete]
==== Match different documents

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

[source,yaml]
-------------------
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.

[discrete]
==== Match single and different documents

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

[source,yaml]
-------------------
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.

[discrete]
==== Nested fields inside other nested fields

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

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

To match on a single nested document:

[source,yaml]
-------------------
level1.level2:{ prop1:foo and prop2:bar }
-------------------