privatestaticfinalStringMAX_LEVEL_DESCRIPTION="Possible direction values are 'TO' and 'FROM'. The 'maxLevel' defines how many relation levels should the query search 'recursively'. ";
privatestaticfinalStringFETCH_LAST_LEVEL_ONLY_DESCRIPTION="Assuming the 'maxLevel' is > 1, the 'fetchLastLevelOnly' defines either to return all related entities or only entities that are on the last level of relations. ";
"Allows to filter entities that are related to the provided root entity. "+
MAX_LEVEL_DESCRIPTION+
FETCH_LAST_LEVEL_ONLY_DESCRIPTION+
"The 'filter' object allows you to define the relation type and set of acceptable entity types to search for. "+
"The relation query calculates all related entities, even if they are filtered using different relation types, and then extracts only those who match the 'filters'.\n\n"+
"For example, this entity filter selects all devices and assets which are related to the asset with id 'e51de0c0-2a7a-11ec-94eb-213c95f54092':\n\n"+
"Allows to filter assets that are related to the provided root entity. Filters related assets based on the relation type and set of asset types. "+
MAX_LEVEL_DESCRIPTION+
FETCH_LAST_LEVEL_ONLY_DESCRIPTION+
"The 'relationType' defines the type of the relation to search for. "+
"The 'assetTypes' defines the type of the asset to search for. "+
"The relation query calculates all related entities, even if they are filtered using different relation types, and then extracts only assets that match 'relationType' and 'assetTypes' conditions.\n\n"+
"For example, this entity filter selects 'charging station' assets which are related to the asset with id 'e51de0c0-2a7a-11ec-94eb-213c95f54092' using 'Contains' relation:\n\n"+
"Allows to filter devices that are related to the provided root entity. Filters related devices based on the relation type and set of device types. "+
MAX_LEVEL_DESCRIPTION+
FETCH_LAST_LEVEL_ONLY_DESCRIPTION+
"The 'relationType' defines the type of the relation to search for. "+
"The 'deviceTypes' defines the type of the device to search for. "+
"The relation query calculates all related entities, even if they are filtered using different relation types, and then extracts only devices that match 'relationType' and 'deviceTypes' conditions.\n\n"+
"For example, this entity filter selects 'Charging port' and 'Air Quality Sensor' devices which are related to the asset with id 'e52b0020-2a7a-11ec-94eb-213c95f54092' using 'Contains' relation:\n\n"+
"Allows to filter entity views that are related to the provided root entity. Filters related entity views based on the relation type and set of entity view types. "+
MAX_LEVEL_DESCRIPTION+
FETCH_LAST_LEVEL_ONLY_DESCRIPTION+
"The 'relationType' defines the type of the relation to search for. "+
"The 'entityViewTypes' defines the type of the entity view to search for. "+
"The relation query calculates all related entities, even if they are filtered using different relation types, and then extracts only devices that match 'relationType' and 'deviceTypes' conditions.\n\n"+
"For example, this entity filter selects 'Concrete mixer' entity views which are related to the asset with id 'e52b0020-2a7a-11ec-94eb-213c95f54092' using 'Contains' relation:\n\n"+
"Allows to filter edge instances that are related to the provided root entity. Filters related edge instances based on the relation type and set of edge types. "+
MAX_LEVEL_DESCRIPTION+
FETCH_LAST_LEVEL_ONLY_DESCRIPTION+
"The 'relationType' defines the type of the relation to search for. "+
"The 'deviceTypes' defines the type of the device to search for. "+
"The relation query calculates all related entities, even if they are filtered using different relation types, and then extracts only devices that match 'relationType' and 'deviceTypes' conditions.\n\n"+
"For example, this entity filter selects 'Factory' edge instances which are related to the asset with id 'e52b0020-2a7a-11ec-94eb-213c95f54092' using 'Contains' relation:\n\n"+
privatestaticfinalStringEMPTY="\n\n## Entity Type Filter\n\n"+
"Allows to filter multiple entities of the same type using the **'starts with'** expression over entity name. "+
"For example, this entity filter selects all devices which name starts with 'Air Quality':\n\n"+
MARKDOWN_CODE_BLOCK_START+
""+
MARKDOWN_CODE_BLOCK_END+
"";
privatestaticfinalStringENTITY_FILTERS=
"\n\n # Entity Filters"+
"\nEntity Filter body depends on the 'type' parameter. Let's review available entity filter types. In fact, they do correspond to available dashboard aliases."+
"Filter Key defines either entity field, attribute or telemetry. It is a JSON object that consists the key name and type. "+
"The following filter key types are supported: \n\n"+
" * 'CLIENT_ATTRIBUTE' - used for client attributes; \n"+
" * 'SHARED_ATTRIBUTE' - used for shared attributes; \n"+
" * 'SERVER_ATTRIBUTE' - used for server attributes; \n"+
" * 'ATTRIBUTE' - used for any of the above; \n"+
" * 'TIME_SERIES' - used for time-series values; \n"+
" * 'ENTITY_FIELD' - used for accessing entity fields like 'name', 'label', etc. The list of available fields depends on the entity type; \n"+
" * 'ALARM_FIELD' - similar to entity field, but is used in alarm queries only; \n"+
"\n\n Let's review the example:\n\n"+
MARKDOWN_CODE_BLOCK_START+
"{\n"+
" \"type\": \"TIME_SERIES\",\n"+
" \"key\": \"temperature\"\n"+
"}"+
MARKDOWN_CODE_BLOCK_END+
"";
privatestaticfinalStringFILTER_VALUE_TYPE="\n\n## Value Type and Operations\n\n"+
"Provides a hint about the data type of the entity field that is defined in the filter key. "+
"The value type impacts the list of possible operations that you may use in the corresponding predicate. For example, you may use 'STARTS_WITH' or 'END_WITH', but you can't use 'GREATER_OR_EQUAL' for string values."+
"The following filter value types and corresponding predicate operations are supported: \n\n"+
" * 'STRING' - used to filter any 'String' or 'JSON' values. Operations: EQUAL, NOT_EQUAL, STARTS_WITH, ENDS_WITH, CONTAINS, NOT_CONTAINS; \n"+
" * 'NUMERIC' - used for 'Long' and 'Double' values. Operations: EQUAL, NOT_EQUAL, GREATER, LESS, GREATER_OR_EQUAL, LESS_OR_EQUAL; \n"+
" * 'BOOLEAN' - used for boolean values; Operations: EQUAL, NOT_EQUAL \n"+
" * 'DATE_TIME' - similar to numeric, transforms value to milliseconds since epoch. Operations: EQUAL, NOT_EQUAL, GREATER, LESS, GREATER_OR_EQUAL, LESS_OR_EQUAL; \n";
"Filter Predicate defines the logical expression to evaluate. The list of available operations depends on the filter value type, see above. "+
"Platform supports 4 predicate types: 'STRING', 'NUMERIC', 'BOOLEAN' and 'COMPLEX'. The last one allows to combine multiple operations over one filter key."+
"\n\nSimple predicate example to check 'value < 100': \n\n"+
MARKDOWN_CODE_BLOCK_START+
"{\n"+
" \"operation\": \"LESS\",\n"+
" \"value\": {\n"+
" \"defaultValue\": 100,\n"+
" \"dynamicValue\": null\n"+
" },\n"+
" \"type\": \"NUMERIC\"\n"+
"}"+
MARKDOWN_CODE_BLOCK_END+
"\n\nComplex predicate example, to check 'value < 10 or value > 20': \n\n"+
MARKDOWN_CODE_BLOCK_START+
"{\n"+
" \"type\": \"COMPLEX\",\n"+
" \"operation\": \"OR\",\n"+
" \"predicates\": [\n"+
" {\n"+
" \"operation\": \"LESS\",\n"+
" \"value\": {\n"+
" \"defaultValue\": 10,\n"+
" \"dynamicValue\": null\n"+
" },\n"+
" \"type\": \"NUMERIC\"\n"+
" },\n"+
" {\n"+
" \"operation\": \"GREATER\",\n"+
" \"value\": {\n"+
" \"defaultValue\": 20,\n"+
" \"dynamicValue\": null\n"+
" },\n"+
" \"type\": \"NUMERIC\"\n"+
" }\n"+
" ]\n"+
"}"+
MARKDOWN_CODE_BLOCK_END+
"\n\nMore complex predicate example, to check 'value < 10 or (value > 50 && value < 60)': \n\n"+
MARKDOWN_CODE_BLOCK_START+
"{\n"+
" \"type\": \"COMPLEX\",\n"+
" \"operation\": \"OR\",\n"+
" \"predicates\": [\n"+
" {\n"+
" \"operation\": \"LESS\",\n"+
" \"value\": {\n"+
" \"defaultValue\": 10,\n"+
" \"dynamicValue\": null\n"+
" },\n"+
" \"type\": \"NUMERIC\"\n"+
" },\n"+
" {\n"+
" \"type\": \"COMPLEX\",\n"+
" \"operation\": \"AND\",\n"+
" \"predicates\": [\n"+
" {\n"+
" \"operation\": \"GREATER\",\n"+
" \"value\": {\n"+
" \"defaultValue\": 50,\n"+
" \"dynamicValue\": null\n"+
" },\n"+
" \"type\": \"NUMERIC\"\n"+
" },\n"+
" {\n"+
" \"operation\": \"LESS\",\n"+
" \"value\": {\n"+
" \"defaultValue\": 60,\n"+
" \"dynamicValue\": null\n"+
" },\n"+
" \"type\": \"NUMERIC\"\n"+
" }\n"+
" ]\n"+
" }\n"+
" ]\n"+
"}"+
MARKDOWN_CODE_BLOCK_END+
"\n\n YOu may also want to replace hardcoded values (for example, temperature > 20) with the more dynamic "+
"expression (for example, temperature > 'value of the tenant attribute with key 'temperatureThreshold'). "+
"It is possible to use 'dynamicValue' to define attribute of the tenant, customer or user that is performing the API call. "+
"\n\n Note that you may use 'CURRENT_USER', 'CURRENT_CUSTOMER' and 'CURRENT_TENANT' as a 'sourceType'. The 'defaultValue' is used when the attribute with such a name is not defined for the chosen source.";
privatestaticfinalStringKEY_FILTERS=
"\n\n # Key Filters"+
"\nKey Filter allows you to define complex logical expressions over entity field, attribute or latest time-series value. The filter is defined using 'key', 'valueType' and 'predicate' objects. "+
"Single Entity Query may have zero, one or multiple predicates. If multiple filters are defined, they are evaluated using logical 'AND'. "+
"The example below checks that temperature of the entity is above 20 degrees:"+
"\n\n"+MARKDOWN_CODE_BLOCK_START+
"{\n"+
" \"key\": {\n"+
" \"type\": \"TIME_SERIES\",\n"+
" \"key\": \"temperature\"\n"+
" },\n"+
" \"valueType\": \"NUMERIC\",\n"+
" \"predicate\": {\n"+
" \"operation\": \"GREATER\",\n"+
" \"value\": {\n"+
" \"defaultValue\": 20,\n"+
" \"dynamicValue\": null\n"+
" },\n"+
" \"type\": \"NUMERIC\"\n"+
" }\n"+
"}"+
MARKDOWN_CODE_BLOCK_END+
"\n\n Now let's review 'key', 'valueType' and 'predicate' objects in detail."
"For example, \"temperature > 20 or temperature< 10\" or \"name starts with 'T', and attribute 'model' is 'T1000', and timeseries field 'batteryLevel' > 40\"."+
"\n\nLet's review the example:"+
"\n\n"+MARKDOWN_CODE_BLOCK_START+
"{\n"+
" \"entityFilter\": {\n"+
" \"type\": \"entityType\",\n"+
" \"entityType\": \"DEVICE\"\n"+
" },\n"+
" \"keyFilters\": [\n"+
" {\n"+
" \"key\": {\n"+
" \"type\": \"ATTRIBUTE\",\n"+
" \"key\": \"active\"\n"+
" },\n"+
" \"valueType\": \"BOOLEAN\",\n"+
" \"predicate\": {\n"+
" \"operation\": \"EQUAL\",\n"+
" \"value\": {\n"+
" \"defaultValue\": true,\n"+
" \"dynamicValue\": null\n"+
" },\n"+
" \"type\": \"BOOLEAN\"\n"+
" }\n"+
" }\n"+
" ]\n"+
"}"+
MARKDOWN_CODE_BLOCK_END+
"\n\n Example mentioned above search all devices which have attribute 'active' set to 'true'. Now let's review available entity filters and key filters syntax:"+
"For example, \"temperature > 20 or temperature< 10\" or \"name starts with 'T', and attribute 'model' is 'T1000', and timeseries field 'batteryLevel' > 40\"."+
"\n\nThe **entity fields** and **latest values** contains list of entity fields and latest attribute/telemetry fields to fetch for each entity."+
"\n\nThe **page link** contains information about the page to fetch and the sort ordering."+
"\n\n Example mentioned above search all devices which have attribute 'active' set to 'true'. Now let's review available entity filters and key filters syntax:"+
ENTITY_FILTERS+
KEY_FILTERS+
TENANT_AND_USER_AUTHORITY_PARAGRAPH;
privatestaticfinalStringALARM_DATA_QUERY_DESCRIPTION="This method description defines how Alarm Data Query extends the Entity Data Query. "+
"See method 'Find Entity Data by Query' first to get the info about 'Entity Data Query'."+
"\n\n The platform will first search the entities that match the entity and key filters. Then, the platform will use 'Alarm Page Link' to filter the alarms related to those entities. "+
"Finally, platform fetch the properties of alarm that are defined in the **'alarmFields'** and combine them with the other entity, attribute and latest time-series fields to return the result. "+
"\n\n See example of the alarm query below. The query will search first 100 active alarms with type 'Temperature Alarm' or 'Fire Alarm' for any device with current temperature > 0. "+
"The query will return combination of the entity fields: name of the device, device model and latest temperature reading and alarms fields: createdTime, type, severity and status: "+
@ -83,12 +729,18 @@ public class EntityQueryController extends BaseController {
}
}
@ApiOperation(value="Find Entity Keys by Query",
notes="Uses entity data query (see 'Find Entity Data by Query') to find first 100 entities. Then fetch and return all unique time-series and/or attribute keys. Used mostly for UI hints.")
Andrii Shvaika
5 years ago