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):

RequestLive Response
Copy
1
2
3
4
5
6
7
8
9
{
  spaces {
    isPartOf {
      id
      name
      exactType
    }
  }
}

For a building, this would show the site information:

RequestLive Response
Copy
1
2
3
4
5
6
7
8
9
{
  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:

RequestLive Response
Copy
1
2
3
4
5
6
7
8
9
{
  buildings {
    hasPart {
      id
      name
      exactType
    }
  }
}

Places can also have relationships with things. Use isLocationOf to see things associated with the space:

RequestLive Response
Copy
1
2
3
4
5
6
7
8
9
{
  spaces {
    isLocationOf {
      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:

RequestLive Response
Copy
1
2
3
4
5
6
7
8
9
10
{
  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:

RequestLive Response
Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  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:

RequestLive Response
Copy
1
2
3
4
5
6
7
8
9
10
11
{
  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:

RequestLive Response
Copy
1
2
3
4
5
6
7
8
9
{
  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:

RequestLive Response
Copy
1
2
3
4
5
6
7
8
9
10
11
{
  things(filter: {id: {eq: "THGJjbQG52zKvVYif43R7SCSu"}}) {
    name
    id
    hasPart {
      name
      id
      exactType
    }
  }
}

For the inverse, you'd use the isPartOf field, also part of things:

RequestLive Response
Copy
1
2
3
4
5
6
7
8
9
10
11
12
{
  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:

Request Response
Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  things(filter: {exactType: {eq: "Air_Handling_Unit"}}) {
    id
    name
    exactType
    feeds {
      ... on Thing {
        id
        name
        exactType
      }
    }
  }
}

Serves:

Request Response
Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  things(filter: {exactType: {eq: "Occupancy_Sensing_Device"}}) {
    id
    name
    exactType
    serves {
      ... on Zone {
        id
        name
        exactType
      }
    }
  }
}