BQL

How a BQL Query Actually Resolves

A BQL query is never evaluated on its own. It is the last segment of an ORD chain, and everything to its left decides what the query is able to see. In station:|slot:/Drivers/BacnetNetwork|bql:select name, out.value from control:NumericPoint, the bql: segment inherits the BacnetNetwork component as its starting object and cannot reach anything outside that branch, no matter what the where clause says.

The engine walks the tree beneath that starting object and evaluates the where clause on each component after it has been reached. Cost therefore tracks components enumerated, not components matched: a filter that returns four rows costs the same as one returning four thousand when both start from the same place. That is also why a query which was quick during engineering can be slow in production without a single character changing. The count of components under the base ORD grew; the query did not.

History queries resolve through a different space and behave differently again. A history ORD names one point's record set rather than a branch of the live tree, so the size of the tree is irrelevant and the record count inside each history governs the time. A report covering two hundred points is two hundred resolutions unless the history space itself is queried first for the set.

Which scheme precedes the bql: segment therefore matters as much as the query text, because each one resolves against a different space with a different cost. These are the ones that turn up in front of a bql: segment most often:

• slot: the ordinary slot path through the live component space, either absolute from the station root or relative to whatever resolved before it.
• h: resolves a component by its persistent handle instead of its path. The handle survives a rename or a move that would break a slot path, at the price of an ORD no human can read and one that means nothing in any other station.
• history: the history space rather than the component space. Aimed at a single history it returns records; aimed at the space itself it returns the histories, which is how you find out what actually exists to report on.
• virtual: the virtual component space, where components are created on demand by a driver instead of being stored in the station. Queries here can force the driver to instantiate and fetch, so the cost includes network round trips to field devices, not just processor time.
• neql: Niagara Entity Query Language, Niagara 4 only, which selects by tag and relation rather than by path or type. It is often the more durable half of a query that then hands its result to bql:.

Where the Query Runs, and Under Whose Rights

On a Niagara network, reporting queries normally belong on the Supervisor, because that is where history import descriptors have already archived the subordinate stations' records. A controller keeps only what its own capacity retains before rollover, so asking a JACE for last spring returns whatever survived rather than an error, and the report looks complete while covering a shorter period than it claims.

Running the same query on the controller also places it on the processor that is executing control logic. A large history query there competes with the engine cycle, and operators notice it as sluggish graphics and writes that take a moment to land. Because reports are scheduled, this arrives at the same hour every day, which makes it easy to blame on whatever else happens at that hour.

BQL reads and does nothing else. There is no update, insert or delete, so a scheduled report is not a route by which control state can drift, and the account behind it needs read rights and nothing more. The consequence in the other direction is easy to miss: results are filtered by that account's permissions, so a report running under a restricted user returns fewer rows rather than a permission error. Totals come back low with nothing on screen to say why.

What the Histories Have to Look Like Before the Numbers Mean Anything

Collection mode decides what an average means. An interval history writes on a fixed period, so records are evenly spaced and a plain average over them is a time-weighted average. A change-of-value history writes only when the value moves past a tolerance, so a point sitting still for six hours contributes one record while a hunting point contributes hundreds, and averaging those records weights the answer by how often the value moved. The same query run over the two collection types is answering two different questions.

Records also carry status, and status is invisible in a total. Fault, down, stale and null records sit alongside good ones, and a query that selects value without filtering on status folds them in. The failure is asymmetric: an outage leaves a gap, which drags a sum down by exactly the missing quantity while leaving an average looking entirely normal. So totals expose the problem and averages conceal it. Filter on status, then count what was excluded, because a report that quietly discarded a third of its records is describing the instrumentation rather than the building.

Timestamps carry a zone and a calendar. Records are stamped in the station's local time, so a Supervisor sitting in another zone and bucketing by day is grouping around a boundary that is not the site's midnight. Two days a year also hold 23 and 25 hours, so a daily total compared against the same date last year is comparing unequal periods. The error is small enough to read as noise and consistent enough to survive into a trend line.

Capacity has to cover the reporting period before the first report is written rather than after. A history extension configured to keep a fixed record count rolls the oldest records off without complaint: 5000 records at a fifteen minute interval is about 52 days, which satisfies a monthly report and quietly fails a quarterly one by returning a short period instead of an error.

Version Differences That Do Not Announce Themselves

The from clause names a Niagara type as module:Type, and both halves of that name are version specific. Modules were reorganized between NiagaraAX and Niagara 4, and some types moved or were renamed in the process, so a query carried across the migration can name a type the running version does not have. It does not raise an error. An unmatched type matches nothing and the query returns an empty table, which at a glance is indistinguishable from a building where nothing met the criteria.

The test that separates those two cases takes a minute. Widen the from clause to baja:Component, leave the base ORD alone, and count rows. Rows mean the scope is fine and the type name is wrong; no rows mean the base ORD is not resolving where you think it is. Run that before rebuilding anything, and check the finished query against figures somebody already knows to be correct.

In a mixed network the semantics follow where the query executes, not where the data originally came from. Histories imported onto a Niagara 4 Supervisor from an older station are Niagara 4 histories once they land, and queries over them run under Niagara 4 rules. A query resolved through the Niagara network to the older station itself executes there, under that station's syntax and type names. One report can therefore need two versions of a query, and the version that gets tested is usually the local one.

Where BQL Stops Being the Right Instrument

BQL queries one station's spaces. A question spanning several stations with no Supervisor between them has no single tree to resolve against, and the honest structure is to answer it per station and combine the results outside Niagara rather than to write a query that pretends the stations are one system.

The distinction that matters for integration is direction, not schedule. A scheduled export is BQL work: the station runs the query on its own clock, once, and pushes the result out to a file, a database, or a business system. What BQL is a poor instrument for is the reverse, an external system polling the station for current values on its own schedule, because every poll re-resolves the ORD and re-walks the tree from scratch, and several clients polling every few seconds multiply that cost with nothing shared between them. Exposing the points through an interface such as oBIX, where a client registers interest in specific objects and reads them back by address, costs the station far less for the same data.

Long-horizon analysis is the other boundary. Once the question spans several years and many buildings, and has to be set against data the station does not hold at all, such as weather, occupancy or utility billing, the station is the wrong place to keep asking. Export the histories into a relational database on a schedule and let the analysis run there. BQL's job in that arrangement is the export.