building

Query buildings in your account.

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
      }
    }
  }
}