[DOCS] Reformat match query (#45152)

Author: jrodewig

docs/reference/query-dsl/match-query.asciidoc

@@ -4,37 +4,191 @@
 <titleabbrev>Match</titleabbrev>
 ++++
 
+Returns documents that match a provided text, number, date or boolean value. The
+provided text is analyzed before matching.
 
-`match` queries accept text/numerics/dates, analyzes
-them, and constructs a query. For example:
+The `match` query is the standard query for performing a full-text search,
+including options for fuzzy matching.
+
+
+[[match-query-ex-request]]
+==== Example request
 
 [source,js]
 --------------------------------------------------
 GET /_search
 {
     "query": {
         "match" : {
-            "message" : "this is a test"
+            "message" : {
+                "query" : "this is a test"
+            }
         }
     }
 }
 --------------------------------------------------
 // CONSOLE
 
-Note, `message` is the name of a field, you can substitute the name of
-any field instead.
+
+[[match-top-level-params]]
+==== Top-level parameters for `match`
+
+`<field>`::
+(Required, object) Field you wish to search.
+
+
+[[match-field-params]]
+==== Parameters for `<field>`
+`query`::
++
+--
+(Required) Text, number, boolean value or date you wish to find in the provided
+`<field>`.
+
+The `match` query <<analysis,analyzes>> any provided text before performing a
+search. This means the `match` query can search <<text,`text`>> fields for
+analyzed tokens rather than an exact term.
+--
+
+`analyzer`::
+(Optional, string) <<analysis,Analyzer>> used to convert the text in the `query`
+value into tokens. Defaults to the <<specify-index-time-analyzer,index-time
+analyzer>> mapped for the `<field>`. If no analyzer is mapped, the index's
+default analyzer is used.
+
+`auto_generate_synonyms_phrase_query`::
++
+--
+(Optional, boolean) If `true`, <<query-dsl-match-query-phrase,match phrase>>
+queries are automatically created for multi-term synonyms. Defaults to `true`.
+
+See <<query-dsl-match-query-synonyms,Use synonyms with match query>> for an
+example.
+--
+
+`fuzziness`::
+(Optional, string) Maximum edit distance allowed for matching. See <<fuzziness>>
+for valid values and more information. See <<query-dsl-match-query-fuzziness>>
+for an example.
+
+`max_expansions`::
+(Optional, integer) Maximum number of terms to which the query will
+expand. Defaults to `50`.
+
+`prefix_length`::
+(Optional, integer) Number of beginning characters left unchanged for fuzzy
+matching. Defaults to `0`.
+
+`transpositions`::
+(Optional, boolean) If `true`, edits for fuzzy matching include
+transpositions of two adjacent characters (ab → ba). Defaults to `true`.
+
+`fuzzy_rewrite`::
++
+--
+(Optional, string) Method used to rewrite the query. See the
+<<query-dsl-multi-term-rewrite, `rewrite` parameter>> for valid values and more
+information.
+
+If the `fuzziness` parameter is not `0`, the `match` query uses a `rewrite`
+method of `top_terms_blended_freqs_${max_expansions}` by default.
+--
+
+`lenient`::
+(Optional, boolean) If `true`, format-based errors, such as providing a text
+`query` value for a <<number,numeric>> field, are ignored. Defaults to `false`.
+
+`operator`::
++
+--
+(Optional, string) Boolean logic used to interpret text in the `query` value.
+Valid values are:
+
+`OR` (Default)::
+For example, a `query` value of `capital of Hungary` is interpreted as `capital
+OR of OR Hungary`.
+
+`AND`::
+For example, a `query` value of `capital of Hungary` is interpreted as `capital
+AND of AND Hungary`.
+--
+
+`minimum_should_match`::
++
+--
+(Optional, string) Minimum number of clauses that must match for a document to
+be returned. See the <<query-dsl-minimum-should-match, `minimum_should_match`
+parameter>> for valid values and more information.
+--
+
+`zero_terms_query`::
++
+--
+(Optional, string) Indicates whether no documents are returned if the `analyzer`
+removes all tokens, such as when using a `stop` filter. Valid values are:
+
+`none` (Default)::
+No documents are returned if the `analyzer` removes all tokens.
+
+`all`::
+Returns all documents, similar to a <<query-dsl-match-all-query,`match_all`>>
+query.
+
+See <<query-dsl-match-query-zero>> for an example.
+--
+
+
+[[match-query-notes]]
+==== Notes
+
+[[query-dsl-match-query-short-ex]]
+===== Short request example
+
+You can simplify the match query syntax by combining the `<field>` and `query`
+parameters. For example:
+
+[source,js]
+----
+GET /_search
+{
+    "query": {
+        "match" : {
+            "message" : "this is a test"
+        }
+    }
+}
+----
+// CONSOLE
 
 [[query-dsl-match-query-boolean]]
-==== match
+===== How the match query works
 
 The `match` query is of type `boolean`. It means that the text
 provided is analyzed and the analysis process constructs a boolean query
-from the provided text. The `operator` flag can be set to `or` or `and`
+from the provided text. The `operator` parameter can be set to `or` or `and`
 to control the boolean clauses (defaults to `or`). The minimum number of
 optional `should` clauses to match can be set using the
 <<query-dsl-minimum-should-match,`minimum_should_match`>>
 parameter.
 
+Here is an example with the `operator` parameter:
+
+[source,js]
+--------------------------------------------------
+GET /_search
+{
+    "query": {
+        "match" : {
+            "message" : {
+                "query" : "this is a test",
+                "operator" : "and"
+            }
+        }
+    }
+}
+--------------------------------------------------
+// CONSOLE
+
 The `analyzer` can be set to control which analyzer will perform the
 analysis process on the text. It defaults to the field explicit mapping
 definition, or the default search analyzer.
@@ -44,7 +198,7 @@ data-type mismatches,  such as trying to query a numeric field with a text
 query string. Defaults to `false`.
 
 [[query-dsl-match-query-fuzziness]]
-===== Fuzziness
+===== Fuzziness in the match query
 
 `fuzziness` allows _fuzzy matching_ based on the type of field being queried.
 See <<fuzziness>> for allowed settings.