OpenSearch:Index retrieval - query clause

Overview

The query clause is required for any search request. It specifies what to search for in a specific index field and defines the relationship between multiple query conditions by using logical operators such as AND, OR, ANDNOT, and RANK.

For example, you can combine two TEXT type fields, such as title and subject, into a single composite index named default. A search against the default index then retrieves documents where the search query matches the content of either the title or subject source fields.

Alternatively, if you create an index named title_search based only on the title field, a query against title_search returns only documents where the search query matches the content of the title field.

Syntax

Query conditions use the following formats:

Standard query: index:'search query'^boost

range search: index:'circle(longitude latitude,radius)'

range search: index:[value1,value2]

• index: The name of the index field to search, as defined in your index schema. The search finds documents where the search query appears in any of the source fields that comprise this index field.

• search query: The content that you want to search for.

• boost: The relevance boost to apply to the search query. The value must be an integer from 0 to 99. If unspecified, the default is 99. This parameter is optional and only takes effect if the exact_match_boost() function is configured in the rough sort expression.

• You can combine multiple query conditions by using the following logical operators: (), AND, OR, ANDNOT, and RANK. These operators must be in uppercase. The operators are evaluated in the following order of precedence, from lowest to highest: RANK<OR<AND<ANDNOT<().

• To perform a phrase query, enclose the search query in double quotation marks (""). A phrase query finds documents where the analyzed terms appear in the same order and position as in the original phrase.

• A range search supports queries on geographical locations and numerical ranges. For more information, see range search.

Usage notes

• The query clause is required and cannot be empty.

• The ANDNOT operator cannot be used by itself. The query condition to the left of ANDNOT must not be empty, such as index_name:''.

• If the RANK operator is not at the end of the query, such as in index1:'xxx' RANK index2:'xxx' AND index3:'xxx', you must group the RANK operation with parentheses, for example: (index1:'xxx' RANK index2:'xxx') AND index3:'xxx'. Otherwise, all subsequent conditions are included in the RANK operation, and the query is interpreted as index1:'xxx' RANK (index2:'xxx' AND index3:'xxx').

• You must enclose the search query in single (' ') or double (" ") quotation marks. Otherwise, the query might fail, return no results, or produce unexpected behavior.

• You can only use TEXT or SHORT_TEXT fields to create a composite index.

• If the boost value is less than 0, it is treated as 0. If it is greater than 99, it is treated as 99.

• For more information about how different search types are processed, see built-in analyzer.

Examples

1. Search for documents where the title index field contains "Peking University":

   query=title:'Peking University'

2. Search for documents where the title index field contains both "Peking University" and "Zhejiang University":

   query=title:'Peking University' AND title:'Zhejiang University'

3. Search for documents where the title index field contains either "Peking University" or "Zhejiang University", and the type field is "1":

   query=(title:'Peking University' OR title:'Zhejiang University') AND type:'1'

4. Search for documents where the title index field contains either "Peking University" or "Zhejiang University". This example shows an alternative syntax for OR:

   query=title:'Peking University'|'Zhejiang University'

5. Search for documents where the title index field contains Peking University but not Tsinghua. If the title also contains President, rank these documents higher:

   query=(title:'Peking University' ANDNOT title:'Tsinghua') RANK title:'President'
   // The fine sort expression is: text_relevance(title)

6. Search for documents where the title index field contains the exact phrase Peking University. This prevents matching documents with similar but separate terms, such as "University of Beijing":

   query=title:"Peking University"

7. Search a field of the INT_ARRAY type:

   // Assume you have an INT_ARRAY field indexed as arr_index_1.
   // This query retrieves any document where the array contains the value 1.
   query=arr_index_1:'1'

8. Search a field of the LITERAL_ARRAY type: A LITERAL_ARRAY is an array of string constants where each element is not tokenized and supports only an exact match. Assume you have a LITERAL_ARRAY field indexed as tags_index:

   // The document is retrieved if any element in the array is an exact match for 'Red'.
   // Note: Because LITERAL_ARRAY performs an exact match, the search query must be identical to an array element. For example, if an element is 'Peking University', a search for 'Peking' does not return a match.
   query=tags_index:'Red'
   
   // Search for documents where the array contains either 'Red' or 'Blue'.
   query=tags_index:'Red' OR tags_index:'Blue'