BRIQL Query Language

BRIQL API overview

BRIQL is a protocol used for querying semantic models, to extract building information that is useful to applications. BRIQL provides a domain-specific query syntax, and returns data in a JSON structure that is readily useful to client applications. 'Under the hood', the BRIQL API is performing SPARQL queries to extract information. This means that it is producing solutions by matching variables to model entities, and associating and/or constraining variables by the topology of nodes inside models.

When BRIQL queries are executed, the following events occur:

  • Client software sends a BRIQL invocation to DCH endpoint.

  • Access to models mentioned in the BRIQL invocation is verified.

  • BRIQL invocation translated into SPARQL 1.1 query.

  • SPARQL is executed in graph database.

  • SPARQL solution is translated to a BRIQL solution.

  • BRIQL solution is returned to the client software.

BRIQL queries may be either:

  • a "select" query, with arbitrary matching logic over one or more models.

  • a "describe" query, which will provide detailed information about a single node of a single model.

The response payload for select queries differ to responses for describe queries.

BRIQL-to-SPARQL translation

This table briefly summarises relationship between BRIQL and SPARQL concepts. It may be useful to developers who are already familiar with SPARQL and RDF.

BRIQL Concept
SPARQL Concept
BRIQL-SPARQL Translation Notes

block

Parameters on a block determine the type of Graph Pattern in SPARQL.

model

Models specified in an invocation are transparently translated to a list of graphs to set the SPARQL query's ensemble 'default graph' (the Brick schema is implicitly included).

NodeVar

For each BRIQL variable (a NodeVar), requested properties are mapped to SPARQL variables.

output

NodeVars with "output"="true" will be included in the SELECT projection.

REST endpoint

The DCH endpoint URL for BRIQL queries is https://dataclearinghouse.org/api/mv/v1/query/briql

Optionally, the URL query parameter ?return_sparql=true can be added. This can be useful during development to determine precisely what a BRIQL invocation is doing.

BRIQL Request Classes

QueryInvocation

This class is the request payload submitted to the BRIQL endpoint.

Field
Type
Meaning

queryDef

Query (nullable)

If set, this specifies a Query to be run. The query is implicitly a "select" query. This is mutually exclusive with both 'queryRef' and 'describe'.

describe

NodeReference (nullable)

If set, the invocation's response will fully describe this node. The query is implicitly a "describe" query. This is mutually exclusive with both 'queryRef' and 'queryDef'.

models

List of ModelReference

List of ModelReferences against which the query is to be run. This determines the models over which the Query in queryDef will execute.

limitNodeRefs

Map (nullable) Keys: string Values: NodeReference

Keys of this map refer to BRIQL variable names in the query. If used, values will be injected into the composed SPARQL query, in the form VALUES (?varname) { (uri1) (uri2) etc}, to fo

Query

Field
Type
Meaning

ref

string (nullable)

(Ignored in DCH2)

comment

string (nullable)

Optional string to describe query’s purpose

variables

List of QueryVar

In select mode: list of variables used in the query Block.

query

Block

In select mode: the outermost block of the SPARQL SELECT query to be matched. When composed into SPARQL, triples and graph patterns derived from this block will follow triples derived from the query variables.

NodeReference

Field
Type
Meaning

modelRef

ModelReference

Reference to a model (site or building) which contains the node.

nodeId

String (nullable)

If null: the NodeReference represents the model itself. Otherwise, the NodeReference represents the identified node within the model.

ModelReference

Field
Type
Meaning

orgId

string

ID of the organisation to which the model belongs

siteId

string (nullable)

Site models: ID of the site Building models: ID of the site to which the building belongs

buildingId

string (nullable)

Building models only: ID of the building; unique within the site.

dataPoolId

String (nullable)

Data pool models only: ID of the data pool.

NodeVar

Field
Type
Meaning

name

string

Name of the variable. Unlike SPARQL, do not prefix with '$' or '?'.

comment

string (nullable)

Optional comment about variable’s purpose

output

boolean (nullable)

If set and true, this variable will be included in solutions.

nullable

boolean (nullable)

If set and true, then SPARQL generated for this NodeVar will be composed with OPTIONAL{...}, and solutions to the BRIQL query may be emitted with a 'null' in this variable's position.

constraints

Block (nullable)

If set, apply this Block's triples as constraints on this QueryVar. This is necessary for nullable NodeVars (where all triples should be gathered in a single optional block / graph pattern), and a convenience for non-nullable NodeVars.

nested

List of NodeVar

Useful primarily for nullable (optional) variables: If set and non-empty, these QueryVars will have matching triples materialised inside the optional matching block of the enclosing variable. In other words, if variable X is nullable, and variable Y will only exist if X exists, then nest Y in X.

fetch

List of VarFields (nullable)

list of fields to fetch and return in results (if null/empty, default is just [id]). Required if 'output' is 'true'. If this list contains 'pointinfo', then 'fetchPoints' must be non-null and non-empty.

orgId

string (nullable)

If these fields are set in a query or invocation, compose a node URI to be bound to the variable.

siteId

string

buildingId

string (nullable)

nodeId

string (nullable)

brickTypes

List of MatchType (nullable)

If set, all non-null solutions for this NodeVar must match at least one of the listed MatchTypes.

nodeProperty

List of QueryEntityProperty (nullable)

If set, require that matched solution nodes will have all of these properties.

fetchPoints

List of MatchType (nullable)

If set, only return associated points that match at least one of the listed MatchTypes. This field is required to be set if the fetch field includes pointinfo.

filterOn

list of VarFields (nullable)

If set and filterString is set, then the filter string is applied to these fields.

filterString

string (nullable)

If set and filterOn is set, then fields listed in 'filterOn' will be filtered to require this string is present.

orderHint

List of NodeVarField

If set, this determines the order of triples in SPARQL emitted for this NodeVar. Values may be: "brickTypes", "nodeProperty," and/or "fetchPoints" (listed here in default order). One, two or all three may be specified. Any absent values will be assumed to follow specified values, in their default order. Any repetition of a previously given value is silently discarded.

The default ordering means that triples relating to 'brickTypes' for the node will be emitted first, followed by entity property related triples, followed by point matching triples.

Use of a different ordering may improve performance. For example, if it can be assumed that (in most models) the node's type is very common but the node's associated point types of interest are very rare, then matching "fetchPoint" before "brickTypes" will generally be faster.

QueryEntityProperty

Exactly one of 'property' or 'key' fields must be set.

Exactly one 'val' field (intval, numval, strval, urival, boolval) must be set.

Field
Type
Meaning

property

Prefixed or IRI term (nullable)

The brick property. Most commonly this will be a prefix-form URI. JSON examples of prefixed and IRI forms are, respectively:

  • {"prefixed":"brick:hasPart"}

  • {"iri":"https://brickschema.org/schema/Brick#hasPart"}

key

string (nullable)

intval

integer (nullable)

An integer value to be matched for this property.

numval

double (nullable)

A numeric value to be matchedfor this property.

strval

string (nullable)

A string value to be matched for this property.

urival

string (nullable)

A URI value to be matched for this property.

boolval

boolean (nullable)

A boolean value to be matched for this property.

unit

Prefixed or IRI term (nullable)

A QUDT unit to be matched for this property. e.g.:

  • {"prefixed":"unit:M2"}

  • {"iri":"http://qudt.org/vocab/unit/M2"}

VarFields

VarFields is an enumeration, represented in JSON with a string equal to one of the following. Members are case sensitive.

String value
Meaning

id

The ID of the node

type

The Brick type of the node

hypernym

The hypernym of the node’s type (I.e. Location, Equipment, Zone or Point)

pointInfo

The IDs and streams IDs of points attached to the node

streams

Streams IDs of points attached to the node

label

The label of the node

entityProperty

The entity property(ies) of the node

unit

The unit(s) of the node.

MatchType

MatchType determines how NodeVars are matched.

Field
Type
Meaning

match

Match (nullable)

Specify the kind of match to perform on type field:

  • isa (match this Brick type or its child types or equivalent types) [e.g. AHU and Air_Handler_Unit]

  • equals (match this Brick type exactly)

  • parent (match only child types of this type)

  • hypernym (match this hypernym)

  • equalsOrEquivalent (match this Brick type and its aliases)

type

string (nullable)

Match this Brick type. Requires match is 'equals', 'hypernym', 'isa', or 'parent'. Mutually exclusive with tags. This field expects only the fragment component of the type’s URI without prefix or delimeters (eg “Room”, not “brick:Room”).

tags

List of string (nullable)

If set and match is “tags”, match any Brick type which has all of these tags

hasAllProperties

List of QueryEntityProperty (nullable)

If set and not empty, the matched node must fit all of these entity properties (in addition to matching by tag or class)

Match

Match is an enumeration, represented in JSON with a string equal to one of the following case-sensitive values.

Read this section in conjunction with the definitions of

String value
Meaning
In MatchType, use in conjunction with...

isa

Match model nodes which have a type that matches the nominated type, ether:

  • exactly,

  • as direct/indirect (transitive) sub-classes of the nominated type, or

  • as types which are 'equivalent'.

For example:

  • if type is 'AHU', also find nodes of type 'Air_Handling_Unit' and 'Air_Handler_Unit', which are equivalent types in Brick Schema.

  • If type is 'Equipment', also find nodes of type 'AHU', since 'AHU' is an transitive subclass of 'Equipment' in Brick Schema.

SPARQL property path: rdf:type/(rdfs:subClassOf|owl:equivalentClass)*

type

equals

Match model nodes that have the nominated Brick type exactly (regardless of owl:equivalentClass).

SPARQL property path: rdf:type

type

parent

Nominated type is the 'parent' type; match only model nodes that have a type that is a child classes of the parent type.

For example:

  • If type is 'Room', then nodes of a more specialised type like 'Workshop' would be found, but not nodes of type 'Room'.

SPARQL property path: rdf:type/rdfs:subClassOf+

type

hypernym

For use where the type is one of the top-level hypernym types (Location, Point, Equipment, Zone), with simpler internal SPARQL.

SPARQL property path: rdf:type/brick:hyponymOf+

type

equalsOrEquivalent

Streams IDs of points attached to the node

SPARQL property path: rdf:type/owl:equivalentClass?

type

tags

Match nodes which have a type that is tagged with all of the nominated tags.

tags

Block

At run time, queries attempt to find solutions that match a nested structure of query elements. The fundamental unit of a BRIQL query is the Block. Each block contains zero or more paths, and zero or more nested blocks. Internally, these are translated to SPARQL graph patterns at query run time. Paths are converted to triples patterns first (in specified order), followed by conversion of blocks (again, in specified order).

Field
Type
Meaning

comment

string

Comment about block’s purpose.

paths

List of PropertyPath (nullable)

If set, these all of these paths must all be matched. These paths will act as constraints on variables.

nested

List of Block (nullable)

If set, nest these Blocks inside this Block.

logic

string (nullable)

Either 'and' (assumed by default) or 'or', indicating the matching logic to be applied to the elements enclosed by this block (all match, or any match respectively). When translated to SPARQL, blocks with "logic"="or" will have their internal triples composed as a series of UNION graph patterns.

optional

boolean (nullable)

If set and true, this block’s constraints are matched optionally. Defaults to false. This allows matching without eliminating un-matched subgraphs from the query's solution.

types

List of NodeVariableTypeConstraint

If set, apply these type matches to the named variables, inside this Block's context (rather than in the variable's definition).

retain

string ("present", "absent")

If set, this block removes bindings from the solution set.

  • 'present' is equivalent to SPARQL's FILTER EXISTS{...} form.

  • 'absent' is equivalent to SPARQL's FILTER NOT EXISTS{...} form.

See https://www.w3.org/TR/sparql11-query/#neg-notexists-minus

NodeVariableTypeConstraint

Used in 'types' list in Block instances to constrain a variable's type, in that Block's context.

Field
Type
Meaning

name

string

Variable name

brickTypes

List of MatchType

The named variable must match at least one of these MatchTypes.

PropertyPath

A property path expresses a chain of edges between one model node and another. A property path matches one subject node, one or more predicates (properties), and an object node.

Field
Type
Meaning

fromRef

string

The SPARQL subject node (value must be the name of a variable in the query definition)

properties

Non-empty list of Property

One or more Property, representing the chain of predicates between subject node and object node.

toRef

string

The SPARQL object node (value must be the name of a variable in the query definition).

Property

Field
Type
Meaning

property

string (nullable)

If set, this Property is the named Brick property (mutually exclusive with the variable and or field)

variable

string (nullable)

If set, this Property is the named variable (mutually exclusive with the property and or field)

or

List of Property (nullable)

If set, this Property’s position in the matched property path may take any one of the named Brick Properties (mutually exclusive with the property and variable field)

min

null, 0 or 1

Min and max fields, if set, apply property path quantifiers to specify how many chained occurrences of this property are to be matched by the query. min==0 → zero or more occurrences. This is equivalent to SPARQL's ZeroOrMorePath ("*") quantifier.

min==1 and max==null → at least one occurrence. This is equivalent to SPARQL's OneOrMorePath ("+") quantifier.

min==0 and max ==1 → either zero or one occurrence. This is equivalent to SPARQL's ZeroOrOne ("?") quantifier.

Other combinations are not supported at this time.

max

null, or 1

Min and max fields, if set, apply property path quantifiers to specify how many chained occurrences of this property are to be matched by the query. min==0 → zero or more occurrences. This is equivalent to SPARQL's ZeroOrMorePath ("*") quantifier.

min==1 and max==null → at least one occurrence. This is equivalent to SPARQL's OneOrMorePath ("+") quantifier.

min==0 and max ==1 → either zero or one occurrence. This is equivalent to SPARQL's ZeroOrOne ("?") quantifier.

Other combinations are not supported at this time.

Query response (for select queries)

When a BRIQL invocation is complete, a response is returned to the client.

For a select query, the response is a QueryResponse object. This is serialised as JSON.

The 'solutionTable' list of a QueryResponse is a table-like structure where each row is a single solution to the query. Each 'column' contains references to an entry in solutionNodes.

The 'solutionNodes' map of a QueryResponse contains descriptions of nodes mentioned in the solutionTable.

QueryResponse

Field
Type
Meaning

models

List of ModelReference

The models which were included in the query.

variableNames

list of string

Names of output variables.

solutionNodes

map of string to (map of string to ResponseValue)

Outer key: variable’s name Inner key: node’s full URI Inner value: a NodeValue describing the node

solutionTable

List of (map of string to NodeValueRef)

The outer list is a list of solutions (rows).

Each solution is a map of variable name to a ResponseValue.

ResponseValue

ResponseValue may be either NullValue or NodeValue.

NullValue

(Has no fields; represents an value that is not bound to anything in this solution, for this variable.)

NodeValueRef

For use inside the solutionTable. This is a reference to an entry of solutionNodes.

Field
Type
Meaning

fullId

string

The models which were included in the query.

NodeValue

This represents node values bound to variables in solutions.

Field
Type
Meaning

modelIndex

integer

The model to which the node belongs (an index into the list in the models field of the QueryResponse)

id

string

The ID (local to the model) of the node, if requested

type

string

The brick type of the node, if requested

hypernym

string

The hypernym of the node’s type (if requested)

pointinfo

List of PointInfo

List of PointInfo instances (if requested and any exist)

streams

List of string

List of Seanaps stream IDs (if 'streams' was requested in fetch field). This is only useful if the requested node is a Point.

PointInfo

This represents information about Points which are attached to a node.

Field
Type
Meaning

type

string

The Brick type of the Point

point

string

The Point’s node ID

streams

List of string

The Senaps stream ID(s), if any, belonging to the Point

entityProperty

List of EntityPropertyFromQuery

The entity properties, if any, of the Point.

unit

string

The unit (a QUDT URI) of the Point, if it exists.

EntityPropertyFromQuery

This represents entity properties.

Field
Type
Meaning

property

string

The Brick property URI.

key

string

for brick:keyValue, this is the key of the key-value pair

value

string

for brick:keyValue, this is the key of the key-value pair

unit

string

for entity properties with an applied QUDT unit, this is the URI of the unit.

nested

List of EntityPropertyFromQuery

Any entity properties nested within this one, for complex types.

Query response (for describe queries)

A describe query is a request for all information about a single node (its metadata, and relationships to other adjacent nodes within the model graph). This means that the response to a describe query is different to that of a select query.

DescribeResponse

Field
Type
Meaning

node

NodeReference

The node which was described in the response (equal to 'describe' value in QueryInvocation).

type

string

The brick type of the described node.

hypernym

string

The hypernym (top level class) of the described node.

unit

string

The described node's unit as a QUDT URI (if it has one).

label

string (nullable)

The label of the described node, if it has one.

comment

string (nullable)

The comment of the described node, if it has one.

streamIds

List of string

If the described node is a Point, its senaps stream IDs will be set here.

properties

List of EntityPropertyFromQuery

If the described node has entity properties, these are listed here.

relatedNodes

List of RelatedNode

If the described node has any adjacent nodes, these are listed here.

RelatedNode

Field
Type
Meaning

relationship

string

The Brick relationship (feeds, feedsAir, isFedBy, hasPart, isPartOf, hasPoint, isPointOf, hasLocation, isLocationOf, hasSubMeter, isSubMeterOf, meters, isMeteredBy) by which the described node is associated to the related node.

node

NodeReference

A reference to the related node.

type

string

The brick type of the related node.

hypernym

string

The hypernym (top level class) of therelated node.

unit

string

The related node's unit as a QUDT URI (if it has one).

label

string (nullable)

The label of the related node, if it has one.

comment

string (nullable)

The comment of the related node, if it has one.

streamIds

List of string

If the related node is a Point, its senaps stream IDs will be set here.

properties

List of EntityPropertyFromQuery

If the related node has entity properties, these are listed here.

Last updated