BRIQL Query Language
Last updated
Last updated
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 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.
This table briefly summarises relationship between BRIQL and SPARQL concepts. It may be useful to developers who are already familiar with SPARQL and RDF.
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.
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.
This class is the request payload submitted to the BRIQL endpoint.
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
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.
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.
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.
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.
Exactly one of 'property' or 'key' fields must be set.
Exactly one 'val' field (intval, numval, strval, urival, boolval) must be set.
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 is an enumeration, represented in JSON with a string equal to one of the following. Members are case sensitive.
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 determines how NodeVars are matched.
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 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
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
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
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)
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.
Used in 'types' list in Block instances to constrain a variable's type, in that Block's context.
name
string
Variable name
brickTypes
List of MatchType
The named variable must match at least one of these MatchTypes.
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
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==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==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.
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.
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 may be either NullValue or NodeValue.
(Has no fields; represents an value that is not bound to anything in this solution, for this variable.)
For use inside the solutionTable. This is a reference to an entry of solutionNodes.
fullId
string
The models which were included in the query.
This represents node values bound to variables in solutions.
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.
This represents information about Points which are attached to a node.
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.
This represents entity properties.
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.
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.
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.
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.
Match model nodes that have the nominated Brick type exactly (regardless of ).
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 at query run time. Paths are converted to triples patterns first (in specified order), followed by conversion of blocks (again, in specified order).
If set and true, this block’s constraints are matched . Defaults to false. This allows matching without eliminating un-matched subgraphs from the query's solution.
See
A 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.
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 ("*") .
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 ("*") .