Search Query Syntax¶
Virto's unified search has a special query syntax. It is processed by our proprietary query syntax parser. The parser interprets it into the Virto query object model. Then, an appropriate search adapter translates it into specific search engine syntax. This makes the query syntax search engine agnostic.
The syntax defines the grammar for the searchPhrase expression as follows:
1 searchPhrase : WS* phrase (WS phrase)* WS*;
2 phrase : keyword | filters;
3 keyword : String;
4 filters : negation? (attributeFilter | rangeFilter);
5 attributeFilter : fieldName FD attributeFilterValue;
6 rangeFilter : fieldName FD rangeFilterValue;
7 fieldName : String;
8 attributeFilterValue : string (VD string)*;
9 rangeFilterValue : range (VD range)*;
10 range : rangeStart WS* lower? WS* RD WS* upper? WS* rangeEnd;
11 rangeStart : RangeStart;
12 rangeEnd : RangeEnd;
13 lower : String;
14 upper : String;
15 string : String;
16
17 negation : '!';
18 FD : ':'; // Filter delimiter
19 VD : ','; // Value delimiter
20 RD : 'TO' | 'to'; // Range delimiter
21 RangeStart : '[' | '(';
22 RangeEnd : ']' | ')';
23
24 String : SimpleString | QuotedString;
25 fragment SimpleString : ~[!":,[\]() \t]+;
26 fragment QuotedString : ('"' (Esc | ~["\\])* '"');
27 fragment Esc : '\\' (["\\rnt]);
28
29 WS : [ \t]+; // Whitespace
The searchPhrase parameter accepts strings as input. These strings can contain two types of elements:
keywordfor full text search.filtersfor refining search criteria.
The search supports any language and allows the use of boolean operators, precedence operators, wildcard or prefix characters for starts with queries, escape characters, and URL encoding characters within the searchPhrase parameter.
term phraseis a query consisting of one or more terms, where any of the terms are considered a match, such as single words like test or hello.phraseis an exact phrase in quotation marks.filter phraseis used to apply additional criteria to a search query apart from the full text search terms.
Example
| Query | Description |
|---|---|
Red wine |
Searches for documents containing Red and/or wine anywhere in any order. |
"Red wine" |
Matches only the documents that contain the entire phrase in the appropriate order (lexical analysis applies). |
"\"Red wine\"" |
search request syntax is used to escape the quotation marks in a phrase search, for example, in Postman, in a POST request. |
Full Text Search¶
The parameter that performs full text search (term and phrase search) against the document index is query. Provide a full text search phrase to make it work.
Searchable Fields¶
The full text search runs over data in the index. All searchable text data are stored in a single __content field in the resulting index document, with the full text search being performed only for this field.
Below is an example of the product document in the index:
1 "__content": [
2 "JGC-85796278",
3 "ASUS ZenFone 2 ZE551ML Gold",
4 "asus",
5 "android",
6 "2.3 ghz intel gtx quad-core",
7 "micro-sim",
8 "1080"
9 ],
With an example request asus, you will get the search to find all documents where the __content field contains the asus value as an entire phrase or a part of it.
Filters¶
filter provides value-based criteria for selecting which documents to include in the search results. A filter can be a single value or an expression. Unlike full text search, a filter succeeds only if an exact match is obtained.
Filters are specified in individual fields. A field definition must be set as filterable if you want to use it in filter expressions.
Fields¶
When performing a search, you can:
-
Specify a field by typing the field name followed by a colon (
:) and then the term you are looking for: -
Specify multiple values in one field parameter, separated by a comma. It will return products in which at least one of the specified values matches (i.e. acting as an
ORoperator). The example below shows a request that filters products that are either black, grey, or blue:
Range Filtration¶
Range filtration helps you find products that have field values within a specified range. This range is defined by a range expression, which can be set to include or exclude the upper and lower bounds. Inclusive range queries use square brackets [ ], while exclusive queries use round brackets ( ).
Example
| Query | Description |
|---|---|
price:[100 TO 200] |
Finds products with prices between 100 and 200, inclusive. |
price:(100 TO 200] |
Finds products with prices between 100, exclusive, and 200, inclusive. |
price:(TO 100] |
The price must be less than or equal to 100. |
Boolean Operators¶
Having multiple field terms separated by a space delimiter in a single filter expression will combine them with an AND operator.
The following search request filters products of a certain brand, Onkyo, and a certain color, black:
Warning
At the moment, we support logical AND operators for filter expressions.
Wildcard Search¶
Within a single phrase or phrase terms, you can use:
| Character | Function | Example |
|---|---|---|
? |
Single character wildcard search. | b?ll finds ball, bell, or bill. |
* |
Multiple character wildcard search. You can use * anywhere in the string. |
test* finds test, tests, or tester.hea*one finds headphone, healthone, or heartstone. |
Info
Inside the double quotes block, you may use any unsafe characters.
To escape double quote character, use backslash (\):
Example
| Query | Description |
|---|---|
color:Black,White |
The color is either black or white. |
color:Black color:White |
The color is both black and white. |
price_usd:[100 TO 200] |
The price is between $100 and $200, inclusive. |
price:(100 TO 200) |
The price in any currency is between 100 and 200, exclusive. |
price:(0 TO) |
The price is greater than zero. |
price:(TO 100] |
The price is less than or equal to 100. |
Da?? Red* |
? replaces a single character.* replaces zero or more characters. |
color:Black price:[100 TO 200) |
Combine keywords and filters. |