From 8e715883ca4d619e18457e0b08fbe6164074bdcb Mon Sep 17 00:00:00 2001 From: Matt Bargar Date: Wed, 2 Aug 2017 15:16:00 -0400 Subject: [PATCH] Add Kuery docs and break search page into subsections (#13074) * Add Kuery docs and break search page into subsections --- docs/discover/kuery.asciidoc | 115 ++++++++++++++++++++++++++++++++++ docs/discover/search.asciidoc | 47 +++++++++----- 2 files changed, 145 insertions(+), 17 deletions(-) create mode 100644 docs/discover/kuery.asciidoc diff --git a/docs/discover/kuery.asciidoc b/docs/discover/kuery.asciidoc new file mode 100644 index 0000000000000..af19622484485 --- /dev/null +++ b/docs/discover/kuery.asciidoc @@ -0,0 +1,115 @@ +[[kuery-query]] +=== Kuery + +experimental[This functionality is experimental and may be changed or removed completely in a future release.] + +Kuery is a new query language built specifically for Kibana. It aims to simplify the search experience in Kibana +and enable the creation of helpful features like auto-complete, seamless migration of saved searches, additional +query types, and more. Kuery is a basic experience today but we're hard at work building these additional features on +top of the foundation Kuery provides. + +Kueries are built with functions. Many functions take a field name as their first argument. Extremely common functions have shorthand notations. + +`is("response", 200)` will match documents where the response field matches the value 200. +`response:200` does the same thing. `:` is an alias for the `is` function. + +Multiple search terms are separated by whitespace. + +`response:200 extension:php` will match documents where response matches 200 and extension matches php. + +All terms must match by default. The language supports boolean logic with and/or operators. The above query is equivalent to `response:200 and extension:php`. + +We can make terms optional by using `or`. + +`response:200 or extension:php` will match documents where response matches 200, extension matches php, or both. + +By default, `and` has a higher precedence than `or`. + +`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. + +We can override the default precedence with grouping. + +`response:200 and (extension:php or extension:css)` will match documents where response is 200 and extension is either php or css. + +Terms can be inverted by prefixing them with `!`. + +`!response:200` will match all documents where response is not 200. + +Entire groups can also be inverted. + +`response:200 and !(extension:php or extension:css)` + +Some query functions have named arguments. + +`range("bytes", gt=1000, lt=8000)` will match documents where the bytes field is greater than 1000 and less than 8000. + +Quotes are generally optional if your terms don't have whitespace or special characters. `range(bytes, gt=1000, lt=8000)` +would also be a valid query. + +[NOTE] +============ +Terms without fields will be matched against all fields. For example, a query for `response:200` will search for the value 200 +in the response field, but a query for just `200` will search for 200 across all fields in your index. +============ + +==== Function Reference + +[horizontal] +Function Name:: Description + +and:: +Purpose::: Match all given sub-queries +Alias::: `and` as a binary operator +Examples::: +* `and(response:200, extension:php)` +* `response:200 and extension:php` + +or:: +Purpose::: Match one or more sub-queries +Alias::: `or` as a binary operator +Examples::: +* `or(extension:css, extension:php)` +* `extension:css or extension:php` + +not:: +Purpose::: Negates a sub-query +Alias::: `!` as a prefix operator +Examples::: +* `not(response:200)` +* `!response:200` + +is:: +Purpose::: Matches a field with a given term +Alias::: `:` +Examples::: +* `is("response", 200)` +* `response:200` + +range:: +Purpose::: Match a field against a range of values. +Alias::: `:[]` +Examples::: +* `range("bytes", gt=1000, lt=8000)` +* `bytes:[1000 to 8000]` +Named arguments::: +* `gt` - greater than +* `gte` - greater than or equal to +* `lt` - less than +* `lte` - less than or equal to + +exists:: +Purpose::: Match documents where a given field exists +Examples::: `exists("response")` + +geoBoundingBox:: +Purpose::: Creates a geo_bounding_box query +Examples::: +* `geoBoundingBox("coordinates", topLeft="40.73, -74.1", bottomRight="40.01, -71.12")` (whitespace between lat and lon is ignored) +Named arguments::: +* `topLeft` - the top left corner of the bounding box as a "lat, lon" string +* `bottomRight` - the bottom right corner of the bounding box as a "lat, lon" string + +geoPolygon:: +Purpose::: Creates a geo_polygon query given 3 or more points as "lat, lon" +Examples::: +* `geoPolygon("geo.coordinates", "40.97, -127.26", "24.20, -84.375", "40.44, -66.09")` \ No newline at end of file diff --git a/docs/discover/search.asciidoc b/docs/discover/search.asciidoc index a1b141d826147..f63680d15255c 100644 --- a/docs/discover/search.asciidoc +++ b/docs/discover/search.asciidoc @@ -1,10 +1,10 @@ [[search]] == Searching Your Data You can search the indices that match the current index pattern by entering -your search criteria in the Query bar. You can perform a simple text search, -use the Lucene https://lucene.apache.org/core/2_9_4/queryparsersyntax.html[ -query syntax], or use the full JSON-based {ref}/query-dsl.html[Elasticsearch -Query DSL]. +your search criteria in the Query bar. You can use the Lucene +https://lucene.apache.org/core/2_9_4/queryparsersyntax.html[ +query syntax], the full JSON-based {ref}/query-dsl.html[Elasticsearch +Query DSL] or Kuery, an experimental new query language built specifically for Kibana. When you submit a search request, the histogram, Documents table, and Fields list are updated to reflect the search results. The total number of hits @@ -19,6 +19,17 @@ To search your data, enter your search criteria in the Query bar and press *Enter* or click *Search* image:images/search-button.jpg[] to submit the request to Elasticsearch. +[NOTE] +=========== +By default, Kibana will accept either the Lucene query syntax or the +Elasticsearch Query DSL in the Query bar. In order to use the new Kuery +language you must enable language switching in *Management > Advanced Settings* +via the `search:queryLanguage:switcher:enable` option. You can also change the +default language with the `search:queryLanguage` setting. +=========== + +[[lucene-query]] +=== Lucene Query Syntax * 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`. @@ -36,18 +47,22 @@ status codes, you could enter `status:[400 TO 499]`. codes and have an extension of `php` or `html`, you could enter `status:[400 TO 499] AND (extension:php OR extension:html)`. -NOTE: These examples use the Lucene query syntax. You can also submit queries -using the Elasticsearch Query DSL. For examples, see -{ref}/query-dsl-query-string-query.html#query-string-syntax[query string syntax] -in the Elasticsearch Reference. +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. -[float] -[[save-search]] -=== Saving a Search +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]. + +include::kuery.asciidoc[] + +[[save-open-search]] +=== Saving and Opening Searches Saving searches enables you to reload them into Discover and use them as the basis for <>. Saving a search saves both the search query string and the currently selected index pattern. +==== Saving a Search To save the current search: . Click *Save* in the Kibana toolbar. @@ -55,18 +70,17 @@ To save the current search: You can import, export and delete saved searches from *Management/Kibana/Saved Objects*. -[float] -[[load-search]] -=== Opening a Saved Search +==== Opening a Saved Search To load a saved search into Discover: . Click *Open* in the Kibana toolbar. . Select the search you want to open. If the saved search is associated with a different index pattern than is currently -selected, opening the saved search also changes the selected index pattern. +selected, opening the saved search changes the selected index pattern. The query language +used for the saved search will also be automatically selected. + -[float] [[select-pattern]] === Changing Which Indices You're Searching When you submit a search request, the indices that match the currently-selected @@ -77,7 +91,6 @@ different index pattern. For more information about index patterns, see <>. -[float] [[autorefresh]] === Refreshing the Search Results As more documents are added to the indices you're searching, the search results