Browse Source

[DOCS] Rewrite term-level queries overview (#43337)

James Rodewig 6 years ago
parent
commit
97f70c5e27

+ 1 - 1
docs/java-rest/high-level/query-builders.asciidoc

@@ -27,7 +27,7 @@ This page lists all the available search queries with their corresponding `Query
 | {ref}/query-dsl-simple-query-string-query.html[Simple Query String] | {query-ref}/SimpleQueryStringBuilder.html[SimpleQueryStringBuilder]                 | {query-ref}/QueryBuilders.html#simpleQueryStringQuery-java.lang.String-[QueryBuilders.simpleQueryStringQuery()]
 |======
 
-==== Term level queries
+==== Term-level queries
 [options="header"]
 |======
 | Search Query                                                        | QueryBuilder Class | Method in QueryBuilders

+ 1 - 1
docs/reference/mapping/params/normalizer.asciidoc

@@ -7,7 +7,7 @@ produces a single token.
 
 The `normalizer` is applied prior to indexing the keyword, as well as at
 search-time when the `keyword` field is searched via a query parser such as
-the <<query-dsl-match-query,`match`>> query or via a term level query 
+the <<query-dsl-match-query,`match`>> query or via a term-level query 
 such as the <<query-dsl-term-query,`term`>> query.
 
 [source,js]

+ 32 - 41
docs/reference/query-dsl/term-level-queries.asciidoc

@@ -1,68 +1,59 @@
 [[term-level-queries]]
-== Term level queries
+== Term-level queries
 
-While the <<full-text-queries,full text queries>> will analyze the query
-string before executing, the _term-level queries_ operate on the exact terms
-that are stored in the inverted index, and will normalize terms before executing 
-only for <<keyword,`keyword`>> fields with <<normalizer,`normalizer`>> property.
+You can use **term-level queries** to find documents based on precise values in
+structured data. Examples of structured data include date ranges, IP addresses,
+prices, or product IDs.
 
-These queries are usually used for structured data like numbers, dates, and
-enums, rather than full text fields.  Alternatively, they allow you to craft
-low-level queries, foregoing the analysis process.
+Unlike <<full-text-queries, full-text queries>>, term-level queries do not
+analyze search terms. Instead, term-level queries match the exact terms stored
+in a field.
 
-The queries in this group are:
 
-<<query-dsl-term-query,`term` query>>::
+[NOTE]
+====
+Term-level queries still normalize search terms for `keyword` fields with the
+`normalizer` property. For more details, see <<normalizer, `normalizer`>>.
+====
 
-    Find documents which contain the exact term specified in the field
-    specified.
+[float]
+[[term-level-query-types]]
+=== Types of term-level queries
 
-<<query-dsl-terms-query,`terms` query>>::
+<<query-dsl-term-query,`term` query>>::
+Returns documents that contain an exact term in a provided field.
 
-    Find documents which contain any of the exact terms specified in the field
-    specified.
+<<query-dsl-terms-query,`terms` query>>::
+Returns documents that contain one or more exact terms in a provided field.
 
 <<query-dsl-terms-set-query,`terms_set` query>>::
-
-    Find documents which match with one or more of the specified terms. The
-    number of terms that must match depend on the specified minimum should
-    match field or script.
+Returns documents that contain a minimum number of exact terms in a provided
+field. You can define the minimum number of matching terms using a field or
+script.
 
 <<query-dsl-range-query,`range` query>>::
-
-    Find documents where the field specified contains values (dates, numbers,
-    or strings) in the range specified.
+Returns documents that contain terms within a provided range.
 
 <<query-dsl-exists-query,`exists` query>>::
-
-    Find documents where the field specified contains any non-null value.
+Returns documents that contain any indexed value for a field.
 
 <<query-dsl-prefix-query,`prefix` query>>::
-
-    Find documents where the field specified contains terms which begin with
-    the exact prefix specified.
+Returns documents that contain a specific prefix in a provided field.
 
 <<query-dsl-wildcard-query,`wildcard` query>>::
-
-    Find documents where the field specified contains terms which match the
-    pattern specified, where the pattern supports single character wildcards
-    (`?`) and multi-character wildcards (`*`)
+Returns documents that contain terms matching a wildcard pattern.
 
 <<query-dsl-regexp-query,`regexp` query>>::
-
-    Find documents where the field specified contains terms which match the
-    <<regexp-syntax,regular expression>> specified.
+Returns documents that contain terms matching a
+https://en.wikipedia.org/wiki/Regular_expression[regular expression].
 
 <<query-dsl-fuzzy-query,`fuzzy` query>>::
-
-    Find documents where the field specified contains terms which are fuzzily
-    similar to the specified term.  Fuzziness is measured as a
-    http://en.wikipedia.org/wiki/Damerau%E2%80%93Levenshtein_distance[Levenshtein edit distance]
-    of 1 or 2.
+Returns documents that contain terms similar to the search term. {es} measures
+similarity, or fuzziness, using a
+http://en.wikipedia.org/wiki/Levenshtein_distance[Levenshtein edit distance].
 
 <<query-dsl-ids-query,`ids` query>>::
-
-    Find documents with the specified IDs.
+Returns documents based on their <<mapping-id-field, document IDs>>. 
 
 
 include::term-query.asciidoc[]