IGSDB Web Application

GraphQL for IGSDBv2

The IGSDBv2 provides access to its database of products via an experimental GraphQL API endpoint. This document provides a quick overview on the API and some examples of how to list, filter and retrieve product information.

Background

GraphQL is an open-source data query and manipulation language for APIs. Unlike more traditional REST-based APIs, GraphQL APIs allow queries that can pull arbitrary data from nested relationships (the 'graph') with one query. One motivation behind GraphQL effort was to address the issues of overfetching and underfetching data often experienced when using REST APIs.

A GraphQL API was initially added to the IGSDBv1 as part of the Building Envelope Data (ICON) project. That implementation has been updated and extended in IGSDBv2 to continue to support a subset of the GraphQL and JSON schemas defined by the Building Envelope Data project.

IGSDB's GraphQL API

The IGSDB GraphQL API is located here:


            
                https://igsdb-v2.herokuapp.com/graphql

If you visit this page using your browser, the IGSDB website provides you with an implementation of the "GraphiQL" web GUI to access the API. You can use this GUI to test queries against the API. NOTE: You must be logged in to access this page.

Query Definitions

There are two main queries defined by the API:

Query Name	Purpose
`allData`	Return all products in the IGSDBv2 database.
`allOpticalData`	Return all products in the IGSDBv2 database with optical data measurements (i.e. specular data).
`entities`	Get a list of entities in the IGSDB database. An entity can have a `COMPANY` type or a `NON_PROFIT` type.
`institutions`	"Institution" is a BED term, and it corresponds directly to the Entity model in the IGSDB v2 database. An "institution" can have a `COMPANY` type or a `NON_PROFIT` type. This query is included to support the query terms expected by Building Envelope Data project.

A simple query to return the componentId and name of all products with optical data would be

        
query {
    allOpticalData {
        edges {
            node {
                componentId
                name
            }
        }
        pageInfo {
            hasNextPage
            startCursor
            endCursor
        }
    }
}

As shown in the above query, our GraphQL API expects the use of "edges" and "node" to structure results. This follows the convention specified by the Relay cursor connections specification.

Results are paginated by default, and a maximum of 100 records are returned on one page.

To control the number of records returned, you can use the first argument. For example, to return the first 10 records, you can use:

    
query {
    allOpticalData(first: 10) {
        edges {
            node {
                componentId
                name
            }
        }
        pageInfo {
            hasNextPage
            startCursor
            endCursor
        }
        totalCount
    }
}

The optional totalCount field returns the total number of records that match the query.

Pagination information is returned by including the optional pageInfo field. This field can have the following subfields:

hasPreviousPage
hasNextPage
startCursor
endCursor

When using pagination, you can control which page to start at by using the after argument. For example:

    
query {
    allOpticalData(first: 50, after: "(endCursor value returned in last query)") {
        ...

The "allOpticalData" Query Fields

The allOpticalData Query provides the following fields that can be used to indicate the type of data to be returned. These fields are defined by the Building Envelope Data standard.

Field Name	Purpose
`componentId`	The UUID (Universally Unique Identifier) for this product, which is the same in both the IGSDB and in the Building Envelope Data metabase.
`databaseId`	The UUID for the parent database. This is the same for all products in the IGSDBv2, as the databaseId for the IGSDB is `ffbf9d8a-7761-4aec-b982-d4db99ee8a89`
`timestamp`	The date and time the product was created or last updated.
`description`	A short description of the product, if available.
`nearnormalHemisphericalVisibleTransmittances`	An array of two values, the first of which is the "front" visible transmittance and the second of which is the "back" visible transmittance. (corresponds to `tf_vis` and `tb_vis`.)
`nearnormalHemisphericalVisibleReflectances`	An array of two values, the first of which is the "front" visible reflectance and the second of which is the "back" visible reflectance. ( corresponds to `rf_vis` and `rb_vis`. )
`nearnormalHemisphericalSolarTransmittances`	An array of two values, the first of which is the "front" solar transmittance and the second of which is the "back" solar transmittance. ( corresponds to `tf_sol` and `tb_sol`. )
`nearnormalHemisphericalSolarReflectances`	An array of two values, the first of which is the "front" solar reflectance and the second of which is the "back" solar reflectance. ( corresponds to `rf_sol` and `rb_sol`. )
`infraredEmittances`	An array of two values, the first of which is the "front" infrared emittance and the second of which is the "back" infrared emittance. ( corresponds to `emis_front` and `emis_back`. )
`resourceTree`	A Building Envelope Data "resource tree" object, which provides a list of resources associated with the product. Each resource is a JSON object with a nested "locator" field that provides an HTTP endpoint for the resource.

The Query Filters

A set of basic filters are available on both queries. We hope to increase the number and types of filters available over time.

Filtering is performed by including a where object argument to either the allData or allOpticalData query.

    
        query {
            allOpticalData(where: { ... }) {
                ...
            }
        }

That where object can have the following filter fields:

Filter Field
`componentId`	Filter by the `componentId` of the product. The "componentId" is a uuid (universally unique identifier) for the product in both the IGSDBv2 database and the Building Envelope Data metabase. If this filter is used, it must be defined using the `equalTo` subfield.
`token`	Filter by the `token` of the product. The "token" is a unique identifier for the product in the IGSDBv2 database. If this filter is used, it must be defined using the `equalTo` subfield.
`type`	Filter by the `type` of the product. The "type" is a string value, either "GLAZING" or "SHADING". These are the only two types of products currently represented in the IGSDBv2. If this filter is used, it must be defined using the `equalTo` subfield.
`subtype`	Filter by the `subtype` of the product. The "subtype" is a string value with one of the following values: `MONOLITHIC` `LAMINATE` `INTERLAYER` `EMBEDDED_COATING` `COATED` `COATING` `APPLIED_FILM` `FILM` `VENETIAN_BLIND` `DIFFUSING_SHADE` `ROLLER_SHADE` `WOVEN_SHADE` `VERTICAL_LOUVER` `PERFORATED_SCREEN` `CELLULAR_SHADE` `PLEATED_SHADE` `ROMAN_SHADE` `SHADE_MATERIAL` `FRITTED_GLASS` `ACID_ETCHED_GLASS` `SANDBLASTED_GLASS` `CHROMOGENIC` If this filter is used, it must be defined using the `equalTo` subfield.
`and`	This filter field allows you to construct a boolean filter using an "and" boolean logical operator. See the section below on "Boolean Filters" for more information.
`or`	This filter field allows you to construct a boolean filter using an "or" boolean logical operator. See the section below on "Boolean Filters" for more information.

For example, to return all products with a subtype of "MONOLITHIC", you can use:

    
query {
    allOpticalData(where: {subtype: "MONOLITHIC"}) {
        ...

You can use the and and or filter fields to construct a boolean filter. The following filter fields can be included in the and and or filter fields. :

And / Or Filter Field
`nearnormalHemisphericalVisibleTransmittances`
`nearnormalHemisphericalVisibleReflectances`
`nearnormalHemisphericalSolarTransmittances`
`nearnormalHemisphericalSolarReflectances`
`infraredEmittances`
`resources`

Each of these And/Or filter fields can include the following subfields

And / Or Filter Subfield
`dataFormatId`
`some`
`equalTo`
`greaterThanOrEqualTo`
`lessThanOrEqualTo`
`lessThanOrEqualTo`

So, for example, one might use the and field to search for optical data in the following way

    
query {
  allOpticalData(
    where: {
      and: [
        {
          nearnormalHemisphericalVisibleTransmittances: {
            some: { greaterThanOrEqualTo: 0.9 }
          }
        }
        {
          nearnormalHemisphericalVisibleReflectances: {
            some: { lessThanOrEqualTo: 0.01 }
          }
        }
      ]
    }
  ) {
    edges {
      node{
      componentId
      token
      nfrcId
      nearnormalHemisphericalSolarReflectances
      nearnormalHemisphericalSolarTransmittances
      nearnormalHemisphericalVisibleReflectances
      nearnormalHemisphericalVisibleTransmittances
      infraredEmittances
      resourceTree {
        root {
          value {
            locator
          }
        }
      }
      }
    }
  }
}

Example Queries

Here are a few queries you can use to exercise the GraphQL API. These queries are based on some of the basic queries defined by the Building Envelope Data specification.

Example: All Products

List the 'token', 'product ID' and 'name' property of all products in the IGSDBv2 database:

        
query {
  allData {
    edges {
      node {
        token
        componentId
        name
        nfrcId
      }
    }
  }
}

Example: All Optical Data Products with Locator

Do the same list as the last query, but this time return only optical data. Also, include the Building Energy Data "locator" field, which gives you an HTTP endpoint for a description of the product in BED JSON format.

        
query {
  allOpticalData {
    edges {
      node {
        token
        componentId
        name
        nfrcId
        resourceTree {
          root {
            value {
              locator
            }
          }
        }
      }
    }
  }
}

Example: All COATED Products

List the 'componentId' and 'name' property of all products in the IGSDBv2 database of subtype 'COATED':


query {
  allData(where:{subtype:"COATED"}) {
    edges {
      node {
        componentId
        name
        token
        nfrcId
      }
    }
  }
}

Example: Optical Properties for One Product

List some of the optical data properties of one particular product, keyed by componentId


query {
  allOpticalData(
    where: {
        componentId: {
            equalTo: "d5ce8bbb-3d25-48e6-88d7-329a179f201f"
        }
    }
  )
  {
    edges {
      node {
          componentId
          token
          nfrcId
          nearnormalHemisphericalSolarReflectances
          nearnormalHemisphericalSolarTransmittances
          nearnormalHemisphericalVisibleReflectances
          nearnormalHemisphericalVisibleTransmittances
          infraredEmittances
          resourceTree {
            root {
              value {
                locator
              }
            }
          }
        }
    }
  }
}

Example: Entity Information

List entities.


query {
  entities {
    edges {
      node {
        entityId
        name
        type
      }
    }
  }

List institutions. "Institution" is the BED terminology for an entity. (This query is a convenience query for BED users and returns the same data as the entities query.)


query {
  institutions {
    edges {
      node {
        entityId
        name
        type
      }
    }
  }

4.6. GraphQL