From 67326252d867dcd23c3ad54e261cee0bb92fc986 Mon Sep 17 00:00:00 2001
From: James Rodewig <james.rodewig@elastic.co>
Date: Thu, 30 May 2019 08:30:30 -0400
Subject: [PATCH] [DOCS] Rewrite 'wildcard' query (#42670)

---
 .../query-dsl/wildcard-query.asciidoc         | 86 +++++++++++--------
 1 file changed, 51 insertions(+), 35 deletions(-)

diff --git a/docs/reference/query-dsl/wildcard-query.asciidoc b/docs/reference/query-dsl/wildcard-query.asciidoc
index ba1c72bb1e5..b2e8eb0adf7 100644
--- a/docs/reference/query-dsl/wildcard-query.asciidoc
+++ b/docs/reference/query-dsl/wildcard-query.asciidoc
@@ -1,51 +1,67 @@
 [[query-dsl-wildcard-query]]
 === Wildcard Query
+Returns documents that contain terms matching a wildcard pattern.
 
-Matches documents that have fields matching a wildcard expression (*not
-analyzed*). Supported wildcards are `*`, which matches any character
-sequence (including the empty one), and `?`, which matches any single
-character. Note that this query can be slow, as it needs to iterate over many
-terms. In order to prevent extremely slow wildcard queries, a wildcard
-term should not start with one of the wildcards `*` or `?`. The wildcard
-query maps to Lucene `WildcardQuery`.
+A wildcard operator is a placeholder that matches one or more characters. For
+example, the `*` wildcard operator matches zero or more characters. You can
+combine wildcard operators with other characters to create a wildcard pattern.
+
+[[wildcard-query-ex-request]]
+==== Example request
+
+The following search returns documents where the `user` field contains a term
+that begins with `ki` and ends with `y`. These matching terms can include `kiy`,
+`kity`, or `kimchy`.
 
 [source,js]
---------------------------------------------------
+----
 GET /_search
 {
     "query": {
-        "wildcard" : { "user" : "ki*y" }
+        "wildcard": {
+            "user": {
+                "value": "ki*y",
+                "boost": 1.0,
+                "rewrite": "constant_score"
+            }
+        }
     }
 }
---------------------------------------------------
+----
 // CONSOLE
 
-A boost can also be associated with the query:
+[[wildcard-top-level-params]]
+==== Top-level parameters for `wildcard`
+`<field>`::
+Field you wish to search.
 
-[source,js]
---------------------------------------------------
-GET /_search
-{
-    "query": {
-        "wildcard" : { "user" : { "value" : "ki*y", "boost" : 2.0 } }
-    }
-}
---------------------------------------------------
-// CONSOLE
+[[wildcard-query-field-params]]
+==== Parameters for `<field>`
+`value`::
+Wildcard pattern for terms you wish to find in the provided `<field>`.
++
+--
+This parameter supports two wildcard operators:
 
-Or :
+* `?`, which matches any single character
+* `*`, which can match zero or more characters, including an empty one
 
-[source,js]
---------------------------------------------------
-GET /_search
-{
-    "query": {
-        "wildcard" : { "user" : { "wildcard" : "ki*y", "boost" : 2.0 } }
-    }
-}
---------------------------------------------------
-// CONSOLE
+WARNING: Avoid beginning patterns with `*` or `?`. This can increase
+the iterations needed to find matching terms and slow search performance.
+-- 
 
-This multi term query allows to control how it gets rewritten using the
-<<query-dsl-multi-term-rewrite,rewrite>>
-parameter.
+`boost`::
+Floating point number used to decrease or increase the
+<<query-filter-context, relevance scores>> of a query. Default is `1.0`.
+Optional.
++
+You can use the `boost` parameter to adjust relevance scores for searches
+containing two or more queries.
++
+Boost values are relative to the default value of `1.0`. A boost value between
+`0` and `1.0` decreases the relevance score. A value greater than `1.0`
+increases the relevance score.
+
+`rewrite` (Expert)::
+Method used to rewrite the query. For valid values and more information, see the
+<<query-dsl-multi-term-rewrite, `rewrite` parameter>>. Optional.
\ No newline at end of file