Custom field filtering and sorting

Filter and sort assets and geo objects by their custom field values in Business Data Repository.

Business Data Repository's assets and geo objects are the entities that support custom fields, and both can be filtered and sorted by their custom field values. This is in addition to the standard filter and orderBy arguments described in Filtering and sorting.

For an overview of custom fields themselves, see Custom fields.

Filtering by custom fields

Add conditions to the customFields array inside the filter argument:

query {
  bdr {
    assets(
      workspaceId: "019d48ea-0752-8000-801f-444556437ab1"
      filter: {
        customFields: [
          { code: "cf_fuel_type", operator: EQ, value: { string: "diesel" } }
        ]
      }
    ) {
      nodes {
        id
        title
      }
    }
  }
}

Each condition in the customFields array has three parts:

Field	Description
code	The custom field's code, as defined in its CustomFieldDefinition
operator	How to compare the value
value	The value to compare against. Provide exactly one option, the one matching the field's type

Operators

Operator	Description
EQ	Equals
NE	Not equals
GT	Greater than
GTE	Greater than or equal
LT	Less than
LTE	Less than or equal
CONTAINS	String contains (case-insensitive)
IN	Matches any value in the provided array
IS_NULL	Field has no value
IS_NOT_NULL	Field has a value

How CONTAINS matches

On STRING and TEXT fields, CONTAINS ignores letter case and matches everything else literally:

• Case differences never prevent a match, in any alphabet: diesel finds Diesel Truck, and дизель finds Дизельный грузовик.

• Accents count: cafe does not find café.

• Digits match literally: part 7 does not find part 0007, and a Western digit does not find its equivalent from another script.

• Invisible characters count: a soft hyphen or a zero-width space inside the stored value breaks the match.

Search for the substring exactly as it is stored; only letter case can differ.

The whole-value operators EQ, NE, and IN compare strings with the natural-language rules that sorting uses, and those rules treat some visibly different strings as equal: for them, 1 equals 01. A value that EQ matches is therefore not always found by CONTAINS with the same search string.

Value formats

The value field is a @oneOf input: provide exactly one of its options, the one matching your field's type:

Option	Field types	Example
string	STRING, TEXT, OPTIONS	{ string: "diesel" }
decimal	DECIMAL	{ decimal: 42.50 }
integer	INTEGER	{ integer: 42 }
boolean	BOOLEAN	{ boolean: true }
date	DATE	{ date: "2024-01-15" }
datetime	DATETIME	{ datetime: "2024-01-15T10:30:00Z" }
id	DEVICE, REFERENCE	{ id: "019a6a3f-..." }
stringList	IN operator on string-based fields	{ stringList: ["option_a", "option_b"] }
idList	IN operator on DEVICE and REFERENCE fields	{ idList: ["uuid1", "uuid2"] }

For IS_NULL and IS_NOT_NULL operators, omit value or set it to null.

Multiple conditions

Multiple custom field conditions are combined with AND logic:

filter: {
  customFields: [
    { code: "cf_fuel_type", operator: EQ, value: { string: "diesel" } },
    { code: "cf_year", operator: GTE, value: { integer: 2020 } }
  ]
}

This returns assets where fuel type is diesel AND year is 2020 or later.

Multi-value fields

For custom fields configured to hold multiple values (isMulti: true), the filter matches if any stored value satisfies the condition:

# Asset has colors: ["red", "blue", "white"]
filter: {
  customFields: [
    { code: "cf_colors", operator: EQ, value: { string: "red" } }
  ]
}
# Matches — "red" is one of the values

Combining standard and custom filters

You can use standard filter fields and custom field conditions together:

query {
  bdr {
    assets(
      workspaceId: "019d48ea-0752-8000-801f-444556437ab1"
      filter: {
        typeIds: ["type-truck-uuid"]
        titleContains: "north"
        customFields: [
          { code: "cf_region", operator: EQ, value: { string: "northwest" } }
        ]
      }
    ) {
      nodes {
        id
        title
      }
    }
  }
}

This returns trucks with "north" in their title that are assigned to the northwest region.

Sorting by custom fields

Assets and geo objects support sorting by custom field values. The sortable field types are STRING, DECIMAL, INTEGER, DATE, DATETIME, plus the reference types DEVICE and single-value REFERENCE, which sort by the title of the entity they point at rather than by the stored ID. TEXT, OPTIONS, BOOLEAN, and GEOJSON fields are not sortable, and neither is a multi-value REFERENCE or a REFERENCE pointing at an entity with no title.

query {
  bdr {
    assets(
      workspaceId: "019d48ea-0752-8000-801f-444556437ab1"
      orderBy: { customFieldCode: "cf_priority", direction: DESC }
    ) {
      nodes {
        id
        title
      }
    }
  }
}

Use either field or customFieldCode in your orderBy input, not both — they are mutually exclusive.

See also

• Filtering and sorting: Narrow list queries and control result order

• Defining and using custom fields: Define custom fields and store your own data on entities