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 the GraphQL and JSON schemas defined by the Building Envelope Data (BED) project. See in particular the GraphQL schema for product-data databases and the JSON schema for optical data.

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
`allOpticalData`	Return products in the IGSDBv2 database with optical data measurements (i.e. specular data) for which the `where` clause is true.
`allGeometricData`	Return all products in the IGSDBv2 database with geometric data measurements (i.e. thickness) for which the `where` clause is true.
`entities`	Get a list of entities in the IGSDB database. An entity can have a `COMPANY` type or a `NON_PROFIT` type.

A simple query to return the component ID 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)") {
        ...

You can also filter optical data as in

        
query {
    allOpticalData(
        where: {
            and: [
                { type: { equalTo: GLAZING } },
                { subtype: { notEqualTo: MONOLITHIC } },
                { coatedSide: { in: [ FRONT, BACK ] } }
            ]
        }
    ) {
        edges {
            node {
                componentId
                name
            }
        }
        pageInfo {
            hasNextPage
            startCursor
            endCursor
        }
    }
}

The "allOpticalData" Query Fields

The allOpticalData Query provides among others 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. For a complete list see https://igsdb-v2.herokuapp.com/graphql.

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. See the list of components registered at Building Envelope Data.
`databaseId`	The UUID for the parent database. This is the same for all products in the IGSDBv2, as the database ID for the IGSDB is `48994b60-670d-488d-aaf7-53333a64f1d6` according to the list of databases registered at Building Envelope Data.
`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 allOpticalData or allGeometricData query.

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

That where object can have among others 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 an enumeration 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 an enumeration 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.
`nearnormalHemisphericalVisibleTransmittances`
`nearnormalHemisphericalVisibleReflectances`
`nearnormalHemisphericalSolarTransmittances`
`nearnormalHemisphericalSolarReflectances`
`infraredEmittances`
`resources`
`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.
`not`	This filter field allows you to construct a boolean filter using a "not" 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: {equalTo: MONOLITHIC}}) {
        ...

You can use the and, or, and not filter fields to construct boolean filters. Conjunctions and disjunctions have lists of subfilters as values. Negation has a subfilter as value.

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 Optical Data Products with Locator

Query the token, product ID, name, NFRC ID, and the locator of the first 100 products with optical data in the IGSDBv2 database. The "locator" field gives you an HTTP endpoint for the optical data 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 {
  allOpticalData(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
      }
    }
  }
}

4.6. GraphQL