This page documents structures used throughout the SolarQuery API.

Datum stream datum are array objects returned from SolarQuery Stream API methods. They are a compact encoding of a datum, without any property names.

Each datum that matches the request criteria is represented as an array with the following items:

• A reference to the datum stream metadata associated with this datum. The metadata defines the property names and their order within this array, as well as the node/location/source/stream IDs associated with the datum stream.
• Datum timestamp
• Instantaneous datum properties, as individual array elements
• Accumulating datum properties, as individual array elements
• Status datum properties, as individual array elements
• Tags, as individual array elements

An example datum stream datum looks like this:

[
  0,
  1650667326308,
  12326,
  null,
  230.19719,
  50.19501,
  6472722,
  "ok",
  "reset"
]

More formally, the datum stream datum array structure looks like this:

The iLen, aLen, and sLen variables represent the number of instantaneous, accumulating, and status datum properties (respectively) included in the metadata associated with the datum. null will be inserted for any property defined in the metadata that the datum does not have.

Take the example datum stream datum array shown previously, in the context of a full response with associated metadata:

{
  "success" : true,
  "meta": [
    {
      "streamId": "7714f762-2361-4ec2-98ab-7e96807b32a6",
      "zone": "Pacific/Auckland",
      "kind": "n",
      "objectId": 123,
      "sourceId": "/power/1",
      "i": [
        "watts",
        "current",
        "voltage",
        "frequency"
      ],
      "a": [
        "wattHours"
      ],
      "s": [
      	"state"
      ]
    }
  ],
  "data": [
    [
      0,
      1650667326308,
      12326,
      null,
      230.19719,
      50.19501,
      6472722,
      "ok",
      "reset"
    ]
  ]
}

Given that metadata, the elements of the datum stream datum array represent:

Datum stream aggregates are array objects returned from SolarQuery Stream API methods. They are a compact encoding of an aggregate datum, without any property names.

Each aggregate datum that matches the request criteria is represented as an array with the following items:

• A reference to the datum stream metadata associated with this datum. The metadata defines the property names and their order within the datum array, as well as the node/location/source/stream IDs associated with the datum stream
• A 2-element array with the aggregate start and end timestamps, as millisecond epoch numbers. For queries where the aggregate period is a fixed value, the end timestamp will be set to null as the value is implied by the aggregate period.
• Instantaneous datum properties, each as 4-element arrays representing the average value, count of values, minimum value, and maximum value.
• Accumulating datum properties, each as 3-element arrays representing the difference between the ending and starting values, the starting value, and the ending value
• Status datum properties, as individual array elements. Not all queries return status properties, so these may be omitted.
• Tags, as individual array elements. Not all queries return tags, so these may be omitted.

An example datum stream datum looks like this:

[
      0,
      [
        1650945600000,
        1651032000000
      ],
      [
        3.6,
        2,
        0,
        7.2
      ],
      [
        19.1,
        2,
        18.1,
        20.1
      ],
      [
        1.422802,
        1138.446687,
        1139.869489
      ],
      "Nominal"
]

More formally, the datum stream aggregate array structure looks like this:

The iLen, aLen, and sLen variables represent the number of instantaneous, accumulating, and status datum properties (respectively) included in the metadata associated with the datum. null will be inserted for any property defined in the metadata that the datum does not have.

Take the example datum stream aggregate array shown previously, in the context of a full response with associated metadata:

{
  "success": true,
  "meta": [
    {
      "streamId": "5514f762-2361-4ec2-98ab-7e96807b3255",
      "zone": "America/New_York",
      "kind": "n",
      "objectId": 123,
      "sourceId": "/pyrometer/1",
      "i": [
        "irradiance",
        "temperature"
      ],
      "a": [
        "irradianceHours"
      ],
      "s": [
        "state"
      ]
    }
  ],
  "data": [
    [
      0,
      [
        1650945600000,
        1651032000000
      ],
      [
        3.6,
        2,
        0,
        7.2
      ],
      [
        19.1,
        2,
        18.1,
        20.1
      ],
      [
        1.422802,
        1138.446687,
        1139.869489
      ],
      "Nominal"
    ]
  ]
}

Given that metadata, the elements of the datum stream aggregate array represent:

Many API methods can return large sets of data, but SolarQuery will break up the results into smaller paged response objects that contain just a subset of the overall data. The response object contains details on the total number of available results along with the starting offset of the returned results:

{
  "success": true,
  "data": {
    "results": [...],
    "totalResults": 2384790,
    "startingOffset": 0,
    "returnedResultCount": 250
  }
}

In the preceding example, 2384790 results are available, but only the first 250 results have been returned in the data array. To get the next set, or page, of results you'd call the same method again but provide a 0-based starting offset for the desired first result. In this case, an offset of 250 would return the next page, which would result in a response like:

{
  "success": true,
  "data": {
    "results": [...],
    "totalResults": 2384790,
    "startingOffset": 250,
    "returnedResultCount": 250
  }
}

For API methods that return paged results objects, the following query parameters are used to specify the page attributes:

An example URL query string to return page 2 of a result set using 100 results per page:

?max=100&offset=100

For API methods that support sorting the result, an array of sort descriptors can be provided on the sorts query parameter. Array parameters must be specified as sort[x].y where x is a 0-based index that specifies the order of the sort descriptor and y is the sort descriptor property as detailed here:

An example URL query string to sort by creation in descending order:

?sorts%5B0%5D.sortKey=created&sorts%5B0%5D.descending=true

In queries like /datum/list that accept sourceId or sourceIds parameters of a source ID value or pattern (or list thereof), a security policy associated with a security token that has a source ID policy can influence the actual source IDs used in query:

1. Non-pattern query source IDs that do not match a policy ID (either exactly or from a policy source ID pattern) will be removed from the query.
2. Query source ID patterns will be removed from the query and then resolved against the policy IDs, with any policy IDs that match added to the query.

Here are some examples to help visualize these rules:

Virtual ID queries are queries where real node or source ID values are combined into results using a virtual ID. Imagine you had several PV inverters on a large solar array, each reporting their energy output on source IDs /pv/1, /pv/2, and /pv/3. You'd like to know the total energy output of all these inverters together. You could query for all 3 source IDs and then add up the results yourself, like this (date parameters omitted):

?nodeId=123&sourceIds=/pv/1,/pv/2,/pv/3&aggregation=Hour

which might return results like this:

[
  {"created":"2018-05-01 12:00:00.000Z", "sourceId":"/pv/1", "wattHours":1000},
  {"created":"2018-05-01 12:00:00.000Z", "sourceId":"/pv/2", "wattHours":1000},
  {"created":"2018-05-01 12:00:00.000Z", "sourceId":"/pv/3", "wattHours":1000},
  {"created":"2018-05-01 13:00:00.000Z", "sourceId":"/pv/1", "wattHours":1000},
  {"created":"2018-05-01 13:00:00.000Z", "sourceId":"/pv/2", "wattHours":1000},
  {"created":"2018-05-01 13:00:00.000Z", "sourceId":"/pv/3", "wattHours":1000}
]

Virtual IDs provide a way to let SolarQuery sum them for you, by mapping the three source IDs into a single virtual ID PV. To do this, you would provide query parameters like this (in addition to those shown before):

?combiningType=Sum&sourceIdMaps=PV:/pv/1,/pv/2,/pv/3&withoutTotalResultsCount=true

This query will return a single result for those three real source IDs, like this:

[
  {"created":"2018-05-01 12:00:00.000Z", "sourceId":"PV", "wattHours":3000},
  {"created":"2018-05-01 13:00:00.000Z", "sourceId":"PV", "wattHours":3000}
]

Node IDs can also be combined into virtual IDs. Imagine a query like this (date parameters omitted):

?nodeIds=123,345&sourceIds=/pv/1,/pv/2,/pv/3&aggregation=Hour

that returned results like this:

[
  {"created":"2018-05-01 12:00:00.000Z", "nodeId":123, "sourceId":"/pv/1", "wattHours":1000},
  {"created":"2018-05-01 12:00:00.000Z", "nodeId":123, "sourceId":"/pv/2", "wattHours":1000},
  {"created":"2018-05-01 12:00:00.000Z", "nodeId":123, "sourceId":"/pv/3", "wattHours":1000},
  {"created":"2018-05-01 12:00:00.000Z", "nodeId":345, "sourceId":"/pv/1", "wattHours":1000},
  {"created":"2018-05-01 12:00:00.000Z", "nodeId":345, "sourceId":"/pv/2", "wattHours":1000},
  {"created":"2018-05-01 12:00:00.000Z", "nodeId":345, "sourceId":"/pv/3", "wattHours":1000}
]

These can be combined into a single -100 virtual ID with query parameters like this (in addition to those shown before):

?combiningType=Sum&nodeIdMaps=-100:123,345&withoutTotalResultsCount=true

that returned results like this:

[
  {"created":"2018-05-01 12:00:00.000Z", "nodeId":-100, "sourceId":"/pv/1", "wattHours":2000},
  {"created":"2018-05-01 12:00:00.000Z", "nodeId":-100, "sourceId":"/pv/2", "wattHours":2000},
  {"created":"2018-05-01 12:00:00.000Z", "nodeId":-100, "sourceId":"/pv/3", "wattHours":2000}
]

Both node IDs and source IDs can be combined at once, so for example you could combine all results into a single virtual source ID PV and node ID -100 with query parameters like:

?combiningType=Sum&nodeIdMaps=-100:123,345&sourceIdMaps=PV:/pv/1,/pv/2,/pv/3&withoutTotalResultsCount=true

which would result in:

[
  {"created":"2018-05-01 12:00:00.000Z", "nodeId":-100, "sourceId":"PV", "wattHours":6000},
]

You can even provide multiple virtual ID mappings, for example to return virtual node IDs -100 and -200 and virtual source IDs PV and LOAD you might have these query parameters:

?combiningType=Sum&nodeIdMaps=-100:123,345&nodeIdMaps=-200:456,678&sourceIdMaps=PV:/pv/1,/pv/2,/pv/3&sourceIdMaps=LOAD:/meter/1,/meter/2&withoutTotalResultsCount=true

The combiningType query parameter defines the operation performed to combine individual results into combined results. See the supported combining types for reference.

Some combining types might be sensitive to the order the individual results are combined in. For example, the Difference type performs a subtraction operation, so the order is significant. The order is defined by the order of the real IDs defined in each nodeIdMaps and sourceIdMaps parameter value. For example, for these query parameters:

?combiningType=Difference&sourceIdMaps=SelfUse:PvGeneration,GridExport&withoutTotalResultsCount=true

defines a subtraction operation like SelfUse = PvGeneration - GridExport.