[DOCS] Re-add term vs. match query example

Author: jrodewig

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

@@ -37,10 +37,12 @@ GET /_search
 ----
 // CONSOLE
 
+[[term-top-level-params]]
 ==== Top-level parameters for `term`
 `<field>`::
 Field you wish to search.
 
+[[term-field-params]]
 ==== Parameters for `<field>`
 `value`::
 Term you wish to find in the provided `<field>`. To return a document, the term
@@ -58,3 +60,151 @@ 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.
 
+[[term-query-notes]]
+==== Notes
+
+[[avoid-term-query-text-fields]]
+===== Avoid using the `term` query for `text` fields
+By default, {es} changes the values of `text` fields during analysis. For
+example, the default <<analysis-standard-analyzer, standard analyzer>> changes
+`text` field values as follows:
+
+* Removes most punctuation
+* Divides the remaining content into individual words, called
+<<analysis-tokenizers, tokens>>
+* Lowercases the tokens
+
+To better search `text` fields, the `match` query also analyzes your provided
+search term before performing a search. This means the `match` query can search
+`text` fields for analyzed tokens rather than an exact term.
+
+The `term` query does *not* analyze the search term. The `term` query only
+searches for the *exact* term you provide. This means the `term` query may
+return poor or no results when searching `text` fields.
+
+To see the difference in search results, try the following example.  
+
+. Create an index with a `text` field called `full_text`.
++
+--
+
+[source,js]
+----
+PUT my_index
+{
+    "mappings" : {
+        "properties" : {
+            "full_text" : { "type" : "text" }
+        }
+    }
+}
+----
+// CONSOLE
+
+--
+
+. Index a document with a value of `Quick Brown Foxes!` in the `full_text`
+field.
++
+--
+
+[source,js]
+----
+PUT my_index/_doc/1
+{
+  "full_text":   "Quick Brown Foxes!"
+}
+----
+// CONSOLE
+// TEST[continued]
+
+Because `full_text` is a `text` field, {es} changes `Quick Brown Foxes!` to
+`[quick, brown, fox]` during analysis.
+
+--
+
+. Use the `term` query to search for `Quick Brown Foxes!` in the `full_text`
+field. Include the `pretty` parameter so the response is more readable.
++
+--
+
+[source,js]
+----
+GET my_index/_search?pretty
+{
+  "query": {
+    "term": {
+      "full_text": "Quick Brown Foxes!"
+    }
+  }
+}
+----
+// CONSOLE
+// TEST[continued]
+
+Because the `full_text` field no longer contains the *exact* term `Quick Brown
+Foxes!`, the `term` query search returns no results.
+
+--
+
+. Use the `match` query to search for `Quick Brown Foxes!` in the `full_text`
+field.
++
+--
+
+[source,js]
+----
+GET my_index/_search?pretty
+{
+  "query": {
+    "match": {
+      "full_text": "Quick Brown Foxes!"
+    }
+  }
+}
+----
+// CONSOLE
+// TEST[continued]
+
+Unlike the `term` query, the `match` query analyzes your provided search term,
+`Quick Brown Foxes!`, before performing a search. The `match` query then returns
+any documents containing the `quick`, `brown`, or `fox` tokens in the
+`full_text` field.
+
+Here's the response for the `match` query search containing the indexed document
+in the results.
+
+[source,js]
+----
+{
+  "took" : 1,
+  "timed_out" : false,
+  "_shards" : {
+    "total" : 1,
+    "successful" : 1,
+    "skipped" : 0,
+    "failed" : 0
+  },
+  "hits" : {
+    "total" : {
+      "value" : 1,
+      "relation" : "eq"
+    },
+    "max_score" : 0.8630463,
+    "hits" : [
+      {
+        "_index" : "my_index",
+        "_type" : "_doc",
+        "_id" : "1",
+        "_score" : 0.8630463,
+        "_source" : {
+          "full_text" : "Quick Brown Foxes!"
+        }
+      }
+    ]
+  }
+}
+----
+// TESTRESPONSE[s/1/$body.took/]
+
+--