Using HodDB

Loading Data

Overview

In Brick, buildings are described using RDF triples. These triples are stored in Turtle (.ttl) files, which can be loaded into a HodDB instance.

HodDB stores buildings in a set of LevelDB databases; the location of these files is determined by the DBPath configuration option which defaults to ./_hoddb.

In order to perform queries on the the database using the Brick classes and relationships, HodDB also needs to import the Turtle files that define the Brick schema. The location of these files are determined by the BrickFrameTTL and BrickClassTTL configuration options. The most recent version of these files can be downloaded from http://brickschema.org/download/.

The Brick ttl files in the configuration file (hodconfig.yaml) are loaded implicitly when HodDB is started.

See the examples page for a small TTL file sample.

CLI Queries

HodDB offers a command-line query interface which has the ability of exposing additional performance information as well as query planner details. The visibility of this information is configurable in the HodDB configuration file.

By default, the command-line query interface can be invoked using the hod cli command:

hod cli
Successfully loaded dataset!
(hod)> SELECT ?floor ?room ?zone
>>> ...WHERE {
>>> ...    ?floor rdf:type brick:Floor .
>>> ...    ?room rdf:type brick:Room .
>>> ...    ?zone rdf:type brick:HVAC_Zone .
>>> ...    ?room bf:isPartOf+ ?floor .
>>> ...    ?room bf:isPartOf+ ?zone .
>>> ...};
INFO query.go:58 Dec 24 15:35:51  ▶ Ran query in 16.58933ms
INFO query.go:64 Dec 24 15:35:51  ▶ Expanded tuples in 10.785491ms
NOTICE api.go:60 Dec 24 15:35:51  ▶ Full Query took 28.42414ms
map[?zone:http://buildsys.org/ontologies/building_example#hvac_zone_C180 ?floor:http://buildsys.org/ontologies/building_example#floor_1 ?room:http://buildsys.org/ontologies/building_example#room_C180]
map[?floor:http://buildsys.org/ontologies/building_example#floor_1 ?room:http://buildsys.org/ontologies/building_example#room_R181 ?zone:http://buildsys.org/ontologies/building_example#hvac_zone_R181]
map[?room:http://buildsys.org/ontologies/building_example#room_R184 ?zone:http://buildsys.org/ontologies/building_example#hvac_zone_R184 ?floor:http://buildsys.org/ontologies/building_example#floor_1]
map[?floor:http://buildsys.org/ontologies/building_example#floor_1 ?room:http://buildsys.org/ontologies/building_example#room_R187A ?zone:http://buildsys.org/ontologies/building_example#hvac_zone_R187A]
map[?zone:http://buildsys.org/ontologies/building_example#hvac_zone_R190A ?floor:http://buildsys.org/ontologies/building_example#floor_1 ?room:http://buildsys.org/ontologies/building_example#room_R190A]
map[?floor:http://buildsys.org/ontologies/building_example#floor_1 ?room:http://buildsys.org/ontologies/building_example#room_R190B ?zone:http://buildsys.org/ontologies/building_example#hvac_zone_R190B]
map[?room:http://buildsys.org/ontologies/building_example#room_R252 ?zone:http://buildsys.org/ontologies/building_example#hvac_zone_R252 ?floor:http://buildsys.org/ontologies/building_example#floor_2]
map[?floor:http://buildsys.org/ontologies/building_example#floor_2 ?room:http://buildsys.org/ontologies/building_example#room_R283E ?zone:http://buildsys.org/ontologies/building_example#hvac_zone_R283E]
map[?zone:http://buildsys.org/ontologies/building_example#hvac_zone_R287 ?floor:http://buildsys.org/ontologies/building_example#floor_2 ?room:http://buildsys.org/ontologies/building_example#room_R287]
...

Note: only a single HodDB instance can be started for a set of backing files, i.e. you cannot run both the CLI and HTTP interface simultaneously.

Config: ShowDependencyGraph

(Defaults to false)

If true, then HodDB will print out the dependency graph generated from the provided query, which is used as input into the query planner.

hod cli
Successfully loaded dataset!
(hod)> SELECT ?floor ?room ?zone
>>> ...WHERE {
>>> ...    ?floor rdf:type brick:Floor .
>>> ...    ?room rdf:type brick:Room .
>>> ...    ?zone rdf:type brick:HVAC_Zone .
>>> ...    ?room bf:isPartOf+ ?floor .
>>> ...    ?room bf:isPartOf+ ?zone .
>>> ...};
 <?zone [{http://www.w3.org/1999/02/22-rdf-syntax-ns#type }] http://buildsys.org/ontologies/Brick#HVAC_Zone>
 <?room [{http://www.w3.org/1999/02/22-rdf-syntax-ns#type }] http://buildsys.org/ontologies/Brick#Room>
   <?room [{http://buildsys.org/ontologies/BrickFrame#isPartOf +}] ?zone>
 <?floor [{http://www.w3.org/1999/02/22-rdf-syntax-ns#type }] http://buildsys.org/ontologies/Brick#Floor>
   <?room [{http://buildsys.org/ontologies/BrickFrame#isPartOf +}] ?floor>
INFO query.go:58 Dec 24 15:43:33  ▶ Ran query in 16.422681ms
INFO query.go:64 Dec 24 15:43:33  ▶ Expanded tuples in 10.002746ms
NOTICE api.go:60 Dec 24 15:43:33  ▶ Full Query took 31.336022ms

Config: ShowQueryPlan

(Defaults to false)

If true, then HodDB will print out the generated query plan for the provided query, showing which low-level operations are being run over the underlying structure.

hod cli
Successfully loaded dataset!
(hod)> SELECT ?floor ?room ?zone
>>> ...WHERE {
>>> ...    ?floor rdf:type brick:Floor .
>>> ...    ?room rdf:type brick:Room .
>>> ...    ?zone rdf:type brick:HVAC_Zone .
>>> ...    ?room bf:isPartOf+ ?floor .
>>> ...    ?room bf:isPartOf+ ?zone .
>>> ...};
-------------- start query plan -------------
DEBUG query.go:45 Dec 24 15:47:00  ▶ op [resolveSubject <?floor [{http://www.w3.org/1999/02/22-rdf-syntax-ns#type }] http://buildsys.org/ontologies/Brick#Floor>]
DEBUG query.go:45 Dec 24 15:47:00  ▶ op [resolveSubject <?room [{http://www.w3.org/1999/02/22-rdf-syntax-ns#type }] http://buildsys.org/ontologies/Brick#Room>]
DEBUG query.go:45 Dec 24 15:47:00  ▶ op [resolveSubject <?zone [{http://www.w3.org/1999/02/22-rdf-syntax-ns#type }] http://buildsys.org/ontologies/Brick#HVAC_Zone>]
DEBUG query.go:45 Dec 24 15:47:00  ▶ op [restrictSubObjByPred <?room [{http://buildsys.org/ontologies/BrickFrame#isPartOf +}] ?floor>]
DEBUG query.go:45 Dec 24 15:47:00  ▶ op [restrictSubObjByPred <?room [{http://buildsys.org/ontologies/BrickFrame#isPartOf +}] ?zone>]
-------------- end query plan -------------
INFO query.go:58 Dec 24 15:47:00  ▶ Ran query in 26.436114ms
INFO query.go:64 Dec 24 15:47:00  ▶ Expanded tuples in 7.149802ms
NOTICE api.go:60 Dec 24 15:47:00  ▶ Full Query took 35.000475ms

Config: ShowQueryPlanLatencies

(Defaults to false)

If true, then HodDB will print out the time to execute each step of the query plan, which can be helpful for debugging slow queries.

hod cli
Successfully loaded dataset!
(hod)> SELECT ?floor ?room ?zone
>>> ...WHERE {
>>> ...    ?floor rdf:type brick:Floor .
>>> ...    ?room rdf:type brick:Room .
>>> ...    ?zone rdf:type brick:HVAC_Zone .
>>> ...    ?room bf:isPartOf+ ?floor .
>>> ...    ?room bf:isPartOf+ ?zone .
>>> ...};
INFO query.go:49 Dec 24 15:49:04  ▶ Formed execution plan in 47.007µs
[resolveSubject <?floor [{http://www.w3.org/1999/02/22-rdf-syntax-ns#type }] http://buildsys.org/ontologies/Brick#Floor>] 201.308µs
[resolveSubject <?room [{http://www.w3.org/1999/02/22-rdf-syntax-ns#type }] http://buildsys.org/ontologies/Brick#Room>] 416.97µs
[resolveSubject <?zone [{http://www.w3.org/1999/02/22-rdf-syntax-ns#type }] http://buildsys.org/ontologies/Brick#HVAC_Zone>] 386.676µs
[restrictSubObjByPred <?room [{http://buildsys.org/ontologies/BrickFrame#isPartOf +}] ?floor>] 8.29247ms
[restrictSubObjByPred <?room [{http://buildsys.org/ontologies/BrickFrame#isPartOf +}] ?zone>] 10.253657ms
INFO query.go:58 Dec 24 15:49:04  ▶ Ran query in 19.647705ms
INFO query.go:64 Dec 24 15:49:04  ▶ Expanded tuples in 7.858543ms
NOTICE api.go:60 Dec 24 15:49:04  ▶ Full Query took 28.793678ms

Config: ShowQueryLatencies

Defaults to true; shows the runtime, tuple-expansion and overall total time to execute the query. Note that this is slightly more accurate than the times shown in the HTTP interface because those involve network and browser overhead.

HTTP API

The HodDB HTTP server can be started on the command line via:

1
2
hod http
NOTICE server.go:78 Dec 24 17:28:53  ▶ Starting HTTP Server on  localhost:47808

The served port can be configured using the ServerPort config option. IPv6 and public/localhost serving are configured via the UseIPv6 and Localhost fields respectively.

The exposed endpoints are:

  • /api/query: receives POST requests containing a query string, returns JSON encoded results of the query
  • /api/loadlinks: receives POST requests containing a JSON-encoded links file. Returns 200 or error.
  • /api/querydot: receives POST requests containing a query string, returns a GraphViz compatible DOT representation of the query as a string.

HTTP Frontend

There is a prototype HodDB interactive query interface available at the base URI, http://localhost:47808. It has its own set of documentation at http://localhost:47808/help.

BOSSWAVE API

There is a prototype HodDB interactive query interface available at the base URI, http://localhost:47808. It has its own set of documentation at http://localhost:47808/help.

Other Tools

The hod tool has a collection of other tools that may be useful. Use the -h flag on any of these to get more documentation on their usage.

  • hod dumpgraph: creates a PDF visualization of the nodes and entities in a TTL file. Warning! This can get very big and intractable.

  • hod dump: prints out the contents of a TTL file as a set of tab-separated triples

  • hod benchload: benchmarks the parsing time of a specified TTL file