317 lines
7.9 KiB
Plaintext
317 lines
7.9 KiB
Plaintext
[[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>>:
|
|
|
|
[role="screenshot"]
|
|
image::images/kql-autocomplete.png[Autocomplete in Search bar]
|
|
|
|
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—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 }
|
|
-------------------
|