| 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 model as the tagID to query for related time series data. You can query up to 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 one 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
- (required) Type of data to retrieve. The following are the supported values.
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 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").
-
Note: If the start date is empty, then the query searches data back only for last 15 days and provides only one latest data point. If the start date is specified, then the query searches data from given start time to now and provides only one latest data point.
|
| JSON fields |
- 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. -
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. -
Note: Not supported by SmartSignal.
- 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 values are:
true, false, default value, and false. -
Note: Not supported by SmartSignal.
- direction
- (optional) The direction by which data points are retrieved (by timestamp). The supported values are:
backward retrieves data points backwards on the endTime; forward retrieves data points forward on the startTime; default value forwards the data. -
Note: Not supported by SmartSignal.
- 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.
|
| JSON fields |
- 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 a correlation ID, which is used to fetch the query result.DYNAMIC - The provides the query result either synchronously or asynchronously based on the underlying data storage configuration. For synchronous queries, users are provided with the query results; for asynchronous queries, users receive a correlation ID.
Note:
fetchType is supported only for the and Proficy Historian data source types. For other data source types, fetchType is ignored, and the results are returned in synchronous mode.
ASYNC and DYNAMIC fetch types are not supported in all infrastructures, in which case ASYNC queries return a 400 error, and DYNAMIC queries are handled as SYNC queries.
- asyncCorrelationId
- The –generated correlation ID used to retrieve the results of previously submitted queries using the
ASYNC and DYNAMIC fetch types.
|
| Method | POST |
| Sample Request |
POST /v5/time_series/query HTTP/1.1
Content-Type: application/json
accept: application/json
Authorization: <Authorization>
tenant: <tenant>
Host: api.example.com
Content-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 OK
Content-Type: application/json;charset=UTF-8
Content-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 the tags in the list, partial access, or no access. However, the response includes only the tags for which you have permissions. If either the tag does not exists or you do not have permissions, it will not appear in the response. If you have no access to the entire list of tags, you still receive a 200 OK with an empty list. |