Filter Syntax
CargoX uses Lucene query syntax for filtering. The syntax is described in the following sections.
Basic Syntax
The basic syntax for a filter is a field name followed by a colon (:) and a value. For example, to filter by the name field, use the following syntax:
name: "John"
Wildcard Searches
CargoX supports single and multiple character wildcard searches within single terms (not within phrase queries).
To perform a single character wildcard search, use the ? symbol. For example, to search for John or Jon, use the following syntax:
name: Jo?n
To perform a multiple character wildcard search, use the * symbol. For example, to search for John, Jon, or Jonathan, use the following syntax:
name: Jo*
You cannot use a * or ? symbol as the first character of a search.
Fuzzy Searches
CargoX supports fuzzy searches based on the Levenshtein Distance, or Edit Distance algorithm. To perform a fuzzy search, use the ~ symbol at the end of a single word term. For example, to search for a term similar in spelling to roam, use the following syntax:
name: roam~
This search will find terms like foam and roams.
Proximity Searches
CargoX supports finding words that are within a specific distance away. To perform a proximity search, use the ~ symbol at the end of a phrase. For example, to search for John and Doe within 10 words of each other in a document, use the following syntax:
name: "John Doe"~10
Range Searches
CargoX supports range searches, where you can match documents whose field(s) values are between the lower and upper bound specified by the range query. Range searches can be inclusive or exclusive of the upper and lower bounds. Sorting is done lexicographically.
To perform a range search, use the following syntax:
name: [John TO Doe]
The TO keyword signifies that the range is inclusive. To perform an exclusive range search, use the following syntax:
name: {John TO Doe}
Boosting a Term
CargoX provides the relevance level of matching documents based on the terms found. To boost a term, use the ^ symbol with a boost factor (a number) at the end of the term you are searching. The higher the boost factor, the more relevant the term will be.
Boosting allows you to control the relevance of a document by boosting its term. For example, if you are searching for John and you want the term Doe to have higher relevance, use the following syntax:
name: John Doe^2
This will make documents with the term Doe appear more relevant. You can also boost phrases:
name: "John Doe"^2 "John Smith"
Boolean Operators
CargoX supports Boolean operators to combine terms. The Boolean operators OR, AND, and NOT must be written in all caps.
The OR operator is the default conjunction operator. This means that if there is no Boolean operator between two terms, the OR operator is used. The OR operator links two terms and finds a matching document if either of the terms exist in a document. This is equivalent to a union using sets. The symbol || can be used in place of the word OR.
To search for documents that contain either John or Doe, use the following syntax:
name: John OR Doe
name: John || Doe
The AND operator matches documents where both terms exist anywhere in the text of a single document. This is equivalent to an intersection using sets. The symbol && can be used in place of the word AND.
To search for documents that contain both John and Doe, use the following syntax:
name: John AND Doe
name: John && Doe
The NOT operator excludes documents that contain the term after NOT. This is equivalent to a difference using sets. The symbol ! can be used in place of the word NOT.
To search for documents that contain John but not Doe, use the following syntax:
name: John NOT Doe
name: John ! Doe
Grouping
CargoX supports using parentheses to group clauses to form sub-queries. This can be useful if you want to control the Boolean logic for a query.
To search for either John or Doe and Smith, use the following syntax:
name: (John OR Doe) AND Smith
Escaping Special Characters
CargoX supports escaping special characters that are part of the query syntax. The current list of special characters are:
+ - && || ! ( ) { } [ ] ^ " ~ * ? : \
To escape these characters, use the \ before the character. For example, to search for (1+1):2, use the following syntax:
name: \(1\+1\)\:2
Checking for the Existence of a Field
CargoX supports checking for the existence of a field. To check for the existence of a field, use the following syntax:
name: *
Negating a Term
To negate a term, use the following syntax:
name:NOT John
Working with Dates
To filter by a date, use the following syntax:
deliveryDate: 2021-01-01
To filter by a date range, use the following syntax:
deliveryDate: [2021-01-01 TO 2021-01-31]
Date formats supported by CargoX are:
yyyyMMddyyyyMMddHHmmyyyyMMddHHmmssyyyy-MM-ddyyyy-MM-dd'T'HH:mm:ssyyyy-MM-dd'T'HH:mm:ss.SSS'Z'
Working with Numbers
CargoX supports filtering by numbers. To filter by a number, use the following syntax:
price: 100
To filter by a number range, use the following syntax:
price: [100 TO 200]
Working with Booleans
CargoX supports filtering by booleans. To filter by a boolean, use the following syntax:
isPaid: true
Working with Enums
CargoX supports filtering by enums. To filter by an enum, use the following syntax:
status: "Pending"
Working with Arrays
CargoX supports filtering by arrays. To filter by an array, use the following syntax:
tags: "tag1"
To filter by an array of values, use the following syntax:
tags: "tag1" "tag2"
Working with Nested Objects
CargoX supports filtering by nested objects. To filter by a nested object, use the following syntax:
address.city: "Ljubljana"
Working with Null Values
CargoX supports filtering by null values. To filter by a null value, use the following syntax:
address.city: NULL
Working with Empty Values
CargoX supports filtering by empty values. To filter by an empty value, use the following syntax:
address.city: ""
Working with Empty Arrays
CargoX supports filtering by empty arrays. To filter by an empty array, use the following syntax:
tags: []