Please ensure Javascript is enabled for purposes of website accessibility
Powered by Zoomin Software. For more details please contactZoomin

CONNECT data services developer documentation

TABLE OF CONTENTS

Data Views

Save PDF
Save selected topicSave selected topic and subtopicsSave all topics
Share
Share to emailCopy topic URL
  • Last UpdatedMar 28, 2023
  • 11 minute read

The DataView API provides mechanisms to create, read, update, and delete data views. This is one portion of the whole data views API.

For a description of the DataView object type, see the DataView documentation.

Other sections of documentation describe how to secure data views by setting their ownership and permissions, and the corresponding API.

List Data Views

Returns a list of data views.

Request

GET /api/v1/tenants/{tenantId}/namespaces/{namespaceId}/dataviews
?skip={skip}&count={count}

Parameters

string tenantId
Tenant identifier.

string namespaceId
Namespace identifier.

[optional] integer skip
An optional parameter representing the zero-based offset of the first data view to retrieve. If not specified, a default value of 0 is used.

[optional] integer count
An optional parameter representing the maximum number of data views to retrieve. If not specified, a default value of 100 is used.

Response

Status Code Body Type Description
200 DataView[] A page of data views. A response header, Total-Count, indicates the total size of the collection.
500 ErrorResponse An error occurred while processing the request. See the response body for details.

Response Headers

Status Header Type Description
200 Total-Count integer The total count of data views visible to the current user.
200 Link string Hyperlinks to the first page and next page of results as applicable.
200 Next-Page string Hyperlink to the next page of results.
200 First-Page string Hyperlink to the first page of results.

Example response body

200 Response

HTTP 201 Created
Content-Type: application/json  
{
  [
    {
      "Id": "demo view 1",
      ... etc.
    },
    {
      "Id": "demo view 2",
      ... etc.
    }
  ]
}

500 Response (ErrorResponse)

{
  "OperationId": "string",
  "Error": "string",
  "Reason": "string",
  "Resolution": "string",
  "Parameters": {
    "property1": "string",
    "property2": "string"
  },
  "ChildErrors": {
    "property1": null,
    "property2": null
  }
}

Create Data View

Creates a new data view with a system-generated identifier.

Request

POST /api/v1/tenants/{tenantId}/namespaces/{namespaceId}/dataviews

Parameters

string tenantId
Tenant identifier.

string namespaceId
Namespace identifier.

Request Body

A DataView object whose Id is null or unspecified.

{
  "Id": "string",
  "Name": "string",
  "Description": "string",
  "IndexField": {
    "Source": 0,
    "Keys": [
      "string"
    ],
    "StreamReferenceNames": [
      "string"
    ],
    "Label": "string",
    "SummaryType": 0,
    "SummaryDirection": 1,
    "IncludeUom": true
  },
  "Queries": [
    {
      "Id": "string",
      "Kind": 1,
      "SourceKind": 0,
      "SourceId": "string",
      "Value": "string"
    }
  ],
  "DataFieldSets": [
    {
      "QueryId": "string",
      "DataFields": [
        {
          "Source": 0,
          "Keys": [
            "string"
          ],
          "StreamReferenceNames": [
            "string"
          ],
          "Label": "string",
          "SummaryType": 0,
          "SummaryDirection": 1,
          "IncludeUom": true
        }
      ],
      "IdentifyingField": {
        "Source": 0,
        "Keys": [
          "string"
        ],
        "StreamReferenceNames": [
          "string"
        ],
        "Label": "string",
        "SummaryType": 0,
        "SummaryDirection": 1,
        "IncludeUom": true
      }
    }
  ],
  "GroupingFields": [
    {
      "Source": 0,
      "Keys": [
        "string"
      ],
      "StreamReferenceNames": [
        "string"
      ],
      "Label": "string",
      "SummaryType": 0,
      "SummaryDirection": 1,
      "IncludeUom": true
    }
  ],
  "DefaultStartIndex": "string",
  "DefaultEndIndex": "string",
  "DefaultInterval": "string",
  "IndexTypeCode": 0,
  "Shape": 0
}

Response

Status Code Body Type Description
201 DataView The data view as persisted, including values for optional parameters that were omitted in the request.
400 ErrorResponse The request is not valid. See the response body for details.
403 ErrorResponse You are not authorized to create a data view.
500 ErrorResponse An error occurred while processing the request. See the response body for details.

Example response body

201 Response

HTTP 201 Created
Content-Type: application/json  
{
  "Id": "c79630cc-21dc-483e-8b37-46880e92c456",
  "Name": "demo",
  "Description": "demonstration",
  "IndexField": { "Label": "Timestamp" },
  "Queries": [],
  "DataFieldSets": [],
  "GroupingFields": [],
  "IndexTypeCode": "DateTime",
  "Shape": "Standard"
}

400 Response (ErrorResponse)

{
  "OperationId": "string",
  "Error": "string",
  "Reason": "string",
  "Resolution": "string",
  "Parameters": {
    "property1": "string",
    "property2": "string"
  },
  "ChildErrors": {
    "property1": null,
    "property2": null
  }
}

Get Data View

Returns the specified data view.

Request

GET /api/v1/tenants/{tenantId}/namespaces/{namespaceId}/dataviews/{id}

Parameters

string tenantId
Tenant identifier.

string namespaceId
Namespace identifier.

string id
Data view identifier.

Response

Status Code Body Type Description
200 DataView The requested data view.
403 ErrorResponse You are not authorized to view the requested data view.
404 ErrorResponse The specified data view identifier is not found.
500 ErrorResponse An error occurred while processing the request. See the response body for details.

Example response body

200 Response

HTTP 200 OK
Content-Type: application/json  
{
  "Id": "demo",
  "Name": "demo",
  "IndexField": { "Label": "Timestamp" },
  "Queries": [
    { 
      "Id": "weather",
      "Kind": "Stream",
      "SourceKind": "Default",
      "SourceId": "",
      "Value":"*weather*" 
    }
  ],
  "DataFieldSets": [],
  "GroupingFields": [],
  "IndexTypeCode": "DateTime",
  "Shape": "Standard"
}

403 Response (ErrorResponse)

{
  "OperationId": "string",
  "Error": "string",
  "Reason": "string",
  "Resolution": "string",
  "Parameters": {
    "property1": "string",
    "property2": "string"
  },
  "ChildErrors": {
    "property1": null,
    "property2": null
  }
}

Get or Create Data View

This method creates the specified data view. If a data view with the same identifier already exists, the existing data view is compared with the specified data view. If they are identical, a redirect (302 Found) is returned with the Location response header indicating the URL where the data view may be retrieved using a Get function. If the data views do not match, the request fails with 409 Conflict.

Request

POST /api/v1/tenants/{tenantId}/namespaces/{namespaceId}/dataviews/{id}

Parameters

string tenantId
Tenant identifier.

string namespaceId
Namespace identifier.

string id
Data view identifier.

Request Body

A DataView object whose Id is null or unspecified.

{
  "Id": "string",
  "Name": "string",
  "Description": "string",
  "IndexField": {
    "Source": 0,
    "Keys": [
      "string"
    ],
    "StreamReferenceNames": [
      "string"
    ],
    "Label": "string",
    "SummaryType": 0,
    "SummaryDirection": 1,
    "IncludeUom": true
  },
  "Queries": [
    {
      "Id": "string",
      "Kind": 1,
      "SourceKind": 0,
      "SourceId": "string",
      "Value": "string"
    }
  ],
  "DataFieldSets": [
    {
      "QueryId": "string",
      "DataFields": [
        {
          "Source": 0,
          "Keys": [
            "string"
          ],
          "StreamReferenceNames": [
            "string"
          ],
          "Label": "string",
          "SummaryType": 0,
          "SummaryDirection": 1,
          "IncludeUom": true
        }
      ],
      "IdentifyingField": {
        "Source": 0,
        "Keys": [
          "string"
        ],
        "StreamReferenceNames": [
          "string"
        ],
        "Label": "string",
        "SummaryType": 0,
        "SummaryDirection": 1,
        "IncludeUom": true
      }
    }
  ],
  "GroupingFields": [
    {
      "Source": 0,
      "Keys": [
        "string"
      ],
      "StreamReferenceNames": [
        "string"
      ],
      "Label": "string",
      "SummaryType": 0,
      "SummaryDirection": 1,
      "IncludeUom": true
    }
  ],
  "DefaultStartIndex": "string",
  "DefaultEndIndex": "string",
  "DefaultInterval": "string",
  "IndexTypeCode": 0,
  "Shape": 0
}

Response

Status Code Body Type Description
201 DataView The data view as persisted, including values for optional parameters that were omitted in the request.
302 None The specified data view already exists. A response header, Location, indicates the URL where the data view may be retrieved with the GET verb.
400 ErrorResponse The request is not valid. See the response body for details.
403 ErrorResponse You are not authorized for this operation.
409 ErrorResponse The specified data view conflicts with an existing data view that is not identical. To forcibly update the data view, see Create Or Update Data View.
500 ErrorResponse An error occurred while processing the request. See the response body for details.

Example response body

201 Response

HTTP 201 Created
Content-Type: application/json  
{
  "Id": "demo2",
  "Name": "demo2",
  "Description": "demonstration 2",
  "IndexField": { "Label": "Timestamp" },
  "Queries": [],
  "DataFieldSets": [],
  "GroupingFields": [],
  "IndexTypeCode": "DateTime",
  "Shape": "Standard"
}

400 Response (ErrorResponse)

{
  "OperationId": "string",
  "Error": "string",
  "Reason": "string",
  "Resolution": "string",
  "Parameters": {
    "property1": "string",
    "property2": "string"
  },
  "ChildErrors": {
    "property1": null,
    "property2": null
  }
}

Create or Update Data View

If a data view with the same identifier already exists, it is updated to the specified value. Otherwise, a new data view is created.

Request

PUT /api/v1/tenants/{tenantId}/namespaces/{namespaceId}/dataviews/{id}

Parameters

string tenantId
Tenant identifier.

string namespaceId
Namespace identifier.

string id
Data view identifier.

Request Body

A DataView object whose Id matches the dataViewId in the URL.

{
  "Id": "string",
  "Name": "string",
  "Description": "string",
  "IndexField": {
    "Source": 0,
    "Keys": [
      "string"
    ],
    "StreamReferenceNames": [
      "string"
    ],
    "Label": "string",
    "SummaryType": 0,
    "SummaryDirection": 1,
    "IncludeUom": true
  },
  "Queries": [
    {
      "Id": "string",
      "Kind": 1,
      "SourceKind": 0,
      "SourceId": "string",
      "Value": "string"
    }
  ],
  "DataFieldSets": [
    {
      "QueryId": "string",
      "DataFields": [
        {
          "Source": 0,
          "Keys": [
            "string"
          ],
          "StreamReferenceNames": [
            "string"
          ],
          "Label": "string",
          "SummaryType": 0,
          "SummaryDirection": 1,
          "IncludeUom": true
        }
      ],
      "IdentifyingField": {
        "Source": 0,
        "Keys": [
          "string"
        ],
        "StreamReferenceNames": [
          "string"
        ],
        "Label": "string",
        "SummaryType": 0,
        "SummaryDirection": 1,
        "IncludeUom": true
      }
    }
  ],
  "GroupingFields": [
    {
      "Source": 0,
      "Keys": [
        "string"
      ],
      "StreamReferenceNames": [
        "string"
      ],
      "Label": "string",
      "SummaryType": 0,
      "SummaryDirection": 1,
      "IncludeUom": true
    }
  ],
  "DefaultStartIndex": "string",
  "DefaultEndIndex": "string",
  "DefaultInterval": "string",
  "IndexTypeCode": 0,
  "Shape": 0
}

Response

Status Code Body Type Description
201 DataView The data view as persisted, including values for optional parameters that were omitted in the request.
204 None Successfully updated the data view.
400 ErrorResponse The request is not valid. See the response body for details.
403 ErrorResponse You are not authorized for this operation.
500 ErrorResponse An error occurred while processing the request. See the response body for details.

Example response body

201 Response (DataView)

{
  "Id": "string",
  "Name": "string",
  "Description": "string",
  "IndexField": {
    "Source": 0,
    "Keys": [
      "string"
    ],
    "StreamReferenceNames": [
      "string"
    ],
    "Label": "string",
    "SummaryType": 0,
    "SummaryDirection": 1,
    "IncludeUom": true
  },
  "Queries": [
    {
      "Id": "string",
      "Kind": 1,
      "SourceKind": 0,
      "SourceId": "string",
      "Value": "string"
    }
  ],
  "DataFieldSets": [
    {
      "QueryId": "string",
      "DataFields": [
        {
          "Source": 0,
          "Keys": [
            "string"
          ],
          "StreamReferenceNames": [
            "string"
          ],
          "Label": "string",
          "SummaryType": 0,
          "SummaryDirection": 1,
          "IncludeUom": true
        }
      ],
      "IdentifyingField": {
        "Source": 0,
        "Keys": [
          "string"
        ],
        "StreamReferenceNames": [
          "string"
        ],
        "Label": "string",
        "SummaryType": 0,
        "SummaryDirection": 1,
        "IncludeUom": true
      }
    }
  ],
  "GroupingFields": [
    {
      "Source": 0,
      "Keys": [
        "string"
      ],
      "StreamReferenceNames": [
        "string"
      ],
      "Label": "string",
      "SummaryType": 0,
      "SummaryDirection": 1,
      "IncludeUom": true
    }
  ],
  "DefaultStartIndex": "string",
  "DefaultEndIndex": "string",
  "DefaultInterval": "string",
  "IndexTypeCode": 0,
  "Shape": 0
}

Delete Data View

Deletes the data view with the specified id.

Request

DELETE /api/v1/tenants/{tenantId}/namespaces/{namespaceId}/dataviews/{id}

Parameters

string tenantId
Tenant identifier.

string namespaceId
Namespace identifier.

string id
Data view identifier.

Response

Status Code Body Type Description
204 None Successfully updated the data view.
403 ErrorResponse You are not authorized for this operation.
404 ErrorResponse The specified data view identifier is not found.
500 ErrorResponse An error occurred while processing the request. See the response body for details.

Definitions

DataView

A declarative way to select, label and shape data

Properties

Property Name Data Type Required Nullable Description
Id string false true The data view's unique identifier
Name string false true The data view's friendly name
Description string false true The data view's description
IndexField Field false true The data view's index field
Queries [Query] false true The collection of queries used by the data view
DataFieldSets [FieldSet] false true The collection of data field sets defined on the data view
GroupingFields [Field] false true The collection of fields to be used as grouping fields
DefaultStartIndex string false true The default start index used when data view data is queried, if no explicit value is specified
DefaultEndIndex string false true The default end index used when data view data is queried, if no explicit value is specified
DefaultInterval string false true The default interval used when data view data is retrieved, if no explicit value is specified
IndexTypeCode SdsTypeCode false false The data type of the index field
Shape DataViewShape false false The output shape of the data view 
{
  "Id": "string",
  "Name": "string",
  "Description": "string",
  "IndexField": {
    "Source": 0,
    "Keys": [
      "string"
    ],
    "StreamReferenceNames": [
      "string"
    ],
    "Label": "string",
    "SummaryType": 0,
    "SummaryDirection": 1,
    "IncludeUom": true
  },
  "Queries": [
    {
      "Id": "string",
      "Kind": 1,
      "SourceKind": 0,
      "SourceId": "string",
      "Value": "string"
    }
  ],
  "DataFieldSets": [
    {
      "QueryId": "string",
      "DataFields": [
        {
          "Source": 0,
          "Keys": [
            "string"
          ],
          "StreamReferenceNames": [
            "string"
          ],
          "Label": "string",
          "SummaryType": 0,
          "SummaryDirection": 1,
          "IncludeUom": true
        }
      ],
      "IdentifyingField": {
        "Source": 0,
        "Keys": [
          "string"
        ],
        "StreamReferenceNames": [
          "string"
        ],
        "Label": "string",
        "SummaryType": 0,
        "SummaryDirection": 1,
        "IncludeUom": true
      }
    }
  ],
  "GroupingFields": [
    {
      "Source": 0,
      "Keys": [
        "string"
      ],
      "StreamReferenceNames": [
        "string"
      ],
      "Label": "string",
      "SummaryType": 0,
      "SummaryDirection": 1,
      "IncludeUom": true
    }
  ],
  "DefaultStartIndex": "string",
  "DefaultEndIndex": "string",
  "DefaultInterval": "string",
  "IndexTypeCode": 0,
  "Shape": 0
}

Field

A data field that targets information resolved within its FieldSet

Properties

Property Name Data Type Required Nullable Description
Source FieldSource false false The target part of a data item, if this Field targets a data item. NotApplicable otherwise.
Keys string[] false true The collection of keys this field can match on its target data source Can be used to account for differences across target data types, e.g. matching either "Temperature" or "temperature_val"
StreamReferenceNames string[] false true The collection of possible stream reference names
Label string false true A friendly label
SummaryType SdsSummaryType false false Specifies summary operation
SummaryDirection SummaryDirection false true Specifies summary direction
IncludeUom boolean false false Specifies whether to include this field's unit of measure as an additional field mapping in the resolved data view 
{
  "Source": 0,
  "Keys": [
    "string"
  ],
  "StreamReferenceNames": [
    "string"
  ],
  "Label": "string",
  "SummaryType": 0,
  "SummaryDirection": 1,
  "IncludeUom": true
}

FieldSource

The targeted part of a DataItem

Enumerated Values

Property Value
NotApplicable 0
Id 1
Name 2
PropertyId 3
PropertyName 4
Metadata 5
Tags 6
TenantId 7
TenantName 8
NamespaceId 9
NamespaceName 10
CommunityId 11
CommunityName 12

SdsSummaryType

Enumerated Values

Property Value
None 0
Count 1
Minimum 2
Maximum 4
Range 8
Mean 16
StandardDeviation 32
PopulationStandardDeviation 64
Total 128
Skewness 256
Kurtosis 512
WeightedMean 1024
WeightedStandardDeviation 2048
WeightedPopulationStandardDeviation 4096

SummaryDirection

Specifies summary direction for a Field

Enumerated Values

Property Value
Forward 1
Backward 2

Query

A query for data items of a specified resource type.

Properties

Property Name Data Type Required Nullable Description
Id string false true The unique identifier of this query
Kind DataItemResourceType false false The type of resource being queried
SourceKind QuerySourceKind false false The kind of source to query from
SourceId string false true The community or namespace that will be queried from
Value string false true The text of this query 
{
  "Id": "string",
  "Kind": 1,
  "SourceKind": 0,
  "SourceId": "string",
  "Value": "string"
}

DataItemResourceType

The type of resource that a data item represents

Enumerated Values

Property Value
Stream 1
Asset 2

QuerySourceKind

Different source kinds that Queries can execute against

Enumerated Values

Property Value
Default 0
Namespace 1
Community 2

FieldSet

A set of fields defined for a particular source of data.

Properties

Property Name Data Type Required Nullable Description
QueryId string false true The identifier of the Query this field set uses.
DataFields [Field] false true The collection of Data Fields defined in this field set.
IdentifyingField Field false true The field used to identify each data item resolved by this field set. 
{
  "QueryId": "string",
  "DataFields": [
    {
      "Source": 0,
      "Keys": [
        "string"
      ],
      "StreamReferenceNames": [
        "string"
      ],
      "Label": "string",
      "SummaryType": 0,
      "SummaryDirection": 1,
      "IncludeUom": true
    }
  ],
  "IdentifyingField": {
    "Source": 0,
    "Keys": [
      "string"
    ],
    "StreamReferenceNames": [
      "string"
    ],
    "Label": "string",
    "SummaryType": 0,
    "SummaryDirection": 1,
    "IncludeUom": true
  }
}

SdsTypeCode

Enumerated Values

Property Value
Empty 0
Object 1
Boolean 3
Char 4
SByte 5
Byte 6
Int16 7
UInt16 8
Int32 9
UInt32 10
Int64 11
UInt64 12
Single 13
Double 14
Decimal 15
DateTime 16
String 18
Guid 19
DateTimeOffset 20
TimeSpan 21
Version 22
NullableBoolean 103
NullableChar 104
NullableSByte 105
NullableByte 106
NullableInt16 107
NullableUInt16 108
NullableInt32 109
NullableUInt32 110
NullableInt64 111
NullableUInt64 112
NullableSingle 113
NullableDouble 114
NullableDecimal 115
NullableDateTime 116
NullableGuid 119
NullableDateTimeOffset 120
NullableTimeSpan 121
BooleanArray 203
CharArray 204
SByteArray 205
ByteArray 206
Int16Array 207
UInt16Array 208
Int32Array 209
UInt32Array 210
Int64Array 211
UInt64Array 212
SingleArray 213
DoubleArray 214
DecimalArray 215
DateTimeArray 216
StringArray 218
GuidArray 219
DateTimeOffsetArray 220
TimeSpanArray 221
VersionArray 222
Array 400
IList 401
IDictionary 402
IEnumerable 403
SdsType 501
SdsTypeProperty 502
SdsStreamView 503
SdsStreamViewProperty 504
SdsStreamViewMap 505
SdsStreamViewMapProperty 506
SdsStream 507
SdsStreamIndex 508
SdsTable 509
SdsColumn 510
SdsValues 511
SdsObject 512
SByteEnum 605
ByteEnum 606
Int16Enum 607
UInt16Enum 608
Int32Enum 609
UInt32Enum 610
Int64Enum 611
UInt64Enum 612
NullableSByteEnum 705
NullableByteEnum 706
NullableInt16Enum 707
NullableUInt16Enum 708
NullableInt32Enum 709
NullableUInt32Enum 710
NullableInt64Enum 711
NullableUInt64Enum 712

DataViewShape

The shape of the data view. By default, each Field will resolve to one or more FieldMappings. In narrow shape, all Fields that map to a DataItem are "pivoted" vertically, into two fields: Label and Value.

Enumerated Values

Property Value
Standard 0
Narrow 1

ErrorResponse

Properties

Property Name Data Type Required Nullable Description
OperationId string false true None
Error string false true None
Reason string false true None
Resolution string false true None
Parameters object false true None
ChildErrors object false true None 
{
  "OperationId": "string",
  "Error": "string",
  "Reason": "string",
  "Resolution": "string",
  "Parameters": {
    "property1": "string",
    "property2": "string"
  },
  "ChildErrors": {
    "property1": null,
    "property2": null
  }
}
In This Topic
Related Links
TitleResults for “How to create a CRG?”Also Available in