Entity sorting
- Last UpdatedMay 13, 2026
- 3 minute read
Entities returned can be sorted based on one filter used within the where field by using the orderBy field within the entities on a query.
Note: The values within the orderBy field must match a valid filter within the where field.
Valid filters include: standard entity fields, properties, and properties on components. Sorting on relationships is not supported.
Note: If you are sorting on a string using an endsWith filter, the returned results will be sorted in reverse alphabetical order.
Ends with example
If you have two entities:
{
"id": "Entity1",
"name": "FirstEntity"
}
{
"id": "Entity2",
"name": "SecondEntity"
}
And you filter on name in DESC order, the returned results would be:
{
"data": {
"entities": {
"items": [
{
"id": "Entity1",
"name": "FirstEntity",
},
{
"id": "Entity2",
"name": "SecondEntity",
}
]
}
}
}
Explanation
The expected result might be Entity2 followed by Entity1 since alphabetically the f in FirstEntity comes before the s in SecondEntity But since the sorting for specifically endWith string filters goes in reverse order, it is actually being sorting alphabetically based on the t at the end of first and the d at the end of second.
OrderBy structure
The orderBy field requires information on the filter being used and a direction by which to sort.
Direction input
Valid directions are:
-
ASC = Ascending
-
DESC = Descending
Sorting by standard entity fields
To sort on a standard entity field, such as name, classId, and createdDate, you must provide only the relevant field within the filter information section of orderBy.
Entity name
To sort on entity name you would only provide the field name and the desired direction within the orderBy field.
Entity name request
Sort entities based on name that starts with "E" in descending order.
input: {
filter: {
where: {
name: { startsWith: "E" }
}
orderBy: {
name: {
direction: DESC
}
}
}
}
Entity name response
{
"data": {
"entities": {
"items": [
{
"id": "ExampleEntity2",
"name": "Entity2",
},
{
"id": "ExampleEntity1",
"name": "Entity1",
}
]
}
}
}
Sorting by entity level properties
To sort entities based on properties, you must provide properties, property id, and direction fields within the orderBy field.
Note: In the case where there are multiple filters that match the provided property id, the first one stated in the where field will be used to sort by.
Entity level properties request
Sort entities based on a property id that equals "Flow Rate" and a numberValue that is greater than 1 in descending order.
input: {
filter: {
where: {
properties: [{ id: "Flow Rate", numberValue: { gt: 1} }]
}
orderBy: {
properties: {
id: "Flow Rate",
direction: DESC
}
}
}
}
Entity level properties response
{
"data": {
"entities": {
"items": [
{
"id": "ExampleEntity1",
"name": "Entity1",
"properties": [
{
"id": "Flow Rate",
"numberValue": 3
}
]
},
{
"id": "ExampleEntity2",
"name": "Entity2",
"properties": [
{
"id": "Flow Rate",
"numberValue": 2
}
]
}
]
}
}
}
Sorting by component level properties
To sort entities based on properties on a component, you must provide components, component typeId, properties, property id, and direction fields in the orderBy field.
Component level properties request
Sort entities based on a component typeId equal to "Pump", property id equal to "FlowRate", and a numberValue that is greater than 1 in descending order.
input: {
filter: {
where: {
components: [
{
typeId: "Pump",
properties: [ { id: "Flow Rate", numberValue: { gt: 1 } } ]
}
]
}
orderBy: {
components: {
typeId: "Pump",
properties: {
id: "Flow Rate",
direction: DESC
}
}
}
}
}
Component level properties response
{
"data": {
"entities": {
"items": [
{
"id": "ExampleEntity1",
"name": "Entity1",
"properties": [
{
"id": "Flow Rate",
"typeId": null, #This is set to null on Entity Level Properties
"numberValue": 2
},
{
"id": "Flow Rate",
"typeId": "Pump",
"numberValue": 6
}
]
},
{
"id": "ExampleEntity2",
"name": "Entity2",
"properties": [
{
"id": "Flow Rate",
"typeId": null, #This is set to null on Entity Level Properties
"numberValue": 3
},
{
"id": "Flow Rate",
"typeId": "Pump",
"numberValue": 5
}
]
}
]
}
}
}
Note: Notice how both entities have two properties that have the id equal to "Flow Rate" but one each that has componentTypeId equal to "Pump". The sorting is based on the numberValue within the properties that have the componentTypeId of "Pump" and ignores the properties that have componentTypeId of null.