Skip to main content

DX Graph Filter Syntax

When querying data within the DX Graph, a filter may be provided in order to further refine the returned records. A filter consists of one or more filter operators and typically looks like the following:

{
"$eq": {
"field": "city",
"value": "Toronto"
}
}

field specifies the field on which to perform the comparison and value specified the value to use for the comparison. While most filter operators (like $eq) use this format, others vary slightly and are detailed below.

Equals

$eq

Tests if a field has a specific value.

Specified valueBehaviour
Single number, string or booleanThe value to match.
Value in Data Record fieldBehaviour
Single number, string or booleanMatched if value is the same as the field's value.
Array of numbers, strings or booleansMatched if value has the same value as any of the values in the field's array.

Example: Filter records that have a city field with a value Toronto.

{
"$eq": {
"field": "city",
"value": "Toronto"
}
}

Example: Filter records that have a hobbies field that is an array of hobbies with a value tennis in the array.

{
"$eq": {
"field": "hobbies",
"value": "tennis"
}
}

Not Equals

Tests if a field does not have a specific value.

$ne

Specified valueBehaviour
Single number, string or booleanThe value that should NOT be matched.
Value in Data Record fieldBehaviour
Single number, string or booleanMatched if value is not the same as the field's value.
Array of numbers, strings or booleansMatched if value does not have the same value as any of the values in the field's array.

In

Tests if a field has a valkue that is in a list of specified values.

Example: Filter records that have an age field with a value that is one of 20 or 30.

{
"$in": {
"field": "age",
"value": [20,30]
}
}
Specified valueBehaviour
Array of strings or numbersValues that are matched against.
Value in Data Record fieldBehaviour
Single number or stringMatched if the field's value is in the list specified in value.
Array of numbers or stringsMatched if any of the field's values is in the list specified in value.

Greater and Less Than

Tests if a field has a value, greater-than, greater-than-or-equal-to, less-than or less-than-or-equal-to a specific value.

Example: Filter records that have an age field with a value less than or equal to 40.

{
"$lte": {
"field": "age",
"value": 40
}
}

Example: Filter records that have an age field with a value less than 70.

{
"$lt": {
"field": "age",
"value": 70
}
}

Example: Filter records that have an age field with a value greater than or equal to 50.

{
"$gte": {
"field": "age",
"value": 50
}
}

Example: Filter records that have an age field with a value greater than 30.

{
"$gt": {
"field": "age",
"value": 30
}
}

$gt

Specified valueBehaviour
Single number or stringMatched records should be greater than this value.
Value in Data Record fieldBehaviour
Single number or stringMatched if the field's value is greater than the specified value.
Array of numbers or stringsMatched if any of the field's value is greater than the specified value.

$gte

Specified valueBehaviour
Single number or stringMatched records should be greater than or equal to this value.
Value in Data Record fieldBehaviour
Single number or stringMatched if the field's value is greater than or equal to the specified value.
Array of numbers or stringsMatched if any of the field's value is greater than or equal to the specified value.

$lt

Specified valueBehaviour
Single number or stringMatched records should be less than this value.
Value in Data Record fieldBehaviour
Single number or stringMatched if the field's value is less than the specified value.
Array of numbers or stringsMatched if any of the field's value is less than the specified value.

$lte

Specified valueBehaviour
Single number or stringMatched records should be less than or equal to this value.
Value in Data Record fieldBehaviour
Single number or stringMatched if the field's value is less than or equal to the specified value.
Array of numbers or stringsMatched if any of the field's value is less than or equal to the specified value.

Blank

Tests if a field is blank.

$isBlank

Tests if a fields value is blank.

Example: Filter records that either does not have the name field or has name with a null or empty value.

{
"$isBlank": {
"field": "name",
"value": true
}
}
Specified valueBehaviour
BooleanIf true, the specified field should be blank. If false, the specified field should not be blank.
Value in Data Record fieldBehaviour
AnythingIf value is true, a matched occurs if the field's value is null (or an empty string) or if field does not exist.

Exists

Tests if a field exists.

$exists

Example: Filter records that have the name field.

{
"$exists": {
"field": "name",
"value": true
}
}
Specified valueBehaviour
BooleanIf true, the specified field should exist. If false, the specified field should not be exist.
Value in Data Record fieldBehaviour
AnythingIf value is true, a match occurs if the field exists.

Pattern Match

$like

Tests if a field's value matches a pattern.

Example: Filter records where first_name has a value that includes ug.

{
"$like": {
"field": "first_name",
"value": "%ug%"
}
}
Specified valueBehaviour
StringA string that contains a pattern to match. % --> Zero, one or many arbitrary characters. _ --> A single arbitrary character.
Value in Data Record fieldBehaviour
StringA match occurs when the field's value matches the specified pattern.
Array of stringsA match occurs when any of the values in the field's array matches the specified pattern.

Combining Filter Operators

Combinations of filter operators is achieved using $and and $or.

$and

Tests that all of the specified filter operators are met.

Example: Returns records where first_name contains ug and age is greater than 20.

{
"$and": [
{
"$like": {
"field": "first_name",
"value": "%ug%"
}
},
{
"$gt": {
"field": "age",
"value": 20
}
}
]

}

$or

Tests that at least one of the specified filter operators are met.

Example: Returns records where first_name contains ug or age is greater than 20.

{
"$or": [
{
"$like": {
"field": "first_name",
"value": "%ug%"
}
},
{
"$gt": {
"field": "age",
"value": 20
}
}
]
}