OpenSearch Retrieval Engine Edition supports two query languages for vector retrieval: HA3 syntax and SQL syntax. Both support the same retrieval options — top-N limits, similarity thresholds, category filters, and custom retrieval parameters.
All examples below use index_name as a placeholder for your vector index name.
Basic query
HA3 syntax
query=index_name:'0.1,0.2,0.98,0.6;0.3,0.4,0.98,0.6...'Specify the vectors to query after the colon (:). Separate multiple vectors with semicolons (;).
SQL syntax
query=select proxima_score('index_name') as score,id from table_name where MATCHINDEX('index_name', ?) order by score asc limit 5&&kvpair=timeout:1000,iquan.plan.cache.enable:true;urlencode_data:false;iquan.plan.prepare.level:jni.post.optimize;dynamic_params:[["0.892704,0.783731"]]The dynamic_params parameter in the kvpair clause carries the vectors to query.
Return top N results
Add the n parameter to limit the number of results returned.
HA3 syntax
query=index_name:'0.1,0.2,0.98,0.6;0.3,0.4,0.98,0.6&n=10'SQL syntax
query=select proxima_score('index_name') as score,id from table_name where MATCHINDEX('index_name', ?) order by score asc limit 5&&kvpair=timeout:1000,iquan.plan.cache.enable:true;urlencode_data:false;iquan.plan.prepare.level:jni.post.optimize;dynamic_params:[["0.892704,0.783731&n=10"]]Place &n=10 inside the dynamic_params value, after the vector values.
Filter by similarity threshold
Add the sf parameter to exclude documents that fall below the similarity threshold. The threshold value is interpreted differently depending on the search_type set in schema.json.
search_type | Effect of sf |
|---|---|
ip (inner product) | Excludes documents whose inner product score is less than sf |
l2 (Euclidean distance) | Excludes documents whose Euclidean distance is higher than 2.0 when sf=4 — OpenSearch computes the square of the Euclidean distance for performance, so the effective distance threshold is 2.0, not 4.0 |
HA3 syntax (sf=4)
query=index_name:'0.1,0.2,0.98,0.6;0.3,0.4,0.98,0.6&n=10&sf=4'SQL syntax (sf=4)
query=select proxima_score('index_name') as score,id from table_name where MATCHINDEX('index_name', ?) order by score asc limit 5&&kvpair=timeout:1000,iquan.plan.cache.enable:true;urlencode_data:false;iquan.plan.prepare.level:jni.post.optimize;dynamic_params:[["0.892704,0.783731&n=10&sf=4"]]Query by category
To query vectors within specific categories, prefix each vector with its category ID, separated by a number sign (#). Number signs must be URL-encoded as %23.
| Separator | Character | URL-encoded |
|---|---|---|
| Category ID and vector | # | %23 |
| Multiple vectors | ; | %3b |
| Multiple categories | , | %2c |
HA3 syntax (raw and URL-encoded)
query=aitheta_index_name:'16#0.1,0.2,0.98,0.6;1512#0.3,0.4,0.98,0.6&n=200'
query=aitheta_index_name:'16%230.1%2c0.2%2c0.98%2c0.6%3b1512%230.3%2c0.4%2c0.98%2c0.6%26n%3d200'Submit the URL-encoded form in production requests.
SQL syntax
query=select proxima_score('index_name') as score,id from table_name where MATCHINDEX('index_name', ?) order by score asc limit 5&&kvpair=timeout:1000,iquan.plan.cache.enable:true;urlencode_data:false;iquan.plan.prepare.level:jni.post.optimize;dynamic_params:[["16%230.1%2c0.2%2c0.98%2c0.6%3b1512%230.3%2c0.4%2c0.98%2c0.6%26n%3d200"]]The entire dynamic_params value must be URL-encoded for category queries.
Pass retrieval parameters
Use search_params to fine-tune the underlying retrieval engine. The value must be valid JSON.
HA3 syntax
query=index_name:'0.1,0.2,0.98,0.6;0.3,0.4,0.98,0.6&n=10&sf=0.8&search_params={"proxima.qc.searcher.scan_ratio":0.001,"proxima.general.searcher.scan_count":10000}'SQL syntax
query=select proxima_score('index_name') as score,id from table_name where MATCHINDEX('index_name', ?) order by score asc limit 5&&kvpair=timeout:1000,iquan.plan.cache.enable:true;urlencode_data:false;iquan.plan.prepare.level:jni.post.optimize;dynamic_params:[["0.892704,0.783731&n=10&sf=0.8&search_params={"proxima.qc.searcher.scan_ratio":0.001,"proxima.general.searcher.scan_count":10000}"]]Supported parameters:
| Parameter | Description |
|---|---|
proxima.qc.searcher.scan_ratio | Fraction of the index to scan. For details, see the Parameter description section in the Vector indexes topic. |
proxima.general.searcher.scan_count | Number of documents to scan. Equivalent to min_scan_doc_cnt. |
The order of the n, sf, and search_params parameters cannot be changed.
Sort results by similarity score
HA3 syntax
query=index_name:'0.1,0.2,0.98,0.6;0.3,0.4,0.98,0.6...'&&kvpairs=first_formula:proxima_score(index_name)&&sort=+RANKkvpairs=first_formula:proxima_score(index_name)sets the similarity score as the rough sort expression.sort=+RANKsorts results in ascending order by similarity score.
SQL syntax
query=select proxima_score('index_name') as score,id from table_name where MATCHINDEX('index_name', ?) order by score asc limit 5&&kvpair=timeout:1000,iquan.plan.cache.enable:true;urlencode_data:false;iquan.plan.prepare.level:jni.post.optimize;dynamic_params:[["0.892704,0.783731"]]proxima_score('index_name') returns the similarity score for each result. Use order by score asc for ascending order or order by score desc for descending order.