Malformed query strings cause OpenSearch to return no results or silent errors, and poorly structured queries slow down search on large datasets. This page covers the query syntax rules you must follow to avoid parse errors, and the optimization techniques that reduce computation and improve response time.
Query syntax rules
The following rules apply to all queries in OpenSearch High-Performance Search Edition. Violating any of them causes parse errors or empty results.
Specify an index
Every query must target a named index.
query='mp3' # equivalent to: query=default:'mp3'
query=default:'mp3' # explicit index referenceIf no index is specified, OpenSearch falls back to the default index. If the default index does not exist, the query fails with an error and returns no results. Always name the index explicitly to avoid unexpected fallback behavior.
Enclose keywords in single quotation marks
Keywords in a query string must be wrapped in single quotation marks (').
Unquoted keywords cause a parse error and return no results.
# Incorrect — returns an error
query=default:mp3
# Correct
query=default:'mp3'Escape special characters
Two characters require special handling inside quoted keywords.
Apostrophes (`'`) — escape with a backslash (\) or remove the character.
An unescaped apostrophe inside a keyword breaks the quoted string and causes a parse error.
# Fails to parse — the apostrophe breaks the quoted string
query=default:'abc's efg'
# Correct — apostrophe is escaped
query=default:'abc\'s efg'Backslashes (`\`) — a trailing backslash escapes the closing quotation mark, which causes a parse error. Always escape any literal backslash in your keyword.
# Error — the backslash escapes the closing quote
query=default:'abc\'
# Correct — literal backslash escaped
query=default:'abc\\'query=default:'Beijing University' retrieves documents that contain both Beijing and University.
Performance optimization
Search performance depends on how many documents match a query. Fewer matching documents means less computation and faster results. Apply the following techniques to reduce unnecessary work at each stage of the search pipeline.
Move field filters into the query clause
Impact: high
When filtering on a field value, index that field and move the condition into the query clause instead of using filter.
# Less efficient — filter runs after the query, without index acceleration
query=user_id:'123' && filter=type_id=1
# More efficient — both conditions use indexed lookup
query=user_id:'123' AND type_id:'1'The query clause benefits from index acceleration; the filter clause does not. Moving conditions into query lets OpenSearch use the index to eliminate non-matching documents early, before any ranking or retrieval work begins.
Use range search for time-based filtering
Impact: high
Filtering large datasets by a timestamp range using filter is slow because OpenSearch scans all documents that match the preceding conditions. For time-based queries, use a range search on an indexed timestamp field instead.
# Slow — OpenSearch scans all 50 million user_id=123 records to find the 1,000 in range
query=user_id:'123' && filter=time>"2016-09-16"
# Faster — range query uses the index to retrieve only matching records directly
query=user_id:'123' AND index_timestamp:(1473955200000,)Range search is effective when the indexed field eliminates most documents early in the pipeline, avoiding the full-scan cost of a post-query filter.
Reduce the number of matched documents
Impact: medium
The fewer documents OpenSearch retrieves, the faster it returns results.
Add more specific terms or field constraints to reduce the hit count.
The default page size is 20 results. Avoid requesting more results per page than your application actually displays.
Return only the fields you need
Impact: medium
After documents are matched, OpenSearch fetches the full record for each result. Fetching unused fields adds latency, especially when result payloads are large.
Specify only the fields your application needs by modifying the default display fields or configuring the fetch_fields parameter.