[DOCS] Rewrite term query docs for new format
#41498
Conversation
jrodewig
added
>docs
|
Pinging @elastic/es-search |
|
|
||
| A `term` query can also match against <<range, range data types>>. | ||
|
|
||
| .Why doesn't the `term` query match my document? |
There was a problem hiding this comment.
Whilst I'm not wedded to having this explanation in this page of the documentation I think it would be useful to make sure we explain the differece between searching with analyzed or not analyzed queries somewhere since it gives some understanding into how search works and how to avoid some pitfalls. wdyt?
There was a problem hiding this comment.
Thanks for the feedback.
I think the warning provides enough information for users looking to get started quickly, but it doesn't explain why you should avoid using term-level queries for analyzed fields. The example in the aside is great for that.
I think that content would fit better in a concept-focused page like "Search structured data" or "Search full-text." Those don't exist yet, but I'll work on creating them and add it to this PR.
There was a problem hiding this comment.
That sounds great, thanks
There was a problem hiding this comment.
I like the cleanup and the succinctness of the rewrite in general. I'd love to see (or keep) some longer examples like the ones removed here either in later sections in the docs (maybe linked from here), or on the bottom of the page though. Nothing to block this PR, but I'd like to hear your and other opinions on this.
| <3> The `full_text` inverted index will contain the terms: [`quick`, `foxes`]. | ||
| <4> The `exact_value` inverted index will contain the exact term: [`Quick Foxes!`]. | ||
|
|
||
| Now, compare the results for the `term` query and the `match` query: |
There was a problem hiding this comment.
Just out of curiosity: are there follow up plans to move these more detailed examples somewhere else? While I like the idea of having succinct, standardized docs for each query, I find these kind of examples quite useful and better to understand than merely the minimal snippet that remains. Not saying this shouldn't go away, I'm just curious what the plan is for examples like this in this rewriting effort.
There was a problem hiding this comment.
Thanks for the feedback @cbuescher.
For this particular set of examples, I think a concept-focused page like "Search structured data" or "Search full-text" would be a better fit. Those pages don't exist yet, but I'll work on creating them and add it to this PR.
For other queries, I think we can include additional sections for detailed examples below parameter documentation. A good example of this would be the missing query section for the exists query.
Let me know if you feel differently. I'm still new so there could be context I'm missing.
|
@jrodewig IT looks like something has gone wrong with merging here. Let me know if you need help correcting it |
* Simplifies description of `term` query * Replaces aside with warning to not use for `text` field types * Removes detailed information about boost * Adds parameters sections
|
Yep. Sorry about that @colings86. Looks like my rebase went wrong. Should be fixed up now. |
|
Awesome, thanks for the quick fix @jrodewig |
|
Thanks again for your feedback @colings86 and @cbuescher. With ed44215, I changed directions and re-added a revised version of the " I initially proposed to include this example in a new "Search structured data" or "Search full text" page. However, after beginning work, I realized my plan had a few issues:
Please let me know what you think of the new changes. Thanks again. |
|
@jrodewig I like this new approach as it still provides the important information for understanding what the query is doing but keeps it from getting in the way of the details on how to specify the query |
* [DOCS] Restructure `term` query docs.
* [DOCS] Restructure `term` query docs.
* [DOCS] Restructure `term` query docs.
* elastic/master: (414 commits) Add tasks to build Docker build context artifacts (elastic#41819) Replace more uses of immutable map builder (elastic#41823) Force selection of calendar or fixed intervals in date histo agg (elastic#33727) Switch run task to use real distro (elastic#41590) Clarify that path_match also considers object fields. (elastic#41658) [DOCS] remove 'es.scripting.update.ctx_in_params' system property for 7.0 (elastic#41643) Clarify _doc is a permanent part of certain document APIs. (elastic#41727) Remove the jdk directory to save space on bwc tests (elastic#41743) Fix full text queries test that start with now (elastic#41854) Remove `nonApplicationWrite` from `SSLDriver` (elastic#41829) SQL: [Docs] Add example for custom bucketing with CASE (elastic#41787) Cleanup Bulk Delete Exception Logging (elastic#41693) [DOCS] Rewrite `term` query docs for new format (elastic#41498) Mute PermissionsIT#testWhen[...]ByILMPolicy (elastic#41858) ReadOnlyEngine assertion fix (elastic#41842) [ML] addresses preview bug, and adds check to PUT (elastic#41803) Fix javadoc in WrapperQueryBuilder Testsclusters use seprate configurations per version (elastic#41504) Skip explain fetch sub phase when request holds only suggestions (elastic#41739) remove unused import ...
* [DOCS] Restructure `term` query docs.
* [DOCS] Restructure `term` query docs.
Changes
termquerytextfield typesThis is part of #40977, an effort to standardize documentation for query types.
Any and all feedback welcome!
Things to note for possible discussion
valueparameter) as it made parameter documentation a bit more clear.boostis important, it felt out of place here. I made a note about this in [DOCS] Standardize query documentation #40977.Before / After
Before changes
After changes