Time Series Data - GE.com · 2020. 3. 25. · About Time Series Data Sources2. Assign a Default Time Series Data Source4. Modify an Existing Time Series Data Source4. Modify an Existing

Time Series Data

© 2020 General Electric Company

Contents

Chapter 1: Time Series Data Sources 1About Time Series Data Sources 2

Assign a Default Time Series Data Source 4

Modify an Existing Time Series Data Source 4

Modify an Existing Time Series Data Source with Incorrect Value 5

Delete a Time Series Data Source 5

Chapter 2: Time Series Data Retrieval Service 6About Time Series Data Retrieval Service 7

Time Series Data Retrieval Service 7

Aggregation Across Tags 21

Chapter 3: Time Series Data Ingestion 25About Time Series Data Ingestion 26

Ingest Time Series Data 27

Verify Time Series Ingestion 30

Predix Time Series Data Bulk Ingestion 31

Stream Time Series Data 32

Chapter 4: Time Series Data Delete Service 33About Time Series Data Delete Service 34

Time Series Data Delete Service 34

Chapter 5: Troubleshoot Time Series Data 38Configuration Fields 39

Time Series Data Delete Service 39

Chapter 6: Release Notes 41Fourth Quarter of 2019 42

ii Time Series Data

Third Quarter of 2019 43

Second Quarter of 2019 43

First Quarter of 2019 44

iii

Copyright GE Digital© 2020 General Electric Company.

GE, the GE Monogram, and Predix are either registered trademarks or trademarks of All other trademarksare the property of their respective owners.

This document may contain Confidential/Proprietary information of and/or its suppliers or vendors.Distribution or reproduction is prohibited without permission.

THIS DOCUMENT AND ITS CONTENTS ARE PROVIDED "AS IS," WITH NO REPRESENTATION ORWARRANTIES OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TOWARRANTIES OF DESIGN, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE. ALL OTHERLIABILITY ARISING FROM RELIANCE UPON ANY INFORMATION CONTAINED HEREIN IS EXPRESSLYDISCLAIMED.

Access to and use of the software described in this document is conditioned on acceptance of the EndUser License Agreement and compliance with its terms.

iv © 2020 General Electric Company

Chapter

1Time Series Data SourcesTopics:

• About Time Series DataSources

• Assign a Default Time SeriesData Source

• Modify an Existing Time SeriesData Source

• Modify an Existing Time SeriesData Source with IncorrectValue

• Delete a Time Series DataSource

© 2020 General Electric Company 1

About Time Series Data Sources

The Time Series Data Source Configuration provides methods to configure connections to the time seriesdata sources, and to manage and retrieve connection information. Currently, for Predix and SmartSignaldata source types, this service supports connections to Predix Essentials instances of Predix andSmartSignal (instances that are deployed along with Predix Essentials). This service supports ProficyHistorian and External Predix Data as its external data source connection.

To ensure that connectivity and resources can be accessed as needed, make sure the following JSONfields are configured correctly:

Table 1: Proficy Configuration Fields

JSON Field Description

alias A unique alias name to save the data source configuration forthe tenant. The alias name field in the application and JSONfield must match.

precisionLevel The default precision level for the time-series data points. If noprecision level is indicated during retrieval, the default value isused.

authHost The authorization host URL of the data source, for example,https://fssfed.stage.ge.com.

auth The authorization token URI to retrieve the authorization tokento connect to the data source host, for example, /fss/as/token.oauth2.

authRequired The boolean value to indicate if authorization is required toconnect to the data source host.

clientId The OAuth client ID required to access the OAuth client.

clientPwd The OAuth password required to access the OAuth client.

grantType The authorization grant type. The default value isclient_credentials.

authHeaderParams Header parameters required to retrieve the authorization token.

authQueryParams Query parameters required to retrieve the authorization token,for example, scope:api.

serviceHost The service URL to retrieve time series data.

interpolated The URI to retrieve interpolated data, for example, /osmdatalayer/data/interpolated.

raw The URI to retrieve raw data, for example, /osmdatalayer/data/interpolated.

current The URI to retrieve sample data, for example, /osmdatalayer/data/sampled.

write The URI to write back time series data into the Proficy datasource.

2 © 2020 General Electric Company


serviceHeaderParams Header parameters required to pass to the service URL toretrieve the time series data.

Note: Only define the service headers in the configuration if it isapplicable to all types of time series data retrieval such as raw,current, and interpolated.

serviceQueryParams Query parameters required to pass to the service URL toretrieve the time series data.

Note: Only define the query parameters in the configuration if itis applicable to all types of time series data retrieval such asraw, current, and interpolated. If not properly defined, dataretrieval may fail.

asyncFetchMode Indicates whether the data source supports asynchronousqueries.

The default value that appears is false. Any value other thantrue is false.

If your data source supports asynchronous queries, change thevalue to true.

Attention: If you are unsure about the configuration,do not change the value.

Table 2: External Predix Data Time Series Configuration Fields


alias A unique alias name to save the data source configuration forthe tenant. The alias name field in the application and JSONfield must match.

precisionLevel The default precision level for the time-series data points. If noprecision level is indicated during retrieval, the default value isused.

ingestURI The ingestion endpoint of the data source.

ingestUserName The user name to connect to the ingestion endpoint. This is notthe Time Series Data ingestion credential. The value ofingestUserName is specific to the External Predix Time Seriesdata source being configured.

ingestPassword The password to connect to the ingestion endpoint. This is notthe Time Series Data ingestion credential. The value ofingestPassword is specific to the External Predix Time Seriesdata source being configured.

interpolationMode The modes for interpolating data. These modes are initiated byentering either of these case-sensitive values: Math orHistorian. In Math mode, Time Series Data returnsempty data when interpolating a time period. Time Series Datareturns zeros for Historian. You do not have to enter a value forthis field if you prefer Math mode.

authUrl The URL to access the resource.

authClientId The OAuth client ID required to access the OAuth client.

authClientSecret The OAuth password required to access the OAuth client.

authHeader The authorization header type. The default value isBearer.



authType The authorization type. The default value is ZAC.predixTsZoneID The Predix Time Series service zone ID.

zoneTokenScopes The Predix Time Series service zone token scope. Scopes arepermissions associated with an OAuth Client to determine useraccess to the resource through the application.

queryURI The query URI for retrieving time series data.

extension (Optional) This numeric value is represented in milliseconds.When configured, the interpolation query uses this time tocontrol the start and end of the query bound intervals. If notconfigured or the value is configured as 0, then this parameteris ignored and the interpolation will look to fetch the start andend time data from infinite time.

Note: This feature is currently not available in any PredixEssentials tenants in the US East.

asyncFetchMode Indicates whether the data source supports asynchronousqueries.

The default value that appears is false. Any value other thantrue is false.

If your data source supports asynchronous queries, change thevalue to true.

Attention: If you are unsure about theconfiguration, do not change the value.

Assign a Default Time Series Data Source

Before You Begin

You have permission to perform the task.

Procedure

1. In the module navigation menu, select Administration > Time Series Data Sources.

2. In the Time Series Data Sources section, select the radio button next to the name in the Defaultcolumn.

3. The changes will be saved automatically.

Modify an Existing Time Series Data SourceUse the Time Series Data Source page to modify an existing time series data source.

Before You Begin


Procedure

1. In the module navigation menu, select Administration > Time Series Data Sources.

2. In the Time Series Data Sources section, select next to the name you want to modify.


3. Modify the JSON file. Make sure you have provided all the required key value pairs for a successfulconfiguration of the data source you are modifying.

4. Select Save to permanently save your changes. Or, select Cancel to return to the Time Series DataSources page without any changes.

Modify an Existing Time Series Data Source with Incorrect ValueUse the Time Series Data Source page to modify an existing time series data source with incorrect value.

Before You Begin


Procedure

1. In the module navigation menu, select Administration > Time Series Data Sources.2. In the Time Series Data Sources section, select Edit next to the name that has the incorrect values.3. Modify the JSON file that displays in the text box.

Entering an invalid key-value pair generates a message that the alias does not match the Data Sourcename. Select OK, and enter the correct alias name.

Entering a mismatched JSON alias value generates a message that the information will be saved withthe JSON alias you are entering. Select OK to continue. Or, select Cancel to return to the previousscreen.

4. Select Save to permanently save your changes. Or, select Cancel to return to the Time Series DataSources page without any changes.

Delete a Time Series Data Source

Before You Begin


You cannot delete SmartSignal or Predix Time Series data source types.

Procedure

1. In the module navigation menu, select Admin, select Operations Managers, and then select TimeSeries Data.

Note: In the module navigation menu of Predix Essentials, select Time Series Data Sources.2. In the Time Series Data Sources section, select X next to the time series data source you want to

delete.3. Select OK to permanently delete the selected data source configuration from the system. Or, select

Cancel to return to the Time Series Data Sources page without any changes.


Chapter

2Time Series Data Retrieval ServiceTopics:

• About Time Series DataRetrieval Service

• Time Series Data RetrievalService

• Aggregation Across Tags


About Time Series Data Retrieval Service

Use the following service to retrieve time series data for one or more asset tags collected over a specifiedtime interval and aggregated by a specified function. The procedure retrieves time series data in aspecified data store.

Time Series Data Retrieval ServiceThe Time Series Data service performs a check to ensure users can only query tags that are associatedwith assets they have permission to access.

The V5 version of the service supports partial tag access queries. For example, if tags are not associatedwith a Predix Essentials asset, or permission is not configured properly, you can query time series datausing the Time Series Data service. The query response has only the tags to which you have access. TheV3 version of the service supports passing the unit of measurement at the tag level. Use the UnitsTo keyto specify the unit of measure for the resulting times series data (to be converted to) for the applied tag inthe tagList.

This version also supports cross-tenancy data access. For example, when you have access to assets fromone or more tenants, using this API, you can retrieve the data for all the assigned assets.


Table 3: Time Series Data Retrieval Service APIs v5

URL https://api.example.com/v5/time_series/query

Note: V5 endpoint displays data quality when using KairosDB format.


JSON fields Pass the json file in the request containing the following fields.

tagList

(required) Array of tag data. You must pass the tag source key configured in the asset modelas the tagID to query for related time series data. You can query up to 100 tags per request.All tags must be associated with corresponding Predix Essentials assets and a time serieslink must be provided to retrieve the time series data in the data store.

Note: SmartSignal only supports one tag.

UnitsTo

(optional) Used for conversion of data units of measure. Specifies the unit of measureto which the resulting tag data will be converted. If defined at the tag level, theconversion is applied to that specific tag in the tagList.

UnitsFrom

(optional) Used for conversion of data units of measure. Specifies the unit of measureto which the resulting tag data will be converted. If defined at the tag level, theconversion is applied to that specific tag in the tagList. If omitted, the units are derivedon the tag configuration in the asset model.

systemOfMeasure

A service that provides users with a UnitsTo and UnitsFrom conversion method for aspecified UOM instance. If not specified, it will default to None.

attributes

(optional) Used to filter the time series data by tag attributes. Defining this at the taglevel, the filter applies to the tag. If defined at the query level, the filter applies to alltags listed in the query. Definition at the tag level takes precedence over the querylevel.

groups

(optional) Used to group the time series data by tag attributes. Defining this at the taglevel, the grouping applies to the tag, or if defined at the query level, the groupingapplies to all tags listed in the query. Definition at the tag level takes precedence overthe query level.

operation

(required) Type of data to retrieve. The following are the supported values.

• (All data sources) raw - retrieve all data points as they were ingested.• (SmartSignal data sources only) downsampled - returns sampled data points from

SmartSignal.

Note: If you are using this operation for other data sources, then this operation will beignored, and all raw data points will be returned.

• (All data sources) interpolated - retrieve data points interpolated based on thesampleCount or interval parameters.

• (All data sources) current - retrieve most recent data point.• (Predix data sources only) sum - retrieve all data points in the specified time range and

sum them to receive one aggregated value, or explicitly specify a time interval toreceive a sum of each interval.

• (Predix data sources only) avg - retrieve all data points in the specified time range withan interval to return the average value of each interval.

Note: For SmartSignal, the only values supported are raw and downsampled.

startTime

(required, if operation is interpolated or raw) Beginning of the time range. The supportedformats are:

• Unix Epoch - in milliseconds,• ISO8601 (formats: [yyyy-MM-dd’T’HH:mm:ss.SSS±hhmm, yyyy-MM-

dd’T’HH:mm:ss.SSS]),• Relative time (format: "<value><units>-ago", units: [ms, s, mi, h, d, w], example: "10d-

ago").

Note: If the start date is empty, then the query searches data back only for last 15 days andprovides only one latest data point. If the start date is specified, then the query searchesdata from given start time to now and provides only one latest data point.

endTime

(required, if operation is interpolated) End of the time range. The default value is currentdate and time. The supported formats are:



ago").

interval

(optional) Positive integer in milliseconds. Indicates a time interval that query forinterpolated data is based on. For example, 1000 - every one second. Use eithersampleCount or interval, but not both.

Note: Not supported by SmartSignal.

sampleCount

(optional) Number of data points to retrieve when using raw and interpolated operation.For interpolated operation, use either sampleCount or interval, but not both.


last

(Predix data sources only) The value of the last point in the interval.

dataSource

(optional) Name of the data source as defined by the data source configuration.

useOnlyGoodData

(optional) Indicator to retrieve data with the quality indicator 'Good' (3). The allowed valuesare: true, false, default value, and false.


direction

(optional) The direction by which data points are retrieved (by timestamp). The supportedvalues are: backward retrieves data points backwards on the endTime; forwardretrieves data points forward on the startTime; default value forwards the data.


queryDirection

(optional) The query that retrieves data points using the values backward andforward, which are specified direction options associated only with the startTime.

responseFormat

(optional) The format of the retrieved data. The supported valuesare :KAIROSDB,PROFICYLIKE and ANALYTICS. The default value isPROFICYLIKE.

precisionLevel

(optional) Positive integer that defines precision level of numeric tag values. The defaultvalue is as defined by the configuration.

useOnlyNumericData

(optional) Indicator to retrieve only numeric tag values. The allowed values are: true,false. The default value is true

fetchType

(optional) Defines the fetch type for the query result. Supported values:

• SYNC - (default) Fetches the query data in synchronous mode.

• ASYNC - Fetches the query data asynchronously. Users are provided with acorrelation ID, which is used to fetch the query result.

• DYNAMIC - The Predix Time Series service provides the query result eithersynchronously or asynchronously based on the underlying data storage configuration.For synchronous queries, users are provided with the query results; for asynchronousqueries, users receive a correlation ID.

Note:

fetchType is supported only for the Predix Time Series and Proficy Historian datasource types. For other data source types, fetchType is ignored, and the results arereturned in synchronous mode.

ASYNC and DYNAMIC fetch types are not supported in all Predix Time Series serviceinfrastructures, in which case ASYNC queries return a 400 error, and DYNAMIC queriesare handled as SYNC queries.

asyncCorrelationId

The Time Series Data–generated correlation ID used to retrieve the results of previouslysubmitted queries using the ASYNC and DYNAMIC fetch types.


Method POSTSample Request POST /v5/time_series/query HTTP/1.1

Content-Type: application/jsonaccept: application/jsonAuthorization: <Authorization>tenant: <tenant>Host: api.example.comContent-Length: 350

{ "operation" : "raw", "startTime" : "2015-12-13T18:42:33.224", "endTime" : "2016-02-09T16:00:00.000Z", "sampleCount" : 3, "useOnlyGoodData" : true, "direction" : "forward", "responseFormat" : "kairosDB", "precisionLevel" : "3", "useOnlyNumericData" : true, "tagList" : [ { "tagId" : "/tenants/361d09ad-735d-4259-8d52-c0494ac99cf5/tags/bd42f265-13dc-417c-8382-99cd25b02347" } ]}

The following is a sample request for cross-tenancy only:

HTTP/1.1 200 OK

Content-Type: application/json;charset=UTF-8

Content-Length: 238

{

"queries" : [ {

"sample_size" : 3,

"results" : [ {

"name" : "/tenants/361d09ad-735d-4259-8d52-c0494ac99cf5/tags/bd42f265-13dc-417c-8382-99cd25b02347",

"values" : [ [ 1454811103000, 2.123, 3 ], [ 1454880103000, 2.123, 3 ], [ 1454885503000, 999.234, 3 ] ]

} ]

} ]

}


Sample response HTTP/1.1 200 OKContent-Type: application/json;charset=UTF-8Content-Length: 238

{ "queries" : [ { "sample_size" : 3, "results" : [ { "name" : "Inverter1-ASSET-TYPE1.Tag_Length", "values" : [ [ 1454811103000, 2.123, 3 ], [ 1454880103000, 2.123, 3 ], [ 1454885503000, 999.234, 3 ] ] } ] } ]}

Status Code On successful retrieval, you receive a 200 OK and tag data in requested format.

The query output in the response is 200 OK regardless of whether you have access to all thetags in the list, partial access, or no access. However, the response includes only the tags forwhich you have permissions. If either the tag does not exists or you do not have permissions, itwill not appear in the response. If you have no access to the entire list of tags, you still receive a200 OK with an empty list.




Note: V4 endpoint displays data quality when using KairosDB format.



tagList

(required) Array of tag data. You must pass the tag source key configured in the asset modelas the tagID to query for related time series data. You can query up to 100 tags per request.All tags must be associated with corresponding Predix Essentials assets and a time serieslink must be provided to retrieve the time series data in the data store.


UnitsTo

(optional) Used for conversion of data units of measure. Specifies the unit of measureto which the resulting tag data will be converted. If defined at the tag level, theconversion is applied to that specific tag in the tagList.

UnitsFrom

(optional) Used for conversion of data units of measure. Specifies the unit of measureto which the resulting tag data will be converted. If defined at the tag level, theconversion is applied to that specific tag in the tagList. If omitted, the units are derivedon the tag configuration in the asset model.

systemOfMeasure

A service that provides users with a UnitsTo and UnitsFrom conversion method for aspecified UOM instance. If not specified, it will default to None.

attributes

(optional) Used to filter the time series data by tag attributes. Defining this at the taglevel, the filter applies to the tag. If defined at the query level, the filter applies to alltags listed in the query. Definition at the tag level takes precedence over the querylevel.

groups

(optional) Used to group the time series data by tag attributes. Defining this at the taglevel, the grouping applies to the tag, or if defined at the query level, the groupingapplies to all tags listed in the query. Definition at the tag level takes precedence overthe query level.

operation


• (All data sources) raw - retrieves all data points as they were ingested.• (All data sources) interpolated - retrieves data points interpolated based on the

sampleCount or interval parameters.• (All data sources) current - retrieves most recent data point.• (Predix data sources only) sum - retrieves all data points in the specified time range and

sum them to receive one aggregated value, or explicitly specify a time interval toreceive a sum of each interval.

• (Predix data sources only) avg - retrieves all data points in the specified time range withan interval to return the average value of each interval.

Note: For SmartSignal, the only value supported is raw.

startTime

(required, if operation is interpolated or raw) Beginning of the time range. The supportedformats are:



ago").

Note: If the start date is empty, then the query searches data back only for last 15 days andprovides only one latest data point. If the start date is specified, then the query searchesdata from given start time to now and provides only one latest data point.

endTime

(required, if operation is interpolated) End of the time range. The default value is currentdate and time. The supported formats are:



ago").

interval

(optional) Positive integer in milliseconds. Indicates a time interval that query forinterpolated data is based on. For example, 1000 - every one second. Use eithersampleCount or interval, but not both.


interpolatedMode

(optional) This mode is applicable only if the operation is interpolated. The supportedvalues are:

• Historian• SampleAndHold• Math

The default mode is Historian. When this field is empty, the query will use the default mode.

Note: Not supported by SmartSignal and Proficy.

sampleCount

(optional) Number of data points to retrieve when using raw and interpolated operation.For interpolated operation, use either sampleCount or interval, but not both.


dataSource


useOnlyGoodData

(optional) Indicator to retrieve data with the quality indicator 'Good' (3). The allowed valuesare: true, false, default value, and false.


direction

(optional) The direction by which data points are retrieved (by timestamp). The supportedvalues are: backward retrieves data points backwards on the endTime; forwardretrieves data points forward on the startTime; default value forwards the data.


queryDirection

(optional) The query that retrieves data points using the values backward andforward, which are specified direction options associated only with the startTime.


responseFormat

(optional) The format of the retrieved data. The supported valuesare :KAIROSDB,PROFICYLIKE and ANALYTICS. The default value isPROFICYLIKE.

precisionLevel

(optional) Positive integer that defines precision level of numeric tag values. The defaultvalue is as defined by the configuration.

useOnlyNumericData

(optional) Indicator to retrieve only numeric tag values. The following values are allowed:true, false. The default value is true



Content-Type: application/jsonContent-Type: application/jsonaccept: application/jsonaccept: application/jsonAuthorization: <Authorization>tenant: <tenant>Host: api.example.comContent-Length: 350

{ "operation" : "raw", "startTime" : "2015-12-13T18:42:33.224", "endTime" : "2016-02-09T16:00:00.000Z", "sampleCount" : 3, "useOnlyGoodData" : true, "direction" : "forward", "responseFormat" : "kairosDB", "precisionLevel" : "3", "useOnlyNumericData" : true, "tagList" : [ { "tagId" : "Inverter1-ASSET-TYPE1.Tag_Length" } ]}


{ "queries" : [ { "sample_size" : 3, "results" : [ { "name" : "Inverter1-ASSET-TYPE1.Tag_Length", "values" : [ [ 1454811103000, 2.123, 3 ], [ 1454880103000, 2.123, 3 ], [ 1454885503000, 999.234, 3 ] ] } ] } ]}

Status Code On successful retrieval, you receive a 200 OK and a tag data in requested format.




Note: The V3 version of the service supports passing the unit of measurement at the tag level.

Use the UnitsTo key to specify the unit of measure for the resulting times series data (to be

converted to) for the applied tag in the tagList.



tagList

(required) Array of tag data. You must pass the tag source key configured in the asset model

as the tagID to query for related time series data. You can query up to 40 tags per request.

All tags must be associated with corresponding Predix Essentials assets and a time series

link must be provided to retrieve the time series data in the data store.

Note: SmartSignal only supports 1 tag.

UnitsTo

(optional) Used for conversion of data units of measure. Specifies the unit of measure

to which the resulting tag data will be converted. If defined at the tag level, the

conversion is applied to that specific tag in the tagList.

UnitsFrom

(optional) Used for conversion of data units of measure. Specifies the unit of measure

to which the resulting tag data will be converted. If defined at the tag level, the

conversion is applied to that specific tag in the tagList. If omitted, the units are derived

on the tag configuration in the asset model.

systemOfMeasure

A service that provides users with a UnitsTo and UnitsFrom conversion method for a

specified UOM instance. If not specified, it will default to None.

attributes

(optional) Used to filter the time series data by tag attributes. Defining this at the tag

level, the filter applies to the tag. If defined at the query level, the filter applies to all

tags listed in the query. Definition at the tag level takes precedence over the query

level.

groups

(optional) Used to group the time series data by tag attributes. Defining this at the tag

level, the grouping applies to the tag, or if defined at the query level, the grouping

applies to all tags listed in the query. Definition at the tag level takes precedence over

the query level.

operation


• (All data sources) raw - retrieves all data points as they were ingested.

• (All data sources) interpolated - retrieves data points interpolated based on the

sampleCount or interval parameters.

• (All data sources) current - retrieves most recent data point.

• (Predix data sources only) sum - retrieves all data points in the specified time range and

sum them to receive one aggregated value, or explicitly specify a time interval to

receive a sum of each interval.

• (Predix data sources only) avg - retrieves all data points in the specified time range with

an interval to return the average value of each interval.


startTime

(Required) Beginning of the time range. The supported formats are:

• Unix Epoch - in milliseconds,

• ISO8601 (formats: [yyyy-MM-dd’T’HH:mm:ss.SSS±hhmm, yyyy-MM-

dd’T’HH:mm:ss.SSS]),

• Relative time (format: "<value><units>-ago", units: [ms, s, mi, h, d, w], example: "10d-

ago").

endTime

(required, if operation is interpolated) End of the time range. The default value is current

date and time. The supported formats are:

• Unix Epoch - in milliseconds,

• ISO8601 (formats: [yyyy-MM-dd’T’HH:mm:ss.SSS±hhmm, yyyy-MM-

dd’T’HH:mm:ss.SSS]),

• Relative time (format: "<value><units>-ago", units: [ms, s, mi, h, d, w], example: "10d-

ago").

interval

(optional) Positive integer in milliseconds. Indicates a time interval that query for

interpolated data is based on. For example, 1000 - every one second. Use either

sampleCount or interval, but not both.


sampleCount

(optional) Number of data points to retrieve when using raw and interpolated operation.

For interpolated operation, use either sampleCount or interval, but not both.


dataSource


useOnlyGoodData

(optional) Indicator to retrieve data with the quality indicator 'Good' (3). The allowed values

are: true, false, default value, and false.


direction

(optional) The direction by which data points are retrieved (by timestamp). The supported

values are: backward retrieves data points backwards on the endTime; forwardretrieves data points forward on the startTime; default value forwards the data.


queryDirection

(optional) The query that retrieves data points using the values backward and

forward, which are specified direction options associated only with the startTime.


responseFormat

(optional) The format of the retrieved data. The supported values

are :KAIROSDB,PROFICYLIKE and ANALYTICS. The default value is

PROFICYLIKE.

precisionLevel

(optional) Positive integer that defines precision level of numeric tag values. The default

value is as defined by the configuration.

useOnlyNumericData




Content-Type: application/jsonaccept: application/jsonaccept: application/jsonAuthorization: <Authorization>tenant: <tenant>Host: api.example.comContent-Length: 700

{ "tagList" : [ { "tagId" : "Inverter1-ASSET-TYPE1.Tag_Pressure", "unitsTo" : "psi", "systemOfMeasure" : "test", "attributes" : { "key1" : [ "value1" ], "key2" : [ "value2" ] }, "groups" : [ { "name" : "attribute", "attributes" : [ "Key1", "key2" ] } ] }, { "tagId" : "Inverter1-ASSET-TYPE2.Tag_Temperature", "unitsTo" : "c" }, { "tagId" : "Inverter1-ASSET-TYPE3.Tag_Length" } ], "operation" : "raw", "startTime" : "2016-02-09T15:00:00.000Z", "endTime" : "2016-02-09T16:00:00.000Z", "sampleCount" : 300, "useOnlyGoodData" : true, "direction" : "forward", "responseFormat" : "PROFICYLIKE", "precisionLevel" : "3", "useOnlyNumericData" : true}


Sample response HTTP/1.1 200 OKContent-Type: application/jsonContent-Length: 886

{ "errorCode" : "0", "errorMessage" : "", "tagList" : [ { "tagId" : "Inverter1-ASSET-TYPE1.Tag_Pressure", "errorCode" : "0", "errorMessage" : "", "data" : [ { "ts" : "2016-02-07T02:11:33.000", "v" : "31.123", "q" : "3" }, { "ts" : "2016-02-07T02:11:35.000", "v" : "38.123", "q" : "3" } ], "attributes" : { "key1" : [ "value1" ] } }, { "tagId" : "Inverter1-ASSET-TYPE2.Tag_Temperature", "errorCode" : "0", "errorMessage" : "", "data" : [ { "ts" : "2016-02-07T02:11:34.000", "v" : "11.123", "q" : "3" } ], "attributes" : { } }, { "tagId" : "Inverter1-ASSET-TYPE3.Tag_Length", "errorCode" : "0", "errorMessage" : "", "data" : [ { "ts" : "2016-02-07T02:11:35.000", "v" : "12.123", "q" : "3" } ], "attributes" : { } } ]}

Status Code On successful retrieval, you receive a 200 OK and tag data in requested format.


Table 6: Time Series Data Retrieval Service APIs V2

URL https://apm-timeseries-services-/v2/time_series?


Query Parameters operation

(required)Type of data to retrieve. Supported values are raw retrieve all data points as

they were ingested. Interpolated, retrieves data points interpolated based on the

sampleCount or interval parameters. Current,retrieves most recent data point.


tagList

(required, if tagExpressionList is not specified) List of comma separated tag names.

When querying time series data need to refer to a tag via tag source key as configured in

the asset model. All tags must be associated with corresponding Predix Essentials assets

and ensure a time series link is provided for retrieving the time series data in the data store.

The value of the time series link should match the raw tag name ingested in the time series

data source. You can query up to 40 tags per request. To add a tag to the asset model, refer

to Add a Tag Instance to an Instance. To update the reserved attribute value, refer to About

Reserved Attributes for an Asset Instance.


tagExpressionList

(required, if tagList is not specified) List of comma separated tag expressions. A tag

expression may contain one or more tag source key and constant as operands, separated

by operators. Tag source key should adhere to regex - '@[a-zA-Z0-9_#\.-]+': E.g. -

@TAG1_SOURCE_KEY + 1, @TAG1_SOURCE_KEY + (@TAG2_SOURCE_KEY * 1.23456) /

0.45678; Operators - +,-,*,/,().

When querying time series data, we need to refer to a tag via tag source key as configured

in the asset model. All tags must be associated with corresponding Predix Essentials assets

and ensure a time series link is provided for retrieving the time series data from the data

store.

Attention: You can use the tag expressions when querying a tag using the tag

source key. However, you cannot use the tag expressions when querying a tag

using the Uniform Resource Identifier (URI) of the tag. In addition, you cannot use

the tag expressions when querying a tag that is associated with an asset

belonging to another tenant.

Restriction: When using tagExpressionList, if a tag value is divided by an integer, the query

output will be an integer. For example, if the query output of the expression (@TS-ASSET-

TYPE1.TS-TAG1/100) is 0.93, the query will return 0 instead of 0.93. The workaround is to

use the float data type for numeric tag values.

startTime

(required) Beginning of the time range. Supported formats: Unix Epoch in milliseconds,

ISO8601 format. For example, yyyy-MM-dd'T'HH:mm:ss.SSS±hhmm, yyyy-MM-

dd'T'HH:mm:ss.SSS.

endTime

(required, if operation is interpolated) End of the time range. Supported formats: Unix

Epoch in milliseconds, ISO8601 format. For example, yyyy-MM-dd'T'HH:mm:ss.SSS±hhmm,

yyyy-MM-dd'T'HH:mm:ss.SSS.

interval

(optional) Positive integer in milliseconds. Indicates a time interval that query for

interpolated data is based on. For example, 1000 - every one second. Use either

sampleCount or interval, but not both.


sampleCount

(optional) Number of data points to retrieve when using raw and interpolated operation.

For interpolated operation, use either sampleCount or interval, but not both.


dataSource

(optional) Name of the data source as defined by the data source configuration. The default

value are as defined by the data source configuration.

useOnlyGoodData

(optional) Indicator to retrieve data with the quality indicator 'Good' (3). The allowed values

are: true, false,default value, and false.


direction

(optional) The direction by which data points are retrieved (by timestamp). The supported

values are: backward retrieves data points backwards on the endTime; forwardretrieves data points forward on the startTime; default valueforwards the data.


queryDirection

(optional) The query that retrieves data points using the values backward and

forward, which are specified directional options associated only with the startTime.


responseFormat

(optional) The format of the retrieved data. The supported values

are :KAIROSDB,PROFICYLIKE,ANALYTICS The default value is

PROFICYLIKE.

valueBounds

(optional) To retrieve the values according to lower or upper bound. Use [] to indicate

inclusive check and () to indicate exclusive check. Only one condition (lower or upper

bound) is supported, not both. For example, [,5] returns data with tag values less or equal

to 5,and (1,) returns data with tag values greater than 1.

precisionLevel

(optional) Positive integer that defines precision level of numeric tag values. The default

value is as defined by the configuration.

useOnlyNumericData


UnitsFrom

(optional) Used for conversion of data units of measure. Specifies the unit of measure for

the stored tag data (to be converted from). The conversion is applied to ALL tags in the

tagList parameter.

UnitsTo

(optional; required if from_unit is specified) Used for conversion of data units of measure.

Specifies the unit of measure for the result tag data (to be converted to). The conversion is

applied to ALL tags in the tagList parameter.

systemOfMeasure

A service that provides you with a UnitsTo and UnitsFrom conversion method for a specified

UoM instance. If not specified, it will default to None.

rounding

Rounding will be calculated based on your specified precisionLevel. Supported values are:

ceiling, floor.


Method GETSample Request http://<hostname>/services/apm/timeseries/data?

operation=interpolated&tagList=TR6.LNG_PSK_T2C1_21;TR7.LNG_PSK_T2C1_20;TR6.LNG_PSK_T2M1_11;TR7.LNG_PSK_T2M1_11;TR6.LNG_PSK_T2M1_14&startTime=1970-01-01T22:18:33.000&endTime=2016-04-23T00:28:03.000&sampleCount=300&tenant=sample&useOnlyGoodData=true&dataSource=predixtss.MVP3R2SysInt&responseFormat=KairosDB

This sample requests, time series for asset tags

TR6.LNG_PSK_T2C1_21,TR7.LNG_PSK_T2C1_20,TR6.LNG_PSK_T2M1_11, TR7.LNG_PSK_T2M1_11 andTR6.LNG_PSK_T2M1_14

Response Headers Authorization

Type the token_type followed by a space, then the access_token in the response you

previously obtained. For example, bearer eyJhbGciOiJSUzI1NiJ9.A...The following code sample includes a bearer token:

{ "access_token": "eyJhbGciOiJSUzI1NiJ9.A...", "token_type": "bearer", "refresh_token": "eyJhbGciOiJSUzI1NiJ9.e..", "expires_in": 86399, "scope": "openid", "jti": "5e2c90ea-9edd-4da1-80c8-4a0d67f77ef3"}

tenant

The unique ID for the tenant (for example, 07F28C049E0F4F29B8E85E4A6C916D7F)

Status Code On successful retrieval, you receive 200 OK and tag data in requested format.

Aggregation Across TagsUse this service to aggregate across multiple tags containing numeric values by time interval or number ofdata points. This is available for the V2 and V3 Time Series Data APIs.

Table 7: Multi-tag Aggregation Mode Parameters:

Field Description

tagID Provides a list of two-10 tag names that must be separated bycommas. All tags used in multi-tag aggregation mode mustcontain numeric values.

operation Specifies the optional data results: sum or avg.


Field Description

interval Defines the length of time and determines the size of theaggregation. This value is indicated numerically.

aggregationMode Gives you the ability to aggregate across multiple tags whenyou enter the multi-tag value. This parameter can only beset at the tag level, not the global level.

intervalUnit Sets the unit of time for the interval. You can use any of thesevalues:

• ms (milliseconds)

• s (seconds)

• mi (minutes)

• h (hours)

• d (days)

• w (weeks)

• mm (months)

• ys (years)

If you do not use intervalUnit, it will default to milliseconds.

Sample curl request $ curl 'https://api.example.com/v3/time_series/query' -i -X POST -H 'Content-Type: application/json' -H 'Content-Type: application/json' -H 'accept: application/json' -H 'accept: application/json' -H 'Authorization: <Authorization>' -H 'tenant: <tenant>' -d '{ "tagList" : [ { "tagId" : "Inverter1-ASSET-TYPE1.Tag_Pressure,Inverter1-ASSET-TYPE2.Tag_Temperature", "operation" : "sum", "interval" : 20, "aggregationMode" : "multi-tag", "intervalUnit" : "mi" } ], "startTime" : "2016-02-09T15:00:00.000Z", "endTime" : "2016-02-09T16:00:00.000Z", "useOnlyGoodData" : true, "responseFormat" : "PROFICYLIKE", "valueBounds" : "", "precisionLevel" : "", "useOnlyNumericData" : true}'


Field Description

Sample HTTP request POST /v3/time_series/query HTTP/1.1Content-Type: application/jsonContent-Type: application/jsonaccept: application/jsonaccept: application/jsonAuthorization: <Authorization>tenant: <tenant>Host: api.example.comContent-Length: 453

{ "tagList" : [ { "tagId" : "Inverter1-ASSET-TYPE1.Tag_Pressure,Inverter1-ASSET-TYPE2.Tag_Temperature", "operation" : "sum", "interval" : 20, "aggregationMode" : "multi-tag", "intervalUnit" : "mi" } ], "startTime" : "2016-02-09T15:00:00.000Z", "endTime" : "2016-02-09T16:00:00.000Z", "useOnlyGoodData" : true, "responseFormat" : "PROFICYLIKE", "valueBounds" : "", "precisionLevel" : "", "useOnlyNumericData" : true}


Field Description


{ "errorCode" : "0", "errorMessage" : "", "tagList" : [ { "tagId" : "Inverter1-ASSET-TYPE1.Tag_Pressure,Inverter1-ASSET-TYPE2.Tag_Temperature", "errorCode" : "0", "errorMessage" : "", "data" : [ { "ts" : "2016-02-09T15:00:00.000", "v" : "12.123", "q" : "3" }, { "ts" : "2016-02-09T15:20:00.000", "v" : "12.124", "q" : "3" }, { "ts" : "2016-02-09T15:40:00.000", "v" : "12.125", "q" : "3" }, { "ts" : "2016-02-09T16:00:00.000", "v" : "12.126", "q" : "3" } ], "attributes" : { } } ]}


Chapter

3Time Series Data IngestionTopics:

• About Time Series DataIngestion

• Ingest Time Series Data• Verify Time Series Ingestion• Predix Time Series Data Bulk

Ingestion• Stream Time Series Data


About Time Series Data Ingestion

The Predix Essentials Time Series Data module provides POST methods, JSON payload and CSV file, toingest time series data. The CSV supported formats are ODBExportCSV, and ProficyFileCollectorCSV. Thismodule is used by various features and other modules to consume time series data for display, charting,and analysis.

The two ingestion methods can be used for one or more tags. For each tag, a series of data points aredefined by timestamp, data value, and data quality indicator. The data points are specified as numeric,string or boolean values.

After creating the ingestion files, they are submitted through REST endpoints and can be queried usingthe time series data retrieval endpoint to ensure correct data ingestion. Correct any errors in theingestion file by resubmitting as needed, which replaces the existing data. Any data with new value typeor quality indicator ingests as new records.

Note: All CRUD operations are performed within the context of a tenant. Every request header mustinclude the authorization header and the tenant UUID.

The following definitions are helpful for understanding the headers and parameters:

AuthorizationEnter the token_type followed by a space, then the access_token that is in the response youpreviously obtained, for example, bearer eyJhbGciOiJSUzI1NiJ9.A... The following codesample includes a bearer token:

{ "access_token": "eyJhbGciOiJSUzI1NiJ9.A...", "token_type": "bearer", "refresh_token": "eyJhbGciOiJSUzI1NiJ9.e..", "expires_in": 86399, "scope": "openid", "jti": "5e2c90ea-9edd-4da1-80c8-4a0d67f77ef3"}

Content-typeThe MIME type of the body of the request. Supported types for ingestion are application/x-www-form-urlencoded, and application/json

tenantThe unique ID for the tenant (for example, 07F28C049E0F4F29B8E85E4A6C916D7F)

file_typeThe file type you are using to ingest time series data. It is a required parameter. The permitted valuesare json, X-GE-CsvFormat, and ProficyFileCollectorCSV

dataSourceThe data source you are using for time series data. This parameter is optional. If provided, overridesthe default data source defined in the configuration file. For example, predixtss.PredixTSS is atime series data source.

200On successful ingestion, a 200 OK message appears.


Ingest Time Series Data

Before You Begin

Note: The maximum number of concurrent ingestion processes is 10. Additional processes are enqueueduntil threads become available.

You need the following files and information:

• Time series data stored JSON, ZIP or CSV file format.

Note: The maximum file size per ingestion is 50MB.

Make sure that the time stamp provided in the CSV file is in the YYYY-MM-DDTHH:MM:SS.000 format.• Supported numeric, string, and Boolean tag values.• OAuth token used to ingest time series data.

Important: Make sure you have a valid, unexpired token. Tokens are client-specific and expire within aspecified time. Check the JSON response for the token expiration.

• In the Setup section, obtain the following information:

◦ Client ID◦ Time Series Data ingestion URL◦ User name

• Access to a REST client such as Postman or Advanced REST client.

Note: Time Series Data performs a check to ensure users can only query tags that are associated withassets they have permission to access. If tags are not associated with a Predix Essentials asset, orpermission is not configured properly, users can no longer query time series data using Time Series Data.

The following table describes the value and their definitions as it relates to quality:

Value Description

0 Bad quality.

1 Uncertain quality.

2 Not applicable.

3 Good quality. If you do not specify quality, the default is good (3).

Procedure

1. In the REST client, enter the ingestion URL in the HOST value field. Append the required queryparameters. For example, to ingest ODB format into Time Series Data, the query parameters aredataSource=predixtss.PredixTSS&file_type=ODBExportCSV.

Note: You can obtain this URL in the Setup section.2. Select POST.3. Add the required headers.4. In the Body field, perform one of the following actions depending on the content-type of the raw

request.


If file_type is Do this

ODBExportCSV a. Select form-data.

b. Select CSV file from the drop-down list box.

c. Paste the time series data in text format in the Body field.

The following code sample shows a time series in comma-separated format as exported from an Oracle database:

Time,298936.AUTOMATION,298936.AFPAP,298936.AFPCS,298936.AFPEP,298936.CA_CRT 9/15/15 2:22:02 PM,182.4691925,30.22567177,3.45894742,0,96.1139679 9/15/15 2:27:02 PM,182.1760254,30.22491646,3.397117376,0,96.15263367 9/15/15 2:32:02 PM,182.2230225,30.22415924,3.405554295,0,96.19130707 9/15/15 2:37:02 PM,181.9922791,30.22340202,3.410028934,0,96.22998047

JSON a. Select rawb. Select JSON (application/json) from the drop-down list

box.c. Paste the time series data in JSON format in the Body field.

The following code sample shows time series data withmultiple tags:

{ "tags": [ { "tagId": "TagLength", "data": [ { "ts": "2015-04-13T18:10:00.000-0000", "v": "1.123", "q": "3" }, { "ts": "2015-04-13T18:11:00.000-0000", "v": "3.223", "q": "3" }, { "ts": "2015-04-13T18:12:00.000-0000", "v": "1.323", "q": "3" }, { "ts": "2015-04-13T18:13:00.000-0000", "v": "3.423", "q": "3" }, { "ts": "2015-04-13T18:14:00.000-0000", "v": "1.523", "q": "3" }, { "ts": "2015-04-13T18:15:00.000-0000", "v": "", "q": "3" } ] }, { "tagId": "TagPressure", "data": [ { "ts": "2015-04-13T18:00:00.000-0000", "v": 2.231, "q": "3" }, { "ts": "2015-04-13T18:01:00.000-0000", "v": 2.232, "q": "3" }, { "ts": "2015-04-13T18:02:00.000-0000", "v": 2.233, "q": "3" }, { "ts": "2015-04-13T18:03:00.000-0000", "v": 2.234, "q": "3" }, { "ts":


If file_type is Do this

"2015-04-13T18:04:00.000-0000", "v": null, "q": "3" }, { "ts": "2015-04-13T18:05:00.000-0000", "v": null, "q": "3" } ] }, { "tagId": "Tag_Temperatue", "data": [ { "ts": "2015-04-13T18:10:00.000-0000", "v": "1.123", "q": "3" }, { "ts": "2015-04-13T18:11:00.000-0000", "v": "3.223", "q": "3" }, { "ts": "2015-04-13T18:12:00.000-0000", "v": "1.323", "q": "3" }, { "ts": "2015-04-13T18:13:00.000-0000", "v": "3.423", "q": "3" }, { "ts": "2015-04-13T18:14:00.000-0000", "v": "1.523", "q": "3" }, { "ts": "2015-04-13T18:15:00.000-0000", "v": "3.623", "q": "3" } ] } ] }

ProficyFileCollectorCSV a. Select form-datab. Select File from the drop-down list box.

c. Select Choose Files to attach a valid CSV file for ingestion.

The following code sample shows valid time series data in plain-text format (comma-separated values from a Proficy Historianfile collector export):

1445752668,BFP_PenDemo.Tag_Length,13.20765,Double,GOOD1445752768,BFP_PenDemo.Tag_Length,18.782133,Double,GOOD1445752868,BFP_PenDemo.Tag_Length,36.648777,Double,GOOD1445752968,BFP_PenDemo.Tag_Length,36.648777,Double,GOOD1445753068,BFP_PenDemo.Tag_Length,36.648777,Double,GOOD1445753168,BFP_PenDemo.Tag_Length,36.648888,Double,GOOD

In this sample, each row shows the following data sequence:

a. Timestamp in UNIX EPOCH format (for example,1445752668).

b. Tag name (for example, BFPPenDemo.TagLength).c. Tag value (for example: 13.20765).d. Data type (for example, Double).e. Data quality (for example, good).

5. Select Send.


Results

Upon successful request, a 201 created message appears.

Verify Time Series IngestionAfter ingesting time series data using the REST endpoint, you can use HTTP POST, cURL, or PredixEssentials to verify proper ingestion.

Before You Begin

You must have ingested the asset model with tag data and ingested time series data for the previouslyingested tags in the asset model using the POST method for a specific tenant. For that tenant, you musthave access permission for assets you wish to query and access time series data.

About This Task

You can use one of the following ways to retrieve the ingested time series data:

• Use HTTP POST method.• Use the cURL command to retrieve data.• Plot tags using the Analysis tab in the Predix Essentials application.

Procedure

• Using the HTTP POST method

1. In the REST client, select POST.2. Enter the retrieval URL in the HOST value field.3. Add the required headers.4. In the Body field, select raw.5. Select JSON (application/json) from the drop-down box.6. Paste the JSON format in the Body field with the required retrieval parameters. Make sure you

provide the tags list, start and end time to retrieve specific the ingested time series data.

On successful retrieval, you receive 200 OK and tag data in requested format.• Using the cURL command

1. Access the command prompt.2. Run a cURL command as shown in the example below to retrieve the required time series data.

curl 'https://api.example.com/v3/time_series/query' -i -X POST -H 'Content-Type: application/json' -H 'accept: application/json' -H 'accept: application/json' -H 'Authorization: <Authorization>' -H 'tenant: <tenant>' -d '{ "tagList" : [ { "tagId" : "Inverter1-ASSET-TYPE1.Tag_Pressure", "unitsTo" : "psi", "attributes" : { "kay1" : [ "value1" ], "key2" : [ "value2" ] }, "groups" : [ { "name" : "attribute", "attributes" : [ "Key1", "key2" ] } ] }, {


"tagId" : "Inverter1-ASSET-TYPE2.Tag_Temperature", "unitsTo" : "c" }, { "tagId" : "Inverter1-ASSET-TYPE3.Tag_Length" } ], "operation" : "raw", "startTime" : "2016-02-09T15:00:00.000Z", "endTime" : "2016-02-09T16:00:00.000Z", "sampleCount" : 300, "useOnlyGoodData" : true, "direction" : "forward", "responseFormat" : "PROFICYLIKE", "precisionLevel" : "3", "useOnlyNumericData" : true}

On successful retrieval, you receive 200 OK and tag data in requested format.• Use Predix Essentials to plot tags

1. Log into Predix Essentials.2. In the module navigation menu, select Essentials > Analysis.3. Navigate to the specific asset from the Context Browser.4. Select New Ad Hoc Analysis from the View Selector. The Ad Hoc Analysis view displays with no

tags plotted.5. Use the Date Picker to select a date and time range.

Note: Select a date and time-range around when the time series data was ingested into the tenantto obtain the resulting time-series data for the specific asset tags.

6. To plot tags from the search list to the chart:

a. Select , and enter at least three characters.

Tip: The search allows you to find a tag that includes the characters sequentially entered.b. Select a tag in the search list, drag it over a chart, and then drop it on the chart. The selected

chart is highlighted and framed as you drop the tag. If the tag is already plotted on the selectedchart, Predix Essentials displays an error message.

c. Close the Search field to access the list of plotted tags.7. Select List, and then select Save as Template.8. Type a unique label for the template, and then select Save.

Your analysis view is saved to the selected asset. You can use the View drop-down list box to selectthe saved view. This way you do not have to plot tags again. Predix Essentials allows tags with no datafor a specified time range to be plotted to a chart. The tag displays in the plotted tags list, but is

disabled. indicates that no data is available. Make sure to change the date range to when the timeseries data was ingested to include tag data. This way the tag displays as enabled and plots its data onthe analysis chart.

Predix Time Series Data Bulk Ingestion

You need to work with the Time Series Data team to ingest Predix time series data in bulk. This module isin limited release.


Stream Time Series DataTo ingest time series data into Predix Essentials using a web socket, a ServiceOps ticket is needed to getthe credentials to enable time series data streaming. To perform this task, do the following:

Procedure

1. File http://sc.ge.com/*apmtimeseriesstreaming to request information to enable data streaming foryour tenant. The ticket provides zone ID, web socket URL, scope, client ID, and secret.

2. Follow the https://www.ge.com/digital/product-documentation to initiate web socket streaming.


http://sc.ge.com/*apmtimeseriesstreaming

https://www.ge.com/digital/product-documentation

Chapter

4Time Series Data Delete ServiceTopics:

• About Time Series Data DeleteService

• Time Series Data Delete Service


About Time Series Data Delete ServiceThe Time Series Data Delete service enables you to permanently delete time series data for a list of assettags over a period of time. The time interval can range from as little as an hour to days, months, or evenyears.

Note: Your Time Series Data permissions must include access to the Delete Timeseries scope andto the asset tags that identify the data to be deleted.

Time Series Data Delete ServiceThe Time Series Data Delete service provides two endpoints: v2/time_series/delete and v2/time_series/delete/status.

Delete Time Series Data

The v2/time_series/delete endpoint enables you to delete time series data based on:

• Start time,• End time,• List of asset tags, and• Data source.

Table 8: v2/time_series/delete

URI https://apm-timeseries-services-/v2/time_series/delete

Method DELETE


Request JSON Fields startTime

(required) The startTime field sets the beginning of the time range.

Supported formats include:

• Unix Epoch time in milliseconds

• ISO 8601 format — For example, yyyy-MM-dd'T'HH:mm:ss.SSS or yyyy-MM-

dd'T'HH:mm:ss.SSS±hhmm

Start time must be the beginning of the hour; for example, 03:00:00.000. Any value other

than zero for minutes, seconds, and milliseconds causes an error.

The minimum start time is 1945-07-03T04:00:00.000 GMT.

Note: On dedicated clusters, start time is not restricted to the beginning of the hour.

Minutes, seconds, and milliseconds can be any values within the hour; for example,

03:12:22.072. The minimum start time on dedicated clusters is 1945-07-03T03:38:06.720

GMT.

endTime

(required) The endTime field sets the end of the time range.

Supported formats include:

• Unix Epoch time in milliseconds

• ISO 8601 format — For example, yyyy-MM-dd'T'HH:mm:ss.SSS or yyyy-MM-

dd'T'HH:mm:ss.SSS±hhmm

End time must be the last millisecond of the hour; for example, 11:59:59.999. Any value

other than 59:59.999 for minutes, seconds, and milliseconds causes an error.

The maximum end time is 2214-12-26T10:59:59.999 GMT.

Note: On dedicated clusters, the minutes, seconds, and milliseconds of end time are not

restricted to 59:59.999. Any values within the hour can be used; for example, 09:33.152. The

maximum end time on dedicated clusters is 2214-12-26T11:38:49.200 GMT.

tagList

(required) The tagList field is a comma-separated list of tag source keys. When querying time

series data, you need to refer to a tag by the tag source key as configured in the asset model.

All tags must be associated with corresponding Predix Essentials assets and ensure a time

series link is provided for retrieving the time series data in the data store. The value of the

time series link should match the raw tag name ingested in the Time Series Data data source.

You can query as many as 100 tags per request. To add a tag to the asset model, refer to the

Add a Tag Instance to an Instance documentation. To update the reserved attribute value,

refer to the About Reserved Attributes for an Asset Instance documentation.

dataSource

(required) The dataSource field specifies the name of the data source. The default value is

defined by the data source configuration.


Sample Request DELETE /v2/time_series/delete HTTP/1.1Content-Type: application/jsonAccept: application/jsonAuthorization: <Authorization>Tenant: <tenant>Host: api.example.com

{ "startTime" : "2016-02-09T15:00:00.000Z", "endTime" : "2016-02-09T16:00:00.000Z", "tagList" : [ { "tagId" : "<Tag Id>", "attributes" : { "kay1" : [ "value1" ], "key2" : [ "value2" ] } }, { "tagId" : "<Tag Id>", "attributes" : { "kay1" : [ "value1" ], "key2" : [ "value2" ] } } ],"dataSource" : "<data source name>"}

Response JSON Fields apmCorrelationID

The apmCorrelationID field provides a standard-format UUID that you can use to check the

status of the delete operation. See the Check the Status of a Delete Request on page 36

section below.

statusCode

The value of the statusCode field is the HTTP response code. If the request is accepted, HTTP

response code 202 Accepted is returned. Otherwise, statusCode contains an error response

code.

Sample Response HTTP/1.1 200 OKContent-Type: application/json

{ "apmCorrelationId": "5623038b-e06f-44de-9d81-bc3336fb4b67", "statusCode": 202}

Check the Status of a Delete Request

The v2/time_series/delete/status endpoint enables you to check the status of an HTTPDELETE request made with the Time Series Data Delete service.


Table 9: v2/time_series/delete/status

URI https://apm-timeseries-services-/v2/time_series/delete/status

Method GETQuery Parameters apmCorrelationID

(required) The apmCorrelationID field specifies a standard-format UUID generated by Time

Series Data in response to a DELETE request. See the Delete Time Series Data on page 34

section above.

Sample Request https://apm-timeseries-services-/v2/time_series/delete/status?apmCorrelationID=5623038b-e06f-44de-9d81-bc3336fb4b67

Sample Response { "Job status": "Deletion completed without error", "Submit date": "<Date submitted>", "Completion date": "<Date completed>"}

or

{ "Job status": "Deletion failed", "Submit date": "<Date submitted>", "Error code": "<error code>", "Error message": "<Message text>"}


Chapter

5Troubleshoot Time Series DataTopics:

• Configuration Fields• Time Series Data Delete Service


Configuration FieldsErrors may occur when the following configuration fields contain incorrect values:

asyncFetchMode

Asynchronous queries are not supported in all Time Series Data environments. The following matricesshow the results of Async and Dynamic queries based on the value of asyncFetchMode and whether theenvironment supports asynchronous queries.

Table 10: Environment Supports Asynchronous Queries

asyncFetchMode Async Query Result Dynamic Query Result

true Query returns a correlation ID. Query returns either a correlation ID or data,

depending on the date range of the query.

false (default) Query returns HTTP status code 400 Bad Request. Query is translated to the Sync fetch type and

returns results synchronously.

Table 11: Environment Does Not Support Asynchronous Queries

asyncFetchMode Async Query Result Dynamic Query Result

true Query returns HTTP status code 400 Bad Request. Query returns HTTP status code 400 Bad Request.

false (default) Query returns HTTP status code 400 Bad Request. Query is translated to the Sync fetch type and

returns results synchronously.

Time Series Data Delete ServiceThe Time Series Data Delete service may produce errors in response to service requests.

v2/time_series/delete

The following table contains errors that may occur as a result of requests made to the v2/time_series/delete endpoint.

Table 12: Request Errors

HTTP Status Code Message Cause

403 Access Denied The user does not have access permission to the

Delete Timeseries scope.

400 You either do not have sufficient privileges for the

requested tags or the tags were not found.

The user does not have access permission to the

asset to which the tags apply.

400 Start time is missing. Please provide a start time. A start time was not provided.

400 End time is missing. Please provide an end time. An end time was not provided.


HTTP Status Code Message Cause

400 The tag list is empty. Please provide a tag in the

tag list.

No tags were provided in the tag list.

400 Invalid Start Time. Start time cannot be less than

-773094113280.

The start time was before Tuesday, July 3, 1945

3:38:06.720 AM GMT.

400 Invalid End Time. End time cannot be greater than

7730941129200.

The end time was after Monday, December 26,

2214 11:38:49.200 AM GMT.

None Delete time range does not span exact hours. On shared clusters, the start time must be the

beginning of an hour (for example, nn:00:00.000),

and the end time must be the end of an hour (for

example, nn:59:59.999).


Chapter

6Release NotesTopics:

• Fourth Quarter of 2019• Third Quarter of 2019• Second Quarter of 2019• First Quarter of 2019


Fourth Quarter of 2019

Time Series DataThis topic provides a list of product changes released for this module on the specified dates.

Release Date: December 13, 2019

Table 13: Enhancements and New Features

The following enhancements and new features have been added.

Description Tracking ID

You can now access the Sample and Hold interpolation mode data using the Time Series Data

Retrieval Service v4 and v5 APIs.

F48127

Table 14: Resolved Issues

The following issues, which existed in one or more previous versions, have been resolved.


Previously, in a query, if you specified raw as the operation type and did not use the sampleCount

field, the APM Time Series query service returned only one data point from Proficy Data Sources.

This issue has been resolved. The service now returns all the data points between the specified

date range.

DE122195

Release Date: November 1, 2019


The following issues, which existed in one or more previous versions, have been resolved.


Previously, if you used the QueryDirection field in a query to retrieve data from a Proficy Data

Source, an error occurred. This issue has been resolved. Now, the APM Time Series query service

ignores the QueryDirection field for any tags with a Proficy Data Source.

DE122223


Third Quarter of 2019

Time Series DataThis topic provides a list of product changes released for this module on the dates listed below.

Release Date: September 27, 2019


The following issues that existed in one or more previous versions have been resolved.


Previously, when you attempted to delete time series data, even though you had the Delete

Timeseries permission, an error occurred. This issue has been resolved.

DE119509

Release Date: August 13, 2019




To enhance the usability when retrieving time series data from the OSM data source, queries now

run asynchronously. Asynchronous queries enable applications to continually poll the Time Series

Data service to obtain the query results.

Note: This is applicable only for OSM data sources that can support the asynchronous query

method.

F39400

Second Quarter of 2019


Release Date: June 28, 2019





Queries now support up to 100 tags in the Time Series Data Retrieval Service v4 and v5 APIs and

the v2/time_series/delete endpoint. Previously, the maximum number of tags in a single query

was 40.

Note: The Time Series Data Retrieval Service v2 and v3 APIs still support a maximum of only 40

tags.

US341163

First Quarter of 2019


Release Date: March 29, 2019




To enhance usability when retrieving time series data archived in S3 storage, queries can now run

asynchronously. Asynchronous queries enable applications to continually poll the Time Series

Data service to obtain the query results. This feature is available only in new Predix Time Series

service schema; currently, it is not supported in AWS West.

F34716

To enable users to permanently delete time series data, a new DELETE endpoint has been added.

The endpoint enables users to free up storage space and reduce storage costs. This feature is

available only in new Predix Time Series service schema; currently, it is not supported in AWS

West.

F20644


Time Series Data - GE.com · 2020. 3. 25. · About Time Series Data Sources2. Assign a Default Time Series Data Source4. Modify an Existing Time Series Data Source4. Modify an Existing

Documents