Merge branch 'master' into manage-own-api-key-privilege

Author: Yogesh Gaikwad

.ci/bwcVersions

@@ -7,5 +7,6 @@ BWC_VERSION:
   - "7.2.1"
   - "7.3.0"
   - "7.3.1"
+  - "7.3.2"
   - "7.4.0"
   - "8.0.0"

client/rest-high-level/src/test/java/org/elasticsearch/client/SearchIT.java

@@ -43,6 +43,7 @@
 import org.elasticsearch.common.xcontent.XContentBuilder;
 import org.elasticsearch.common.xcontent.XContentFactory;
 import org.elasticsearch.common.xcontent.XContentType;
+import org.elasticsearch.index.query.MatchAllQueryBuilder;
 import org.elasticsearch.index.query.MatchQueryBuilder;
 import org.elasticsearch.index.query.QueryBuilders;
 import org.elasticsearch.index.query.ScriptQueryBuilder;
@@ -81,6 +82,7 @@
 import org.elasticsearch.search.suggest.Suggest;
 import org.elasticsearch.search.suggest.SuggestBuilder;
 import org.elasticsearch.search.suggest.phrase.PhraseSuggestionBuilder;
+import org.elasticsearch.xpack.core.index.query.PinnedQueryBuilder;
 import org.hamcrest.Matchers;
 import org.junit.Before;
 
@@ -92,7 +94,10 @@
 import java.util.Map;
 
 import static org.elasticsearch.common.xcontent.XContentFactory.jsonBuilder;
+import static org.elasticsearch.test.hamcrest.ElasticsearchAssertions.assertFirstHit;
+import static org.elasticsearch.test.hamcrest.ElasticsearchAssertions.assertSecondHit;
 import static org.elasticsearch.test.hamcrest.ElasticsearchAssertions.assertToXContentEquivalent;
+import static org.elasticsearch.test.hamcrest.ElasticsearchAssertions.hasId;
 import static org.hamcrest.Matchers.both;
 import static org.hamcrest.Matchers.containsString;
 import static org.hamcrest.Matchers.either;
@@ -1373,7 +1378,19 @@ public void testCountAllIndicesMatchQuery() throws IOException {
         assertCountHeader(countResponse);
         assertEquals(3, countResponse.getCount());
     }
-
+    
+    public void testSearchWithBasicLicensedQuery() throws IOException {
+        SearchRequest searchRequest = new SearchRequest("index");
+        SearchSourceBuilder searchSourceBuilder = new SearchSourceBuilder();
+        PinnedQueryBuilder pinnedQuery = new PinnedQueryBuilder(new MatchAllQueryBuilder(), "2", "1");
+        searchSourceBuilder.query(pinnedQuery);
+        searchRequest.source(searchSourceBuilder);
+        SearchResponse searchResponse = execute(searchRequest, highLevelClient()::search, highLevelClient()::searchAsync);
+        assertSearchHeader(searchResponse);
+        assertFirstHit(searchResponse, hasId("2"));
+        assertSecondHit(searchResponse, hasId("1"));
+    }
+    
     private static void assertCountHeader(CountResponse countResponse) {
         assertEquals(0, countResponse.getSkippedShards());
         assertEquals(0, countResponse.getFailedShards());

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

@@ -83,6 +83,7 @@ This page lists all the available search queries with their corresponding `Query
 | {ref}/query-dsl-percolate-query.html[Percolate]                     | {percolate-ref}/PercolateQueryBuilder.html[PercolateQueryBuilder]                   |
 | {ref}/query-dsl-wrapper-query.html[Wrapper]                         | {query-ref}/WrapperQueryBuilder.html[WrapperQueryBuilder]                           | {query-ref}/QueryBuilders.html#wrapperQuery-java.lang.String-[QueryBuilders.wrapperQuery()]
 | {ref}/query-dsl-rank-feature-query.html[Rank Feature]               | {mapper-extras-ref}/RankFeatureQuery.html[RankFeatureQueryBuilder]                  |
+| {ref}/query-dsl-pinned-query.html[Pinned Query]                     | The PinnedQueryBuilder is packaged as part of the xpack-core module                 |
 |======
 
 ==== Span queries

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

@@ -4,39 +4,174 @@
 <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 when providing additional parameters (note the slight
-change in structure, `message` is the field name):
+Here is an example with the `operator` parameter:
 
 [source,js]
 --------------------------------------------------
@@ -63,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.

docs/reference/scripting/using.asciidoc

@@ -195,6 +195,21 @@ DELETE _scripts/calculate-score
 // CONSOLE
 // TEST[continued]
 
+[float]
+[[modules-scripting-search-templates]]
+=== Search templates
+You can also use the `_scripts` API to store **search templates**. Search
+templates save specific <<search-search,search requests>> with placeholder
+values, called template parameters.
+
+You can use stored search templates to run searches without writing out the
+entire query. Just provide the stored template's ID and the template parameters.
+This is useful when you want to run a commonly used query quickly and without
+mistakes.
+
+Search templates use the http://mustache.github.io/mustache.5.html[mustache
+templating language]. See <<search-template>> for more information and examples.
+
 [float]
 [[modules-scripting-using-caching]]
 === Script caching