clarify.dataFrame

Require access to Clarify namespace

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

A data method for selecting item time-series data. This method allow extraction of raw data as well as rollup aggregation using item defaults. That is, "count", "min", "max", "sum" and "avg" for numeric items, and "state-histogram-seconds" including all available state values for enum items. For more control over the rollup operations, including support for fast and powerful server-side calculations, we recommend using the clarify.evaluate method instead. Associated items can be side-loaded.

Method parameters

Parameter	Properties	Description
query Resource query	default={}	Resource query to select items.
data Data query	default={}	Data query to filter/aggregate the returned data frame.
include array(string("item"))	default=[]	Relationships to include.
format Selection format	default={"dataAsArray":false,"groupIncludedByType":false}	Configure result format.

Result

The result contains a data frame with either raw or aggregated time-series data, as well as side-loaded item meta-data if requested.

type: object

Field	Description
meta Selection meta	Selection meta data.
data Data frame,array(Data frame)	A matrix view of selected/aggregated data points.
included array(resource),map(string => array(resource))	Side-loaded resources from relationships.

Limits

Query:

• query.limit:

  • default is 10.
  • maximum is 50.

Data query:

• data.filter.times:

  • Maximum window size is:
    • 40 days (40 * 24 hours) when rollup is null or less than PT1M (1 minute).
    • 400 days (400 * 24 hours) whenrollup is greater than or equal to PT1M (1 minute).
    • about 5 years (1900 * 24 hours) whenrollup is greater than or equal to PT24H (24 hours).
    • about 13 years (3660 * 24 hours) whenrollup is greater than or equal to P30D (40 days).
    • Without limit when rollup is window.

• data.filter.times.$gte:

  • Defaults to $lt - 14 days when $lt is set.
  • Defaults to now - 7 days otherwise.

• data.filter.times.$lt:

  • Defaults to $gte + 14 days.

Example

cURL

The curl example uses Basic Auth for simplicity.

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.1' \
  --data \
  '
  {
    "jsonrpc": "2.0",
    "id": 1,
    "method": "clarify.dataFrame",
    "params": {
      "query": {
        "filter": {
          "annotations.docs-clarify-io/example/name": "publish_signals"
        },
        "limit": 10,
        "skip": 0,
        "total": true
      },
      "data": {
        "filter":{
          "times": {
            "$gte": "2022-01-01T01:01:01Z",
            "$lt": "2022-02-01T01:01:01Z"
          }
        },
        "rollup": "PT24H"
      },
      "include": ["item"]
    }
  }
  '

Python

from datetime import datetime, timedelta
from pyclarify import Client, query


client = Client("./clarify-credentials.json")

filter = query.Filter(fields={
    "annotations.docs-clarify-io/example/name": query.Equal(value="publish_signals")
})

t1 = datetime.now() - timedelta(hours=24)
t2 = datetime.now() + timedelta(hours=24)

response = client.data_frame(
    filter=filter,
    gte=t1,
    lt=t2,
    rollup=timedelta(hours=24),
    limit=10,
    include=["item"]
)

data = response.result.data

Go

package main

import (
    "context"
    "encoding/json"
    "os"
    "time"

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

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

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

    t1 := time.Now().Add(-24 * time.Hour)
    t2 := time.Now().Add(24 * time.Hour)

    query := fields.Query().
        Where(fields.CompareField("annotations.docs-clarify-io/example/name", fields.Equal("publish_signals"))).
        Limit(10)

    data := fields.Data().
        Where(fields.TimeRange(t1, t2)).
        RollupDuration(time.Hour, time.Monday)

    result, err := client.Clarify().DataFrame(query, data).Do(ctx)
    if err != nil {
        panic(err)
    }
    enc := json.NewEncoder(os.Stdout)
    enc.SetIndent("", "  ")
    enc.Encode(result)
}