Skip to content
Last update: January 30, 2024

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:

  • keyword for full text search.
  • filters for 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 phrase is 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.
  • phrase is an exact phrase in quotation marks.
  • filter phrase is used to apply additional criteria to a search query apart from the full text search terms.
Example

Red wine searches for documents containing Red and/or wine anywhere in any order.

"Red wine" only matches 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.

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 the full text search, a filter succeeds only if an exact match is achieved.

Filters are specified in individual fields. A field definition must be attributed 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:

    `name:"My cool name" color:Black`
    

  • 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 OR operator). The example below shows a request that filters products that are either black, grey, or blue:

    `color:Black,Gey,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:

`color:Black brand:Onkyo`

Warning

At the moment, we support logical AND operators for filter expressions.

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 (\):

`\"my cool property\":\"&~!'\"`

Examples
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.