Skip to main content
Version: 1.1beta2

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 / aliasSemanticsDefault
field-name[ / alias-name]merge OR replacevalue 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 / aliasSemanticsDefault
annotationsmergeN/A
namereplaceinput value
descriptionreplace""
labelsreplace{}
sourceTypereplace"measurement"
valueType / typereplace"numeric"
engUnitreplace""
enumValuesreplace{}
sampleIntervalreplacenull
gapDetectionreplacenull

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 / aliasSemanticsDefault
annotationsmergeN/A
namereplacesignal value
descriptionreplace""
labelsreplace{}
sourceTypereplacesignal value
valueTypereplacesignal value
engUnitreplace""
enumValuesreplace{}
sampleIntervalreplacenull
gapDetectionreplacenull

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.

ProjectionSource field
projection-pathfield-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

ProjectionSource 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

ProjectionSource 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

ProjectionSource field
idid (identity)
typetype (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

ProjectionSource field
idid (identity)
typetype (identity)
meta.*all meta fields
attributes.*all attribute fields
relationships.itemitem (relationship)
relationships.integrationintegration (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

FieldDescription
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(Input 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]
}
}