Run vector-based queries from the Query Test page in the OpenSearch Vector Search Edition console to validate your index and data after reindexing completes.
Prerequisites
Before you begin, ensure that you have:
Completed reindexing for your OpenSearch instance
At least one table in the In Use state
Choose a query mode
The Query Test page offers two modes. Select the one that fits your use case before configuring query parameters:
| Mode | Best for | Limitations |
|---|---|---|
| Form Mode | Quick validation with a simple form UI | Single vector, single namespace, single index only; returns all fields and vector data by default |
| Developer Mode | Full control over query parameters via JSON | None — all query features are supported |
To access the Query Test page, go to the details page of your OpenSearch instance and click Query Test in the left-side navigation pane. On the Vector-based Query tab, select the table to query from the Table Name drop-down list. In the upper-right corner, select Form Mode or Developer Mode. Form Mode is selected by default.
Run a query in Form mode
In Form Mode, query parameters appear as form fields and results display below the form.
Configure the following parameters:
| Parameter | Required | Description |
|---|---|---|
| Table Name | Yes | The table to query. Select a table in the In Use state. |
| Index Name | Yes | Auto-populated when you select a table. No manual selection needed. |
| TopK | Yes | Maximum number of results to return. Default: 10. Must be a positive integer. |
| Filter Condition | No | Filter expression to narrow results. Supported operators: >, <, =, <=, >=, !=. Use AND, OR, and () to combine conditions. See Filter expression. |
| Query Type | Yes | Data type used for the query: Vector, Image, or Text. |
| Namespace | No | Partition namespace for the vector index. |
| Result Sort Order | Yes | Sort order for results: ASC or DESC. Default: ASC. |
Choosing the right sort order
The correct sort order depends on the distance type configured for your table:
Inner product — a higher score means higher relevance. Set to DESC.
Euclidean distance — a lower score means higher relevance. Set to ASC.
Query by vector
After you select a table, the index name is automatically populated. A tip below the Vector field shows the required number of vector dimensions.
Enter a vector value with the correct number of dimensions in the Vector field, then click Search. Results appear below the form.
Query by image
Image queries require the built-in embedding feature to be enabled on the selected table.
After you select a table, the index name is automatically populated. The Method for Providing Images parameter appears with two options: Upload Image File and Base64 Encoding (default).
Upload Image File
Click the blank area in the Upload Image section to upload a local image. Enable Multi-subject Recognition if needed, then click Search.
Supported image formats: PNG, JPG, and JPEG. Maximum file size: 2 MB.
When Multi-subject Recognition is enabled:
All detected subjects are framed and numbered.
The subject with the highest pixel size is selected by default, and its results are displayed.
Click a subject's number to switch to that subject. Results and the highlighted area update accordingly.
Base64 Encoding
Enter the Base64-encoded string of the image in the input field, then click Search. Results appear below the form.
Query by text
Text queries require the built-in embedding feature to be enabled on the selected table.
After you select a table, the index name is automatically populated. A tip below the Query Type field confirms that text queries require built-in embedding.
Enter the text to query in the Text field, then click Search. Results appear below the form.
Run a query in Developer mode
Developer Mode displays query parameters and results as raw JSON, giving you full access to all query features.
Enter your query JSON in the left panel, then click Search. Results appear in the right panel.
Single vector query
{
"vector": [0.345263, 0.346272, 0.33663.....],
"topK": 10,
"indexName": "",
"includeVector": true,
"namespace": "test1"
}Multiple vectors with namespaces
{
"tableName": "gist",
"indexName": "vec_index",
"queries": [
{
"vector": [0.1, 0.2, 0.3],
"namespace": "space_a"
},
{
"vector": [0.4, 0.5, 0.6],
"namespace": "space_b"
}
],
"topK": 3,
"includeVector": true
}JSON parameters
| Parameter | Required | Description |
|---|---|---|
vector | Yes | Vector value in list[float] format. The number of dimensions must match the vector index dimensions. |
topK | No | Maximum number of results to return. Default: 10. |
indexName | No | Name of the vector index. |
includeVector | No | Whether to include vector data in results. Default: true. |
namespace | Conditional | Required only if a category is configured for the instance. |
tableName | No | Table name (used in multi-vector queries). |
queries | No | List of vector-namespace pairs for multi-vector queries. |
For the full parameter reference, see Vector-based query.
Form mode limitations and workarounds
The following limitations apply to Form Mode. Switch to Developer Mode to work around each one.
| Limitation | Workaround in Developer Mode |
|---|---|
| Single namespace only | Use the queries array to query multiple namespaces |
| Single vector index only | Specify indexName per query |
| Single vector per query | Use the queries array for multi-vector queries |
| All fields returned by default | Control field selection via query parameters |
| Vector data included in results by default | Set "includeVector": false |
| Result scores are filtered by default | Use Developer Mode for full score visibility |