Tags and Queries

Overview

Tag queries are a powerful tool to help you find entities in your system according to specific criteria.

Creating Tags

Tags can be added to Data sources, Devices and Points.

In addition to system defined tags, such as "curVal" (Current Value) and "dis" (Display Name), you can add any custom tags you like by clicking on a Config tree node and selecting the tags tab.

In addition to simple "Marker" tags, that purely aid in identifying nodes. The following is a list of all types of tags that are currently supported:

  • Marker: the tag is merely a marker annotation and has no meaningful value. Marker tags are used to indicate a "type" or "is-a" relationship.
  • Reference: reference to another entity. Reference tag is for defining relationships and being able to access the referenced nodes tags during query time.
  • String: a string of Unicode characters.
  • Number: integer or floating point number annotated with an optional unit of measurement.
  • Boolean: boolean "true" or "false".
  • Lat/Long: geographic coordinate in latitude/longitude
  • URI: a Universal Resource Identifier

To add tags to a set of points or devices, multi-select Config tree nodes and manage the tags for the selection.

Testing Queries

After adding the appropriate tags to the system, click the "Query" icon in the toolbar to test out your tags in the console.

Using Queries in DGLux

To use the Queries in DGLux Dashboards:

  1. Add a "Table" Dynamic Property
  2. Click the "Add" button in the table and select "Query"
  3. In the "DB Connection" list, choose "tags"
  4. Type in or bind a string into the "Query" field
  5. Bind the results of the query to Widgets or Charts

Query Examples

To find all points:

point

To find all points and schedules:

point or schedule

To find all points in device 'MyDevice':

point and deviceRef->dis=="MyDevice"

To find all points with a present value greater than 10:

point and curVal > 10

To find all points in the system that are BACnetIP:

point and dataSourceRef->dataSourceType == "BACnetIP"

To find all points with a name "like" AI and present value greater than 10:

point and dis ~ "%AI%" and curVal > 10

*Please note that the difference between the textual like operators, is that "~" is case-sensitive and "~~" is case-insensitive.

To find all the active events and alarms in the system:

event and active

Query Syntax

<filter>      :=  <condOr>
<condOr>      :=  <condAnd> ("or" <condAnd>)*
<condAnd>     :=  <term> ("and" <term>)*
<term>        :=  <parens> | <has> | <missing> | <cmp>
<parens>      :=  "(" <filter> ")"
<has>         :=  <path>
<missing>     :=  "not" <path>
<cmp>         :=  <path> <cmpOp> <val>
<cmpOp>       :=  "=" | "!=" | "<" | "<=" | ">" | ">=" | "~" | "~~"
<path>        :=  <name> ("->" <name>)*
<name>        :=  <alphaLo> (<alpha> | <digit> | "_")*
<val>         :=  <bool> | <ref> | <str> | <uri> | <decimal> | <date> | <time>
<bool>        := "true" or "false"
<ref>         := "@" <refChar>* [ " " <str> ]
<str>         := """ <strChar>* """
<uri>         := "`" <uriChar>* "`"
<decimal>     := ["-"] <digits> ["." <digits>] [<exp>] [<unit>]
<date>        := YYYY-MM-DD
<time>        := hh:mm:ss.FFFFFFFFF
<refChar>     := <alpha> | <digit> | "_" | ":" | "-" | "." | "~"
<strChar>     := <unicodeChar> | <strEscChar>
<uriChar>     := <unicodeChar> | <uriEscChar>
<digits>      := <digit> (<digit> | "_")*
<digit>       := ('0' - '9')
<exp>         := ("e"|"E") ["+"|"-"] <digits>
<unit>        := <unitChar>*
<alpha>       := <alphaLo> | <alphaHi>
<unicodeChar> := any 16-bit Unicode char >= 0x20 (except str/uri quote)
<strEscChar>  := "\b" | "\f" | "\n" | "\r" | "\t" | "\"" | "\\" | "\$" | <uEscChar>
<uriEscChar>  := "\:" | "\/" | "\?" | "\#" | "\[" | "\]" | "\@" | "\\" | "\&" | "\=" | "\;" | <uEscChar>
<unitChar>    := <alpha> | "%" | "_" | "/" | "$" | any char > 128
<alphaLo>     := ('a' - 'z')
<alphaHi>     := ('A' - 'Z')
<uEscChar>    := "\u" <hexDigit> <hexDigit> <hexDigit> <hexDigit>
<hexDigit>    := ('a'-'f') | ('A'-'F') | <digit>