Views

Resources in Clarify, are accessed through views. Resource save views are used when creating and updating resources, while resource select views are used to expose them. Data that's assocaited with resources is uploaded and exposed through data views.

Resource save views

Resource save views are views used to create or update resources. Schema definition for resource save views are as follows:

Field / alias	Semantics	Default
field-name[ / alias-name]	merge OR replace	value that's used when omitted

// Common template for resource save views.
{
  "annotations": {
    "<key>": "<value>"
  },
  "<attribute field>": <attribute value>
}

Signal save (integration namespace)

The signal save view allow replacing all signal attributes except input, and patching the annotations field.

type: object

Field / alias	Semantics	Default
annotations	merge	N/A
name	replace	input value
description	replace	""
labels	replace	{}
sourceType	replace	"measurement"
valueType / type	replace	"numeric"
engUnit	replace	""
enumValues	replace	{}
sampleInterval	replace	null
gapDetection	replace	null

Examples

// Numeric signal.
{
  "annotations": {
    "docs-clarify-io/example/development": "arrested"
  },
  "name": "Amount",
  "description": "Amount of money at location, counted manually.",
  "labels": {
    "location": ["banana stand", "pier"],
    "data-source": ["manual"]
  },
  "sourceType": "measurement",
  "valueType": "numeric",
  "engUnit": "USD"
}
// Enum signal.
{
  "annotations": {
    "docs-clarify-io/example/development": "arrested"
  },
  "name": "Building status",
  "description": "The overall state of the building, aggregated from environmental sensors.",
  "labels": {
    "location": ["banana stand", "pier"],
    "data-source": ["environmental sensors"]
  },
  "sourceType": "aggregate",
  "valueType": "enum",
  "enumValues": {
    "0": "not on fire",
    "1": "on fire"
  }
}

Item save (admin namespace)

The item save view allow replacing all item attributes, and patching the annotations field.

type: object

Field / alias	Semantics	Default
annotations	merge	N/A
name	replace	signal value
description	replace	""
labels	replace	{}
sourceType	replace	signal value
valueType	replace	signal value
engUnit	replace	""
enumValues	replace	{}
sampleInterval	replace	null
gapDetection	replace	null

Examples

// Numeric item.
{
  "annotations": {
    "docs-clarify-io/example/development": "arrested"
  },
  "name": "Amount",
  "description": "Amount of money at location, counted manually.",
  "labels": {
    "location": ["Banana Stand", "Pier"],
    "data-source": ["Manual"]
  },
  "sourceType": "measurement",
  "valueType": "numeric",
  "engUnit": "USD"
}
// Enum item.
{
  "annotations": {
    "docs-clarify-io/example/development": "arrested"
  },
  "name": "Building status",
  "description": "The overall state of the building, aggregated from environmental sensors.",
  "labels": {
    "location": ["Banana Stand", "Pier"],
    "data-source": ["Environmental Sensors"]
  },
  "sourceType": "aggregate",
  "valueType": "enum",
  "enumValues": {
    "0": "not on fire",
    "1": "on fire"
  }
}

Resource select views

Most resource select views expose resource fields using a JSON:API encoding format. This is a format that explicitly separate identity, meta, attribute and relationship fields.

In JSON:API encoding, relationship fields in particular, are projected using a JSON objects with a data property. If the relationship is a to-one relationship, this property is either null or a JSON object containing the identity fields of the relation (id and type). If the relationship is to-many, data holds a (potentially empty) array of identity objects.

Projection	Source field
projection-path	field-path (field-category) OR Descriptive reference

// Common template for select views.
{
  "id": "<resource id>",
  "type": "<resource type>",
  "meta": {
    "<meta field>": <meta value>
  },
  "attributes": {
    "<attribute field>": <attribute value>
  },
  "relationships": {
    "<to-one relationship name>": {
      "data": {"type": "<resource type>", "id":"<resource id>"}
    },
    "<to-many relationship name>": {
      "data": [{"type": "<resource type>", "id":"<resource id>"}]
    }
  }
}

Select views not using a JSON:API encoding format, include the Create summary and Save summary views. This is mostly for backward compatibility reasons with formats used in API v1.0.

Create summary

Summary of a save operation where resources can be either created or left unchanged.

type: object

Projection	Source field
id string	id (identity)
created bool	true if the resource was created.

Example

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

Save summary

Summary of a save operation where resources can be either created, updated or left unchanged.

type: object

Projection	Source field
id string	id (identity)
created bool	true if the resource was created.
updated bool	true if the resource was updated.

Example

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

Item select (clarify namespace)

The item select view expose all fields from items with JSON:API compatible encoding.

type: object

Projection	Source field
id	id (identity)
type	type (identity)
meta.*	all meta fields
attributes.*	all attribute fields

Currently no relationships are exposed.

Examples

{
  "type": "items",
  "id": "capggebtaf7dgmpf7g4g",
  "meta": {
    "annotations": {
      "docs-clarify-io/example/development": "arrested"
    },
    "attributesHash": "57bc11493e429653e8873eb112419a9543d334e8",
    "relationshipsHash": "5f36b2ea290645ee34d943220a14b54ee5ea5be5",
    "createdAt": "2022-06-22T12:16:57.386Z",
    "updatedAt": "2022-06-22T12:18:37.949Z"
  },
  "attributes": {
    "name": "Building status",
    "description": "Overall building status, aggregated from environmental sensors.",
    "valueType": "enum",
    "sourceType": "aggregation",
    "engUnit": "",
    "sampleInterval": "PT15M",
    "gapDetection": "PT2H",
    "labels": {
      "data-source": ["Environmental Sensors"],
      "location": ["Banana Stand", "Pier"]
    },
    "enumValues": {
      "0": "✅",
      "1": "🔥"
    },
    "visible": true
  },
  "relationships": {}
}

Signal select (admin namespace)

The signal select view expose all fields from signals with JSON:API compatible encoding.

type: object

Projection	Source field
id	id (identity)
type	type (identity)
meta.*	all meta fields
attributes.*	all attribute fields
relationships.item	item (relationship)
relationships.integration	integration (relationship)

Examples

// Numeric signal (not exposed).
{
  "type": "signals",
  "id": "capggajtaf7dgmpf7g40",
  "meta": {
    "annotations": {
      "docs-clarify-io/example/development": "arrested"
    },
    "attributesHash": "6fa3392f573628ffc1d6e3863c5fd7e284096500",
    "relationshipsHash": "d8d76afa916ffc39d87415bfb500a173be80ceb9",
    "createdAt": "2022-06-22T12:16:42.195Z",
    "updatedAt": "2022-06-22T12:18:34.426Z"
  },
  "attributes": {
    "name": "Amount",
    "description": "Amount at location, counted manually.",
    "valueType": "numeric",
    "sourceType": "measurement",
    "engUnit": "USD",
    "sampleInterval": null,
    "gapDetection": null,
    "labels": {
      "data-source": [
        "manual"
      ],
      "location": [
        "banana stand",
        "pier"
      ]
    },
    "enumValues": {},
    "input": "banana-stand/amount"
  },
  "relationships": {
    "integration": {
      "data": {
        "type": "integrations",
        "id": "c8uppnhhqir3jld68nr0"
      }
    },
    "item": {
      "data": null
    }
  }
}
// Enum signal (exposed as item).
{
  "type": "signals",
  "id": "capggajtaf7dgmpf7g3g",
  "meta": {
    "annotations": {
      "docs-clarify-io/example/development": "arrested"
    },
    "attributesHash": "5578cec3c4dd8d20715a17172f6d4d7a78b819e4",
    "relationshipsHash": "5ca582fe47aee24d5e07ce6d26825d1c7609fa8a",
    "createdAt": "2022-06-22T12:16:42.193Z",
    "updatedAt": "2022-06-22T12:18:34.423Z"
  },
  "attributes": {
    "name": "Building status",
    "description": "Overall building status, aggregated from environmental sensors.",
    "valueType": "enum",
    "sourceType": "aggregation",
    "engUnit": "",
    "sampleInterval": "PT15M",
    "gapDetection": "PT2H",
    "labels": {
      "data-source": [
        "environmental sensors"
      ],
      "location": [
        "banana stand",
        "pier"
      ]
    },
    "enumValues": {
      "0": "not on fire",
      "1": "on fire"
    },
    "input": "banana-stand/status"
  },
  "relationships": {
    "integration": {
      "data": {
        "type": "integrations",
        "id": "c8uppnhhqir3jld68nr0"
      }
    },
    "item": {
      "data": {
        "type": "items",
        "id": "capggebtaf7dgmpf7g4g"
      }
    }
  }
}

Data views

Data views are described using the same schema syntax as fields. This category currently only include one view.

Data frame

This is a special-case view for dealing with time-series data that's associated with either signals (during insert) or items (during read).

When writing data, time-series are referred to by a signal's input attribute. When reading data, the keys of the series map is either item IDs (raw data), or item IDs with an aggregation suffix (rollup data).

type: object

Field	Description
times array(Date/Time,integer)	All times we provide values for. Integer values are interpreted as whole seconds since the UNIX epoch (1970-01-01T00:00:00Z). Date/Time values allow up to microsecond resolution.
series map(Series key => array(number,null))	Mapping of keys to arrays of data values. Each member should match the length of the times array. Each array index contain a value corresponding to the time at the same index.

Examples

Input data for integration.insert:

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

Result data from clarify.dataFrame (raw data):

{
  "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": [250000, null, null, null, null, 0]
  }
}

Result data from clarify.dataFrame (rollup "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": [250000, 0],
    "c92rujqsahsunml6lo00_count": [1, 0],
    "c92rujqsahsunml6lo00_max": [250000, null],
    "c92rujqsahsunml6lo00_min": [250000, null],
    "c92rujqsahsunml6lo00_sum": [250000, 0]
  }
}

Result data from clarify.dataFrame (rollup "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": [125000],
    "c92rujqsahsunml6lo00_count": [2],
    "c92rujqsahsunml6lo00_max": [250000],
    "c92rujqsahsunml6lo00_min": [250000],
    "c92rujqsahsunml6lo00_sum": [250000]
  }
}