Unify and manage your data

Filtering Entities

Learn about filtering entities

Format

When the filter parameter is supported in an operation (for example, entity search), it enables filtering entities using condition types.

Format for the filter query parameter: filter=({Condition Type}[AND/OR {Condition Type}]*)
Note: Irrespective of the value that you enter in the filter={Condition Type}(property, value) condition, the search engine considers only the first 256 symbols of the entered value and ignores the rest.
Table 1. Supported Filter Condition Types
FilterDescription of Condition TypesExample
equalsequals(property, value): This condition type filters entities based on the exact match condition by ignoring the case of the conditional values.
  • Filter by entity type organization: filter=equals(type, 'configuration/entityTypes/Organization')
  • Filter by the string 'Ann' across all the attributes: filter=equals(attributes, 'Ann')
  • Filter by an attribute with a given value: filter=equals(attributes.<entity_attribute>, <value>)
  • Filter by a relation attribute with a given value: filter=equals(relation.attributes.<entity_attribute>, <value>)
  • Filter the individual entities that belong to a category with URI 'categories/000777': filter=(equals(type, 'configuration/entityTypes/Individual') and equals(categories, '000777'))
  • For historical events filter all the ENTITY_CHANGED events: filter=equals(type, 'ENTITY_CHANGED')
equalsCaseSensitiveequalsCaseSensitive(property, value): This condition type filters entities based on the exact match condition by considering the case of the conditional values.Filter by first name ‘John’ (case sensitive): filter=equalsCaseSensitive(attributes.FirstName, ‘John’)
containsWordStartingWith containsWordStartingWith(property, tokenized value): This is a prefixed condition type and returns entities that have the conditional property starting with the conditional value.
In this condition type, the search engine considers the following symbols in a value as word separators:
  • '
  • ,
  • @
  • #
  • $
  • ;
  • :
  • &
  • %
  • <>
  • ()
  • []
  • *
  • |
  • /
  • \
  • !
  • ?
  • Filter by name containing a word starting with ‘Bobby’: filter=containsWordStartingWith(attributes.Name, ‘Bobby’)
  • Filter entities with attribute values 'D Souza', 'D, Souza', 'D@Souza', and 'D#Souza': filter=containsWordStartingWith(attributes,"D'Souza")
fullText fullText(property, value): This condition type combines individual results into the overall result and returns entities that have the conditional property with the conditional value (any place). Any entity whose title field contains at least one of the specified terms matches the query. The more terms that match, the more relevant is the entity. Full text search across all blog entries: filter=fullText(attributes.Blogs, 'Golf')
fuzzyfuzzy(property, value): This condition type filters entities based on the fuzzy match condition. The condition permits minor differences between the query and target strings. Fuzzy search logic can be applied to any string attribute search.

For more information, see Fuzzy Filtering.

Filter by the name Smith:

fuzzy(attributes.Name,'Smith')

missing missing(property): This condition type returns entities with fields that have no values for property or the property value is empty.Filter entities that do not have the Education.University attribute or have empty value for this attribute: filter=missing(attributes.Education.University)
exists exist(property): This condition type returns entities having non-empty value for property.Filter entities that have non-empty value for the Education.University attribute: filter=exists(attributes.Education.University)
inSameAttributeValueThis condition type returns only those entities that have sub-attributes within a single nested or reference attribute that meet the conditions specified by the sub-query.

Note that the sub-query supports the use of all operands except regexp and in. Also, as noted above, the sub-attributes specified by the sub-queries must all be from within the same nested or reference attribute.

For example, if Address and Education are two distinct nested attributes with their own sets of sub-attributes, then they can’t both be used inside the same inSameAttributeValue sub-query.
  • Find all entities having Address from 'Chicago', 'IL' with Zip code '12345':
filter=inSameAttributeValue(equals(attributes.Address.City, 'Chicago') and equals(attributes.Address.State, 'IL') and equals(attributes.Address.Zip.Zip5, '12345'))
startsWith startsWith(property, stricted value): This is a prefixed condition type and returns entities that have the condition property starting with the conditional value.Filter by last name starting with ‘Pitt’: filter=startsWith(attributes.LastName, 'Pitt')
listEqualsThis condition type has the following variants:
  • listEquals(property, file URL) - This condition type returns entities that have a conditional property with conditional values from the file (one value in each row). This condition type returns an empty result if the file is unavailable or is deleted. The supported file formats are TXT and CSV. You can specify a file with public access in the filter or can upload a file to Reltio bucket. For more information, see Uploading a File for File-based Search.
    Note: The CSV format for file-based search is supported provided:
    • It has a single column.
    • The input CSV must not have a header row.
    Note: The input file can contain a maximum of 5000 rows only. The maximum file size is 10 MB.
  • listEquals(property, value, value) - This condition type is passed if the conditional property is equal to one of the comma-separated values.
Note: The case of the values is not considered when filtering using any of the variants. Therefore, filtering for both these variants is not case sensitive.
  • Find all entities having a value from a public file:

    filter=listEquals(attributes.Education.University, 'URL:https://reltio.com/example.txt')

  • Find all entities having a value from uploaded to Reltio bucket file:

    filter=listEquals(attributes.Education.University, 'URL:s3://bucketName/envName/valueListFiles/01-Jan-2021/TenantID/data053231.txt')

  • Find all entities having a value from a list:

    filter=listEquals(attributes.FirstName, Steve, Peter)

ltelte(property, value): This condition type indicates the lesser than or equals conditions. This condition type is only used in the entity history operation.
  • Filter entities with age lesser than or equal to 40: filter=lte(attributes.Age, 40)
  • Filter historical events with a timestamp earlier than or equal to a specified value: filter=lte(timestamp, '1428309071535')
gtegte(property, value): This condition type indicates the greater than or equals conditions. This condition type is only used in the entity history operation.
  • Filter entities with age greater than or equal to 18: filter=gte(attributes.Age, 18)
  • Filter historical events with a timestamp later than or equal to a specified value: filter=gte(timestamp, '1428309071535')
lt lt(property, value): This condition type indicates the lesser than condition. This condition type is only used in the entity history operation.
  • Filter entities created earlier than '1540805153527': filter=lt(createdTime, 1540805153527)
  • Filter historical events with a timestamp earlier than a specified value: filter=lt(timestamp, '1428309071535')
gt gt(property, value): This condition type indicates the greater than condition. This condition type is only used in the entity history operation.
  • Filter entities updated later than '1540805153527': filter=gt(updatedTime, 1540805153527)
  • Filter historical events with a timestamp later than a specified value: filter=gt(timestamp, '1428309071535')
range range(property, start, end): This condition type indicates that the property is between (including edges, ignoring case) the specified start and end values. This condition type is also used in the entity connection operations.Filter entities with age between '20' and '40': filter=range(attributes.Age, 20, 40)
inin(property, value): The value must contain a comma-separated value for the in filter clause.Filter entities with first names Janaki or Titilayo: filter=in(attributes.FirstName, "Janaki,Titilayo")
listEqualsCaseSensitiveThis condition type has the following variants:
  • listEqualsCaseSensitive(property, file URL) - This condition type returns entities that have a conditional property with conditional values from the file (one value in each row). This condition type returns an empty result if the file is unavailable or is deleted. The supported file formats are TXT and CSV. You can specify a file with public access in the filter or can upload a file to Reltio bucket. For more information, see Uploading a File for File-based Search.
    Note: The CSV format for file-based search is supported provided:
    • It has a single column.
    • The input CSV must not have a header row.
    Note: The input file can contain a maximum of 5000 rows only.
  • listEqualsCaseSensitive(property, value, value) - This condition type is passed if the conditional property is equal to one of the comma-separated values.
Note: The case of the values is considered when filtering using any of the variants. Therefore, filtering for both these variants is case-sensitive.
  • Find all entities having a value from a public file: filter=listEqualsCaseSensitive(attributes.Education.University, 'URL:https://reltio.com/example.txt')
  • Find all entities having a value that is uploaded to Reltio bucket file: filter=listEqualsCaseSensitive(attributes.Education.University, 'URL:s3://bucketName/envName/valueListFiles/01-Jan-2021/TenantID/data053231.txt')
  • Find all entities having a value from a list: filter=listEqualsCaseSensitive(attributes.FirstName, Steve, Peter)
containscontains(property, *value or ?value): This condition type is passed if property satisfies a wildcard record. The supported wildcards are as follows:
  • * - Matches any character sequence (including the empty one)
  • ? - Matches any single character (not case sensitive)
  • Filter by a specific attribute: filter=contains(attributes.Name, '*Johnson*')
  • Filter by no specific attribute: filter=contains(attributes, '*Johnson*')
regexpregexp(attributes.Identifiers.ID, value): This condition type is passed if attributes.Identifiers.ID satisfies a regular expression (case sensitive).Filter by first name: filter=regexp(attributes.Name, 'Mat.*')
insideCategoryTreeinsideCategoryTree(category, <category URI>): This condition type filters all entities that have a category inside the category tree specified by category URI. By being inside the category tree, it implies that the entity belongs to the specified category or to any child category of the specified category.Filter by category URI: filter=insideCategorytree(category, <category URI>)
changeschanges(attribute): This condition type matches the changes for a specific attribute. This condition type is only used in the entity history operation.Filter historical events with changes of the first name attribute made by 'test.user': filter= changes(configuration/entityTypes/HCP/attributes/FirstName) and equals(user, 'test.user')
notThis operator negates a condition and can be used with other operators.Filter all entities with the Association_Status attribute that do not start with TEMP_: filter=not(startsWith(attributes.Association_Status, 'TEMP_'))
Note: Consider the following points when using the condition types:
  • Search by multiple conditions is supported with AND and OR operands. Following are some examples:
    • Filtering entities that have 'License' without 'Specialty': filter=(exists(attributes.License) and missing(attributes.License.Specialty))
    • Filter individual entities that have the first name starting with 'An': filter=(equals(type, 'configuration/entityTypes/Individual') and startsWith(attributes.FirstName, 'An'))
    • Filter active entities by '2005-10-17': filter=(gt(activeness.startDate, 1129507200) and lt(activeness.endDate, 1129507200)
  • In a condition type expression, property is a dot-delimited path to the property to be searched with. For example: type, roles, attributes.Name, attribute.Education.Degree. For entity connections operations, it can be one of the following:
    • entity.label
    • relation.label
    • group.name
    • memberType.label
  • Search is not case sensitive except for the equalsCaseSensitive, listEqualsCaseSensitive, and regexp condition types.
  • Search by a certain attribute count is supported with the special word count. For example, to search for 'Address', use filter=equals(attributes.Address.count, 3). All condition types are supported.
  • Replace + with %2B on the client side in the search requests. For example, to search for 'some+d-423type', use filter=equals(attributes.Identifiers.Type, 'some%2Bd-423type').
  • For the entity history operation, the equals match condition is used for filtering users who made changes for history event type and for timestamps. The lt, lte, gt, and gte conditions are applicable only for timestamps and the changes condition is applicable only for filtering events with certain attribute changes.
Note: You can filter lookup attributes using lookup codes. You cannot filter lookup attributes using lookup value, since it is not supported.
Note: Get ready to wait longer to get your results — for complex searches — when:
  • you use the contains or regular expressions regexp conditions, along with wildcard characters (for example, '*John' in 'entities?filter=contains(attributes.FirstName, '*John')')
  • you use multiple wildcard searches simultaneously

Entity Connections Requests Filters

Consider the following examples when you want to filter entity connections requests:

Example - Filter Entity and Relationship Labels
filter=(startsWith(entity.label, 'iri') and startsWith(relation.label, 'fath'))
Example - Filter a Relationship's Attributes
filter=(equals(relation.attributes.ORG_RSHP_TYP_CD, 'DOMESTICULTIMATE') and (equals(relation.attributes.XTRN_IND, 'Y'))
Example - Filter Entity and Relationship Attributes Simultaneously
filter=(equals(type,'configuration/entityTypes/Organizations') and startsWith(relation.attributes.ORG_RSHP_TYP_CD, 'GLOBAL'))
Example - Filter Other Relationship Properties (activeness, createdBy, createdTime, etc.)
filter=lt(relation.createdTime, '1428309071535')

For more information about Connections Requests, see Requesting Multiple Entity Connections with a Request.

Search for Pinned or Ignored Entity attributes

Use the equals or missing filters to find Pinned or Ignored attributes.

You can filter to find any entities where:
  • Any attribute is Pinned or Ignored - Case 1
  • A defined attribute is Pinned or Ignored - Case 2
Note: By default, your search include simple and reference attributes. If you want your search to include nested attributes, reindex your entities.
Case 1 - Search for any attribute
Note: Only use this filter with value="true", as in the example above. You'll get a bad request error for value="false". for example, equals(attributes.pinned, "false").
Example - search for all entities where, at least, one attribute is Pinned.
equals(attributes.pinned, "true")
Case 2 - Search for a defined attribute
Example - search for all entities where the simple attribute, LastName, is pinned.
equals(attributes.LastName.pinned, "true")
Example - search for all entities where the reference attribute, Address.AddressLine1, isn't Ignored.
missing(attributes.Address.AddressLine1.ignored)
Example - search for all entities where th nested attribute, Education.University, is ignored.
equals(attributes.Education.University.ignored, "true")