GraphQL API

The Energy Workbench Server also offers limited support for GraphQL queries. This documentation only provides a basic overview - more information on GraphQL can be found at https://graphql.org/learn/.

Getting started with GraphQL

The Energy Workbench Server GraphQL endpoint provides its own documentation of the queries and fields available in its schema. Some API development tools, such as Insomnia, allow you to view this schema as you build your queries. Using one of these tools is strongly advised to allow full use of the GraphQL functionality, as this page only covers the basics.

All GraphQL queries use the same endpoint:

Type	Path	Description
POST	/ewb/api/graphql	The endpoint for all GraphQL queries.

This endpoint is also composed around the Evolve CIM Profile. As such, the queries below will return objects from this profile.

GraphQL Queries

Query	Description
getIdentifiedObject(mRID: string)	Request an IdentifiedObject by mRID.
getIdentifiedObjects(mRIDs: [string])	Request many IdentifiedObjects by their mRID. The maximum number that can be requested per query is 100. If the list contains more than this the response will be truncated to the first 100 MRIDs that are found. If a requested MRID cannot be found it will be ignored and will not cause an error.
findIdentifiedObjects(criteria: [FindIdentifiedObjectCriteriaInput])	Find all IdentifiedObjects that match the provided criteria. Available criteria are listed below.

FindIdentifiedObjectCriteriaInput fields

Field	Description	Required?
includeClasses: [string]	A list of IdentifiedObject class names that the results will be filtered by.	No
includeNameTypes: [string]	A list of NameType class names that the results will be filtered by.	No
inDiagrams: [string]	The MRIDs of diagrams IdentifiedObjects must have an associated DiagramObject in.	No
limit: int	The maximum number of results to return. This is currently limited to a maximum of 100. If set to larger than 100 results will be capped at 100.	Yes
toMatch: string	The value to match to an IdentifiedObject MRID or name.	Yes

Other GraphQL features

Meta fields

GraphQL provides introspective fields that provide information on the GraphQL schema itself. One of these fields is __typename, which will return the name of the object type. This is useful when requesting IdentifiedObjects, as it returns the specific CIM object type (e.g. AcLineSegment).

Inline fragments

Because all the GraphQL queries return IdentifiedObjects, only IdentifiedObject attributes (mRID, name, description) and meta fields (__typename, type, numDiagramObjects) can be requested and returned by default. To request data from other object types, inline fragments can be used. Inline fragments allow you to query certain fields depending on the type of object returned, using the syntax ... on <typename>{fields}. It's easiest to understand this by looking at the examples included below.

Example queries

Here we are requesting the name and description for three mRIDs, as well as requesting the mRID in the body so we can easily tell which returned object is which. We're also requesting the object type using __typename.

Query:

{
  getIdentifiedObjects(mRIDs: ["abc123", "def456", "ghi789"]){
    name
    description
    mRID
    __typename
  }
}

Response:

{
  "data": {
    "getIdentifiedObjects": [
      {
        "name": "TestObject123",
        "description": "This is a test object"
        "mRID": "abc123"
        "__typename": "Feeder"
      },
      {
        "name": "TestObject456",
        "description": "This is a different test object"
        "mRID": "def456"
        "__typename": "AcLineSegment"
      },
      {
        "name": "TestObject789",
        "description": "And another test object"
        "mRID": "ghi789"
        "__typename": "Breaker"
      }
    ]
  }
}

Once we know the object types, we can start to retrieve specific fields depending on the object type.

Query:

{
  getIdentifiedObjects(mRIDs: ["abc123", "def456", "ghi789"]){
    name
    mRID
    __typename
    # For returned Feeder objects, also request a list of their child equipment objects 
    # that are either Junctions or Disconnectors
    ... on Feeder {
      currentEquipment(types: ["Junction", "Disconnector"]){
        mRID
        name
        __typename
      }
    }
    
    # For returned AcLineSegments, also request the length, the parent feeder(s) mRIDs, 
    # and check if it is underground 
    ... on AcLineSegment{
      length
      currentFeeders{
        mRID
      }
      isUnderground
    }
    
    # For returned Breakers, also check whether the breaker is open 
    ... on Breaker{
      isOpen
    }
  }
}

Response:

{
  "data": {
    "getIdentifiedObjects": [
      {
        "name": "TestObject123",
        "mRID": "abc123",
        "__typename": "Feeder",
        "currentEquipment": [
          {
            "mRID": "junc1",
            "name": "TestJunction1",
            "__typename": "Junction"
          },
          {
            "mRID": "disc1",
            "name": "TestDisconnector1",
            "__typename": "Disconnector"
          },
          {
            "mRID": "junc2",
            "name": "TestJunction2",
            "__typename": "Junction"
          },
          {
            "mRID": "disc2",
            "name": "TestDisconnector2",
            "__typename": "Disconnector"
          },
          {
            "mRID": "junc3",
            "name": "TestJunction3",
            "__typename": "Junction"
          }
        ]
      },
      {
        "name": "TestObject456",
        "mRID": "def456",
        "__typename": "AcLineSegment",
        "length": 4.97348017,
        "currentFeeders": [
          {
            "mRID": "feeder2468"
          }
        ],
        "isUnderground": true
      },
      {
        "name": "TestObject789",
        "mRID": "ghi789",
        "__typename": "Breaker",
        "isOpen": false
      }
    ]
  }
}