From f59b046ebd07f9ad236b4b4c2d0f1f7ba872153a Mon Sep 17 00:00:00 2001 From: Anton Rubin Date: Tue, 20 May 2025 16:12:36 +0100 Subject: [PATCH 1/5] adding wrapper dsl query docs Signed-off-by: Anton Rubin --- _query-dsl/specialized/index.md | 2 +- _query-dsl/specialized/wrapper.md | 48 +++++++++++++++++++++++++++++++ 2 files changed, 49 insertions(+), 1 deletion(-) create mode 100644 _query-dsl/specialized/wrapper.md diff --git a/_query-dsl/specialized/index.md b/_query-dsl/specialized/index.md index d28451cfa8d..7e3c1a0376a 100644 --- a/_query-dsl/specialized/index.md +++ b/_query-dsl/specialized/index.md @@ -28,4 +28,4 @@ OpenSearch supports the following specialized queries: - [`script_score`]({{site.url}}{{site.baseurl}}/query-dsl/specialized/script-score/): Calculates a custom score for matching documents using a script. -- `wrapper`: Accepts other queries as JSON or YAML strings. +- [`wrapper`]({{site.url}}{{site.baseurl}}/query-dsl/specialized/wrapper/): Accepts other queries as JSON or YAML strings. diff --git a/_query-dsl/specialized/wrapper.md b/_query-dsl/specialized/wrapper.md new file mode 100644 index 00000000000..9f122216f33 --- /dev/null +++ b/_query-dsl/specialized/wrapper.md @@ -0,0 +1,48 @@ +--- + +layout: default +title: Wrapper query +parent: Specialized queries +nav_order: 80 +--- + +# Wrapper query + +The `wrapper` query lets you submit a complete query in Base64-encoded JSON format. It is useful when the query must be embedded in contexts that only support string values. + +Use this query only when you need to work around system constraints. For readability and maintainability, it's better to use standard JSON-based queries when possible. + +## Example use case + +Let’s say you want to run the following query: + +```json +{ + "match": { + "title": "headphones" + } +} +``` +{% include copy-curl.html %} + +Encode that JSON as a Base64 string. The Base64-encoded version of the above is: + +``` +eyAibWF0Y2giOiB7InRpdGxlIjogImhlYWRwaG9uZXMifSB9 +``` + +Wrap this base64 encoded string in a `wrapper` query: + +```json +POST /products/_search +{ + "query": { + "wrapper": { + "query": "eyAibWF0Y2giOiB7InRpdGxlIjogImhlYWRwaG9uZXMifSB9" + } + } +} +``` +{% include copy-curl.html %} + +This executes the same query as the original `match` clause. From 38e2e8405e2e7e8ff10fc92378610f4c889b55e2 Mon Sep 17 00:00:00 2001 From: Anton Rubin Date: Wed, 21 May 2025 11:48:27 +0100 Subject: [PATCH 2/5] adding changes to the docs Signed-off-by: Anton Rubin --- _query-dsl/specialized/wrapper.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/_query-dsl/specialized/wrapper.md b/_query-dsl/specialized/wrapper.md index 9f122216f33..ba9be6effa8 100644 --- a/_query-dsl/specialized/wrapper.md +++ b/_query-dsl/specialized/wrapper.md @@ -1,12 +1,12 @@ --- layout: default -title: Wrapper query +title: Wrapper parent: Specialized queries nav_order: 80 --- -# Wrapper query +# Wrapper The `wrapper` query lets you submit a complete query in Base64-encoded JSON format. It is useful when the query must be embedded in contexts that only support string values. @@ -14,7 +14,7 @@ Use this query only when you need to work around system constraints. For readabi ## Example use case -Let’s say you want to run the following query: +If you want to run the following query: ```json { @@ -23,9 +23,8 @@ Let’s say you want to run the following query: } } ``` -{% include copy-curl.html %} -Encode that JSON as a Base64 string. The Base64-encoded version of the above is: +Encode this JSON as a Base64 string. The Base64-encoded version is: ``` eyAibWF0Y2giOiB7InRpdGxlIjogImhlYWRwaG9uZXMifSB9 From 35862caa6911d54d79ac3b2ef0b903792abc180a Mon Sep 17 00:00:00 2001 From: Anton Rubin Date: Thu, 3 Jul 2025 12:11:03 +0100 Subject: [PATCH 3/5] addressing the PR comments Signed-off-by: Anton Rubin --- _query-dsl/specialized/wrapper.md | 66 ++++++++++++++++++++++++++----- 1 file changed, 57 insertions(+), 9 deletions(-) diff --git a/_query-dsl/specialized/wrapper.md b/_query-dsl/specialized/wrapper.md index ba9be6effa8..9c2f42086c4 100644 --- a/_query-dsl/specialized/wrapper.md +++ b/_query-dsl/specialized/wrapper.md @@ -12,36 +12,84 @@ The `wrapper` query lets you submit a complete query in Base64-encoded JSON form Use this query only when you need to work around system constraints. For readability and maintainability, it's better to use standard JSON-based queries when possible. -## Example use case +## Example -If you want to run the following query: +Create index named `products` with the following mappings: ```json +PUT /products { - "match": { - "title": "headphones" + "mappings": { + "properties": { + "title": { "type": "text" } + } } } ``` +{% include copy-curl.html %} -Encode this JSON as a Base64 string. The Base64-encoded version is: +Index sample documents: +```json +POST /products/_bulk +{ "index": { "_id": 1 } } +{ "title": "Wireless headphones with noise cancellation" } +{ "index": { "_id": 2 } } +{ "title": "Bluetooth speaker" } +{ "index": { "_id": 3 } } +{ "title": "Over-ear headphones with rich bass" } ``` -eyAibWF0Y2giOiB7InRpdGxlIjogImhlYWRwaG9uZXMifSB9 +{% include copy-curl.html %} + +Base64 encode the following query: + +```bash +echo -n '{ "match": { "title": "headphones" } }' | base64 ``` -Wrap this base64 encoded string in a `wrapper` query: +Execute the query inside `wrapper` using the encoded string: ```json POST /products/_search { "query": { "wrapper": { - "query": "eyAibWF0Y2giOiB7InRpdGxlIjogImhlYWRwaG9uZXMifSB9" + "query": "eyAibWF0Y2giOiB7ICJ0aXRsZSI6ICJoZWFkcGhvbmVzIiB9IH0=" } } } ``` {% include copy-curl.html %} -This executes the same query as the original `match` clause. +The hits return two documents: + +```json +{ + ... + "hits": { + "total": { + "value": 2, + "relation": "eq" + }, + "max_score": 0.20098841, + "hits": [ + { + "_index": "products", + "_id": "1", + "_score": 0.20098841, + "_source": { + "title": "Wireless headphones with noise cancellation" + } + }, + { + "_index": "products", + "_id": "3", + "_score": 0.18459359, + "_source": { + "title": "Over-ear headphones with rich bass" + } + } + ] + } +} +``` From 2cc2ac92029dc315f8168eab3417e80cf3749fe8 Mon Sep 17 00:00:00 2001 From: AntonEliatra Date: Thu, 3 Jul 2025 17:05:21 +0100 Subject: [PATCH 4/5] Apply suggestions from code review Co-authored-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> Signed-off-by: AntonEliatra --- _query-dsl/specialized/wrapper.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/_query-dsl/specialized/wrapper.md b/_query-dsl/specialized/wrapper.md index 9c2f42086c4..1a5b36e7bed 100644 --- a/_query-dsl/specialized/wrapper.md +++ b/_query-dsl/specialized/wrapper.md @@ -14,7 +14,7 @@ Use this query only when you need to work around system constraints. For readabi ## Example -Create index named `products` with the following mappings: +Create an index named `products` with the following mappings: ```json PUT /products @@ -41,13 +41,14 @@ POST /products/_bulk ``` {% include copy-curl.html %} -Base64 encode the following query: +Encode the following query in Base64 format: ```bash echo -n '{ "match": { "title": "headphones" } }' | base64 ``` +{% include copy.html %} -Execute the query inside `wrapper` using the encoded string: +Execute the encoded query: ```json POST /products/_search @@ -61,7 +62,7 @@ POST /products/_search ``` {% include copy-curl.html %} -The hits return two documents: +The response contains the two matching documents: ```json { From 243ff5ed62599e07569a85c8fa592e5a49afee07 Mon Sep 17 00:00:00 2001 From: Nathan Bower Date: Tue, 8 Jul 2025 06:44:41 -0400 Subject: [PATCH 5/5] Update _query-dsl/specialized/wrapper.md Signed-off-by: Nathan Bower --- _query-dsl/specialized/wrapper.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_query-dsl/specialized/wrapper.md b/_query-dsl/specialized/wrapper.md index 1a5b36e7bed..b5ee0fd6326 100644 --- a/_query-dsl/specialized/wrapper.md +++ b/_query-dsl/specialized/wrapper.md @@ -10,7 +10,7 @@ nav_order: 80 The `wrapper` query lets you submit a complete query in Base64-encoded JSON format. It is useful when the query must be embedded in contexts that only support string values. -Use this query only when you need to work around system constraints. For readability and maintainability, it's better to use standard JSON-based queries when possible. +Use this query only when you need to manage system constraints. For readability and maintainability, it's better to use standard JSON-based queries when possible. ## Example