clarify.selectItems

Require access to Clarify namespace

For an integration to access this method, it must have been granted access to the Clarify namespace in Clarify.

This method retrieves item meta-data and/or associated time series data.

Example

cURL

# BASIC_AUTH_USERNAME=<Username from Basic Auth credentials>
# BASIC_AUTH_PASSWORD=<Password from Basic Auth credentials>
# INTEGRATION_ID=${BASIC_AUTH_USERNAME}
curl --request POST \
  --url 'https://api.clarify.io/v1/rpc' \
  --header 'content-type: application/json' \
  --header 'Authorization: Bearer <YOUR ACCESS TOKEN>' \
  --header 'X-API-Version: 1.1' \
  --data \
  '
    {
      "jsonrpc": "2.0",
      "method": "clarify.selectItems",
      "id": 10,
      "params": {
        "integration": "'${INTEGRATION_ID}'",
        "signals": {
          "include": true,
          "filter": {"createdAt":{"$gte": "2022-01-01T00:00:00Z"}},
          "limit": 2
        },
        "items": {
          "include": true
        }
      }
    }
  '

Method parameters

type: object

Name	Type	Properties	Description
items	Resource query	default = {}	Query which items to select, and configure inclusion or exclusion of meta-data in the response. By default, no meta-data is included.
data	Data query	default = {}	Configure which data to include in the response.

Response result

type: object

Properties

Name	Type	Presence	Description
items	map of Item ID => Item select view	When items.included is true.	Selected Items meta-data.
data	Data Frame	when data.included is true,	time series data.

Limits

Items query:

• items.limit can maximum be:

  • 50 if data.include == true.
  • 1000 otherwise.

Data query:

• Time window data.notBefore -> data.before can maximum be:
  • 40 days when data.rollup < "PT1M" or data.rollup == null.
  • 400 days when data.rollup >= "PT1M" or data.rollup == "window".

Schema references

Data frame

The exact format of the keys in the "series" property depend on your query:

• If data.rollup is configured, the keys will be "<item id>_(sum|min|max|avg|count)".
• If data.rollup is not configured, the keys will be "<item id>".

Data frame holds data for one or more time-series.

type: object

Properties

Name	Type	Required	Description
times	array of Timestamp	Yes	Array of timestamps to insert.
series	map of Input ID => array of (number or null)	Yes	Array of data points to insert by Input ID. The length of each array must match that of the times array. To omit a value for a given timestamp in times, use the value null.

Timestamp

type: string OR number(integer)

Timestamp must either be a RFC 3339 date-time string or an integer containing a UNIX timestamp. A UNIX timestamp is always defined as the number of seconds that has elapsed since the "epoch" (1970-01-01T00:00:00:00Z).

When using an RFC 3339 date-time string, Clarify can store a maximum resolution of one microsecond (µs).

Examples

Raw response:

{
  "times": [
    "2021-03-11T21:49:00Z",
    "2021-03-11T21:50:00Z",
    "2021-03-11T21:51:00.00123Z",
    "2021-04-08T00:00:00Z"
  ],
  "series": {
    "c92rtu2sahsul7t74fag": [-10, 10, 20, 55.3, 231, 34],
    "c92rujqsahsunml6lo00": [10000000, null, null, null, null, 0]
  }
}

Rollup response ("PT1H"):

{
  "times": ["2021-03-11T21:00:00Z", "2021-04-08T00:00:00Z"],
  "series": {
    "c92rtu2sahsul7t74fag_avg": [61, 34],
    "c92rtu2sahsul7t74fag_count": [5, 1],
    "c92rtu2sahsul7t74fag_max": [-10.0, 34],
    "c92rtu2sahsul7t74fag_min": [231, 34],
    "c92rtu2sahsul7t74fag_sum": [306, 34],
    "c92rujqsahsunml6lo00_avg": [10000000, 0],
    "c92rujqsahsunml6lo00_count": [1, 0],
    "c92rujqsahsunml6lo00_max": [10000000, null],
    "c92rujqsahsunml6lo00_min": [10000000, null],
    "c92rujqsahsunml6lo00_sum": [10000000, 0]
  }
}

Rollup response ("window"):

{
  "times": ["2021-03-11T21:00:00Z"],
  "series": {
    "c92rtu2sahsul7t74fag_avg": [55.666667],
    "c92rtu2sahsul7t74fag_count": [6],
    "c92rtu2sahsul7t74fag_max": [-10.0],
    "c92rtu2sahsul7t74fag_min": [231],
    "c92rtu2sahsul7t74fag_sum": [340],
    "c92rujqsahsunml6lo00_avg": [5000000],
    "c92rujqsahsunml6lo00_count": [2],
    "c92rujqsahsunml6lo00_max": [10000000],
    "c92rujqsahsunml6lo00_min": [10000000],
    "c92rujqsahsunml6lo00_sum": [10000000]
  }
}

Data query

type: object

Properties

Name	Type	Properties	Description
include	bool	default = false	Selected Items meta-data.
notBefore	null or string(RFC 3339 timestamp)	default = 7 days ago	Do not include data before the specified time
before	null or string(RFC 3339 timestamp)	default = 14 days after notBefore	Include only data before the specified time

Input ID

Input ID routes data to a signal during insert. The input ID must be unique per integration only.

type: string(regex: ^[a-zA-Z0-9-_:.#+/]{1,128}$)

Item ID

Item ID uniquely identities a item resource entry.

type: string(regex: "^[a-v0-9]{20}$")

Item select view

The item select view lists all exposed item fields.

type: object

Properties

Name	Type	Description
id	string(regex: "^[a-v0-9]{20}$")
meta	Resource meta
annotations	map of string(regex: "^[A-Za-z0-9-_/]{1,128}$") => string	Arbitrary configuration parameters. Customer-provided annotations should use a relevant prefix, e.g. company-domain/application-name/.
name	string	The default signal display name.
type	string(numeric or enum)	The default signal type.
description	string	The default signal description
labels	map of string(regex: "^[A-Za-z0-9-_/]{1,128}$") => array of string	The default signal labels.
engUnit	string	Default signal display unit, used in numeric representations.
enumValues	map of string(integer in range 0-9999) => string	Default item enum values, used to replace numeric values with text in enumerated representations.
sourceType	string("measurement" or "aggregation" or "prediction")	Default item source type.
sampleInterval	null or string(RFC 3339 duration)	How often the signal is sampled (on average).
gapDetection	null or string(RFC 3339 duration)	The default item gap detection. A gap will be drawn whenever there is no data for a duration longer than the specified value.

Example

{
  "name": "Ice Cream Temperature",
  "type": "numeric",
  "description": "Temperature measurement of the ice cream",
  "labels": {
    "flavours": ["sweet", "sour"],
    "location": ["pier", "banana stand"]
  },
  "engUnit": "°C",
  "sourceType": "measurement",
  "sampleInterval": "PT1M",
  "gapDetection": "PT5M"
}

Resource meta

type: object

Properties

Name	Type	Description
contentHash	string	Hash of "relevant" fields in the resource (better definition in expected next API version)
createdAt	string(RFC 3339 timestamp)	When the resource was created.
updatedAt	string(RFC 3339 timestamp)	When the resource was updated.

Resource query

Query a resource in Clarify.

type: object

Properties

Name	Type	Properties	Description
include	boolean	default = null	Set to true to include matched resources in the response.
filter	Resource filter	default = {}	Filter which resources to include.
limit	integer	default = 10	Number of resources to include in the result.
skip	integer	default = 0	Skip the first N items.