Skip to content

adding wrapper dsl query docs #9939

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Merged
Show file tree
Hide file tree
Changes from 2 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion _query-dsl/specialized/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
47 changes: 47 additions & 0 deletions _query-dsl/specialized/wrapper.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
---

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 work around system constraints. For readability and maintainability, it's better to use standard JSON-based queries when possible.

## Example use case

If you want to run the following query:

```json
{
"match": {
"title": "headphones"
}
}
```

Encode this JSON as a Base64 string. The Base64-encoded version is:

```
eyAibWF0Y2giOiB7InRpdGxlIjogImhlYWRwaG9uZXMifSB9
```

Wrap this base64 encoded string in a `wrapper` query:

```json
POST /products/_search
{
"query": {
"wrapper": {
"query": "eyAibWF0Y2giOiB7InRpdGxlIjogImhlYWRwaG9uZXMifSB9"
Copy link
Contributor

@sgup432 sgup432 Jul 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Curious as to where we decode this eventually? Also do we also need to mention here if any explicit plugin needs to be enabled to use this or basically any pre-requisite? @AntonEliatra

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@sgup432 this comes with standard opensearch, no special plugins needed. I dont think we should start adding this clarification, because we would have to add that to everything that comes out of the box with OS. What do you think?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since this is part of core OS functionality, we don't need to specify any prerequisites here.

}
}
}
```
{% include copy-curl.html %}

This executes the same query as the original `match` clause.