Resources
A specific instance of a given resource type, is called a "resource". A resource instance is recongized by it's identity fields (id
and type
). In Clarify, all resources extend the same Base resource.
Resource schemas
Resource schemas describe all available fields or properties for a a specific resource type. These fields are again exposed by resource views for either read or write purposes. Any operation relying on field paths, such as a resource resource query, will be using the schema more directly in order to validate the query.
Field | Categories | Description |
---|---|---|
field-name type-expression | field-category, query-categories... | Short description. |
Each field can have exactly one field-category, and 0-2 query categories. When two query categories are present, then the final category is "sort".
Valid field-category values are:
- identifier: fields (
type
andid
). This field set is the same for all resources. Identify fields can never be changed for any resource. - meta: Non-standard fields such as annotations, as well as a set of generated read-only fields. This field set is the same for all resources in Clarify.
- attribute: Fields that doesn't directly reference other resources.
- relationship: Fields that reference other resources by referring to their identifier fields.
Valid query-category values are:
- comparable: Allows equality based comparisons against the stored values.
- ordered: Allows comparable as well as order based comparisons against the stored values.
- string: Allows comparable, ordered as well as text matching comparisons.
- sort: Declares the field as sortable.
Field paths
A field path, is the path of a field joined with dots (.
). The field-category (used in select view projections), is not considered a part of the field path. Be aware of special semantics regarding set types such as the Labels field, or relationship fields.
Example
// Resource selection with field paths as comments.
{
"type": "signals", // "type"
"id": "capggajtaf7dgmpf7g3g", // "id"
"meta": {
"annotations": {
"docs-clarify-io/example/development": "arrested" // "annotations.docs-clarify-io/example/development"
},
...
"createdAt": "2022-06-22T12:16:42.193Z", // "createdAt"
"updatedAt": "2022-06-22T12:18:34.423Z" // "updatedAt"
},
"attributes": {
"name": "Building status", // "name"
...
"labels": {
"data-source": [
"environmental sensors" // query path: "labels.data-source"
],
"location": [
"banana stand", // query path: "labels.location"
"pier" // query path: "labels.location"
]
}
},
"relationships": {
"item": {
"data": {
"type": "items",
"id": "capggebtaf7dgmpf7g4g" // query path: "item"
}
}
}
}
Resource view
A resource view allow access to certain resource fields, either for read or write purposes. Read more on the views page.
Resource types
A resource type is a group of resources that hold the same type
property. Within Clarify, that all resource type names are plural. I.e. the type
property if an item instance is "items" not "item".
Resources that are of the same type, must comply to a given schema. Note that this schema is not used directly for payload validation as all resource access is done through views.
Base resource
The identity
and meta
fiels are the same for all resources:
Field | Categories | Description |
---|---|---|
id string | identifier, ordered, sort | A unique ID generated by the server. Queries may be considered invalid if trying to use an invalid ID format according to the target resource type. |
type string | identifier | A string identifying the plural name of the resource type. |
createdAt Date/Time | meta, ordered, sort | A timestamp for when the resource was created. |
updatedAt Date/Time | meta, ordered, sort | A timestamp for when the resource was last updated. |
attributesHash string | meta | A SHA1 hash generated from all attribute fields. The hash is not stored, and can not be queried. |
relationshipsHash string | meta | A SHA1 hash generated from all relationship fields. The hash is not stored, and can not be queried. |
annotations Annotations | meta, text | A key-value store where integrations can store programmatic meta-data about the resource instance. Filtering is done one member fields. |
Integrations
ID regex: "^[a-v0-9]{20}$"
The integrations resource type is not currently made available for selection, but is documented as other resources contain references to it. An integration is an object that represents your code. Integrations are used to manage credentials and control access to the different API namespaces in the Clarify API.
Items
ID regex: "^[a-v0-9]{20}$"
The items resource type hold the sanitized meta-data set for a time-series instance and allows reading associated data within the scope of a single organization. The data can come from different sources, such as signals, data sets or other items. This relationship details is currently not exposed through the API, except signals that are exposed through items, include a link to the item that expose it.
Items extends the Base resource with the following fields:
Field | Categories | Description |
---|---|---|
name string(len:1-128) | attribute, text, sort | A human-readable name for the resource. |
description string(len:0-1000) | attribute, text | A free-form description of the resource. |
labels Labels | attribute, text | A map of custom classification attributes. Filtering is done on label keys (labels.<key> ). |
sourceType string(enum) | attribute, comparable | Classification of the data source. The value must be "aggregation" , "measurement" or "prediction" . |
valueType string(enum) | attribute, comparable | How to interpret time-series data points. The value must be "enum" or "numeric" . |
engUnit string | attribute, text, sort | Engineering unit for time-series data in numeric representations. |
enumValues map(string => string(len:1-128)) | attribute, text, sort | Map of numeric values to display text in enum representations. The key must represent an integer in range 0-9999. |
sampleInterval Fixed Duration, null | attribute, ordered, sort | The expected distance between data points. |
gapDetection Fixed Duration, null | attribute, ordered, sort | The maximum distance between two data-points before considering it to be a gap. |
Signals
ID regex: "^[a-v0-9]{20}$"
Signals is a resource type that holds meta-data associated with an integration time-series input. Integrations write time-series data or meta-data by referring to a signals input
attribute.
Note that signals describe time-series input only. Thus to retrieve time-series data written to a signal, you must first expose the signal as an Item.
Signals extends the Base resource with the following fields:
Field | Categories | Description |
---|---|---|
name string(len:1-128) | attribute, text, sort | A human-readable name for the resource. |
description string(len:0-1000) | attribute, text | A free-form description of the resource. |
labels Labels | attribute, text | A map of custom classification attributes. Filtering is done on label keys (labels.<key> ). |
sourceType string(enum) | attribute, comparable | Classification of the data source. The value must be "aggregation" , "measurement" or "prediction" . |
valueType string(enum) | attribute, comparable | How to interpret time-series data points. The value must be "enum" or "numeric" . |
engUnit string | attribute, text, sort | Engineering unit for time-series data in numeric representations. |
enumValues map(string => string(len:1-128)) | attribute, text, sort | Map of numeric values to display text in enum representations. The key must represent an integer in range 0-9999. |
sampleInterval Fixed Duration, null | attribute, ordered, sort | The expected distance between data points. |
gapDetection Fixed Duration, null | attribute, ordered, sort | The maximum distance between two data-points before considering it to be a gap. |
input string | attribute, comparable | A unique key used to reference signals within an integration namespace. Values must satisfy regular expression "^[a-zA-Z0-9-_:.#+/]{1,128}$" . |
integration string(Integration ID) | relationship | The parent integration for the signal. Current methods force filtering signals on this field. |
item string(Item ID), null | relationship, ordered | Link to an item that expose the signal within the organization or null . |