GraphQL Queries

Datalake is an accelerator specific to power utilities. When enabled, it can be accessed via the menu button ( ) in the top-left corner of the Utilihive Console.

Datalake provides a built-in GraphiQL IDE for writing GraphQL queries against the underlying usage point data. Select "Data services" from the left-hand navigation menu to see the following editor:

The GraphQL editor displays three panes: one for queries,one for query variables,and one for the results.

Queries

The editor comes with two queries already prepared: getOrganizationDetails and listUsagePoints. To run either of these, first select the play button ( ) and then select the desired query. The following image demonstrates this process:

The play button displays a dropdown underneath with two selectable query options.

Executing the listUsagePoints query will display the results in JSON format on the right, similar to the following:

{
  "data": {
    "organization": {
      "DataLake": {
        "listUsagePoints": {
          "count": 100,
          "offset": 0,
          "totalCount": -1,
          "usagePoints": [
            {
              "id": "usagepoint-000a7127-7154-40e2-857a-eff100fa14b3",
              "usagePointDetails": {
                "mrId": "usagepoint-000a7127-7154-40e2-857a-eff100fa14b3"
              }
            },
            {
              "id": "usagepoint-000c09c3-df06-43c9-aa8a-369fd400dd1c",
              "usagePointDetails": {
                "mrId": "usagepoint-000c09c3-df06-43c9-aa8a-369fd400dd1c"
              }
            },
            // etc.
          ]
        }
      }
    }
  }
}

The query as-is doesn’t return a lot of information, but additional fields can be requested. For example, the following query adds a usagePointLocation field to retrieve the lat and lon of each usage point:

query listUsagePoints($organizationShortName: String!, $offset: Int, $count: Int) {
  organization(shortName: $organizationShortName) {
    DataLake {
      listUsagePoints(count: $count, offset: $offset) {
        count
        offset
        totalCount
        usagePoints {
          id
          usagePointDetails {
            mrId
          }
          usagePointLocation {
            lat
            lon
          }
        }
      }
    }
  }
}

The returned JSON will then include the following data:

"usagePoints": [
  {
    "id": "usagepoint-000a7127-7154-40e2-857a-eff100fa14b3",
    "usagePointDetails": {
      "mrId": "usagepoint-000a7127-7154-40e2-857a-eff100fa14b3"
    },
    "usagePointLocation": {
      "lat": 59.92564525266654,
      "lon": 10.69502751389645
    }
  },
  // etc.
]

Query Variables

The listUsagePoints query is initially set to retrieve 100 records. You can adjust this by using the query variables pane near the bottom of the page to update the arguments that are passed to the query. For example, the following JSON would return only five records in the usagePoints list:

{
  "organizationShortName": "my-organization",
  "offset": 0,
  "count": 5
}

These variables become the $ parameters in the query. In the following example, a new query has been created with two parameters: $organizationShortName and $search:

query searchPoints($organizationShortName: String!, $search: String!){
  organization(shortName: $organizationShortName) {
    DataLake {
      searchUsagePoint(query: $search) {
        id
        type
        channels {
          name
          isVirtual
        }
      }
    }
  }
}

This query uses $search in conjunction with searchUsagePoint() to search for usage points that partially match the given string. The following query variables would find all usage points that have the word "office" in their IDs:

{
  "organizationShortName": "my-organization",
  "search": "office"
}

Documentation

The GraphQL editor comes with built-in documentation, so you can explore the other fields and arguments that are available to use. Select the "< Docs" button in the top-right corner to open the documentation explorer. In the explorer, you can search for specific terms or click through the query types. The following image demonstrates searching for the UsagePoint schema:

The documentation explorer displays a search box for UsagePoint and lists the available fields underneath.
If you are not very familiar with GraphQL in general, check out the official GraphQL documentation for additional help.