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..b5ee0fd6326 --- /dev/null +++ b/_query-dsl/specialized/wrapper.md @@ -0,0 +1,96 @@ +--- + +layout: default +title: Wrapper +parent: Specialized queries +nav_order: 80 +--- + +# 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. + +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 + +Create an index named `products` with the following mappings: + +```json +PUT /products +{ + "mappings": { + "properties": { + "title": { "type": "text" } + } + } +} +``` +{% include copy-curl.html %} + +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" } +``` +{% include copy-curl.html %} + +Encode the following query in Base64 format: + +```bash +echo -n '{ "match": { "title": "headphones" } }' | base64 +``` +{% include copy.html %} + +Execute the encoded query: + +```json +POST /products/_search +{ + "query": { + "wrapper": { + "query": "eyAibWF0Y2giOiB7ICJ0aXRsZSI6ICJoZWFkcGhvbmVzIiB9IH0=" + } + } +} +``` +{% include copy-curl.html %} + +The response contains the two matching 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" + } + } + ] + } +} +```