building

Query signature

building(siteId: String!, id: String, name: String, nameMatch: NameMatch): [Building!]!

All root queries require siteId to scope to your site. See multi-tenant scoping. Examples below omit siteId for brevity.

Arguments

Argument	Type	Description
`siteId`	`String!`	Required. Scopes the query to a specific site
`id`	`String`	Filter to a specific building
`name`	`String`	Filter by name. Case-insensitive substring match by default
`nameMatch`	`NameMatch`	`CONTAINS` (default) or `EXACT`

Return fields

Field	Type	Description
`uri`	`String!`	Full entity URI
`id`	`ID!`	Building identifier
`name`	`String!`	Building name
`type`	`String!`	Brick class (always `Building`)
`ifcId`	`String`	IFC model element ID. Links to the BIM model
`locations`	`[Location!]!`	Direct child locations. Accepts `name`, `nameMatch`, `is`, `recursive` filters
`equipment`	`[Equipment!]!`	Direct equipment in this building. Accepts `name`, `nameMatch`, `is`, `recursive` filters
`zones`	`[Zone!]!`	Direct zones. Accepts `name`, `nameMatch`, `is`, `recursive` filters
`systems`	`[System!]!`	Direct systems. Accepts `name`, `nameMatch`, `is`, `recursive` filters
`points`	`[Point!]!`	Direct points. Accepts `name`, `nameMatch`, `is`, `recursive` filters
`properties`	`[EntityProperty!]!`	Static metadata as structured objects (`name`, `value`, `unit`)

Name matching: CONTAINS vs EXACT

The name argument supports two matching modes via nameMatch:

Mode	Behavior	Example	Matches
`CONTAINS` (default)	Case-insensitive substring	`name: "Pool"`	”One Pool Street”, “Pool House”
`EXACT`	Exact string match	`name: "One Pool Street", nameMatch: EXACT`	”One Pool Street” only

When to use which:

Scenario	Use	Why
Exploring / discovering entities	`CONTAINS`	Don’t know exact names yet, so cast a wide net
AI agent searching a building	`CONTAINS`	Fuzzy, forgiving, finds partial matches
Linking from another system by name	`EXACT`	Need the precise entity, no false positives
Following up after a discovery query	`EXACT`	Already found the name, now pin it down

You almost never need to specify nameMatch. CONTAINS is the default and works for most queries. Only use EXACT when you need precision and already know the full name.

Examples

List all buildings

{ building { id name type } }

{
  "data": {
    "building": [
      { "id": "B001", "name": "One Pool Street", "type": "Building" }
    ]
  }
}

Find a building by name (CONTAINS, default)

{ building(name: "Pool") { id name } }

Returns all buildings whose name contains “Pool” (case-insensitive). No need to specify nameMatch since CONTAINS is the default.

{
  "data": {
    "building": [
      { "id": "B001", "name": "One Pool Street" }
    ]
  }
}

Find a building by exact name (EXACT)

{ building(name: "One Pool Street", nameMatch: EXACT) { id name } }

Returns only buildings with this exact name, with no substring matching.

Get a specific building

{
  building(id: "B001") {
    name
    equipment { id name type }
  }
}

Spatial tree (wings, floors, zones)

{
  building(id: "B001") {
    name
    locations {
      name
      type
      locations {
        name
        type
      }
    }
  }
}

{
  "data": {
    "building": {
      "name": "One Pool Street",
      "locations": [
        {
          "name": "Tower East",
          "type": "Wing",
          "locations": [
            { "name": "Level 01", "type": "Floor" },
            { "name": "Lobby 1", "type": "HVAC_Zone" },
            { "name": "Research Hub", "type": "HVAC_Zone" }
          ]
        },
        {
          "name": "Tower West",
          "type": "Wing",
          "locations": [
            { "name": "Level 01", "type": "Floor" },
            { "name": "Library", "type": "HVAC_Zone" },
            { "name": "Common Room", "type": "HVAC_Zone" }
          ]
        }
      ]
    }
  }
}

Find locations by name

{
  building(id: "B001") {
    locations(name: "Tower East", nameMatch: EXACT) {
      name
      type
      equipment { name type }
    }
  }
}

Only floors (by Brick class)

{
  building(id: "B001") {
    locations(is: "Floor") {
      name
    }
  }
}

All equipment in a building (recursive)

{
  building(id: "B001") {
    equipment(recursive: true) {
      name
      type
      location { name }
    }
  }
}

Use recursive: true to get equipment at all levels of the spatial hierarchy, not just directly placed on the building.

All points in a building (recursive)

{
  building(id: "B001") {
    points(recursive: true, is: "Temperature_Sensor") {
      name
      type
      unit
    }
  }
}

Combines recursive: true with is to find every temperature sensor in the entire building.

Nested field filters

All nested collection fields (locations, equipment, zones, systems, points) support name, nameMatch, is, and recursive parameters:

{
  building(id: "B001") {
    # Filter locations by name and class
    locations(name: "Tower", is: "Wing") {
      name
      type
      # Nested locations also support the same filters
      equipment(is: "AHU", recursive: true) {
        name
        type
      }
    }
  }
}

Overview

Entities

Relationships

Query signature

Arguments

Return fields

Name matching: CONTAINS vs EXACT

Examples

List all buildings

Find a building by name (CONTAINS, default)

Find a building by exact name (EXACT)

Get a specific building

Spatial tree (wings, floors, zones)

Find locations by name

Only floors (by Brick class)

All equipment in a building (recursive)

All points in a building (recursive)

Nested field filters

​Query signature

​Arguments

​Return fields

​Name matching: CONTAINS vs EXACT

​Examples

​List all buildings

​Find a building by name (CONTAINS, default)

​Find a building by exact name (EXACT)

​Get a specific building

​Spatial tree (wings, floors, zones)

​Find locations by name

​Only floors (by Brick class)

​All equipment in a building (recursive)

​All points in a building (recursive)

​Nested field filters

Query signature

Arguments

Return fields

Name matching: CONTAINS vs EXACT

Examples

List all buildings

Find a building by name (CONTAINS, default)

Find a building by exact name (EXACT)

Get a specific building

Spatial tree (wings, floors, zones)

Find locations by name

Only floors (by Brick class)

All equipment in a building (recursive)

All points in a building (recursive)

Nested field filters