Version: Next

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.

There are two GraphQL endpoints:

Type	Path	Description
POST	/ewb/api/graphql	The endpoint for all network or diagram related GraphQL queries.
POST	/ewb/api/graphql/customers	Endpoint for customer data - any type that is captured by the `CustomerService`.
POST	/ewb/api/graphql/diagrams	Endpoint for diagram data - any type that is captured by the `DiagramService`.

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

GraphQL Queries

Available on the /ewb/api/graphql endpoint:

Lookup 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.
`findIdentifiedObjectsByName(criteria: [NameSearchInput], includeClasses: [string])`	Find all IdentifiedObjects that match the provided name search criteria. Available criteria are listed below.
`getAssetInfo(types: [string])`	Retrieve all AssetInfo and PerLengthLineParameter by class type. `types` must be valid descendant classes of `AssetInfo` or `PerLengthLineParameter`.
`getNetworkHierarchy()`	Retrieve the network hierarchy of the currently running server, containing the `GeographicalRegions`, `Circuits`, `Loops`, and down to the `LvFeeders`.
`getMetadata()`	Retrieve the metadata for the currently running network, including the running server and version, plus the data sources used to produce the model.
`getGeoViewConfig()`	Retrieve the GeoView configuration for this server. Contains zoom and visibility rules for the map.
`getPublicGeoViewConfig()`	Retrieve the GeoView configuration for the public map tile endpoint, if enabled. Contains zoom and visibility rules for the public map if enabled, otherwise returns null.
`getNetworkModels()`	Retrieve the network-model databases available to be loaded on this server.
`getSupplyingTransformers(criteria: [NameOrMRIDInput])`	Find all supplying transformer that matches the provided criteria. The supplying transformers for a given object will be all immediate upstream transformers.
`getUnknownConnectivityEnergyConsumers(mRIDs: [string])`	Find all EnergyConsumers connected to an EquivalentBranch which is attached to the provided EquipmentContainer mRIDs. This will typically be all EnergyConsumers where their exact connectivity in the network is unknown, and so they have been attached at the head of the Feeder or LvFeeder.

Network tracing queries:

Query	Description
`getDownstreamEquipmentTree(mRID: string, includeFilter: [string], excludeFilter: [string], networkState: [NetworkState])`	Request a tree from a downstream equipment trace, given the MRID of a conducting equipment to be used as the root. A depth-first sorted list of nodes is returned.
`getDownstreamEquipment(mRID: string, includeFilter: [string], excludeFilter: [string], networkState: [NetworkState])`	Request the downstream equipment from the given `mRID` for the desired `NetworkState` (default `NORMAL`).
`findUpstreamEquipment(mRID: string, type: string, networkState: [NetworkState])`	Request a list of equipment of a specific CIM type encountered in an upstream trace starting at a given equipment, usage point, or meter, and stopping at matching equipment. Loops in the upstream network result in multiple branches in this trace, in which case more than one matching equipment may be returned.
`getUpstreamEquipment(mRID: string, stopType: string, stopMRID: string, includeFilter: [string], excludeFilter: [string], networkState: [NetworkState])`	Request a list of equipment from an upstream equipment trace, given the MRID of a conducting equipment to be used as the starting point, and tracing to the feeder head, A reversed depth-first sorted list of equipment is returned. Optionally specify a type and/or an mRID as a stopping point rather than the feeder head.
`getConnectedEquipment(mRID: string, steps: Int?, includeFilter: [string], excludeFilter: [string], networkState: [NetworkState])`	Request a list of equipment connected to a specific piece of equipment by a maximum number of steps in a given direction.
`getIsolatedEquipment(isolationPoints: [IsolationQueryExtent], insideIsolation: [IsolationQueryExtent]?, maxSwitches: Int, includeFilter: [string], excludeFilter: [string], networkState: [NetworkState])`	Request the equipment that belongs to an isolation area. You can optionally request only equipment of a specified type.

Available on the /ewb/api/graphql/customers endpoint:

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.
`findIdentifiedObjectsByName(criteria: [NameSearchInput], includeClasses: [string])`	Find all IdentifiedObjects that match the provided name search criteria. Available criteria are listed below.
`getMetadata()`	Retrieve the metadata for the currently running network, including the running server and version, plus the data sources used to produce the model.
`getCustomerSymbols()`	Retrieve the set of all symbols used by `Customers`. Returns a set of all style strings from each `DiagramObject` associated with a `Customer`.
`getAllSymbols()`	Retrieve the set of all symbols used in the `CustomerService`. Returns a set of all style strings from each `DiagramObject` associated with any object inside the `CustomerService`.

Available on the /ewb/api/graphql/diagrams endpoint:

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.
`findIdentifiedObjectsByName(criteria: [NameSearchInput], includeClasses: [string])`	Find all IdentifiedObjects that match the provided name search criteria. Available criteria are listed below.
`getMetadata()`	Retrieve the metadata for the currently running network, including the running server and version, plus the data sources used to produce the model.
`getDiagramObjects(mRIDs: [string])`	Retrieve the diagram objects for the given `IdentifiedObject` mRIDs.

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

NameSearchInput fields

Field	Description	Required?
`nameType: string`	The NameType name that the results will be filtered by.	Yes
`names: [string]`	All possible names to search for.	Yes

NameOrMRIDInput fields

Field	Description	Required?
`nameSearchInput: NameSearchInput`	A NameSearchInput if searching on names within a specific NameType.	No
`mRIDs: [string]`	The mRIDs of an IdentifiedObject.	No

This input allows searching across NameType names or exact mRIDs to retrieve results.

Note that at least one of nameSearchInput or mRIDs must be provided.

IsolationQueryExtent fields

Field	Description	Required?
`mRID: string`	The mRID of the isolating equipment.	Yes
`longitude: Double?`	An optional longitude on the isolating equipment where the isolation occurs. This is only used by an [AcLineSegment], and will be ignored for any other equipment type. If provided, a [latitude] must also be provided	No
`latitude: Double?`	An optional latitude on the isolating equipment where the isolation occurs. This is only used by an [AcLineSegment], and will be ignored for any other equipment type. If provided, a [longitude] must also be provided	No

Query notes

getUnknownConnectivityEnergyConsumers

Unknown connectivity consumers are EnergyConsumers that have limited connectivity information. For example, EnergyConsumers that we know are supplied by a certain distribution PowerTransformer or Feeder, but we don't know exactly where they are connected on that feeder/transformer. These EnergyConsumers will be attached to an EquivalentBranch connected to the head of the relevant Feeder/LvFeeder.

getSupplyingTransformers

Supplying transformers are defined as the transformer which normally provides power for the requested mRID. This query will find all supplying transformers for the requested search criteria. The supplying transformers for a given object will be all immediate upstream transformers, which could be one or many distribution PowerTransformers, or in the case of HV equipment, the zone PowerTransformer, if it is present in the modelled network.

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 many of 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.

Bounding Boxes

Trace GraphQL responses include a BoundingBox which defines a rectangular geographic area defined by the most south-west and north-east corners of the IdentifiedObjects returned within the GqlResponse. This bounding box can be used to identify geographic areas and speed up the process of visualising the network on a geographic map.

Polygon

Trace GraphQL responses include a Polygon which defines a convex polygon encompassing the locations(if available) of the IdentifiedObject's returned within the GqlResponse. This Polygon can provide a more refined geographic region encompassed by the network equipment returned in the trace query.

Network Trace Metrics

Trace GraphQL responses include a metrics field that provides detailed network trace metrics for the identified objects returned in the response.

Query Field	Description
`getConductorLengthMetrics`	Returns conductor length metrics grouped by phase, voltage, and line type.
`getConnectedKVAMetrics`	Returns connected transformer KVA metrics grouped by phase, voltage, and transformer function.
`getConnectedCustomersMetrics`	Returns connected customer metrics grouped by phase and voltage.
`getConductorLengthMetricAggregate(acLineType, voltage, numPhases, phaseKinds, phaseCodes)`	Returns aggregated conductor length metrics. Optional filters: • `acLineType` – Filter by line type (e.g., UG, OG). • `voltage` – Filter by voltage level. • `numPhases` – Filter by number of phases. • `phaseKinds` – Filter by a list of specific single phases. This filter will include all conductors that have at least one of the specified phases. • `phaseCodes` – Filter by list of phase codes.
`getConnectedKVAMetricAggregate(voltage, numPhases, transformerFunctionKind, phaseCodes)`	Returns aggregated transformer KVA metrics. Optional filters: • `voltage` – Filter by voltage level. • `numPhases` – Filter by number of primary winding phases. • `transformerFunctionKind` – Filter by transformer function. • `phaseCodes` – Filter by phase code on primary winding.
`getConnectedCustomersMetricAggregate(voltage, numPhases, phaseCodes)`	Returns aggregated customer count metrics. Optional filters: • `voltage` – Filter by voltage level. • `numPhases` – Filter by number of phases. • `phaseCodes` – Filter by list of phase codes.

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
      }
    ]
  }
}

Getting started with GraphQL​

GraphQL Queries​

FindIdentifiedObjectCriteriaInput fields​

NameSearchInput fields​

NameOrMRIDInput fields​

IsolationQueryExtent fields​

Query notes​

getUnknownConnectivityEnergyConsumers​

getSupplyingTransformers​

Other GraphQL features​

Meta fields​

Inline fragments​

Bounding Boxes​

Polygon​

Network Trace Metrics​

Example queries​