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.
filter=({Condition Type}[AND/OR {Condition Type}]*)
filter={Condition Type}(property, value)
condition, the search engine considers only the first 256 symbols of the entered value and ignores the rest.Filter | Description of Condition Types | Example |
---|---|---|
equals | equals(property, value) : This condition type filters entities based on the exact match condition by ignoring the case of the conditional values. |
|
equalsCaseSensitive | equalsCaseSensitive(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:
|
|
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') |
fuzzy | fuzzy(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:
|
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) |
inSameAttributeValue | This 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. |
|
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') |
listEquals | This condition type has the following variants:
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. |
|
lte | lte(property, value) : This condition type indicates the lesser than or equals conditions. This condition type is only used in the entity history operation. |
|
gte | gte(property, value) : This condition type indicates the greater than or equals conditions. This condition type is only used in the entity history operation. |
|
lt | lt(property, value) : This condition type indicates the lesser than condition. This condition type is only used in the entity history operation. |
|
gt | gt(property, value) : This condition type indicates the greater than condition. This condition type is only used in the entity history operation. |
|
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) |
in | in(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")
|
listEqualsCaseSensitive | This condition type has the following variants:
Note: The case of the values is considered when filtering using any of the variants. Therefore, filtering for both these variants is case-sensitive. |
|
contains | contains(property, *value or ?value) : This condition type is passed if property satisfies a wildcard record. The supported wildcards are as follows:
|
|
regexp | regexp(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.*') |
insideCategoryTree | insideCategoryTree(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>) |
changes | changes(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') |
not | This 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_')) |
- Search by multiple conditions is supported with
AND
andOR
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)
- Filtering entities that have 'License' without 'Specialty':
- 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
, andregexp
condition types. - Search by a certain attribute count is supported with the special word
count
. For example, to search for 'Address', usefilter=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', usefilter=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. Thelt
,lte
,gt
, andgte
conditions are applicable only for timestamps and thechanges
condition is applicable only for filtering events with certain attribute changes.
- you use the
contains
or regular expressionsregexp
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:
filter=(startsWith(entity.label, 'iri') and startsWith(relation.label, 'fath'))
filter=(equals(relation.attributes.ORG_RSHP_TYP_CD, 'DOMESTICULTIMATE') and (equals(relation.attributes.XTRN_IND, 'Y'))
filter=(equals(type,'configuration/entityTypes/Organizations') and startsWith(relation.attributes.ORG_RSHP_TYP_CD, 'GLOBAL'))
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.
- Any attribute is
Pinned
orIgnored
- Case 1 - A defined attribute is
Pinned
orIgnored
- Case 2
- 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,Example - search for all entities where, at least, one attribute is
equals(attributes.pinned, "false")
.Pinned
.equals(attributes.pinned, "true")
- Case 2 - Search for a defined attribute
- Example - search for all entities where the simple attribute,
LastName
, ispinned
.
Example - search for all entities where the reference attribute,equals(attributes.LastName.pinned, "true")
Address.AddressLine1
, isn'tIgnored
.
Example - search for all entities where th nested attribute,missing(attributes.Address.AddressLine1.ignored)
Education.University
, isignored.
equals(attributes.Education.University.ignored, "true")