github-mirrors/kibana
1
0
Fork 0
mirror of https://github.com/elastic/kibana.git synced 2025-04-23 17:28:26 -04:00
Code Issues Projects Releases Packages Wiki Activity

[Docs] Clarify KQL and Lucene docs (#91065)

Browse source 
* [Docs] Clarify KQL and Lucene docs

* Code review suggestions
This commit is contained in:
Wylie Conlon 2021-02-16 13:06:25 -05:00 • committed by GitHub
parent 6f857dd7f3
commit d4f3420b41
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
2 changed files with 79 additions and 46 deletions
Download patch file Download diff file Expand all files Collapse all files

64
docs/discover/kuery.asciidoc
View file

@ -1,55 +1,63 @@
[[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.
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]
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.
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 matches documents that contain one or more *exact* terms in a field.
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 match documents where the response field is `200`:
To query using *exact search terms*, enter the field name followed by `:` and
then the values separated by spaces:
[source,yaml]
-------------------
response:200
http.response.status_code:400 401 404
-------------------
To match documents with the phrase "quick brown fox" in the `message` field.
For text fields, this will match any value regardless of order:
[source,yaml]
-------------------
message:"quick brown fox"
http.response.body.content.text: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".
To query for an *exact phrase*, use quotation marks around the values:
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.
[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.
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:
@ -143,7 +151,7 @@ but in some cases you might need to search on dates. Include the date range in q
[discrete]
=== Exist queries
An exist query matches documents that contain a value for a field, in this case,
An exist query matches documents that contain any value for a field, in this case,
response:
[source,yaml]
@ -151,10 +159,16 @@ response:
response:*
-------------------
Existence is defined by {es} and includes all values, including empty text.
[discrete]
=== Wildcard queries
To match documents where machine.os starts with `win`, such
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]

61
docs/discover/search.asciidoc
View file

@ -53,36 +53,55 @@ include::kuery.asciidoc[]
[[lucene-query]]
=== Lucene query syntax
Kibana's legacy query language was based on the Lucene query syntax. For the time being this syntax
is still available under the options menu in the Query Bar and in Advanced Settings. The following
are some tips that can help get you started.
Lucene query syntax is available to {kib} users who opt out of the <<kuery-query>>.
Full documentation for this syntax is available as part of {es}
{ref}/query-dsl-query-string-query.html#query-string-syntax[query string syntax].
* To perform a free text search, simply enter a text string. For example, if
The main reason to use the Lucene query syntax in {kib} is for advanced
Lucene features, such as regular expressions or fuzzy term matching. However,
Lucene syntax is not able to search nested objects or scripted fields.
To perform a free text search, simply enter a text string. For example, if
you're searching web server logs, you could enter `safari` to search all
fields for the term `safari`.
fields:
* To search for a value in a specific field, prefix the value with the name
of the field. For example, you could enter `status:200` to find all of
the entries that contain the value `200` in the `status` field.
[source,yaml]
-------------------
safari
-------------------
* To search for a range of values, you can use the bracketed range syntax,
To search for a value in a specific field, prefix the value with the name
of the field:
[source,yaml]
-------------------
status:200
-------------------
To search for a range of values, use the bracketed range syntax,
`[START_VALUE TO END_VALUE]`. For example, to find entries that have 4xx
status codes, you could enter `status:[400 TO 499]`.
* To specify more complex search criteria, you can use the Boolean operators
[source,yaml]
-------------------
status:[400 TO 499]
-------------------
For an open range, use a wildcard:
[source,yaml]
-------------------
status:[400 TO *]
-------------------
To specify more complex search criteria, use the boolean operators
`AND`, `OR`, and `NOT`. For example, to find entries that have 4xx status
codes and have an extension of `php` or `html`, you could enter `status:[400 TO
499] AND (extension:php OR extension:html)`.
codes and have an extension of `php` or `html`:
IMPORTANT: When you use the Lucene Query Syntax in the *KQL* search bar, {kib} is unable to search on nested objects and perform aggregations across fields that contain nested objects.
Using `include_in_parent` or `copy_to` as a workaround can cause {kib} to fail.
For more detailed information about the Lucene query syntax, see the
{ref}/query-dsl-query-string-query.html#query-string-syntax[Query String Query]
docs.
NOTE: These examples use the Lucene query syntax. When lucene is selected as your
query language you can also submit queries using the {ref}/query-dsl.html[Elasticsearch Query DSL].
[source,yaml]
-------------------
status:[400 TO 499] AND (extension:php OR extension:html)
-------------------
[[save-open-search]]