Queries
Query folder
The Queries folder of a JSON schema stores queries whose results are available to be used in the schema. This allows JSON content to be generated from the results of bql or neql queries. For example, to name just a few, you can generate a report of overridden points, active alarms, or history logs for a given point.
Query Interval is an important property of the queries folder. It determines how often queries execute, and, therefore, how up-to-date any
data exported by the schema will be when an update strategy of CoV is used.
NOTE: If multiple queries exist, the station runs each query in parallel each time the schema executes.
Queries do not execute each time a schema generates in change-of-value mode, otherwise a query could run every time a point value changes, which could have a negative impact on the performance of the control strategy running in a station. Instead, a BoundQueryResult caches the results and adds them to the schema.
Schemata in on-demand mode and relative schemata do execute each query every time a schema generates.
It is possible to manually invoke query execution using the Execute Queries action of the schema, which could also be linked to some appropriate logic to trigger execution when needed.
IMPORTANT: When executing queries against your station, bear in mind the potential performance implications of running queries frequently. To reduce the scope of the query, focus the first part of the ord to the location where the data are likely to be found, or by using the stop keyword to prevent depth recursion.
Query
You add queries below the Queries folder found at the top level of the schema.
Figure 16. Query properties
A query can be any valid transform, neql or bql statement which returns a BITable.
Here are some useful examples to include in a schema:
| Data to return | Query |
|---|---|
| BACnet points currently in {override} status | slot:/Drivers/BacnetNetwork|bql:select name, out.value from control:ControlPoint where status.overridden = 'true' |
| History records | history:/Newhaven/waveHeight|bql:select timestamp, value |
| Output from a series transform | station:|transform:slot:/VelocityServlet/lineChart/TransformGraph |
| Alarm database contents | alarm:|bql:select timestamp, uuid, ackState, source as 'origin'NOTE: You may rename the columns using the ‘as’ keyword, which the resultant JSON reflects. |
Relative history query
Used in conjunction with a relative schema, the query Pattern Property pre–appends the current base item to a bql query, so that query data can be included in the payload for a given set of points
or devices:
%baseHistoryOrd%?period=today|bql:select timestamp, valueYou may use this in conjunction with a base query that returns a HistoryConfig or a HistoryExt (or the parent of these types):
station:|slot:/JsonExampleComponents|bql:select * from history:HistoryConfigConsider the effect on performance that running many queries on an embedded controller may have.
BoundQueryResult
Once you define a query, use the BoundQueryResult to determine where and how to insert the results into the payload.
You can mix query results, such as bound properties or other query results with all other schema member types in the same payload. For example, if required by the target platform, you could construct a floor summary with historical data and current alarms.
The JSON Toolkit provides various output formats as the following examples demonstrate, and a developer can create new output formats.
The following examples use two columns for the sake of brevity. You may add more columns.
You can format the timestamp returned by a query using the format options in the schema’s Config folder.
REMEMBER:
| Example | JSON |
|---|---|
| Row array with header | "data": [
[
"timestamp", "value"
], [
"2019-02-07 23:27:42.116+0000",
45
], [
"2019-02-07 23:28:03.157+0000",
15
], [
"2019-02-07 23:28:24.197+0000",
85
], [
"2019-02-07 23:28:45.222+0000",
55
], [
"2019-02-07 23:29:06.247+0000",
25
]
]
|
| Row array | "data": [
[
"2019-02-07 23:27:42.116+0000",
45
], [
"2019-02-07 23:28:03.157+0000",
15
], [
"2019-02-07 23:28:24.197+0000",
85
], [
"2019-02-07 23:28:45.222+0000",
55
], [
"2019-02-07 23:29:06.247+0000",
25
]
]
|
| Objects array | "data": [
{
"timestamp": "2019-02-07 23:27:42.116+0000",
"value": 45
},
{
"timestamp": "2019-02-07 23:28:03.157+0000",
"value": 15
},
{
"timestamp": "2019-02-07 23:28:24.197+0000",
"value": 85
},
{
"timestamp": "2019-02-07 23:28:45.222+0000",
"value": 55
},
{
"timestamp": "2019-02-07 23:29:06.247+0000",
"value": 25
}
]
|
| Named objects (The first column is assumed to represent the object name.) | "data": [
"2019-02-07 23:27:42.116+0000": {
"value": 45
},
"2019-02-07 23:28:03.157+0000": {
"value": 15
},
"2019-02-07 23:28:24.197+0000": {
"value": 85
},
"2019-02-07 23:28:45.222+0000": {
"value": 55
},
"2019-02-07 23:29:06.247+0000": {
"value": 25
}
]
|
| Column array with header | "data": [
[
"timestamp",
"2019-02-07 23:27:42.116+0000",
"2019-02-07 23:28:03.157+0000",
"2019-02-07 23:28:24.197+0000",
"2019-02-07 23:28:45.222+0000",
"2019-02-07 23:29:06.247+0000"
], [
"value", 45,
15,
85,
55,
25
]
]
|
| Column array | "data": [
[
"2019-02-07 23:27:42.116+0000",
"2019-02-07 23:28:03.157+0000",
"2019-02-07 23:28:24.197+0000",
"2019-02-07 23:28:45.222+0000",
"2019-02-07 23:29:06.247+0000"
], [
45,
15,
85,
55,
25
]
]
|
| Single column array
NOTE: The query used to populate the BoundQueryResult should only return one column. It would be wasteful to select data that are not expected to emerge in the payload. |
"data": [
45,
15,
85,
55,
25
]
|
| Key Value Pair Object
NOTE: The query used to populate the BoundQueryResult should only return two columns. |
“data”: {
"2019-02-07 23:27:42.116+0000" : 45,
"2019-02-07 23:28:03.157+0000" : 15,
"2019-02-07 23:28:24.197+0000" : 85,
"2019-02-07 23:28:45.222+0000" : 55,
"2019-02-07 23:29:06.247+0000" : 25
} |
| Tuning |
You may use the hidden query folder property |