Add Kuery docs and break search page into subsections #13074

Bargs · 2017-07-24T20:11:34Z

I added some documentation for the new Kuery language and attempted to break the "Searching Your Data" page into subsections that hopefully make it a bit more organized. My intent is for each subsection (prefixed with ===) to have its own page and link in the table of contents on the right hand side though I couldn't totally confirm this was working since local doc builds seem to work slightly differently than they do for the website.

lukasolson

Added a few minor comments below.

lukasolson · 2017-07-27T21:05:03Z

docs/discover/kuery.asciidoc

+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


It might be nice to add additional clarification that these helpful features (like autocomplete) aren't available now, but will be in the future.

++ explicitly stating that these features are not available today help advertise the benefits of the new language.
"It aims to simplify the search experience in Kibana and enable the creation of helpful features that aren't available today. Kuery will pave the way for features like auto-complete, seamless migration of saved searches, additional..." or something along those lines

@alexfrancoeur I already added a clarification per Lukas's suggestion, were you looking at the most recent changes?

lukasolson · 2017-07-27T21:05:46Z

docs/discover/kuery.asciidoc

+
+[NOTE]
+============
+Terms without fields will be matched against all fields. For example, a query for 200 will search for the value 200 across all fields in your index.


Since queries above are inside ticks (to format them as code) I think it'd be nice if it was 200 instead of just 200.

lukasolson · 2017-07-27T21:06:52Z

docs/discover/kuery.asciidoc

+
+Kuery queries 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.


Do you want to add something about how quotes are optional for values that don't have whitespace?

lukasolson · 2017-07-27T21:08:10Z

docs/discover/search.asciidoc

+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 an experimental new query language built specifically for Kibana.


Might be nice to mention Kuery by name here, since you do down below and in the Kuery docs themselves.

Yeah, I tried to fit it in but this is just a really long sentence already. Suggestions to make it flow better?

You could just say "or Kuery, an experimental...". Or, it might honestly be better to break it up into three separate bullet points. Thoughts?

lukasolson · 2017-07-27T21:11:02Z

docs/discover/search.asciidoc

+include::kuery.asciidoc[]
+
+[[save-load-search]]
+=== Saving and Loading Searches


Since it's called "opening" down below, might make sense to use the same terminology here.

Bargs · 2017-07-31T16:32:04Z

@lukasolson I've addressed all your suggestions

lukasolson

LGTM

Bargs · 2017-08-01T16:04:14Z

@alexfrancoeur do you think you'll have time to take a peek at these doc changes? I'd love to get feedback from someone who hasn't looked at the code so I know if what I've written will actually make sense to users 🙃

alexfrancoeur · 2017-08-01T16:41:17Z

@Bargs there is a rogue tab with this documentation open about a week ago somewhere in this mess of tabs and browsers. Reviewing now - apologies for the delay!

alexfrancoeur

Overall this looks good. I had some minor feedback but reading through the docs makes sense. The only thing I found missing here is a comparison to ES/Lucene queries. This may be more for a blog post but the only place I would have expected to see the comparison (if any) is in the function reference section.

alexfrancoeur · 2017-08-01T16:52:07Z

docs/discover/kuery.asciidoc

+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


++ explicitly stating that these features are not available today help advertise the benefits of the new language.
"It aims to simplify the search experience in Kibana and enable the creation of helpful features that aren't available today. Kuery will pave the way for features like auto-complete, seamless migration of saved searches, additional..." or something along those lines

alexfrancoeur · 2017-08-01T16:55:55Z

docs/discover/kuery.asciidoc

+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.
+
+Kuery queries are built with functions. Many functions take a field name as their first argument. Extremely common functions have shorthand notations.


"Kuery" is being thrown around a lot here. Maybe we can replace some of these with other ways to describe kuery, "Our new query language" for example

Instead of "Kuery queries are built with functions" I think it'd fine just saying "Queries are built with functions" If we wanted to have some fun here we could also say "Kueries are built with functions"

I was seeing how far I could get before someone told me to calm down with all the kuery queries 😄

Switched it to just be "Kueries"

alexfrancoeur · 2017-08-01T17:01:21Z

docs/discover/kuery.asciidoc

+
+Entire groups can also be inverted.
+
+`response:200 and !(extension:php or extension:css)`


wasn't there an invert option that uses not that is the equivalent of ! - response:200 and not(extensions:php or extension:css)

Looks like this in mentioned in the function reference - can't hurt to show here as well.

I don't think the not() syntax will get much usage. I worry about making this section too verbose, if we mention not() it seems like we should also mention and() and or()

alexfrancoeur · 2017-08-01T17:02:23Z

docs/discover/kuery.asciidoc

+
+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.
+


good job showing with and without quotes

alexfrancoeur · 2017-08-01T17:05:36Z

docs/discover/kuery.asciidoc

+[NOTE]
+============
+Terms without fields will be matched against all fields. For example, a query for `200` will search for the value 200 across all fields in your index.
+============


Can we add a bit more detail here? I'm guessing that this is referring to a plain text search in the input box? Maybe we can say "Searching for terms without defining a field will default to matching that value against all fields"

I added a counter example that hopefully helps clarify things, let me know what you think.

alexfrancoeur · 2017-08-01T17:11:39Z

docs/discover/kuery.asciidoc

+geoBoundingBox::
+Purpose::: Creates a geo_bounding_box query
+Examples:::
+* `geoBoundingBox("coordinates", topLeft="40.73, -74.1", bottomRight="40.01, -71.12")`


do we ignore whitespace in between lat/long here (and below)?

Yep, added a note

alexfrancoeur · 2017-08-01T17:13:15Z

docs/discover/search.asciidoc

+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.


"DSL], or Kuery," I think we might have one too many comma's ==> "DSL] or Kuery,"

alexfrancoeur · 2017-08-01T17:16:46Z

docs/discover/search.asciidoc

@@ -66,7 +79,6 @@ To load a saved search into Discover:
 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.


How does Kuery behave here? If there are saved searches that were saved with Lucene syntax - does Discover still use Lucene? It might be worth adding a note here "if you're using Kuery, blah blah"

Great point, it'll automatically select the language that the saved search was written in. Added a note.

Bargs · 2017-08-01T19:56:51Z

@alexfrancoeur I made another round of updates, let me know what you think.

* Add Kuery docs and break search page into subsections

alexfrancoeur · 2017-08-02T20:28:20Z

LGTM @Bargs (even though it's already merged 😄 ). Love that we've used kueries in the docs

Bargs · 2017-08-02T21:55:33Z

@alexfrancoeur sorry for the early merge, just wanted to get these in so I could put up another PR that links to these docs from Kibana 😅

Bargs added Team:Docs review v6.0.0-beta1 labels Jul 24, 2017

Bargs requested review from lukasolson and alexfrancoeur July 24, 2017 20:11

lukasolson reviewed Jul 27, 2017

View reviewed changes

lukasolson approved these changes Jul 31, 2017

View reviewed changes

alexfrancoeur approved these changes Aug 1, 2017

View reviewed changes

Bargs added 10 commits August 1, 2017 15:39

Add Kuery docs and break search page into subsections

37e19f5

clarify status of advanced features

1358656

Add note about quotes

cc3ec30

code formatting for plain 200 query

470ce0a

mention kuery by name

58540e6

make load/open terminology consistent

c10f547

chill out with all the kuery queries querying kueries

b90a3cd

Add note about unconstrained terms

cceeaeb

remove extraneous comma

4883c6e

Note behaviour of query language selection when loading a saved search

340dcfc

Bargs force-pushed the kueryDocs branch from 063e7e6 to 340dcfc Compare August 1, 2017 19:52

note that whitespace is ignored between lat lon

944a349

Bargs merged commit f78bb5d into elastic:master Aug 2, 2017

Bargs added v6.0.0 v6.1.0 v7.0.0 and removed v6.0.0-beta1 labels Aug 2, 2017

Bargs added a commit to Bargs/kibana that referenced this pull request Aug 2, 2017

Add Kuery docs and break search page into subsections (elastic#13074)

4d2bcb3

* Add Kuery docs and break search page into subsections

Bargs added a commit to Bargs/kibana that referenced this pull request Aug 2, 2017

Add Kuery docs and break search page into subsections (elastic#13074)

8e71588

* Add Kuery docs and break search page into subsections

Bargs added a commit that referenced this pull request Aug 2, 2017

Add Kuery docs and break search page into subsections (#13074) (#13301)

55db0c5

* Add Kuery docs and break search page into subsections

Bargs added a commit that referenced this pull request Aug 2, 2017

Add Kuery docs and break search page into subsections (#13074) (#13302)

060b9e4

* Add Kuery docs and break search page into subsections

jimgoodwin added the v6.0.0-rc1 label Sep 28, 2017

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add Kuery docs and break search page into subsections #13074

Add Kuery docs and break search page into subsections #13074

Bargs commented Jul 24, 2017

lukasolson left a comment

lukasolson Jul 27, 2017

alexfrancoeur Aug 1, 2017

Bargs Aug 1, 2017

lukasolson Jul 27, 2017

lukasolson Jul 27, 2017

lukasolson Jul 27, 2017

Bargs Jul 28, 2017

lukasolson Jul 28, 2017

lukasolson Jul 27, 2017

Bargs commented Jul 31, 2017

lukasolson left a comment

Bargs commented Aug 1, 2017

alexfrancoeur commented Aug 1, 2017

alexfrancoeur left a comment

alexfrancoeur Aug 1, 2017

alexfrancoeur Aug 1, 2017

alexfrancoeur Aug 1, 2017

Bargs Aug 1, 2017

alexfrancoeur Aug 1, 2017

alexfrancoeur Aug 1, 2017

Bargs Aug 1, 2017

alexfrancoeur Aug 1, 2017

alexfrancoeur Aug 1, 2017

Bargs Aug 1, 2017

alexfrancoeur Aug 1, 2017

Bargs Aug 1, 2017

alexfrancoeur Aug 1, 2017

Bargs Aug 1, 2017

alexfrancoeur Aug 1, 2017

Bargs Aug 1, 2017

Bargs commented Aug 1, 2017

alexfrancoeur commented Aug 2, 2017

Bargs commented Aug 2, 2017


		Kuery queries 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.


		Entire groups can also be inverted.

		`response:200 and !(extension:php or extension:css)`


		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.

		@@ -66,7 +79,6 @@ To load a saved search into Discover:
		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.

Add Kuery docs and break search page into subsections #13074

Add Kuery docs and break search page into subsections #13074

Conversation

Bargs commented Jul 24, 2017

lukasolson left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Bargs commented Jul 31, 2017

lukasolson left a comment

Choose a reason for hiding this comment

Bargs commented Aug 1, 2017

alexfrancoeur commented Aug 1, 2017

alexfrancoeur left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Bargs commented Aug 1, 2017

alexfrancoeur commented Aug 2, 2017

Bargs commented Aug 2, 2017