Entity filtering
- Last UpdatedMay 13, 2026
- 8 minute read
You can filter entities by using the where field within entities on a query.
Filtering by entity ID
You can filter entities by their unique identifiers using the id field.
Retrieve single ID
To retrieve a single entity with a specific id (for example, "pisrv.line1.pump101"), use the eq (equals) operator.
To retrieve the entity with the ID "pisrv.line1.pump101":
input: { filter: { where: { id: { eq: "pisrv.line1.pump101" } } } }
Retrieve multiple IDs
To retrieve multiple entities whose id matches any value in a list (such as "pisrv.line1.pump101", "pisrv.line1.pump102", and "pisrv.line1.pump103"), use the in operator.
To retrieve entities with the specified IDs:
input: { filter: { where: { id: { in: ["pisrv.line1.pump101", "pisrv.line1.pump102", "pisrv.line1.pump103"] } } } }
Filtering by standard fields
Entities include standard fields such as name, classId, and createdDate. You can filter entities based on these fields.
ID, name, or description contains
To retrieve entities whose id, name, or description contains the substring "pump":
Note: The current architecture allows "contains" or "filter" but does not support both in the same query.
input: { contains: "pump" }
Name starts with
To retrieve entities whose name starts with "pump":
input: { filter: { where: { name: { startsWith: "pump" } } } }
Name ends with
To retrieve entities whose name ends with "fl":
input: { filter: { where: { name: { endsWith: "fl" } } } }
Class name equals
To retrieve entities whose className equals "PumpClass":
input: { filter: { where: { className: { eq: "PumpClass" } } } }
Class name in
To retrieve entities whose className matches one of the class names in the list ["PumpClass", "MixerClass"]:
input: { filter: { where: { className: { in: ["PumpClass", "MixerClass"] } } } }
Created date after
To retrieve entities created after January 1, 2024:
input: { filter: { where: { createdDate: { gt: "2024-01-01T00:00:00Z" } } } }
Created date equals
To retrieve entities created on March 15, 2024:
input: { filter: { where: { createdDate: { eq: "2024-03-15T00:00:00Z" } } } }
Created by equals
To retrieve entities created by user with id "795df5a3-535f-45bc-baf7-5fb36abe32fd":
input: { filter: { where: { createdBy: "795df5a3-535f-45bc-baf7-5fb36abe32fd" } } }
Modified date before
To retrieve entities modified before June 1, 2024:
input: { filter: { where: { modifiedDate: { lt: "2024-06-01T00:00:00Z" } } } }
Modified by equals
To retrieve entities last modified by user with id "795df5a3-535f-45bc-baf7-5fb36abe32fd":
input: { filter: { where: { modifiedBy: "795df5a3-535f-45bc-baf7-5fb36abe32fd" } } }
Data sources
To retrieve entities whose data source is "DataSource1":
input: { filter: { where: { dataSources: [ "DataSource1" ] } } }
Security Tags in
To retrieve entities with security tags securityTag1 or securityTag2:
input: { filter: { where: { securityTags: { in: [ "securityTag1", "securityTag2" ] } } } }
Security Tags eq
To retrieve entities with security tag securityTag1:
input: { filter: { where: { securityTags: { eq: "securityTag1" } } } }
Filtering by properties
Entities may have additional properties. You can filter based on these properties to refine your results.
Manufacturer starts with
To retrieve entities where at least one Manufacturer property starts with "Big pump company", use the startsWith operator:
input: { filter: { where: { properties: [ { id: "Manufacturer", stringValue: { startsWith: "Big pump company" } } ] } } }
Manufacturer in
To retrieve entities where at least one Manufacturer property starts with "Big pump company" or "Big sensor company", use the in operator:
input: { filter: { where: { properties: [ { id: "Manufacturer", stringValue: { in: ["Big pump company", "Big sensor company"] } } ] } } }
Numeric property filtering
To retrieve entities where a property (such as maxPressure) is greater than 200:
input: { filter: { where: { properties: [ { id: "maxPressure", numberValue: { gt: 200 } } ] } } }
To retrieve entities where a property (such as maxPressure) is 200 or 300:
input: { filter: { where: { properties: [ { id: "maxPressure", numberValue: { in: [200, 300] } } ] } } }
DateTime property filtering
To retrieve entities where a property (such as lastServiced) is after May 1, 2024:
input: { filter: { where: { properties: [ { id: "lastServiced", dateTimeValue: { gt: "2024-05-01T00:00:00Z" } } ] } } }
To retrieve entities where a property (such as lastServiced) is on May 1, 2024 or June 1, 2024:
input: { filter: { where: { properties: [ { id: "lastServiced", dateTimeValue: { in: ["2024-05-01T00:00:00Z", "2024-06-01T00:00:00Z"] } } ] } } }
Boolean property filtering
To retrieve entities where a property (such as isActive) is true, use one of these methods:
input: { filter: { where: { properties: [ { id: "isActive", booleanValue: { eq: true } } ] } } }
input: { filter: { where: { properties: [ { id: "isActive", booleanValue: { in: [true] } } ] } } }
TimeSpan property filtering
To retrieve entities where a property (such as runTime) equals 1 hour:
input: { filter: { where: { properties: [ { id: "runTime", timeSpanValue: { eq: "01:00:00" } } ] } } }
To retrieve entities where a property (such as runTime) equals 1 hour or 2 hours:
input: { filter: { where: { properties: [ { id: "runTime", timeSpanValue: { in: ["01:00:00", "02:00:00"] } } ] } } }
TypeId property filtering
To retrieve entities where a property Id and TypeId match (this can also be used within component filters):
input: { filter: { where: { properties: [ { id: "runTime", typeId: "Flow Rate" } ] } } }
Enumeration property value filtering
To retrieve entities where a property (such as status) equals enum value 2:
input: { filter: { where: { properties: [ { id: "status", enumValue: { eq: 2 } } ] } } }
To retrieve entities where a property (such as status) equals enum value 2 or 3:
input: { filter: { where: { properties: [ { id: "status", enumValue: { in: [2, 3] } } ] } } }
Enumeration property string value filtering
To retrieve entities where a property (such as status) with enumeration id status equals enum value Active:
input: { filter: { where: { properties: [ { id: "status", enumStringValue: { enumerationSetId: "status", eq: "Active" } } ] } } }
To retrieve entities where a property (such as status) with enumeration id status status enum value Active or Closed:
input: { filter: { where: { properties: [ { id: "status", enumValue: { enumerationSetId: "status", in: [ "Active", "Closed" ] } } ] } } }
Multiple properties
You can combine multiple property filters. To retrieve entities where:
-
The name starts with "HEPA-C".
-
At least one class property starts with "process col".
-
At least one installWeight property has a unit of measure (uom) of "kg" and a value greater than 100 with type code INT_32.
input: {
filter: {
where: {
name: { startsWith: "HEPA-C" }
properties: [
{ id: "class", stringValue: { startsWith: "process col" } }
{ id: "installWeight", numberValue: { gt: 100, uom: "kg" } }
]
}
}
}
Property discovery
To retrieve entities that have a property with the ID "Temperature":
input: { filter: { where: { properties: [ { id: "Temperature" } ] } } }
Filtering by relationships
Entities can be related to other entities or streams. Filtering by relationships allows you to target entities or streams based on these connections.
Entity relationship
To retrieve entities that have a relationship with a specific entity (for example, "pisrv.line1.pump101"):
input: { filter: { where: { relationships: [ { values: ["pisrv.line1.pump101"], targetBase: ENTITY } ] } } }
Event relationship
To retrieve entities that have a relationship with a specific event (for example, "pisrv.line1.pump101.event1"):
input: { filter: { where: { relationships: [ { values: ["pisrv.line1.pump101.event1"], targetBase: EVENT } ] } } }
Stream relationship
To retrieve entities that have a relationship with a specific stream (for example, "HEFAOutput001"):
input: { filter: { where: { relationships: [ { values: ["HEFAOutput001"], targetBase: STREAM } ] } } }
Type relationship
To retrieve entities that have a relationship with a specific type (for example, "pisrv.line1.pump101.type1"):
input: { filter: { where: { relationships: [ { values: ["pisrv.line1.pump101.type1"], targetBase: TYPE } ] } } }
Relationship by type
To retrieve entities that are children of a specific entity:
input: { filter: { where: { relationships: [ { values: ["parent-entity-id"], targetBase: ENTITY, relationshipType: CHILD } ] } } }
Relationship by TypeId filtering
To retrieve entities that have matching typeIds (this can also be used within component filters):
input: { filter: { where: { relationships: [ { id: "Heating_Pump_1T42", values: ["Component.TestTarget"], typeId: "Pump_D1F2" }
Filtering by components
Components are subentities associated with an entity. You can filter entities based on the properties and relationships of their components.
Single component
To retrieve entities that have at least one EquipmentRegister component where:
-
There is at least one class property that starts with "process col".
-
There is at least one HasArea relationship that targets the entity "HEFA-A002".
input: {
filter: {
where: {
components: [
{
typeId: "EquipmentRegister"
properties: [ { id: "class", stringValue: { startsWith: "process col" } } ]
relationships: [ { id: "HasArea", values: ["HEFA-A002"], targetBase: ENTITY } ]
}
]
}
}
}
Multiple components
To retrieve entities that meet multiple component criteria, for example:
-
There is at least one pump component where at least one headPressure property is less than or equal to 100 with a unit of measure of N.
-
There is at least one equipment component where at least one has_plant relationship targets the entity with the ID HEFA.
input: {
filter: {
where: {
components: [
{
typeId: "pump"
properties: [ { id: "headPressure", numberValue: { le: 100, uom: "N" } } ]
},
{
typeId: "equipment"
relationships: [ { id: "has_plant", values: ["HEFA"], targetBase: ENTITY } ]
}
]
}
}
}
Component TypeName property equals
To retrieve entities with a component maintenance with type name maintenance type:
input: {
filter: {
where: {
components: [
{
typeName: {
eq: "maintenance type"
}
}
]
}
}
}
Component TypeName property not equals
To retrieve entities with a component that does not have type name maintenance type:
input: {
filter: {
where: {
components: [
{
typeName: {
ne: "maintenance type"
}
}
]
}
}
}
Component TypeName property startsWith
To retrieve entities with a component with a type name that starts with main:
input: {
filter: {
where: {
components: [
{
typeName: {
startsWith: "main"
}
}
]
}
}
}
Component TypeName property endsWith
To retrieve entities with a component with a type name that ends with type:
input: {
filter: {
where: {
components: [
{
typeName: {
endsWith: "type"
}
}
]
}
}
}
Component TypeName property contains
To retrieve entities with a component with a type name that contains ten:
input: {
filter: {
where: {
components: [
{
typeName: {
contains: "ten"
}
}
]
}
}
}
Component DateTime property less than
To retrieve entities with a component maintenance where a property lastChecked is before June 1, 2024:
input: {
filter: {
where: {
components: [
{
typeId: "maintenance"
properties: [ { id: "lastChecked", dateTimeValue: { lt: "2024-06-01T00:00:00Z" } } ]
}
]
}
}
}
Component Boolean property equals
To retrieve entities with a component sensor where a property isCalibrated is true:
input: {
filter: {
where: {
components: [
{
typeId: "sensor"
properties: [ { id: "isCalibrated", booleanValue: { eq: true } } ]
}
]
}
}
}
Component discovery
To retrieve entities where there is a Pump component:
input: { filter: { where: { components: [ { typeId: "Pump" } ] } } }
Component type inheritance discovery
To retrieve entities where there is a component that inherits from or is of type "BaseAsset":
input: { filter: { where: { components: [ { eqOrInheritsFrom: "BaseAsset" } ] } } }