Relationships
Many of the different GraphQL types available in the Mapped API, such as spaces and things, have relationships that can be viewed using several associated fields. These relationships can be between things and places, between different places, or between different things, and are used to represent the overall composition (a damper is a component of a VAV), topology (an air handler feeds into a VAV) and telemetry (a VAV has a temperature sensor) of the data.
To understand relationships, the best way is to start with the subject of the request, which is how we'll describe the examples below. For each request, there is also an inverse relationship - i.e. a thing can have parts, and can also be a part of something else - which will be outlined as well.
Place Relationships
If your subject is going to be a place, you can use the field isPartOf to see the next level up in the place hierarchy. For a space, this would show the floor its located on (as well as any Zones that might be applicable as well):
{
spaces {
isPartOf {
id
name
exactType
}
}
}
For a building, this would show the site information:
{
buildings {
isPartOf {
id
name
exactType
}
}
}
The inverse would be hasPart, so if you ran the following query for buildings, you'd see all the floors:
{
buildings {
hasPart {
id
name
exactType
}
}
}
Places can also have relationships with things. Use isLocationOf to see things associated with the space:
{
spaces {
isLocationOf {
... on Thing {
id
name
exactType
}
}
}
}
}
The hasLocation field for a thing is the inverse relationship to isLocationOf, which is discussed in the next section.
Thing Relationships
If the subject of your request is a thing, there are several relationships can be retrieved. You can see if the device has any points using the field hasPoint:
{
things(filter: { id: { eq: "THGJjbQG52zKvVYif43R7SCSu" } }) {
name
id
hasPoint {
name
id
}
}
}
The isPointOf field under points is the inverse relationship for hasPoint - this field uses unique GraphQL syntax called a union. Unions are used when a field can have a relationship with multiple GraphQL types, like in this case where a point could be associated with both things and places:
{
points (filter: {id: {eq: "PNTXK13hHH6RUK4sp2csBqSyv"}}) {
name
id
exactType
isPointOf {
... on Thing {
name
id
exactType
}
}
}
}
You can also see where a thing is located using the field hasLocation:
{
things(filter: { id: { eq: "THGJjbQG52zKvVYif43R7SCSu" } }) {
name
id
hasLocation {
name
id
exactType
}
}
}
For the inverse of hasLocation, you'd use the isLocationOf field for a place like spaces or floors:
{
spaces(filter: { id: { eq: "SPCABcPrDFQ3F9ueQnUhRjMU" } }) {
isLocationOf {
id
name
exactType
}
}
}
You can also see if a device has any parts, like a VAV has a damper, using hasPart:
{
things(filter: { id: { eq: "THGJjbQG52zKvVYif43R7SCSu" } }) {
name
id
hasPart {
name
id
exactType
}
}
}
For the inverse, you'd use the isPartOf field, also part of things:
{
things(filter: { id: { eq: "THGDnDb6qzS3bR3ahNg4cX3GC" } }) {
name
id
exactType
isPartOf {
name
id
exactType
}
}
}
Feeds & Serves Relationships
Things can also include feeds or serves. These fields also use the union GraphQL syntax. Feeds represents downstream equipment or locations, like an air handler feeding a VAV or a VAV feeding a zone, whereas serves is used when there isn't an actual physical connection, like an Occupancy Sensor monitoring an Occupancy Zone. The following are two examples showing how feeds and serves work.
Feeds:
{
things(filter: {exactType: {eq: "Air_Handling_Unit"}}) {
id
name
exactType
feeds {
... on Thing {
id
name
exactType
}
}
}
}
Serves:
{
things(filter: {exactType: {eq: "Occupancy_Sensing_Device"}}) {
id
name
exactType
serves {
... on Zone {
id
name
exactType
}
}
}
}