Querying Data Model

Onboard’s data model contains both equipment types (e.g. fans, air handling units) and point types (e.g. zone temperature). We can query the full data model within our API.

Data model column definitions for each of the below tables can be found in data model columns page.

Equipment types

First, we query equipment types.


While the R client get_equip_types() expands nested lists (meaning there is a row for each subtype), the Python client.get_equipment_types() has one row per equipment type, meaning the sub-equipment types are nested as dataframes within each row. In the Python client, you must manually list subtypes for an equipment type as shown in the Python code block.

>>> from onboard.client import OnboardClient
>>> client = OnboardClient(api_key='')
>>> import pandas as pd
>>> # this query returns a JSON object,
>>> # which we convert to data frame using pd.json_normalize()
>>> equip_type = pd.json_normalize(client.get_equipment_types())
>>> equip_type[["id", "tag_name", "name_long", "sub_types"]]
   id           tag_name            name_long                                          sub_types
0  12                ahu    Air Handling Unit  [{'id': 1, 'equipment_type_id': 12, 'tag_name'...
1  19             boiler               Boiler  [{'id': 4, 'equipment_type_id': 19, 'tag_name'...
2  20  chilledWaterPlant  Chilled Water Plant                                                 []
3  21            chiller              Chiller  [{'id': 7, 'equipment_type_id': 21, 'tag_name'...
4  22          condenser            Condenser                                                 []

>>> # to expand sub types:
>>> sub_type = pd.DataFrame(equip_type[equip_type.tag_name == 'fan']['sub_types'].item())
   id  equipment_type_id         tag_name          name_long name_abbr
0  12                 26       exhaustFan        Exhaust Fan       EFN
1  13                 26        reliefFan         Relief Fan      RlFN
2  14                 26        returnFan         Return Fan       RFN
3  15                 26        supplyFan         Supply Fan       SFN

Note that not all equipment types have associated sub-types.

Point types

Accessing point types is very similar:

>>> # Get all point types from the Data Model
>>> point_types = pd.DataFrame(client.get_all_point_types())
>>> point_types[['id', 'tag_name', 'tags']]
      id                                  tag_name                                            tags
0    124                 Occupied Heating Setpoint             [air, sp, temp, zone, heating, occ]
1    118                Outside Air Carbon Dioxide                     [air, co2, sensor, outside]
2    130           Return Air Temperature Setpoint                         [air, sp, temp, return]
3     84  Dual-Temp Coil Discharge Air Temperature  [air, discharge, dualTemp, sensor, temp, coil]

point_types is now a dataframe listing all the tags associated with each point type.


In the following, convenience wrapper functions are currently only available on the development version of the R package. For the official version, use each respective api.get() call mentioned in the code.

We can extract the metadata associated with each tag in our data model like so:

>>> # Get all tags and their definitions from the Data Model
>>> pd.DataFrame(client.get_tags())
      id        name                                         definition def_source                                            def_url
0    120     battery  A container that stores chemical energy that c...      brick  https://brickschema.org/ontology/1.1/classes/B...
1    191  exhaustVAV  A device that regulates the volume of air bein...    onboard                                               None
2    193         oil  A viscous liquid derived from petroleum, espec...      brick  https://brickschema.org/ontology/1.2/classes/Oil/
3    114    fumeHood  A fume-collection device mounted over a work s...      brick  https://brickschema.org/ontology/1.1/classes/F...

This returns a dataframe containing definitions for all tags in our data model, with attribution where applicable.

Unit types

>>> # Get all unit types from the Data Model
>>> unit_types = pd.DataFrame(client.get_all_units())
>>> unit_types[['id', 'name_long', 'qudt']]
   id             name_long                                  qudt
0  55                 Litre          http://qudt.org/vocab/unit/L
1  68             US Gallon     http://qudt.org/vocab/unit/GAL_US
2  75                   Bar        http://qudt.org/vocab/unit/BAR
3  76                 Watts          http://qudt.org/vocab/unit/W

Measurement types

>>> # Get all measurement types from the Data Model
>>> measurement_types = pd.DataFrame(client.get_all_measurements())
>>> measurement_types[['id', 'name', 'qudt_type']]
    id               name                                          qudt_type
0   20     Reactive Power   http://qudt.org/vocab/quantitykind/ReactivePower
1   27              Floor   http://qudt.org/vocab/quantitykind/Dimensionless
2   33       Power Factor   http://qudt.org/vocab/quantitykind/Dimensionless
3   31             Torque  http://qudt.org/vocab/quantitykind/Dimensionle...