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": "aggregation",
"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": "aggregation",
"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]
}
}