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. 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(enum))	default=[]	Relationships to include. Allow inclusion of "item".
groupIncludedByType bool	default=false	Alter result format to group included resources by type.

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	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:

  • Defaults to {"$gte": "<now - 7 days>", "$lt": "<now + 7 days>"}
  • 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).
    • 1900 days (1900 * 24 hours) whenrollup is greater than or equal to PT24H (24 hours).
    • Without limit when rollup is window.

• data.filter.times.$lt:

  • Defaults to $gte + 14 days when $gte is set.

• data.filter.times.$gte:

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

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.1beta2' \
  --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.clarify/clarify-go/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)

	// To select item data or meta-data, you must grant the integration access
	// to the "clarify" namespace in the Clarify admin panel.
	result, err := client.DataFrame().TimeRange(t1, t2).RollupBucket(time.Hour).Filter(
		query.Field("annotations.clarify/clarify-go/example/name", query.Equal("publish_signals")),
	).Limit(10).Do(ctx)
	if err != nil {
		panic(err)
	}
	enc := json.NewEncoder(os.Stdout)
	enc.SetIndent("", "  ")
	enc.Encode(result)
}