CREATE Operation

The CREATE operation is used to create models and things in the models.

Manifest Configuration

The Create operation has one parameter, the name of the input csv, in its configuration:

        {
            "operation_type": "CREATE",
            "config": {
                "object_file": "objects.csv"
            }
        }

Objects

The CSV file used with the CREATE operation is referred to as the objects csv file. It is a CSV consisting of a header row and then a row for each entity to generate within the model(s). It has two required columns:

• Model_ID|Entity_Name: identifier of the entity, composed of the site or building model identifier and a unique name for the entity separated by the | character. Both Model_ID and Entity_Name are case sensitive, but mixing case for either is discouraged (especially as Model_ID is used for file names and not all OS's deal with that). I.e please avoid having both mdl:myBuilding and MDL:myBuilding and/or having both mdl:Room1 and mdl:room1

• Class: Brick Collection, Location and Equipment. See DCH support for Brick classes.

Additionally, an arbitrary number of subsequent 'property' columns can be added for any additional, optional metadata to be added to the model.

See allowable character sets and names for restrictions on identifier names, and csv file interpretation for options for specifying classes.

Examples

Example 1

Example 1: Basic usage to create a site, a building, a room, an Air Handling Unit (AHU) and a Point

---

Inputs

manifest.json

{
    "manifest_version": "1.0.0",
    "id_mapping": {
        "site_model": "dch:org/test_org/site/test_site",
        "building_model": "dch:org/test_org/site/test_site/building/test_building"
    },
    "operations": [
        {
            "operation_type": "CREATE",
            "config": {
                "object_file": "objects.csv"
            }
        }
    ]
}

input_csvs/objects.csv

Model_ID|Entity_Name	Class
site_model|test_site	Site
building_model|test_building	Building
building_model|test_room	Room
building_model|test_ahu	AHU

731B

create_example_1.zip

archive

CREATE Example 1: Full input archive

---

Outputs

Zipping those up and running that through the tool will produce two turtle output files:

site_model.ttl

@prefix brick: <https://brickschema.org/schema/Brick#> .
@prefix site_model: <dch:org/documentation/site/Create_Eg1#> .

site_model:test_site a brick:Site ;
    brick:keyValue [ brick:key "mgtool" ;
            brick:value "version: 2.0" ],
        [ brick:key "mgtool" ;
            brick:value "build date: 2024-04-08" ] .

building_model.ttl

@prefix brick: <https://brickschema.org/schema/Brick#> .
@prefix building_model: <dch:org/documentation/site/Create_Eg1/building/building_eg1#> .

building_model:test_ahu a brick:AHU .

building_model:test_building a brick:Building ;
    brick:keyValue [ brick:key "mgtool" ;
            brick:value "version: 2.0" ],
        [ brick:key "mgtool" ;
            brick:value "build date: 2024-04-08" ] .

building_model:test_room a brick:Room .

mgtool.log

INFO | Processing model generation manifest at ...\manifest.json
INFO | Importing model generation manifest at ...\manifest.json
INFO | Starting the CREATE operation (...\input_csvs\objects.csv)
INFO | Importing building objects from ...\input_csvs\objects.csv
INFO | Graph of model (building_model): number of building objects that already exist: 0
INFO | Graph of model (building_model): number of building objects created: 4
INFO | Graph of model (building_model): number of building objects updated: 0
INFO | Graph of model (site_model): number of building objects that already exist: 0
INFO | Graph of model (site_model): number of building objects created: 1
INFO | Graph of model (site_model): number of building objects updated: 0
INFO | Writing graph of model (site_model) to ...\script_outputs\site_model.ttl
INFO | Writing graph of model (building_model) to ...\script_outputs\building_model.ttl
INFO | Completed the CREATE operation (...\input_csvs\objects.csv)

1KB

generated-create_example_1.zip

archive

CREATE Example 1: Full output archive

Example 2

Example 2: Adding Properties, Comments and Labels

---

In DCH and BRICK things in models can have properties - see https://docs.brickschema.org/metadata/entity-properties.html. Also related to those it is common in BRICK models to allow comments (rdfs:comment) and labels (rdfs:label) to be added to things.

The input_csvs/objects.csv file can be extended with extra columns to specify the properties to set on things including comments and labels. The column headers specify the property to add (and the ordering of the components or subproperties of them). The values in the rows contain the values for those components of the properties. Columns headers need to be unique to avoid ambiguity.

Inputs

manifest.json

{
    "manifest_version": "1.0.0",
    "id_mapping": {
        "site_model": "dch:org/test_org/site/test_site",
        "building_model": "dch:org/test_org/site/test_site/building/test_building"
    },
    "operations": [
        {
            "operation_type": "CREATE",
            "config": {
                "object_file": "objects.csv"
            }
        }
    ]
}

input_csvs/objects.csv

Model_ID|Entity_Name	Class	rdfs:label	brick:area [brick:value, brick:hasUnit]	brick:serial_number [brick:value]	brick:powerComplexity [brick:value]	brick:aggregate [brick:aggregationFunction, brick:aggregationInterval]	rdfs:comment
site_model|test_site	Site	MONA	[5.0, unit:M2]				You should definitely visit: https://mona.net.au/
building_model|test_building	Building	CafeBlock	[420, unit:M2]
building_model|test_room	Room	dubsys	[42.1, unit:M2]
building_model|test_ahu	AHU	AHU_01		SN: 1234001

927B

create_example_2.zip

archive

CREATE Example 2: Full input archive

---

Outputs

Zipping those up and running that through the tool will produce two turtle output files:

site_model.ttl

@prefix brick: <https://brickschema.org/schema/Brick#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix site_model: <dch:org/documentation/site/Create_Eg2#> .
@prefix unit: <http://qudt.org/vocab/unit/> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .

site_model:test_site a brick:Site ;
    rdfs:label "MONA" ;
    rdfs:comment "You should definitely visit: https://mona.net.au/" ;
    brick:area [ brick:hasUnit unit:HA ;
            brick:value 5e+00 ] ;
    brick:keyValue [ brick:key "mgtool" ;
            brick:value "version: 2.0" ],
        [ brick:key "mgtool" ;
            brick:value "build date: 2024-04-08" ] .

building_model.ttl

@prefix brick: <https://brickschema.org/schema/Brick#> .
@prefix building_model: <dch:org/documentation/site/Create_Eg2/building/building_eg2#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix unit: <http://qudt.org/vocab/unit/> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .

building_model:test_ahu a brick:AHU ;
    rdfs:label "AHU_01" ;
    brick:serial_number [ brick:value "SN: 1234001" ] .

building_model:test_building a brick:Building ;
    rdfs:label "CafeBlock" ;
    brick:area [ brick:hasUnit unit:M2 ;
            brick:value 420 ] ;
    brick:keyValue [ brick:key "mgtool" ;
            brick:value "build date: 2024-04-08" ],
        [ brick:key "mgtool" ;
            brick:value "version: 2.0" ] .

building_model:test_room a brick:Room ;
    rdfs:label "dubsys" ;
    brick:area [ brick:hasUnit unit:M2 ;
            brick:value 4.21e+01 ] .

1KB

generated-create_example_2.zip

archive

CREATE Example 2: Full output archive

Example 3

Example 3: Multiple Properties

---

Whilst it is rare, sometimes you might want to add multiple values for a property. The obvious example is the DCH keyValue property where yo could have several keyValue properties on something. A second (not recommended) example of area is also included.

manifest.json

{
    "manifest_version": "1.0.0",
    "id_mapping": {
        "site_model": "dch:org/test_org/site/test_site",
        "building_model": "dch:org/test_org/site/test_site/building/test_building"
    },
    "operations": [
        {
            "operation_type": "CREATE",
            "config": {
                "object_file": "objects.csv"
            }
        }
    ]
}

objects.csv

Model_ID|Entity_Name	Class	rdfs:label	brick:area [brick:value, brick:hasUnit]	brick:keyValue [brick:key, brick:value]	brick:keyValue [brick:key, brick:value]
building_model|test_building	Building	CafeBlock	[4.2, unit:M2]	[model revision,3]	[aspect,North]

800B

create_example_3.zip

archive

CREATE Example 3: Full input archive

---

Outputs

Zipping those up and running that through the tool will produce the following turtle output file:

building_model.ttl

@prefix brick: <https://brickschema.org/schema/Brick#> .
@prefix building_model: <dch:org/documentation/site/Create_Eg3/building/building_eg3#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix unit: <http://qudt.org/vocab/unit/> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .

building_model:test_building a brick:Building ;
    rdfs:label "CafeBlock" ;
    brick:area [ brick:hasUnit unit:INCH2 ;
            brick:value 6510 ],
        [ brick:hasUnit unit:M2 ;
            brick:value 4.2e+00 ] ;
    brick:keyValue [ brick:key "aspect" ;
            brick:value "North" ],
        [ brick:key "model revision" ;
            brick:value 3 ],
        [ brick:key "mgtool" ;
            brick:value "build date: 2024-04-08" ],
        [ brick:key "mgtool" ;
            brick:value "version: 2.0" ] .

As this is not common, a warning is also issued. It is safe to ignore this warning if the duplication was deliberate in order to get multiple values.

WARNING | Header Validation: Metadata columns duplicated: ['brick:area [brick:value, brick:hasUnit] (col 4)', 'brick:area [brick:value, brick:hasUnit] (col 5)', 'brick:keyValue [brick:key, brick:value] (col 6)', 'brick:keyValue [brick:key, brick:value] (col 7)'].

965B

generated-create_example_3.zip

archive

CREATE Example 3: Full output archive