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:

• yyyyMMdd
• yyyyMMddHHmm
• yyyyMMddHHmmss
• yyyy-MM-dd
• yyyy-MM-dd'T'HH:mm:ss
• yyyy-MM-dd'T'HH:mm:ss.SSS'Z'

Working with Relative Dates

CargoX supports relative date expressions based on Lucene/Solr date math that allow you to filter by dates relative to the current time. This is particularly useful for creating dynamic filters that don't require manual date updates.

Current Time Reference

To filter by the current date and time, use the NOW keyword (case-sensitive):

createdDate: NOW

Date Math Syntax

Date math expressions use the following format: NOW followed by mathematical operations using + or - and time units.

Basic syntax: NOW+/-[0-9]+(YEAR|MONTH|DAY|HOUR|MINUTE|SECOND|MILLI)

Time Units Supported

The following time units are supported (case-sensitive):

Unit	Aliases	Description	Example
YEAR	YEARS	Calendar years	NOW+1YEAR
MONTH	MONTHS	Calendar months	NOW-6MONTHS
DAY	DAYS, DATE	Calendar days	NOW+7DAYS
HOUR	HOURS	Hours	NOW-12HOURS
MINUTE	MINUTES	Minutes	NOW+30MINUTES
SECOND	SECONDS	Seconds	NOW-45SECONDS
MILLI	MILLIS, MILLISECOND, MILLISECONDS	Milliseconds	NOW+500MILLIS

Business Date Math Units

In addition to standard calendar units, CargoX supports business-aware date math that respects the organization's configured business calendar (business hours, holidays). These units require a business calendar to be set up for the organization.

Unit	Aliases	Description	Example
BHOUR	BHOURS	Business hours (skips non-working hours, holidays)	NOW+4BHOURS
BDAY	BDAYS	Business days (skips weekends and holidays per the org's business calendar)	NOW+2BDAYS

Business hour calculation walks through the organization's weekly business-hour schedule, accumulating working time and skipping holidays. For example, if business hours are Mon–Fri 09:00–17:00 and the current time is Friday 15:00, NOW+4BHOURS resolves to Monday 11:00 (2 hours remaining Friday + 2 hours into Monday).

Business day calculation counts only days that have at least some business hours (after subtracting holidays). The time-of-day is preserved from the starting time.

Examples:

# Orders due within the next 3 business days
dueDate: [NOW TO NOW+3BDAYS]

# Orders where pickup is more than 8 business hours overdue
pickupDate: [* TO NOW-8BHOURS]

# Filter for orders due by end of next business day (rounded)
dueDate: [* TO NOW/DAY+1BDAY]

note

Business date math requires that a business calendar (type business) is configured for the organization. If no calendar exists, filters using BHOUR/BDAY will return an error. Standard calendar units (DAY, HOUR, etc.) do not require a business calendar and continue to work as before.

Adding Time to Current Date

To filter by a date that is a specific amount of time in the future from now:

deliveryDate: NOW+1DAY

Examples:

• NOW+1YEAR (one year from now)
• NOW+6MONTHS (six months from now)
• NOW+2DAYS (two days from now)
• NOW+12HOURS (twelve hours from now)

Subtracting Time from Current Date

To filter by a date that is a specific amount of time in the past from now:

createdDate: NOW-30DAYS

Examples:

• NOW-1YEAR (one year ago)
• NOW-3MONTHS (three months ago)
• NOW-1DAY (one day ago)
• NOW-24HOURS (twenty-four hours ago)

Date Rounding

You can round dates to specific time units using the / operator. This truncates the date to the beginning of the specified unit.

Syntax: NOW/UNIT

Examples:

• NOW/DAY (beginning of today)
• NOW/MONTH (beginning of current month)
• NOW/YEAR (beginning of current year)
• NOW/HOUR (beginning of current hour)

Combining Operations

You can combine multiple operations in a single expression. Operations are evaluated left to right:

updatedDate: NOW/DAY+1DAY

This example represents tomorrow at midnight (beginning of tomorrow).

More complex examples:

• NOW/MONTH+1MONTH (beginning of next month)
• NOW/DAY-7DAYS (beginning of the day 7 days ago)
• NOW/HOUR+30MINUTES (30 minutes into the current hour)

Relative Date Ranges

Relative dates can be used in range queries to create dynamic date ranges:

createdDate: [NOW-7DAYS TO NOW]

This filters for records created in the last 7 days.

deliveryDate: [NOW TO NOW+30DAYS]

This filters for deliveries scheduled within the next 30 days.

Complex Date Math Examples

Filter for orders created this month:

createdDate: [NOW/MONTH TO NOW]

Filter for deliveries due this week:

deliveryDate: [NOW/DAY TO NOW/DAY+7DAYS]

Filter for invoices overdue (due date is in the past):

dueDate: [* TO NOW-1DAY]

Filter for events scheduled between last week and next week:

eventDate: [NOW-7DAYS TO NOW+7DAYS]

Filter for records created today:

createdDate: [NOW/DAY TO NOW/DAY+1DAY]

Filter for records from the beginning of last month to now:

createdDate: [NOW/MONTH-1MONTH TO NOW]

Time Zone Considerations

By default, all date math expressions are evaluated relative to UTC. However, this can be overridden using the TZ parameter in your request to specify a different time zone.

The NOW keyword represents the exact moment when the query is executed on the server.

Important Notes

• All time unit keywords are case-sensitive and must be in UPPERCASE
• The NOW keyword must be in UPPERCASE
• Date math operations are evaluated left to right
• Rounding operations (/) truncate to the beginning of the specified time unit
• When combining operations, rounding should typically be done first (e.g., NOW/DAY+1DAY)

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: []

JSONB Custom Value Range Filters

Custom values stored as JSONB support type-safe range filtering. Numeric and date values stored in customValues are automatically cast to the appropriate type for comparison.

Numeric Range

customValues.weight: [100 TO 500]
customValues.price: {0 TO *}

Date Range

customValues.ETA: [2026-01-01 TO 2026-03-31]
customValues.pickupDate: {* TO 2026-03-23}

Range filters on JSONB fields use PostgreSQL casting to ensure correct comparison semantics (numeric or timestamp), rather than string comparison.

Error Handling

If a filter expression contains invalid Lucene syntax, the API returns a FILTER_SYNTAX_ERROR error code with a descriptive message, rather than a generic 500 error.