You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
In Kibana 6.3, we introduced a number of exciting experimental query language enhancements. These
5
-
features are now available by default in 7.0. Out of the box, Kibana's query language now includes scripted field support and a
6
-
simplified, easier to use syntax. If you have a Basic license or above, autocomplete functionality will also be enabled.
4
+
The Kibana Query Language (KQL) makes it easy to find
5
+
the fields and syntax for your {es} query. If you have the
6
+
https://www.elastic.co/subscriptions[Basic tier] or above,
7
+
simply place your cursor in the *Search* field. As you type, you’ll get suggestions for fields,
8
+
values, and operators.
7
9
8
-
==== Language syntax
10
+
[role="screenshot"]
11
+
image::images/kql-autocomplete.png[Autocomplete in Search bar]
9
12
10
-
If you're familiar with Kibana's old Lucene query syntax, you should feel right at home with the new syntax. The basics
11
-
stay the same, we've simply refined things to make the query language easier to use.
13
+
If you prefer to use Kibana’s legacy query language, based on the
14
+
<<lucene-query, Lucene query syntax>>, click *KQL* next to the *Search* field, and then turn off KQL.
12
15
13
-
`response:200` will match documents where the response field matches the value 200.
16
+
[discrete]
17
+
=== Terms query
14
18
15
-
Quotes around a search term will initiate a phrase search. For example, `message:"Quick brown fox"` will search
16
-
for the phrase "quick brown fox" in the message field. Without the quotes, your query will get broken down into tokens via
17
-
the message field's configured analyzer and will match documents that contain those tokens, regardless of the order in which
18
-
they appear. This means documents with "quick brown fox" will match, but so will "quick fox brown". Remember to use quotes if you want
19
-
to search for a phrase.
19
+
A terms query matches documents that contain one or more *exact* terms in a field.
20
20
21
-
The query parser will no longer split on whitespace. Multiple search terms must be separated by explicit
22
-
boolean operators. Lucene will combine search terms with an `or` by default, so `response:200 extension:php` would
23
-
become `response:200 or extension:php` in KQL. This will match documents where response matches 200, extension matches php, or both.
24
-
Note that boolean operators are not case sensitive.
21
+
To match documents where the response field is `200`:
25
22
26
-
We can make terms required by using `and`.
23
+
[source,yaml]
24
+
-------------------
25
+
response:200
26
+
-------------------
27
27
28
-
`response:200 and extension:php` will match documents where response matches 200 and extension matches php.
28
+
To match documents with the phrase "quick brown fox" in the `message` field.
29
29
30
-
By default, `and` has a higher precedence than `or`.
30
+
[source,yaml]
31
+
-------------------
32
+
message:"quick brown fox"
33
+
-------------------
31
34
32
-
`response:200 and extension:php or extension:css` will match documents where response is 200 and extension is php OR documents where extension is css and response is anything.
35
+
Without the quotes,
36
+
the query matches documents regardless of the order in which
37
+
they appear. Documents with "quick brown fox" match,
38
+
and so does "quick fox brown".
33
39
34
-
We can override the default precedence with grouping.
40
+
NOTE: Terms without fields are matched against the default field in your index settings.
41
+
If a default field is not
42
+
set, terms are matched against all fields. For example, a query
43
+
for `response:200` searches for the value 200
44
+
in the response field, but a query for just `200` searches for 200
45
+
across all fields in your index.
35
46
36
-
`response:200 and (extension:php or extension:css)` will match documents where response is 200 and extension is either php or css.
37
47
38
-
A shorthand exists that allows us to easily search a single field for multiple values.
48
+
[discrete]
49
+
=== Boolean queries
39
50
40
-
`response:(200 or 404)` searches for docs where the `response` field matches 200 or 404. We can also search for docs
41
-
with multi-value fields that contain a list of terms, for example: `tags:(success and info and security)`
51
+
KQL supports `or`, `and`, and `not`. By default, `and` has a higher precedence than `or`.
52
+
To override the default precedence, group operators in parentheses.
42
53
43
-
Terms can be inverted by prefixing them with `not`.
54
+
To match documents where response is `200`, extension is `php`, or both:
44
55
45
-
`not response:200` will match all documents where response is not 200.
56
+
[source,yaml]
57
+
-------------------
58
+
response:200 or extension:php
59
+
-------------------
46
60
47
-
Entire groups can also be inverted.
61
+
To match documents where response is `200` and extension is `php`:
48
62
49
-
`response:200 and not (extension:php or extension:css)`
63
+
[source,yaml]
64
+
-------------------
65
+
response:200 and extension:php
66
+
-------------------
50
67
51
-
Ranges are similar to lucene with a small syntactical difference.
68
+
To match documents where response is `200` or `404`.
52
69
53
-
Instead of `bytes:>1000`, we omit the colon: `bytes > 1000`.
70
+
[source,yaml]
71
+
-------------------
72
+
response:(200 or 404)
73
+
-------------------
54
74
55
-
`>, >=, <, <=` are all valid range operators.
75
+
To match documents where response is `200` and extension is either `php` or `css`:
56
76
57
-
Exist queries are simple and do not require a special operator. `response:*` will find all docs where the response
58
-
field exists.
77
+
[source,yaml]
78
+
-------------------
79
+
response:200 and (extension:php or extension:css)
80
+
-------------------
59
81
60
-
Wildcard queries are available. `machine.os:win*` would match docs where the machine.os field starts with "win", which
61
-
would match values like "windows 7" and "windows 10".
82
+
To match documents where `response` is 200 and `extension` is
83
+
`php` or extension is `css`, and response is anything:
62
84
63
-
Wildcards also allow us to search multiple fields at once. This can come in handy when you have both `text` and `keyword`
64
-
versions of a field. Let's say we have `machine.os` and `machine.os.keyword` fields and we want to check both for the term
65
-
"windows 10". We can do it like this: `machine.os*:windows 10".
85
+
[source,yaml]
86
+
-------------------
87
+
response:200 and extension:php or extension:css
88
+
-------------------
66
89
90
+
To match documents where response is not `200`:
67
91
68
-
[NOTE]
69
-
============
70
-
Terms without fields will be matched against the default field in your index settings. If a default field is not
71
-
set these terms will be matched against all fields. For example, a query for `response:200` will search for the value 200
72
-
in the response field, but a query for just `200` will search for 200 across all fields in your index.
73
-
============
92
+
[source,yaml]
93
+
-------------------
94
+
not response:200
95
+
-------------------
74
96
75
-
==== Nested field support
97
+
To match documents where response is `200` but extension is not `php` or `css`.
76
98
77
-
KQL supports querying on {ref}/nested.html[nested fields] through a special syntax. You can query nested fields in subtly different
78
-
ways, depending on the results you want, so crafting nested queries requires extra thought.
99
+
[source,yaml]
100
+
-------------------
101
+
response:200 and not (extension:php or extension:css)
102
+
-------------------
79
103
80
-
One main consideration is how to match parts of the nested query to the individual nested documents.
81
-
There are two main approaches to take:
104
+
To match multi-value fields that contain a list of terms:
82
105
83
-
* *Parts of the query may only match a single nested document.* This is what most users want when querying on a nested field.
84
-
* *Parts of the query can match different nested documents.* This is how a regular object field works.
85
-
Although generally less useful, there might be occasions where you want to query a nested field in this way.
106
+
[source,yaml]
107
+
-------------------
108
+
tags:(success and info and security)
109
+
-------------------
86
110
87
-
Let's take a look at the first approach. In the following document, `items` is a nested field. Each document in the nested
111
+
[discrete]
112
+
=== Range queries
113
+
114
+
KQL supports `>`, `>=`, `<`, and `<=`. For example:
115
+
116
+
[source,yaml]
117
+
-------------------
118
+
account_number:>=100 and items_sold:<=200
119
+
-------------------
120
+
121
+
[discrete]
122
+
=== Exist queries
123
+
124
+
An exist query matches documents that contain a value for a field, in this case,
125
+
response:
126
+
127
+
[source,yaml]
128
+
-------------------
129
+
response:*
130
+
-------------------
131
+
132
+
[discrete]
133
+
=== Wildcard queries
134
+
135
+
To match documents where machine.os starts with `win`, such
136
+
as "windows 7" and "windows 10":
137
+
138
+
[source,yaml]
139
+
-------------------
140
+
machine.os:win*
141
+
-------------------
142
+
143
+
To match multiple fields:
144
+
145
+
[source,yaml]
146
+
-------------------
147
+
machine.os*:windows 10
148
+
-------------------
149
+
150
+
This sytax is handy when you have text and keyword
151
+
versions of a field. The query checks machine.os and machine.os.keyword
152
+
for the term
153
+
`windows 10`.
154
+
155
+
156
+
[discrete]
157
+
=== Nested field queries
158
+
159
+
A main consideration for querying {ref}/nested.html[nested fields] is how to
160
+
match parts of the nested query to the individual nested documents.
161
+
You can:
162
+
163
+
* *Match parts of the query to a single nested document only.* This is what most users want when querying on a nested field.
164
+
* *Match parts of the query to different nested documents.* This is how a regular object field works.
165
+
This query is generally less useful than matching to a single document.
166
+
167
+
In the following document, `items` is a nested field. Each document in the nested
88
168
field contains a name, stock, and category.
89
169
90
170
[source,json]
@@ -116,40 +196,61 @@ field contains a name, stock, and category.
116
196
}
117
197
----------------------------------
118
198
119
-
===== Match a single nested document
199
+
[discrete]
200
+
==== Match a single document
120
201
121
-
To find stores that have more than 10 bananas in stock, you would write a query like this:
202
+
To match stores that have more than 10 bananas in stock:
122
203
123
-
`items:{ name:banana and stock > 10 }`
204
+
[source,yaml]
205
+
-------------------
206
+
items:{ name:banana and stock > 10 }
207
+
-------------------
124
208
125
-
`items` is the "nested path". Everything inside the curly braces (the "nested group") must match a single nested document.
209
+
`items` is the nested path. Everything inside the curly braces (the nested group)
210
+
must match a single nested document.
126
211
127
-
The following example returns no matches because no single nested document has bananas with a stock of 9.
212
+
The following query does not return any matches because no single nested
213
+
document has bananas with a stock of 9.
128
214
129
-
`items:{ name:banana and stock:9 }`
215
+
[source,yaml]
216
+
-------------------
217
+
items:{ name:banana and stock:9 }
218
+
-------------------
130
219
131
-
==== Match different nested documents
220
+
[discrete]
221
+
==== Match different documents
132
222
133
-
The subqueries in this example are in separate nested groups and can match different nested documents.
223
+
The following subqueries are in separate nested groups
224
+
and can match different nested documents:
134
225
135
-
`items:{ name:banana } and items:{ stock:9 }`
226
+
[source,yaml]
227
+
-------------------
228
+
items:{ name:banana } and items:{ stock:9 }
229
+
-------------------
136
230
137
-
`name:banana` matches the first document in the array and `stock:9` matches the third document in the array.
231
+
`name:banana` matches the first document in the array and `stock:9`
232
+
matches the third document in the array.
138
233
139
-
==== Combine approaches
234
+
[discrete]
235
+
==== Match single and different documents
140
236
141
-
You can combine these two approaches to create complex queries. What if you wanted to find a store with more than 10
142
-
bananas that *also* stocks vegetables? You could do this:
237
+
To find a store with more than 10
238
+
bananas that *also* stocks vegetables:
143
239
144
-
`items:{ name:banana and stock > 10 } and items:{ category:vegetable }`
240
+
[source,yaml]
241
+
-------------------
242
+
items:{ name:banana and stock > 10 } and items:{ category:vegetable }
243
+
-------------------
145
244
146
-
The first nested group (`name:banana and stock > 10`) must still match a single document, but the `category:vegetables`
245
+
The first nested group (`name:banana and stock > 10`) must match a single document, but the `category:vegetables`
147
246
subquery can match a different nested document because it is in a separate group.
148
247
248
+
[discrete]
149
249
==== Nested fields inside other nested fields
150
250
151
-
KQL's syntax also supports nested fields inside of other nested fields—you simply have to specify the full path. Suppose you
152
-
have a document where `level1` and `level2` are both nested fields:
251
+
KQL supports nested fields inside other nested fields—you have to
252
+
specify the full path. In this document,
253
+
`level1` and `level2` are nested fields:
153
254
154
255
[source,json]
155
256
----------------------------------
@@ -171,6 +272,9 @@ have a document where `level1` and `level2` are both nested fields:
171
272
}
172
273
----------------------------------
173
274
174
-
You can match on a single nested document by specifying the full path:
Copy file name to clipboardExpand all lines: docs/user/reporting/reporting-troubleshooting.asciidoc
+5-2Lines changed: 5 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -18,8 +18,11 @@ Having trouble? Here are solutions to common problems you might encounter while
18
18
19
19
[float]
20
20
[[reporting-diagnostics]]
21
-
=== Reporting Diagnostics
22
-
Reporting comes with a built-in utility to try to automatically find common issues. When Kibana is running, navigate to the Report Listing page, and click the "Run reporting diagnostics..." button. This will open up a diagnostic tool that checks various parts of the Kibana deployment to come up with any relevant recommendations.
21
+
=== Reporting diagnostics
22
+
Reporting comes with a built-in utility to try to automatically find common issues.
23
+
When {kib} is running, navigate to the Report Listing page, and click *Run reporting diagnostics*.
24
+
This will open up a diagnostic tool that checks various parts of the {kib} deployment and
0 commit comments