integration.insert

This call inserts data for one or more signals. Each signal is uniquely identified by its input ID in combination with the integration ID. If no signal with the given combination exists, an empty signal is created.

An integration can only interact with it's own signals using this call.

Example

cURL

# BASIC_AUTH_USERNAME=<Username from Basic Auth credentials>
# BASIC_AUTH_PASSWORD=<Password from Basic Auth credentials>
# INTEGRATION_ID=${BASIC_AUTH_USERNAME}
curl -u ${BASIC_AUTH_USERNAME}:${BASIC_AUTH_PASSWORD} \
  --request POST \
  --url https://api.clarify.io/v1/rpc \
  --header 'Content-Type: application/json' \
  --header 'X-API-Version: 1.0' \
  --data \
  '
    {
      "jsonrpc" : "2.0",
      "method": "integration.Insert",
      "id": "1",
      "params": {
        "integration": "'${INTEGRATION_ID}'",
        "data":{
          "times" : ["2021-03-11T21:00:00Z", "2021-03-11T22:00:00Z"],
          "series": {
            "a": [1.0, 1.2],
            "b": [2.0, null]
          }
        }
      }
    }
  '

Python

from pyclarify.client import APIClient
from pyclarify.data import DataFrame
from datetime import datetime

client = APIClient(credentials=open("credentials.json"))

t1 = datetime.now()
t2 = t1 + datetime.timedelta(hours=1)
df = DataFrame(
    times=[t1, t2],
    series={
        "a":[1.0, 1.2],
        "b":[2.0, None],
    },
)

client.insert(df)

Go

package main

import (
    "context"
    "time"

    clarify "github.com/clarify/clarify-go"
    "github.com/clarify/clarify-go/data"
)

func main() {
    creds, err := clarify.CredentialsFromFile("credentials.json")
    if err != nil {
        panic(err)
    }

    ctx := context.Background()
    client := creds.Client(ctx)

    t1 := data.AsTimestamp(time.Now())
    t2 := t1.Add(data.Hour)
    df := data.Frame{
        "a": {t1: 1.0, t2: 1.2},
        "b": {t1: 2.0},
    }

    if _, err := client.Insert(df).Do(ctx); err != nil {
        panic(err)
    }
}

Method parameters

Name	Type	Required	Description
integration	Integration ID	Yes	The ID if the integration to save signal information for.
data	Data frame	Yes	The data to insert accompanied by timestamps.

Result properties

Name	Type	Description
signalsByInput	map of Input ID => Create summary	Save operation summary per input.

Limits

Data limitations:

• Signals SHOULD not have an average same rate of more than 1 sample/min.
• Signals SHOULD not have a burst sample rate of more than 1 sample/sec.
• Clarify CAN NOT show timestamps with more than one millisecond resolution (ms).
• Clarify CAN NOT store timestamps with more than microsecond (µs).

Be aware that you are charged per signal you store in Clarify. If you have many signals, be sure to adjust your plan in Clarify.

Schema references

Create summary

type: object

Example

{
  "id": "c9137visahsjsdhrim6g",
  "created": true
}

Properties

Name	Type	Description
id	string	Unique ID of the saved resource entry.
created	boolean	True if a new instance was created.

Integration ID

Integration ID unqily identies a integration resourc entry.

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

Data frame

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

type: object

Example

{
  "times": [
    "2021-03-11T21:49:00Z",
    "2021-03-11T21:50:00Z",
    "2021-03-11T21:51:00.00123Z",
    "2021-04-08T00:00:00Z"
  ],
  "series": {
    "banana-stand-icecream-temperature": [-10.0, 10.0, 20, 55.3, 231, 34],
    "banana-stand-cache-reserve": [10000000, null, null, null, null, 0]
  }
}

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 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).

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}$)