NEQL query examples

The Niagara Entity Query Language (NEQL) provides a mechanism for querying tagged entities in Niagara applications. This topic provides grammar and syntax examples to help you construct these queries.

Note that NEQL only queries for tags. NEQL supports traversing defined entity relationships as well as parameterized queries and allows you to use the same syntax for queries in hierarchy level definitions as is used in Search queries.

In addition to using NEQL queries in a hierarchy definition or search, you might use these queries for testing purposes, say to find devices or points in a station. For example, to find all devices in a station enter the query: neql:n:device. Or using the absolute ORD form in Workbench, press CTRL+L to open the ORD dialog and enter the following:

ip:<host>|foxs:|station:|slot:/|neql:n:device

NOTE: In Niagara 4.6 and later, the “sys:” ORD scheme can be used to redirect NEQL queries to resolve against the System Database. For example, the following query searches for all devices known to the System Database:

ip:<host>|foxs:|sys:|neql:n:device

In Niagara 4.4 and later, NEQL queries can be resolved over FOX. Additionally, NEQL results support tables so the results can be displayed in collection tables, reports, Px pages, etc. NEQL can be used in the following cases:

used on a table on a Px page
resolved from the ORD Field Editor
resolved from the browser/path bar when typed in an Hx Profile
used to generate reports

Finally, NEQL and BQL can be used together (although not supported in Search). You can append a BQL query to the end of a NEQL query for additional processing. Do this in any of the cases listed above. The following example shows a BQL select query appended to a NEQL query.

ip:<host>|foxs:|station:|slot:/|neql:n:device|bql:select toDisplayPathString, status

The above query first finds all devices using the NEQL statement, and then the BQL statement processes against the devices returned from the NEQL query, displaying a two–column table with the display path of the devices shown in one column and the status of the devices shown in the other.

CAUTION: Appending a BQL query to the end of a NEQL query can be a costly operation in terms of processing time. You could experience processing delays when using such queries.

Query examples

The following examples are designed to help you construct queries.

To query for	Syntax example	Returns result
point tag	n:point	Any entity with the point tag (in the “n” namespace)
name tag = "foo"	n:name = "foo"	Any entity with the “foo” name tag (in the “n” namespace)
type tag = "baja:Folder"	n:type = "baja:Folder"	Any entity with the ”baja:Folder” type tag (in the “n” namespace)
points that are NumericWritables with hs:coolingCapacity > 4.03	type = "control:NumericWritable" and hs:coolingCapacity > 4.03	Any entity with the “control:NumericWritable” type tag (in the “n” namespace) and the coolingCapacity tag (in the “hs” namespace) with a value greater than 4.03
everything	true	All entities
entities with names containing “Switch”	n:name like “.Switch.”	Any entity with a name that contains "Switch" case-sensitive
entities with geoCity tag with value not equal to Atlanta	n:geoCity != "Atlanta"	Any entity with the geoCity tag (in the n namespace) with a value that is not Atlanta
where n:pxView is a relation	n:pxView->n:type	Any entity with a pxView relation where the endpoint is a niagara type. This is all the entities that have px views.
entities with t:foo but not t:herp	t:foo and not t:herp	Any entity with the foo tag (in the t namespace) that does not also have the herp tag (in the t namespace).
points that were built earlier than 2015 or whose primary function is backup	hs:yearBuilt < 2015 or hs:primaryFunction = “backup”	Any entity with either the yearBuilt tag (in the hs namespace) with value less than 2015 or the primaryFunction tag (in the hs namespace) with value "backup"
child entities of entities with the floor tag = 2	n:parent->hs:floor = 2	Any entity whose parent has the floor tag (in the hs namespace) with value 2

NOTE: Do not create a namespace for a tag dictionary if that namespace is already used for an existing ORD scheme (NEQL or BQL). Since the search service allows for different types of searches (e.g., neql and bql), user must validate the search text and make sure they are not trying to enter an invalid ORD. Precede the query search with "neql:" to specify that it should run a neql query explicitly For Example: “neql:h:test”.

NEQL grammar

The following list is the subset of the NEQL grammar that you can use to build NEQL queries for the “Query” portion of Query Level Defs and the “Filter Expression” portion of Relation Level Defs in Hierarchies. For a more comprehensive overview of NEQL and the complete grammar and examples, refer to NEQL documentation in the Niagara Developer Guide.

<statement> := <full select> | <filter select> | <traverse>

<full select> := select <tag list> where <predicate>

<filter select> := <predicate>

<traverse> := traverse <relation> (where <predicate)

<tag list> := <tag> (, <tag>)*

<tag> := (<namespace>:)<key>

<relation> := (<namespace>:)<key><direction>

<namespace> := <word>

<key> := <word>

<direction> := -> | <-

<predicate> := <condOr>

<condOr> := <condAnd> (or <condAnd>)*

<condAnd> := <term> (and <term>)*

<term> := <cmp> | <tagPath> | <not>

<cmp> := <comparable> <cmpOp> <comparable> | <like>

<like> := <tagPath> like <regex>

<cmpOp> := = | != | < | <= | > | >=

<comparable> := <val> | <tagPath>

<val> := <number> | <bool> | <str>

<tagPath> := (<relation>)*<tag>

<not> := not <negatable> | !<negatable>

<negatable> := (<predicate>) | <tag> // note: parens around <predicate> signify actual paren characters, NOT optional syntax

<number> := <int> | <double>

<bool> := true | false

<str> := "<chars>"

<typeSpec> := <moduleName>:<typeName>

<moduleName> := <word>

<typeName> := <word>

<word> := <chars>

<regex> := "<chars>" // note: some regex edge cases not supported