From 25b4c31b57a625b8ca2157de5dbaa408febdcf2a Mon Sep 17 00:00:00 2001 From: Bharathi-Kanna <99189546+Bharathi-Kanna@users.noreply.github.com> Date: Fri, 17 Jul 2026 12:54:20 +0530 Subject: [PATCH 1/4] Document Mustache template support in Search Relevance Workbench Search configurations can now use Mustache template variables ({{query_string}} and query set custom fields) in the query, in addition to the existing %SearchText% placeholder. Document the templating behavior, variable sources, automatic JSON escaping, and that Mustache partials are not supported, with an example. Also document custom fields on query set entries and how they map to template variables. Corresponds to opensearch-project/search-relevance#342. Signed-off-by: Bharathi-Kanna <99189546+Bharathi-Kanna@users.noreply.github.com> --- .../search-relevance/query-sets.md | 15 ++++++++++ .../search-relevance/search-configurations.md | 30 ++++++++++++++++++- 2 files changed, 44 insertions(+), 1 deletion(-) diff --git a/_search-plugins/search-relevance/query-sets.md b/_search-plugins/search-relevance/query-sets.md index dc6481dbb3c..8f98dde56ad 100644 --- a/_search-plugins/search-relevance/query-sets.md +++ b/_search-plugins/search-relevance/query-sets.md @@ -85,6 +85,7 @@ All query sets comprise one or more entries. Each entry is a JSON object contain | :--- | :--- | :--- | | `queryText` | String | The user query string. Required. | | `referenceAnswer` | String | The expected or correct answer to the user query. This field is used for generating judgments, especially with large language models (LLMs). Optional. | +| Custom fields | String | Any additional field (beyond `queryText` and `referenceAnswer`) is stored as a custom field on the entry. Custom fields are available as [Mustache template variables]({{site.url}}{{site.baseurl}}/search-plugins/search-relevance/search-configurations/#using-mustache-templates) in a search configuration, referenced by field name. Optional. | ### Basic query set example @@ -117,6 +118,20 @@ This format includes the `referenceAnswer` field alongside the `queryText`. It i The `referenceAnswer` field is particularly useful when using [LLMs to generate judgments]({{site.url}}{{site.baseurl}}/search-plugins/search-relevance/judgments/). The LLM can use the reference answer as a ground truth to compare against the retrieved search results, allowing it to accurately score the relevance of the response. +### Query set with custom fields example + +In addition to `queryText`, each entry can include arbitrary custom fields. These values are available as Mustache template variables in a [search configuration]({{site.url}}{{site.baseurl}}/search-plugins/search-relevance/search-configurations/#using-mustache-templates), letting a single search configuration vary its filters or parameters for each query. + +#### Example query set with custom fields + +```json +{"queryText": "phone", "category": "electronics"} +{"queryText": "steel", "category": "materials"} +{"queryText": "keyboard", "category": "electronics"} +``` + +For example, a search configuration whose query references `{{category}}` filters each query's results by the category value provided in the corresponding entry. + ## Managing query sets You can retrieve or delete query sets using the following APIs. diff --git a/_search-plugins/search-relevance/search-configurations.md b/_search-plugins/search-relevance/search-configurations.md index f3d8abef36a..46b86379198 100644 --- a/_search-plugins/search-relevance/search-configurations.md +++ b/_search-plugins/search-relevance/search-configurations.md @@ -29,7 +29,7 @@ Field | Data type | Description :--- | :--- | :--- `name` | String | The name of the search configuration. `description` | String | Description of the search configuration. -`query` | Object | Defines the query in OpenSearch query DSL. Use `%SearchText%` as a placeholder for the user query. Needs to be escaped. +`query` | Object | Defines the query in OpenSearch query DSL. Use the `%SearchText%` placeholder or [Mustache](https://mustache.github.io/) template variables (such as `{{query_string}}`) to substitute query set values at runtime. Needs to be escaped. For more information, see [Using Mustache templates](#using-mustache-templates). `index` | String | The target index queried by this search configuration. `searchPipeline` | String | Specifies an existing search pipeline. Optional. @@ -45,6 +45,34 @@ PUT _plugins/_search_relevance/search_configurations } ``` +### Using Mustache templates + +Instead of the `%SearchText%` placeholder, a query can use [Mustache](https://mustache.github.io/) template variables. If the `query` contains `{{`, it is rendered as a Mustache template; otherwise, the `%SearchText%` placeholder is substituted. Existing `%SearchText%` configurations continue to work unchanged. + +The following variables are available when a template is rendered: + +* `{{query_string}}`: The `queryText` of the current query set entry. +* Any custom field defined on the query set entry, referenced by its field name (for example, `{{category}}`). For more information, see [Query sets]({{site.url}}{{site.baseurl}}/search-plugins/search-relevance/query-sets/). + +Substituted values are automatically JSON-escaped, so query text containing quotation marks or other special characters does not break the query. + +Mustache partials (`{{>...}}`) are not supported and cause the query to be rejected. +{: .note} + +#### Example request: Creating a search configuration that uses a Mustache template + +The following request creates a search configuration that matches the user query against the `title` field and filters results by a `category` custom field provided by each query set entry: + +```json +PUT _plugins/_search_relevance/search_configurations +{ + "name": "mustache_filter", + "query": "{\"query\":{\"bool\":{\"must\":[{\"match\":{\"title\":\"{{query_string}}\"}}],\"filter\":[{\"term\":{\"category\":\"{{category}}\"}}]}}}", + "description": "Title match filtered by a category custom field", + "index": "ecommerce" +} +``` + ## Managing search configurations You can retrieve or delete configurations using the following APIs. From 89f8d004e0dc6c88f809f9454867a0ab97bbf3d0 Mon Sep 17 00:00:00 2001 From: Bharathi-Kanna <99189546+Bharathi-Kanna@users.noreply.github.com> Date: Sat, 18 Jul 2026 01:25:32 +0530 Subject: [PATCH 2/4] Use {{queryText}} for the Mustache query variable Match the query set field name (queryText) instead of {{query_string}}, per review feedback on opensearch-project/search-relevance#342. Signed-off-by: Bharathi-Kanna <99189546+Bharathi-Kanna@users.noreply.github.com> --- _search-plugins/search-relevance/search-configurations.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/_search-plugins/search-relevance/search-configurations.md b/_search-plugins/search-relevance/search-configurations.md index 46b86379198..da8ce16a838 100644 --- a/_search-plugins/search-relevance/search-configurations.md +++ b/_search-plugins/search-relevance/search-configurations.md @@ -29,7 +29,7 @@ Field | Data type | Description :--- | :--- | :--- `name` | String | The name of the search configuration. `description` | String | Description of the search configuration. -`query` | Object | Defines the query in OpenSearch query DSL. Use the `%SearchText%` placeholder or [Mustache](https://mustache.github.io/) template variables (such as `{{query_string}}`) to substitute query set values at runtime. Needs to be escaped. For more information, see [Using Mustache templates](#using-mustache-templates). +`query` | Object | Defines the query in OpenSearch query DSL. Use the `%SearchText%` placeholder or [Mustache](https://mustache.github.io/) template variables (such as `{{queryText}}`) to substitute query set values at runtime. Needs to be escaped. For more information, see [Using Mustache templates](#using-mustache-templates). `index` | String | The target index queried by this search configuration. `searchPipeline` | String | Specifies an existing search pipeline. Optional. @@ -51,7 +51,7 @@ Instead of the `%SearchText%` placeholder, a query can use [Mustache](https://mu The following variables are available when a template is rendered: -* `{{query_string}}`: The `queryText` of the current query set entry. +* `{{queryText}}`: The `queryText` of the current query set entry. * Any custom field defined on the query set entry, referenced by its field name (for example, `{{category}}`). For more information, see [Query sets]({{site.url}}{{site.baseurl}}/search-plugins/search-relevance/query-sets/). Substituted values are automatically JSON-escaped, so query text containing quotation marks or other special characters does not break the query. @@ -67,7 +67,7 @@ The following request creates a search configuration that matches the user query PUT _plugins/_search_relevance/search_configurations { "name": "mustache_filter", - "query": "{\"query\":{\"bool\":{\"must\":[{\"match\":{\"title\":\"{{query_string}}\"}}],\"filter\":[{\"term\":{\"category\":\"{{category}}\"}}]}}}", + "query": "{\"query\":{\"bool\":{\"must\":[{\"match\":{\"title\":\"{{queryText}}\"}}],\"filter\":[{\"term\":{\"category\":\"{{category}}\"}}]}}}", "description": "Title match filtered by a category custom field", "index": "ecommerce" } From b09f820431fa5a1334c7a71ce5a1d6a7d353d72b Mon Sep 17 00:00:00 2001 From: Fanit Kolchina Date: Wed, 29 Jul 2026 14:05:39 -0400 Subject: [PATCH 3/4] Doc review Signed-off-by: Fanit Kolchina --- .../Vocab/OpenSearch/Products/accept.txt | 1 + .../search-relevance/query-sets.md | 11 +++++----- .../search-relevance/search-configurations.md | 21 +++++++++---------- 3 files changed, 16 insertions(+), 17 deletions(-) diff --git a/.github/vale/styles/Vocab/OpenSearch/Products/accept.txt b/.github/vale/styles/Vocab/OpenSearch/Products/accept.txt index e4be8846456..1d80b812525 100644 --- a/.github/vale/styles/Vocab/OpenSearch/Products/accept.txt +++ b/.github/vale/styles/Vocab/OpenSearch/Products/accept.txt @@ -130,6 +130,7 @@ Microsoft Power BI Migration Assistant Migration Console Minikube +Mustache Nagle Nagios NVMe diff --git a/_search-plugins/search-relevance/query-sets.md b/_search-plugins/search-relevance/query-sets.md index 8f98dde56ad..ccaf715b0b3 100644 --- a/_search-plugins/search-relevance/query-sets.md +++ b/_search-plugins/search-relevance/query-sets.md @@ -85,7 +85,7 @@ All query sets comprise one or more entries. Each entry is a JSON object contain | :--- | :--- | :--- | | `queryText` | String | The user query string. Required. | | `referenceAnswer` | String | The expected or correct answer to the user query. This field is used for generating judgments, especially with large language models (LLMs). Optional. | -| Custom fields | String | Any additional field (beyond `queryText` and `referenceAnswer`) is stored as a custom field on the entry. Custom fields are available as [Mustache template variables]({{site.url}}{{site.baseurl}}/search-plugins/search-relevance/search-configurations/#using-mustache-templates) in a search configuration, referenced by field name. Optional. | +| Custom fields | String | Any field other than `queryText` and `referenceAnswer` is stored as a custom field in the entry. You can reference a custom field by its name as a [Mustache template variable]({{site.url}}{{site.baseurl}}/search-plugins/search-relevance/search-configurations/#using-mustache-templates) in a search configuration. Optional. | ### Basic query set example @@ -103,7 +103,7 @@ A basic query set contains only the `queryText` field for each entry. It is suit ### Query set with reference answers example -This format includes the `referenceAnswer` field alongside the `queryText`. It is ideal for evaluating applications designed to provide specific answers, such as chatbots or question-answering systems. +In this format, each entry pairs a `queryText` with a `referenceAnswer`. Use it to evaluate applications that return a specific answer, such as chatbots or question-answering systems. #### Example query set with reference answers @@ -115,23 +115,22 @@ This format includes the `referenceAnswer` field alongside the `queryText`. It i {"queryText": "When was the first iPhone released?", "referenceAnswer": "June 29, 2007"} ``` - The `referenceAnswer` field is particularly useful when using [LLMs to generate judgments]({{site.url}}{{site.baseurl}}/search-plugins/search-relevance/judgments/). The LLM can use the reference answer as a ground truth to compare against the retrieved search results, allowing it to accurately score the relevance of the response. ### Query set with custom fields example -In addition to `queryText`, each entry can include arbitrary custom fields. These values are available as Mustache template variables in a [search configuration]({{site.url}}{{site.baseurl}}/search-plugins/search-relevance/search-configurations/#using-mustache-templates), letting a single search configuration vary its filters or parameters for each query. +In addition to `queryText`, each entry can include custom fields. You can reference these fields as Mustache template variables in a [search configuration]({{site.url}}{{site.baseurl}}/search-plugins/search-relevance/search-configurations/#using-mustache-templates) so that one search configuration applies different filters or parameters to each query. #### Example query set with custom fields +In the following example, each entry includes a `category` custom field. If a search configuration references `{{category}}` in its query, it filters the results for each query by the `category` value in the corresponding entry: + ```json {"queryText": "phone", "category": "electronics"} {"queryText": "steel", "category": "materials"} {"queryText": "keyboard", "category": "electronics"} ``` -For example, a search configuration whose query references `{{category}}` filters each query's results by the category value provided in the corresponding entry. - ## Managing query sets You can retrieve or delete query sets using the following APIs. diff --git a/_search-plugins/search-relevance/search-configurations.md b/_search-plugins/search-relevance/search-configurations.md index da8ce16a838..a074af4ef73 100644 --- a/_search-plugins/search-relevance/search-configurations.md +++ b/_search-plugins/search-relevance/search-configurations.md @@ -29,7 +29,7 @@ Field | Data type | Description :--- | :--- | :--- `name` | String | The name of the search configuration. `description` | String | Description of the search configuration. -`query` | Object | Defines the query in OpenSearch query DSL. Use the `%SearchText%` placeholder or [Mustache](https://mustache.github.io/) template variables (such as `{{queryText}}`) to substitute query set values at runtime. Needs to be escaped. For more information, see [Using Mustache templates](#using-mustache-templates). +`query` | Object | Defines the query in OpenSearch query DSL. Use the `%SearchText%` placeholder or [Mustache](https://mustache.github.io/) template variables (such as {% raw %}`{{queryText}}`{% endraw %}) to substitute query set values at runtime. Needs to be escaped. For more information, see [Using Mustache templates](#using-mustache-templates). `index` | String | The target index queried by this search configuration. `searchPipeline` | String | Specifies an existing search pipeline. Optional. @@ -47,31 +47,30 @@ PUT _plugins/_search_relevance/search_configurations ### Using Mustache templates -Instead of the `%SearchText%` placeholder, a query can use [Mustache](https://mustache.github.io/) template variables. If the `query` contains `{{`, it is rendered as a Mustache template; otherwise, the `%SearchText%` placeholder is substituted. Existing `%SearchText%` configurations continue to work unchanged. +Instead of the `%SearchText%` placeholder, you can use [Mustache](https://mustache.github.io/) template variables in a query. If the `query` parameter contains double curly braces ({% raw %}`{{}}`{% endraw %}), OpenSearch renders the `query` as a Mustache template; otherwise, OpenSearch substitutes the `%SearchText%` placeholder. Existing `%SearchText%` configurations continue to work unchanged. -The following variables are available when a template is rendered: +When OpenSearch renders a template, the following variables are available: -* `{{queryText}}`: The `queryText` of the current query set entry. -* Any custom field defined on the query set entry, referenced by its field name (for example, `{{category}}`). For more information, see [Query sets]({{site.url}}{{site.baseurl}}/search-plugins/search-relevance/query-sets/). +- {% raw %}`{{queryText}}`{% endraw %}: The `queryText` value from the current query set entry. +- {% raw %}`{{}}`{% endraw %}: Any custom field from the query set entry, referenced by its field name (for example, {% raw %}`{{category}}`{% endraw %}). For more information, see [Query sets]({{site.url}}{{site.baseurl}}/search-plugins/search-relevance/query-sets/). -Substituted values are automatically JSON-escaped, so query text containing quotation marks or other special characters does not break the query. +OpenSearch automatically escapes substituted values, so query text that contains quotation marks or other special characters remains valid in JSON. -Mustache partials (`{{>...}}`) are not supported and cause the query to be rejected. +Mustache partials ({% raw %}`{{>...}}`{% endraw %}) are not supported and cause the query to be rejected. {: .note} -#### Example request: Creating a search configuration that uses a Mustache template - -The following request creates a search configuration that matches the user query against the `title` field and filters results by a `category` custom field provided by each query set entry: +For example, the following request creates a search configuration that matches the user query against the `title` field and filters the results by the `category` custom field from each query set entry: ```json PUT _plugins/_search_relevance/search_configurations { "name": "mustache_filter", - "query": "{\"query\":{\"bool\":{\"must\":[{\"match\":{\"title\":\"{{queryText}}\"}}],\"filter\":[{\"term\":{\"category\":\"{{category}}\"}}]}}}", + "query": "{\"query\":{\"bool\":{\"must\":[{\"match\":{\"title\":\"{% raw %}{{queryText}}{% endraw %}\"}}],\"filter\":[{\"term\":{\"category\":\"{% raw %}{{category}}{% endraw %}\"}}]}}}", "description": "Title match filtered by a category custom field", "index": "ecommerce" } ``` +{% include copy-curl.html %} ## Managing search configurations From 0b1402aeaf36ae418cff6070e0e8068831863750 Mon Sep 17 00:00:00 2001 From: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> Date: Wed, 29 Jul 2026 14:28:09 -0400 Subject: [PATCH 4/4] Apply suggestion from @kolchfa-aws Signed-off-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> --- _search-plugins/search-relevance/search-configurations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_search-plugins/search-relevance/search-configurations.md b/_search-plugins/search-relevance/search-configurations.md index a074af4ef73..7d7fbc1b22d 100644 --- a/_search-plugins/search-relevance/search-configurations.md +++ b/_search-plugins/search-relevance/search-configurations.md @@ -29,7 +29,7 @@ Field | Data type | Description :--- | :--- | :--- `name` | String | The name of the search configuration. `description` | String | Description of the search configuration. -`query` | Object | Defines the query in OpenSearch query DSL. Use the `%SearchText%` placeholder or [Mustache](https://mustache.github.io/) template variables (such as {% raw %}`{{queryText}}`{% endraw %}) to substitute query set values at runtime. Needs to be escaped. For more information, see [Using Mustache templates](#using-mustache-templates). +`query` | Object | Defines the query in OpenSearch query DSL, provided as a JSON string with the inner quotation marks escaped (for example, `"query": "{\"query\":{\"multi_match\":{...}}}"`). Use the `%SearchText%` placeholder or [Mustache](https://mustache.github.io/) template variables (such as {% raw %}`{{queryText}}`{% endraw %}) to substitute query set values at runtime. For more information, see [Using Mustache templates](#using-mustache-templates). `index` | String | The target index queried by this search configuration. `searchPipeline` | String | Specifies an existing search pipeline. Optional.