Filtering

The majority of fields available to work with in the Mapped API can be filtered - most typically by values like id so you can retrieve details about a specific building, device, point and so on. While each documentation page provides some examples that typically include filters in a code sample specific to the topic, this guide shows you the various options available to filtering as a whole.

We'll start with the easiest and likely most used - filtering by one specific value.

Filtering using a single criteria

At the top level of each field that supports filtering, filter will be an available field to select, i.e.

Copy
1
sites(filter: {

After filter, you'll have a list of criteria to select from. id will be the most common across all fields, so we'll pick that one:

Copy
1
sites(filter: {id: {

Now you'll have a few operators to work with; since we want to use a single criteria, in this case the id, we'll use eq which represents "equals":

Copy
1
sites(filter: {id: {eq: "SITE44nUdjjbqSX1sEXuwEWucr"}})

That string says, essentially, "all the data that follows from this point on is from this site and this site only". A complete example using that filter and grabbing some data would look like this:

RequestLive Response
Copy
1
2
3
4
5
6
7
8
{
  sites(filter: {id: {eq: "SITE44nUdjjbqSX1sEXuwEWucr"}}) {
    things {
      name
      type
    }
  }
}

That code sample will return all the things located in that particular site and nowhere else.

Stacking filters

You can also stack filters, if the field supports it. Building off the previous example, we filtered down to a single site via the id and returned all the things located at that site. What if we didn't want all the things, but only a specific type of thing located at that site? We can stack the filters like so to get what we're looking for:

RequestLive Response
Copy
1
2
3
4
5
6
7
8
{
  sites(filter: {id: {eq: "SITE44nUdjjbqSX1sEXuwEWucr"}}) {
    things(filter: {type: {eq: "Variable_Air_Volume_Box"}}) {
      name
      type
    }
  }
}

Filtering for multiple matches

If you want to find all the results that potentially match any of the defined criteria, you'll want to use in. This is an operator like eq, where it follows the criteria value, but it looks for any value contained inside a defined set. In the following example, we're going to look for all things that are either a Damper or VAV at the site:

RequestLive Response
Copy
1
2
3
4
5
6
7
8
9
{
  sites(filter: {id: {eq: "SITE44nUdjjbqSX1sEXuwEWucr"}}) {
    things(filter: {type: {in: ["Damper", "VAV"]}}) {
      id
      name
      type
    }
  }
}

Filtering to omit matches

Instead of looking for results that match a set of conditions, you may want to omit results that matched the criteria. For that, you would use either the not operator or the ne operator. You would use not for anything that is an array, like type. For options that have a single result possibility, you would use ne. So if you wanted a list of all the things at a particular site, but wanted to exclude anything related to HVAC, you would do something like this:

RequestLive Response
Copy
1
2
3
4
5
6
7
8
9
{
  sites(filter: {id: {eq: "SITE44nUdjjbqSX1sEXuwEWucr"}}) {
    things(filter: {not: {type: {eq: "HVAC_Equipment"}}}) {
      id
      name
      type
    }
  }
}

If you wanted to omit just the results that returned an exact type of Damper, however, you would do something like this:

RequestLive Response
Copy
1
2
3
4
5
6
7
8
9
10
{
  sites(filter: {id: {eq: "SITE44nUdjjbqSX1sEXuwEWucr"}}) {
    things(filter: {exactType: {ne: "Damper"}}) {
      id
      name
      type
      exactType
    }
  }
}

You can also stack the filters to get more granular control - in this case, we'll return only HVAC_Equipment but also omit Dampers from the results:

RequestLive Response
Copy
1
2
3
4
5
6
7
8
9
10
{
  sites(filter: {id: {eq: "SITE44nUdjjbqSX1sEXuwEWucr"}}) {
    things(filter: {type: {eq: "HVAC_Equipment"}, and: {exactType: {ne: "Damper"}}}) {
      id
      name
      type
      exactType
    }
  }
}

Hopefully this guide helps clarify the various filter concepts available - you'll also find additional, usecase specific filter examples in the rest of the docs that may help as well.