From 3911061869e7854e43c5dc12d00f2fe1e0d905c0 Mon Sep 17 00:00:00 2001 From: Kathleen DeRusso Date: Wed, 22 May 2024 08:04:14 -0400 Subject: [PATCH] Update Search Applications docs with more introductory information about search templates (#108697) * Update Search Applications docs with more introductory information about search templates * Add docs tests * Skip test * Fix test * Unskip test * Add comment RE: reasoning behind test setup --- .../search-application-api.asciidoc | 258 +++++++++++++++--- 1 file changed, 219 insertions(+), 39 deletions(-) diff --git a/docs/reference/search/search-your-data/search-application-api.asciidoc b/docs/reference/search/search-your-data/search-application-api.asciidoc index 0b7510d20658d..6312751d37bca 100644 --- a/docs/reference/search/search-your-data/search-application-api.asciidoc +++ b/docs/reference/search/search-your-data/search-application-api.asciidoc @@ -18,7 +18,7 @@ Search Application templates: * Reduce request size * Ensure security and performance, as the query is predefined and can't be changed arbitrarily -This document provides some sample templates to get you started using <> for additional use cases. +This document provides information and sample templates to get you started using <> for additional use cases. These templates are designed to be easily modified to meet your needs. Once you've created a search application with a template, you can search your search application using this template. @@ -36,11 +36,121 @@ Learn more by reading about <>. If no template is stored with a search application, a minimal <> will be applied at search time. The default template implements a simple search use case. -You can check your query parameters against the current template using the <> API call. + +To create a search application with the default template, issue a <> request without specifying a template: + +// NOTE for test setup: The create search application command will return a warning +// when a template is not specified. This will break docs tests. +// Therefore the setup specifies the default search template +// even though we're using the default template in examples. + +//// + +[source,console] +-------------------------------------------------- +PUT index1 +{ + "mappings": { + "properties": { + "image-vector": { + "type": "dense_vector", + "dims": 3 + } + } + } +} + +PUT index2 + +PUT _application/search_application/my_search_application +{ + "indices": [ "index1", "index2" ], + "template": { + "script": { + "source": { + "query": { + "query_string": { + "query": "{{query_string}}", + "default_field": "{{default_field}}" + } + } + }, + "params": { + "query_string": "*", + "default_field": "*" + } + } + } +} + +-------------------------------------------------- +// TESTSETUP + +[source,console] +-------------------------------------------------- +DELETE _application/search_application/my_search_application + +DELETE index1 + +DELETE index2 +-------------------------------------------------- +// TEARDOWN +//// + +[source,console] +---- +PUT _application/search_application/my_search_application +{ + "indices": ["index1", "index2"] +} +---- +// TEST[warning:Using default search application template which is subject to change. We recommend storing a template to avoid breaking changes.] + +You can then use the <> API call to view your newly created search application, which will also include the default template that was created for you: + +[source,console] +---- +GET _application/search_application/my_search_application +---- +// TEST[continued] +// TEST[warning:Using default search application template which is subject to change. We recommend storing a template to avoid breaking changes.] + +In this case, the response would be: + +[source,console-result] +---- +{ + "name": "my_search_application", + "indices": [ + "index1", + "index2" + ], + "updated_at_millis": 1715802354482, + "template": { + "script": { + "source": """{ + "query": { + "query_string": { + "query": "{{query_string}}", + "default_field": "{{default_field}}" + } + } +} +""", + "lang": "mustache", + "params": { + "default_field": "*", + "query_string": "*" + } + } + } +} +---- +// TESTRESPONSE[s/"updated_at_millis": 1715802354482/"updated_at_millis": $body.$_path/] The default template is very minimal: -[source,js] +[source,console-result] ---- { "template": { @@ -61,19 +171,87 @@ The default template is very minimal: } } ---- -// NOTCONSOLE +// TEST[skip:This is not a console result but NOTCONSOLE annotation by itself still fails the test] This may be useful for initial exploration of search templates, but you'll likely want to update this. -Here are some things to note about this default template: +NOTE: This template does not support additional parameters, including `from`, `size` or `boost`. +If you need to use these, you can customize the template associated with your search application accordingly to include them as parameters. + +You can see the parameters and their default values by viewing the template, but it also may be valuable to view the query that will be generated if you <> with various parameters. + +You can use the <> to view the query this template would generate, including with default parameters. +For example, searching the search application with no parameters: + +[source,console] +---- +POST _application/search_application/my_search_application/_render_query +---- +// TEST[continued] + +will return: + +[source,console-result] +---- +{ + "query": { + "query_string": { + "query": "*", + "default_field": "*", + "fields": [] + } + } +} +---- +// TEST[continued] + +This uses the default parameters that were defined with the template. +You can also specify one or mre parameters to the render call, for example: + +[source,console] +---- +POST _application/search_application/my_search_application/_render_query +{ + "params": { + "query_string": "rock climbing" + } +} +---- +// TEST[continued] + +will return: -* A call to `/_application/search_application/` with no parameters will return all results, in a similar manner to a parameterless call to `/_search`. -* Searching with the `query_string` and/or `default_field` parameters will perform a <> query. -* This template does not support additional parameters, including `from`, `size` or `boost`. +[source,console-result] +---- +{ + "query": { + "query_string": { + "query": "rock climbing", + "default_field": "*", + "fields": [] + } + } +} +---- +// TEST[continued] + +In this case, the `{{query_string}}` parameter has been replaced with the value `rock climbing`, and the `{{default_field}}` parameter was not specified so used the default value of `*`. + +When you actually perform a search with no parameters, it will execute the underlying query that the render call returned. +In this case, a search with no parameters will return all results, in a similar manner to a parameterless call to `/_search`. + +[source,console] +---- +POST _application/search_application/my_search_application/_search +---- +// TEST[continued] + + +Searching with the `query_string` and/or `default_field` parameters will perform a <> query. [WARNING] ==== -This template is subject to change in future versions of the Search Applications feature. +The default template is subject to change in future versions of the Search Applications feature. ==== Try some of the other examples in this document to experiment with specific use cases, or try creating your own! @@ -95,14 +273,14 @@ With the default template, a search looks like this: [source,console] ---- -POST _application/search_application//_search +POST _application/search_application/my_search_application/_search { "params": { - "query_string": "my first query" + "query_string": "kayaking" } } ---- -// TEST[skip:TODO] +// TEST[continued] In this example, we've overridden the `query_string` parameter's default value of `*`. Since we didn't specify `default_field` the value of this parameter will still be `*`. @@ -141,7 +319,7 @@ The following template supports a `multi_match` search over specified fields and ---- PUT _application/search_application/my_search_application { - "indices": ["my_index1", "my_index2"], + "indices": ["index1", "index2"], "template": { "script": { "lang": "mustache", @@ -172,9 +350,9 @@ PUT _application/search_application/my_search_application } } ---- -// TEST[skip:TODO] A search query using this template might look like this: + [source,console] ---- POST _application/search_application/my_search_application/_search @@ -190,7 +368,7 @@ POST _application/search_application/my_search_application/_search } } ---- -// TEST[skip:TODO] +// TEST[continued] The `text_fields` parameters can be overridden with new/different fields and boosts to experiment with the best configuration for your use case. This template also supports pagination and `explain` via parameters. @@ -208,7 +386,7 @@ It outperforms all other ranking algorithms, and often surpasses the best indivi PUT _application/search_application/my-search-app { "indices": [ - "search-my-crawler" + "index1" ], "template": { "script": { @@ -241,10 +419,10 @@ PUT _application/search_application/my-search-app } } } - } + }, {{/elser_fields}} ], - "window_size": {{rrf.window_size}}, + "rank_window_size": {{rrf.rank_window_size}}, "rank_constant": {{rrf.rank_constant}} } } @@ -255,7 +433,7 @@ PUT _application/search_application/my-search-app "text_fields": ["title", "meta_description"], "query_string": "", "rrf": { - "window_size": 100, + "rank_window_size": 100, "rank_constant": 60 } } @@ -263,7 +441,6 @@ PUT _application/search_application/my-search-app } } ---- -// TEST[skip:TODO] NOTE: Replace `` with the model ID of your ELSER deployment. @@ -278,13 +455,13 @@ POST _application/search_application/my-search-app/_search "elser_fields": ["title", "meta_description"], "text_fields": ["title", "meta_description"], "rrf": { - "window_size": 50, + "rank_window_size": 50, "rank_constant": 25 } } } ---- -// TEST[skip:TODO] +// TEST[skip:ELSER requires inference] [discrete] [[search-application-api-catchall-template]] @@ -303,8 +480,8 @@ It also provides a simple default `query_string` query if no parameters are spec PUT _application/search_application/my_search_application { "indices": [ - "my_index1", - "my_index2" + "index1", + "index2" ], "template": { "script": { @@ -385,9 +562,9 @@ PUT _application/search_application/my_search_application } } ---- -// TEST[skip:TODO] A text search query using this template might look like this: + [source,console] ---- POST _application/search_application/my_search_application/_search @@ -404,9 +581,10 @@ POST _application/search_application/my_search_application/_search } } ---- -// TEST[skip:TODO] +// TEST[skip:ELSER requires inference] An ELSER search query using this template will look like the following example: + [source,console] ---- POST _application/search_application/my_search_application/_search @@ -421,9 +599,10 @@ POST _application/search_application/my_search_application/_search } } ---- -// TEST[skip:TODO] +// TEST[skip:ELSER requires inference] A combined text search and ELSER search query using this template will look like the following example: + [source,console] ---- POST _application/search_application/my_search_application/_search @@ -441,7 +620,7 @@ POST _application/search_application/my_search_application/_search } } ---- -// TEST[skip:TODO] +// TEST[skip:ELSER requires inference] [TIP] ==== @@ -462,11 +641,12 @@ Finally, a parameterless search using this template would fall back to a default ---- POST _application/search_application/my_search_application/_search ---- -// TEST[skip:TODO] +// TEST[continued] [discrete] [[search-application-api-elser-template]] ===== ELSER search + This example supports a streamlined version of ELSER search. [source,console] @@ -474,8 +654,8 @@ This example supports a streamlined version of ELSER search. PUT _application/search_application/my_search_application { "indices": [ - "my_index1", - "my_index2" + "index1", + "index2" ], "template": { "script": { @@ -517,7 +697,6 @@ PUT _application/search_application/my_search_application } } ---- -// TEST[skip:TODO] NOTE: Replace `` with the model ID of your ELSER deployment. @@ -532,12 +711,13 @@ POST _application/search_application/my_search_application/_search } } ---- -// TEST[skip:TODO] +// TEST[skip:ELSER requires inference] [discrete] [[search-applications-knn-template]] ===== kNN search + This example supports <> A template supporting exact kNN search will look like the following example: @@ -547,7 +727,7 @@ A template supporting exact kNN search will look like the following example: PUT _application/search_application/my_search_application { "indices": [ - "my_product_index" + "index1" ], "template": { "script": { @@ -585,9 +765,9 @@ PUT _application/search_application/my_search_application } } ---- -// TEST[skip:TODO] A search query using this template will look like the following example: + [source,console] ---- POST _application/search_application/my_search_application/_search @@ -599,7 +779,7 @@ POST _application/search_application/my_search_application/_search } } ---- -// TEST[skip:TODO] +// TEST[continued] A template supporting approximate kNN search will look like the following example: @@ -608,7 +788,7 @@ A template supporting approximate kNN search will look like the following exampl PUT _application/search_application/my_search_application { "indices": [ - "my_product_index" + "index1" ], "template": { "script": { @@ -635,9 +815,9 @@ PUT _application/search_application/my_search_application } } ---- -// TEST[skip:TODO] A search query using this template will look like the following example: + [source,console] ---- POST _application/search_application/my_search_application/_search @@ -652,4 +832,4 @@ POST _application/search_application/my_search_application/_search } ---- -// TEST[skip:TODO] +// TEST[continued]