* [DOCS] Updates KQL doc * [DOCS] Edits to KQL doc * Update docs/discover/kuery.asciidoc Co-authored-by: Kaarina Tungseth <kaarina.tungseth@elastic.co> * Update docs/discover/kuery.asciidoc Co-authored-by: Kaarina Tungseth <kaarina.tungseth@elastic.co> * Update docs/discover/kuery.asciidoc Co-authored-by: Kaarina Tungseth <kaarina.tungseth@elastic.co> * Update docs/discover/kuery.asciidoc Co-authored-by: Kaarina Tungseth <kaarina.tungseth@elastic.co> * Update docs/discover/kuery.asciidoc Co-authored-by: Kaarina Tungseth <kaarina.tungseth@elastic.co> * Update docs/discover/kuery.asciidoc Co-authored-by: Kaarina Tungseth <kaarina.tungseth@elastic.co> * Update docs/discover/kuery.asciidoc Co-authored-by: Kaarina Tungseth <kaarina.tungseth@elastic.co> * Update docs/discover/kuery.asciidoc Co-authored-by: Kaarina Tungseth <kaarina.tungseth@elastic.co> * Update docs/discover/kuery.asciidoc Co-authored-by: Kaarina Tungseth <kaarina.tungseth@elastic.co> * Update docs/discover/kuery.asciidoc Co-authored-by: Kaarina Tungseth <kaarina.tungseth@elastic.co> * Update docs/discover/kuery.asciidoc Co-authored-by: Kaarina Tungseth <kaarina.tungseth@elastic.co> * Update docs/discover/kuery.asciidoc Co-authored-by: Kaarina Tungseth <kaarina.tungseth@elastic.co> * Update docs/discover/kuery.asciidoc Co-authored-by: Kaarina Tungseth <kaarina.tungseth@elastic.co> * Update docs/discover/kuery.asciidoc Co-authored-by: Kaarina Tungseth <kaarina.tungseth@elastic.co> * Apply suggestions from code review Co-authored-by: Kaarina Tungseth <kaarina.tungseth@elastic.co> * [DOCS] Adds image of autocomplete and other edits * [DOCS] Minor edit to KQL doc * [DOCS] Minor edit Co-authored-by: Kaarina Tungseth <kaarina.tungseth@elastic.co>
281 lines
6.7 KiB
Plaintext
281 lines
6.7 KiB
Plaintext
[[kuery-query]]
|
||
=== Kibana Query Language
|
||
|
||
The Kibana Query Language (KQL) makes it easy to find
|
||
the fields and syntax for your {es} query. If you have the
|
||
https://www.elastic.co/subscriptions[Basic tier] or above,
|
||
simply place your cursor in the *Search* field. As you type, you’ll get suggestions for fields,
|
||
values, and operators.
|
||
|
||
[role="screenshot"]
|
||
image::images/kql-autocomplete.png[Autocomplete in Search bar]
|
||
|
||
If you prefer to use Kibana’s legacy query language, based on the
|
||
<<lucene-query, Lucene query syntax>>, click *KQL* next to the *Search* field, and then turn off KQL.
|
||
|
||
[discrete]
|
||
=== Terms query
|
||
|
||
A terms query matches documents that contain one or more *exact* terms in a field.
|
||
|
||
To match documents where the response field is `200`:
|
||
|
||
[source,yaml]
|
||
-------------------
|
||
response:200
|
||
-------------------
|
||
|
||
To match documents with the phrase "quick brown fox" in the `message` field.
|
||
|
||
[source,yaml]
|
||
-------------------
|
||
message:"quick brown fox"
|
||
-------------------
|
||
|
||
Without the quotes,
|
||
the query matches documents regardless of the order in which
|
||
they appear. Documents with "quick brown fox" match,
|
||
and so does "quick fox brown".
|
||
|
||
NOTE: Terms without fields are matched against the default field in your index settings.
|
||
If a default field is not
|
||
set, terms are matched against all fields. For example, a query
|
||
for `response:200` searches for the value 200
|
||
in the response field, but a query for just `200` searches for 200
|
||
across all fields in your index.
|
||
|
||
|
||
[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.
|
||
|
||
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 `<=`. For example:
|
||
|
||
[source,yaml]
|
||
-------------------
|
||
account_number:>=100 and items_sold:<=200
|
||
-------------------
|
||
|
||
[discrete]
|
||
=== Exist queries
|
||
|
||
An exist query matches documents that contain a value for a field, in this case,
|
||
response:
|
||
|
||
[source,yaml]
|
||
-------------------
|
||
response:*
|
||
-------------------
|
||
|
||
[discrete]
|
||
=== Wildcard queries
|
||
|
||
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 sytax 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 }
|
||
-------------------
|