DX Graph Filter Syntax

When querying data within 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 specifies the value to use for the comparison. While most filter operators (like $eq) use this format, others vary slightly and are detailed below.

Equals

Tests if a field has a specific value.

$eq

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"
  }
}

Specified value	Behaviour
Single number, string or boolean	The value to match.

Value in Data Record field	Behaviour
Single number, string or boolean	Matched if value is the same as the field's value.
Array of numbers, strings or booleans	Matched if value has the same value as any of the values in the field's array.

Not Equals

Tests if a field does not have a specific value.

$ne

Specified value	Behaviour
Single number, string or boolean	The value that should NOT be matched.

Value in Data Record field	Behaviour
Single number, string or boolean	Matched if value is not the same as the field's value.
Array of numbers, strings or booleans	Matched 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 value that is in a list of specified values.

$in

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 value	Behaviour
Array of strings or numbers	Values that are matched against.

Value in Data Record field	Behaviour
Single number or string	Matched if the field's value is in the list specified in value.
Array of numbers or strings	Matched 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.

$gt

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

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

Specified value	Behaviour
Single number or string	Matched records should be greater than this value.

Value in Data Record field	Behaviour
Single number or string	Matched if the field's value is greater than the specified value.
Array of numbers or strings	Matched if any of the field's value is greater than the specified value.

$gte

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

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

Specified value	Behaviour
Single number or string	Matched records should be greater than or equal to this value.

Value in Data Record field	Behaviour
Single number or string	Matched if the field's value is greater than or equal to the specified value.
Array of numbers or strings	Matched if any of the field's value is greater than or equal to the specified value.

$lt

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

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

Specified value	Behaviour
Single number or string	Matched records should be less than this value.

Value in Data Record field	Behaviour
Single number or string	Matched if the field's value is less than the specified value.
Array of numbers or strings	Matched if any of the field's value is less than the specified value.

$lte

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

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

Specified value	Behaviour
Single number or string	Matched records should be less than or equal to this value.

Value in Data Record field	Behaviour
Single number or string	Matched if the field's value is less than or equal to the specified value.
Array of numbers or strings	Matched if any of the field's value is less than or equal to the specified value.

Blank

Tests if a field is blank.

$isBlank

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 value	Behaviour
Boolean	If true, the specified field should be blank. If false, the specified field should not be blank.

Value in Data Record field	Behaviour
Anything	If 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 value	Behaviour
Boolean	If true, the specified field should exist. If false, the specified field should not be exist.

Value in Data Record field	Behaviour
Anything	If value is true, a match occurs if the field exists.

Pattern Match

Tests if a field's value matches a pattern.

$like

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

{
  "$like": {
    "field": "first_name",
    "value": "%ug%"
  }
}

Specified value	Behaviour
String	A string that contains a pattern to match. % --> Zero, one or many arbitrary characters. _ --> A single arbitrary character.

Value in Data Record field	Behaviour
String	A match occurs when the field's value matches the specified pattern.
Array of strings	A 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
      }
    }
  ]
}