MetricBase Time Series API
The MetricBase Time Series API provides endpoints to insert data into, retrieve information from, and to run transforms against a MetricBase database.
This API can only be used when the MetricBase plugin (com.snc.clotho) is installed and activated.
Role required to write to this API: clotho_rest_put.
The examples in this section were created using data in the MetricBase (com.snc.clotho) plugin.
Parent Topic:REST API reference
MetricBase Time Series - GET /now/clotho/table/{table}/{subject}/{metric}
Retrieves specified time series data from the MetricBase database.
URL format
Versioned URL: /api/now/{api_version}/clotho/table/{table}/{subject}/{metric}
Supported request parameters
| Name | Description |
|---|---|
| api\_version | |
| metric | Name of the column in the table identified in the subject parameter to use as the metric.Data type: String |
| subject | Sys\_id of the GlideRecord associated with this series.Data type: String |
| table | Name of the table containing the GlideRecord associated with this series.Data type: String |
| Name | Description |
|---|---|
| sysparm\_display\_value | Flag that indicates whether to label the result data with the subject record display value if no other label is specified.Valid values: - true: Result data is labeled with the subject record display value. - false: Result data is not labeled with the subject record display value. Data type: Boolean Default: false |
| sysparm\_end | Required. End time of the evaluation period. An empty or missing value is treated as the current time. Time values are inclusive of this end time.Data type: String Format: ISO 8601 \(UTC\), either: - Absolute date format \[YYYY-MM-DDThh:mm:ss\], such as `2019-03-20T17:04:55`. - Relative to current time duration format`[P(n)Y(n)M(n)DT(n)H(n)M(n)S]`, such as `P1M`. |
| sysparm\_start | Required. Start time of the evaluation period. The special value `all` can be used to set the start time as the current time minus the maximum retention period for the specified metrics. An empty or missing value is treated as an implicit `all`. Time values are inclusive of this start time.Data type: String Format: ISO 8601 \(UTC\), either: - Absolute date format \[YYYY-MM-DDThh:mm:ss\], such as `2019-03-20T17:04:55` - Relative to current time duration format`[P(n)Y(n)M(n)DT(n)H(n)M(n)S]`, such as `P1M`. |
| Name | Description |
|---|---|
| None |
Headers
The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.
| Header | Description |
|---|---|
| Accept | Data format of the response body. Only supports application/json. |
| Header | Description |
|---|---|
| None |
Status codes
The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.
| Status code | Description |
|---|---|
| 200 | Successful. The request was successfully processed. |
| 401 | Unauthorized. The user credentials are incorrect or have not been passed. |
| 500 | Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error. |
Response body parameters (JSON or XML)
| Name | Description |
|---|---|
| label | Label used to identify this metric’s result set. Data type: String |
| seriesRef | Data series results. Data type: Array of Objects |
| seriesRef.metric | Name of the metric from which the data series was obtained. Only appears if the metrics object is passed in the request.Data type: String |
| seriesRef.subject | Sys_id of the data series record. Located in the table specified in seriesRef.table.Data type: String |
| seriesRef.table | Name of the table from where the data series was obtained.Data type: String |
| values | Transformed series values.Data type: Array of Objects |
| values.timestamp | Timestamp of the value.Data type: String Format: ISO 8601 |
| values.value | Metric values.Data type: Number |
cURL request
curl "https://instance.servicenow.com/api/now/v1/clotho/
table/mb_demo_drone/626b051787333200a328c5b836cb0b99/
mb_demo_mt_altitude?sysparm_start=2019-03-20T17%3A04%3A55
&sysparm_end=2019-03-20T17%3A09%3A55" \
--request GET \
--header "Accept:application/json" \
--user "username":"password"
{
"seriesRef": {
"subject": "626b051787333200a328c5b836cb0b99",
"table": "mb_demo_drone",
"metric": "mb_demo_mt_altitude"
},
"label": "626b051787333200a328c5b836cb0b99:
mb_demo_drone|mb_demo_mt_altitude",
"values": [
{
"timestamp": "2019-03-20T17:05:00Z",
"value": 83.150185
},
{
"timestamp": "2019-03-20T17:06:00Z",
"value": 83.46074
},
{
"timestamp": "2019-03-20T17:07:00Z",
"value": 83.83104
},
{
"timestamp": "2019-03-20T17:08:00Z",
"value": 84.260635
},
{
"timestamp": "2019-03-20T17:09:00Z",
"value": 84.749
}
]
}
MetricBase Time Series - GET /now/clotho/transform/{table}/{metric}
Transforms the specified data based on the specified parameters.
URL format
Versioned URL: /api/now/{api_version}/clotho/transform/{table}/{metric}
Supported request parameters
| Name | Description |
|---|---|
| api\_version | |
| metric | Name of the column in the table identified in the subject parameter to use as the metric.Data type: String |
| table | Name of the table containing the GlideRecord associated with this series.Data type: String |
| Name | Description |
|---|---|
| sysparm\_display\_value | Flag that indicates whether to label the result data with the subject record display value if no other label is specified.Valid values: - true: Result data is labeled with the subject record display value. - false: Result data is not labeled with the subject record display value. Data type: Boolean Default: false |
| sysparm\_end | Required. End time of the evaluation period. An empty or missing value is treated as the current time. Time values are inclusive of this end time.Data type: String Format: ISO 8601 \(UTC\), either: - Absolute date format \[YYYY-MM-DDThh:mm:ss\], such as `2019-03-20T17:04:55`. - Relative to current time duration format`[P(n)Y(n)M(n)DT(n)H(n)M(n)S]`, such as `P1M`. |
| sysparm\_query | Encoded query string for finding the subject records.Data type: String Default: None |
| sysparm\_start | Required. Start time of the evaluation period. The special value `all` can be used to set the start time as the current time minus the maximum retention period for the specified metrics. An empty or missing value is treated as an implicit `all`. Time values are inclusive of this start time.Data type: String Format: ISO 8601 \(UTC\), either: - Absolute date format \[YYYY-MM-DDThh:mm:ss\], such as `2019-03-20T17:04:55` - Relative to current time duration format`[P(n)Y(n)M(n)DT(n)H(n)M(n)S]`, such as `P1M`. |
| sysparm\_subject\_limit | Limit size of the subject query result. Data type: Number Default: 10,000 |
| sysparm\_transforms | Comma separated list of transforms. Valid transforms: - add - avg - label - mul - resample - sum - top Data type: String Default: None |
| Name | Description |
|---|---|
| None |
Headers
The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.
| Header | Description |
|---|---|
| Accept | Data format of the response body. Supported types: application/json or application/xml. Default: application/json |
| Header | Description |
|---|---|
| None |
Status codes
The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.
| Status code | Description |
|---|---|
| 200 | Successful. The request was successfully processed. |
| 401 | Unauthorized. The user credentials are incorrect or have not been passed. |
| 500 | Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error. |
Response body parameters (JSON or XML)
| Name | Description |
|---|---|
| label | Label used to identify this metric’s result set. Data type: String |
| seriesRef | Data series results. Data type: Array of Objects |
| seriesRef.metric | Name of the metric from which the data series was obtained. Only appears if the metrics object is passed in the request.Data type: String |
| seriesRef.subject | Sys_id of the data series record. Located in the table specified in seriesRef.table.Data type: String |
| seriesRef.table | Name of the table from where the data series was obtained.Data type: String |
| values | Transformed series values.Data type: Array of Objects |
| values.timestamp | Timestamp of the value.Data type: String Format: ISO 8601 |
| values.value | Metric values.Data type: Number |
cURL request
curl "https://instance.servicenow.com/api/now/v1/clotho/
transform/mb_demo_drone/mb_demo_mt_speed?
sysparm_query=model%3DKingfisher%20Phantom&
sysparm_start=2019-03-25T17%3A04%3A55&
sysparm_end=2019-03-25T17%3A05%3A10" \
--request GET \
--header "Accept:application/json" \
--user "username":"password"
Output:
[
{
"seriesRef": {
"subject": "2a6b051787333200a328c5b836cb0b92",
"table": "mb_demo_drone",
"metric": "mb_demo_mt_speed"
},
"label": "2a6b051787333200a328c5b836cb0b92:mb_demo_drone
|mb_demo_mt_speed",
"values": [
{
"timestamp": "2019-03-25T17:05:00Z",
"value": 33.67892
}
]
},
{
"seriesRef": {
"subject": "666b051787333200a328c5b836cb0b92",
"table": "mb_demo_drone",
"metric": "mb_demo_mt_speed"
},
"label": "666b051787333200a328c5b836cb0b92:mb_demo_drone
|mb_demo_mt_speed",
"values": [
{
"timestamp": "2019-03-25T17:05:00Z",
"value": 41.94985
}
]
},
{
"seriesRef": {
"subject": "a26b051787333200a328c5b836cb0b92",
"table": "mb_demo_drone",
"metric": "mb_demo_mt_speed"
},
"label": "a26b051787333200a328c5b836cb0b92:mb_demo_drone
|mb_demo_mt_speed",
"values": [
{
"timestamp": "2019-03-25T17:05:00Z",
"value": 37.74187
}
]
},
{
"seriesRef": {
"subject": "ea6b051787333200a328c5b836cb0b92",
"table": "mb_demo_drone",
"metric": "mb_demo_mt_speed"
},
"label": "ea6b051787333200a328c5b836cb0b92:mb_demo_drone
|mb_demo_mt_speed",
"values": [
{
"timestamp": "2019-03-25T17:05:00Z",
"value": 34.914192
}
]
},
{
"seriesRef": {
"subject": "ee6b051787333200a328c5b836cb0b91",
"table": "mb_demo_drone",
"metric": "mb_demo_mt_speed"
},
"label": "ee6b051787333200a328c5b836cb0b91:mb_demo_drone
|mb_demo_mt_speed",
"values": [
{
"timestamp": "2019-03-25T17:05:00Z",
"value": 44.170887
}
]
}
]
MetricBase Time Series - POST /now/clotho/accumulate
Accumulates metric values at specified timestamp and saves the result to the database rather than overwriting the value.
Use this API to handle metrics that can be summed for an accumulation, such as kilowatt-hours (kWhs) of electricity. Accumulate makes a call for each metric at the provided timestamp. For example, collected kilowatts for a heater, electric kettle, and washing machine would result in three calls to accumulate.
URL format
Versioned URL: /api/now/{api_version}/clotho/accumulate
Supported request parameters
| Name | Description |
|---|---|
| api\_version | Optional. Version of the endpoint to access. For example, `v1` or `v2`. Only specify this value to use an endpoint version other than the latest. Data type: String |
| Name | Description |
|---|---|
| default\_value | Default value for accumulation at a given timestamp. Used only during the first call to accumulate if a value is unavailable for a given timestamp. A use case could be accumulating a watts metric for a total\_power. You want to accumulate watts for a router connected to an outlet without a power meter to measure it. If you know the consumption value and it is constant\), you can use the constant value as a default value to accumulate total\_power. For example, you would use 20 if the router is constantly plugged in and consumes 20 Watts. Data type: String Default: 0 |
| sysparm\_ignore\_unknown\_series | Flag that indicates whether to ignore an unknown series and continue the transaction without returning an error.Valid values: - true: Ignore unknown series. - false: Don't ignore unknown series. Default: true |
| Name | Description |
|---|---|
| seriesRef | List of strings representing data series information to update.Data type: Array |
| seriesRef.metric | Required. Name of the accumulating metric to update.Data type: String |
| seriesRef.subject | Required. Sys_id of the record in which to update the data.Data type: String Table: Specified in seriesRef.table |
| seriesRef.table | Required. Name of the table in which to save the data.Data type: String |
| values | Required. Series values to accumulate and store. Values with the same timestamp are summed up with the default_value query parameter.Data type: Array |
| values.timestamp | Required. ISO 8601 timestamp of the value.Data type: String Format: YYYY-MM-ddTHH:mm:ddZ The character represented by 'Z' denotes the UTC time zone in an ISO-formatted timestamp. This portion of the timestamp format is optional. Example: `2019-03-21T17:05:00Z` |
| values.value | Required. Metric value.Data type: Number |
Headers
The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.
| Header | Description |
|---|---|
| Accept | Data format of the response body. Only supports application/json. |
| Content-Type | Data format of the request body. Only supports application/json. |
| Header | Description |
|---|---|
| None |
Status codes
The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.
| Status code | Description |
|---|---|
| 200 | Successful. The request was successfully processed. |
| 401 | Unauthorized. The user credentials are incorrect or have not been passed. |
| 500 | Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error. |
Response body parameters (JSON or XML)
| Name | Description |
|---|---|
| message | Message indicating success (OK) or error. |
cURL request
This example shows how to accumulate metric values at a given timestamp.
curl "https://instance.servicenow.com/api/now/v1/clotho/accumulate" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
\"seriesRef\": {
\"subject\": \"3D666b051787333200a328c5b836cb0b92\",
\"table\": \"power_monitoring\",
\"metric\": \"total_power\"
},
\"values\": [
{
\"timestamp\": \"2019-03-21T17:05:00Z\",
\"value\": 0.150185
},
{
\"timestamp\": \"2019-03-21T17:05:00Z \",
\"value\": 0.46074
},
{
\"timestamp\": \"2019-03-21T17:05:00Z \",
\"value\": 0.83104
},
{
\"timestamp\": \"2019-03-21T17:05:00Z \",
\"value\": 1.260635
},
{
\"timestamp\": \"2019-03-21T17:05:00Z \",
\"value\": 1.749
}
]
}" \
--user "username":"password"
Output provided with successful results.
{
"result": {
"message": "ok"
}
}
MetricBase Time Series - POST /now/clotho/transform
Retrieves and optionally groups time series data for one or more metrics after applying a specified list of transforms that form a linear pipeline.
URL format
Versioned URL: /api/now/{api_version}/clotho/transform
Supported request parameters
| Name | Description |
|---|---|
| api\_version | Optional. Version of the endpoint to access. For example, `v1` or `v2`. Only specify this value to use an endpoint version other than the latest. Data type: String |
| Name | Description |
|---|---|
| sysparm\_display\_value | Flag that indicates whether to label the result data with the subject record display value if no other label is specified.Valid values: - true: Result data is labeled with the subject record display value. - false: Result data is not labeled with the subject record display value. Data type: Boolean Default: false |
| Name | Description |
|---|---|
| end | Required. End time of the evaluation period. An empty or missing value is treated as the current time. Time values are inclusive of this end time.Data type: String Format: ISO 8601 \(UTC\), either: - Absolute date format \[YYYY-MM-DDThh:mm:ss\], such as `2019-03-20T17:04:55`. - Relative to current time duration format`[P(n)Y(n)M(n)DT(n)H(n)M(n)S]`, such as `P1M`. |
| limit | Maximum number of records to return. Unusually large values can impact system performance.Data type: Number Default: 10,000 |
| metrics | List of metrics objects to use in the transform. For more information on metrics, see Metrics.Data type: Array ``` "metrics": [ { "groupBy": "String" "label": "String", "metric": "String", "transforms": [Array] } ] |
| results.grouped.groups.series.label | Label of the series.Data type: String |
| results.grouped.groups.series.seriesRef | Results of a single data series. Does not appear if there are multiple data series in the response.Data type: Object ``` "seriesRef": { "metric": "String", "subject": "String", "table": "String" } |
| metrics.label | Label to use for this metric’s result set. It replaces any labels generated by the transform chain.Data type: String Default: Generated default label. |
| metrics.metric | Required if metrics object is passed. Metric field to use in the transform. This field must be in the table specified in the table parameter. Data type: String |
| metrics.transforms | List of transforms \(transform chain\) to apply to the retrieved time series data. Each transform builds on the results of the previous transform. For a list of available transforms, see Supported Transforms below.Data type: Array of Objects |
| metrics.transforms.arg | Dependent on the transform. Parameter or parameters to pass into the transform.General guidelines:
Data type: Number, String, Boolean, or JSON object, depending on transform. (For a list of available transforms, refer to the table Supported transforms below.) |
| metrics.transforms.name | Required if a transforms object is specified. Name of the transform.For a list of available transforms, refer to the table Supported transforms below. Data type: String |
| query | Encoded query to use to filter the result set. You can compose the query using the specified table’s filter editor. Once created, select Copy URL from the filter’s breadcrumbs context menu. Data type: String Default: None |
| start | Required. Start time of the evaluation period. The special value `all` can be used to set the start time as the current time minus the maximum retention period for the specified metrics. An empty or missing value is treated as an implicit `all`. Time values are inclusive of this start time.Data type: String Format: ISO 8601 \(UTC\), either: - Absolute date format \[YYYY-MM-DDThh:mm:ss\], such as `2019-03-20T17:04:55` - Relative to current time duration format`[P(n)Y(n)M(n)DT(n)H(n)M(n)S]`, such as `P1M`. |
| table | Required. Name of the table that contains the GlideRecord associated with this series.Data type: String |
Headers
The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.
| Header | Description |
|---|---|
| Accept | Data format of the response body. Supports the following: - application/json - application/octet-stream or - text/csv To specify the CSV format, use |
| Content-Type | Data format of the request body. Only supports application/json. |
| Header | Description |
|---|---|
| None | Data format of the response body. Based on the specified Accept values of the request, use:- application/json - application/octet-stream or - text/csv If multiple Accept types are specified, the first supported type is returned. |
Status codes
The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.
| Status code | Description |
|---|---|
| 200 | Successful. The request was successfully processed and data will begin streaming.Note: A 200 response can still incur a processing error midstream as the transforms are computed. |
| 400 | Bad Request. A bad request type or malformed request was detected. |
| 401 | Unauthorized. The user credentials are incorrect or have not been passed. |
| 404 | Not found. The requested item wasn't found. |
| 405 | Invalid method. The functionality is disabled. |
| 500 | Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error. |
Response body parameters (Octet-stream or JSON)
| Name | Description |
|---|---|
| Output Stream \(Octet-Stream\) | If the Accept request header is set to application/octet-stream, the matching MetricBase data is returned as a binary serialized stream. The Clotho-Util for Java applications provide a deserializer that enables you to parse this data.The stream consists of a binary serialization of each datum, preceded by an integer representing its length. The following entries describe the data within the binary representation and the order of that data. |
| CSV Stream \(UTF-8 Stream\) | If the Accept request header is set to text/csv, the matching MetricBase data is returned as UTF-8 encoded CSV data in wide or narrow formats.A narrow format returns subject and time stamp columns and a column for each returned metric. A wide format returns a time stamp column with a separate column for each metric-subject pair. |
| Subject | Source of the data. For example, if the metric for the data is drone altitudes, this value may be the ID of a specific drone. If a colon is included in the value, the parts after the subject represent the metric that the data is a part of. Null values are represented by an encoded empty string.Data type: String \(Java Modified UTF\) Size: 2+ bytes |
| Dimension | Metric that the data is from. Null values are represented by an encoded empty string. Data type: String \(Java Modified UTF\) Size: 2+ bytes |
| Label | Label of the data. Null values are represented by an encoded empty string.Data type: String \(Java Modified UTF\) Size: 2+ bytes |
| Type | Type of data encoded into a byte.Possible values: - Float Mode - Float Signal - Double Model - Double Signal Data type: Byte Size: 1 byte |
| Flags | Encoded serializeFlags variable. If serializeTags is true and the data contains tags, the value is 2, otherwise it is 0.Data type: Byte Size: 1 byte |
| Period | Period associated with the data. Data type: Number \(Integer\) Size: 4 bytes |
| Number of Tags | If serializeTags is true, then this is the number of tags stored in the data. Data type: Number (Integer) Size: 4 bytes |
| Tags | If serializeTags is true, each tag is stored in the data.Data type: String (Java modified UTF) Size: Depends on number of tags (2+ bytes). |
| Start Epoch Second | Epoch UTC time representing the start time of this data series. Data type: Number \(Long\) Size: 8 bytes |
| Number of Values | Number of values stored in this data. Data type: Number \(Integer\) Size: 4 bytes |
| Values | If Type is Data type: Number (Float) |
| Values | If Type is Size: Number of Values * 4 bytes |
| Model Json \(Model\) | If Type is Size: 2+ bytes |
| Big Model Marker \(Big Model\) | If the length of the model’s JSON is greater than 65,535 bytes, then this field is written instead of the Model Json. Data type: String (Java Modified UTF) Size: 5 |
| Big Model Size \(Big Model\) | Length of the JSON representation of the big model. Data type: Number \(Integer\) Size: 4 bytes |
| Big Model Json \(Big Model\) | JSON representation of the model as a series of UTF characters, The size is dictated by the Big Model Size field.Data type: String (UTF chars) Size: 65535-256000 bytes |
| JSON Stream \(JSON\) | If the Accept request header is set to application/json, the matching MetricBase data is returned as a stream of new line separated JSON objects. The following entries describe the possible elements in each returned object. |
| label | Data’s label. This value is either generated by the endpoint or is the value passed in the metrics.label parameter.Data type: String |
| period | Amount of time between each value. For example, a period of 60 would mean that each value is a minute apart. Data type: Number Unit: Seconds |
| range | Start and end times of the data Data type: Array Format: ISO 8601 \(UTC\) |
| series | Identifies the individual data. If present, is typically in the form of `[glide record id]:[metric]`. This may not be present when using transforms.Data type: String |
| species | Type of return data. For a series of either float or double values, this is either FLOAT\_SIGNAL or DOUBLE\_SIGNAL. For a model meant to analyze float or double data, this is either FLOAT\_MODEL or DOUBLE\_MODEL.Data type: String |
| tags | Tags associated with the data.Data type: Array of Strings |
| value | Float or Double values for the data.Data type: Array of Numbers |
| error | Error message if the transformation of the specified data series fails.Data type: String |
Supported transforms
| Transform | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| add | Adds the specified number to each timestamp value.Argument: arg \(Decimal data type\) – Number to add. For example: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| autocorrelate | Calculates the correlation between timestamp values separated by an increasing number of periods starting at 1. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| avg | Aggregates the time series into one series containing the average value for each corresponding timestamp across the input. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| bottom | Returns the specified number of series that have the lowest values.Argument: `arg` \(Integer\) – The number of series to return. For example, the following returns the two time series that contain the lowest sets of values. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| ceil | Rounds the value in each timestamp up to the specified precision: `ceil(value / | collect | Displays the transform results of the transform chain up to the point of the collect transform call. Collect transform results contain a unique marker, but you may want to also define a label.For example: | constrainValues | Replaces any value outside the specified range with the corresponding maximum or minimum value.For example, if you specified the following, the transform replaces any value that is less than 0 with 0, and any value that is more than 100 with 100. | count | Aggregates the time series into one series. The new series contains the number of values that are not NaN \(Not a Number\) for each corresponding timestamp across the series. | derivative | Determines the rate of change between timestamps. Divides the difference between the value in each timestamp and the value in the next timestamp by the timestamp’s period.Note: This transform returns one less value than the number of values in the series. | div | Divides the value in each timestamp by the specified number \(arg\).Argument: arg \(Decimal – The number by which to divide the value of each timestamp. | envelope | Returns two time series, where, at any point in time, one contains the largest value and the other contains the smallest value.Note: NaNs are ignored, but are returned if there are no other return values. | exp | Raises the value of the specified base to the power of the value in each timestamp.Argument: arg \(Decimal data type\) – The base value. | filter | Applies an aggregator to the contents of a sliding window, such as producing a moving average.Arguments: - aggregator \(Aggregator data type\): Type of aggregation to perform. - window \(Duration data type\): The duration of the sliding window. | floor | Rounds the value in each timestamp down to the specified precision: `floor(value / | fractiles | Returns a time series for each fraction in the specified array. Each timestamp value is the value at which the specified fraction of values, for the corresponding timestamp across the input series, is below the specified percentage. For example, if the fraction is 0.5, then the value in the timestamp is the value where half the values in the input series are below 0.5.Argument: arg \(Array of Decimal\) – The fractions to use on the input series. For example: | groupBy | Groups data by the specified fields before collecting or applying aggregated transformations.Argument: arg \(String\) - A comma separated list of fields in the table to use to group the transform results. For example: | integrate | Multiplies the value in each timestamp by its period. | interpolate | Creates a data value for a NaN data item by interpolating from adjacent data values.Argument: arg \(Integer\) – Number of data samples in each direction to check for a non-NaN value. If a non-NaN value is not found, then NaN is used. | inverse | Computes the inverse of each timestamp value. | iqr | Performs an interquartile range transform and creates a result set that contains four series: 1. -IQR: The median of all entries below Note: label | Labels a transformation chain.Note: Subsequent transformations may modify or replace the label. Argument: arg (String) – Text of the label. Can contain the following formatting expressions:
For example: limit | Returns, at most, the specified duration or number of values, starting with the most recently saved value.Arguments: - arg \(Integer\): Number of timestamp values to return for each time series. OR - arg \(Duration data type\): Duration to limit each time series to. | log | Runs a logarithm on the value in each timestamp where the result is the log of the specified base for the timestamp value.Argument: arg \(Decimal data type\) – Base for the logarithm calculation. | mapValues | Replaces any values within the specified range (inclusive) with the specified value. If both lowerBound and upperBound are specified as NaN, then it replaces any NaN value with the targetValue.Arguments:
For example, the following changes all values in the time series that are between .1 and .9 to 1: max | Returns a series that contains the maximum value for each corresponding timestamp across the input. | median | Creates a series that contains the median of values for each timestamp across a set of series.If there are `n` series: - If `n` is odd, the median is the `(n / 2 + 1)` value for a timestamp. - If `n` is even, the median is the average of the `(n / 2)` and `(n / 2 + 1)` values for a timestamp. | min | Returns a series that contains the minimum value for each corresponding timestamp across the input. | mul | Multiplies the value in each timestamp by the specified number.Argument: arg \(Decimal data type\) – Number by which to multiply the value of each timestamp. | partition | Produces a new series with values filtered by applying a specified aggregator to a non-overlapping window. Arguments: - aggregator \(Aggregator data type\): Type of aggregation to perform. - base \(DateTime data type\): The zero offset to use for partitioning. For example, to partition by day \(24h\), set this value to Monday at midnight in your time zone. To partition by a 30-day period, set this value to the first day of the most recent month. Default: Beginning of the EPOCH. - window \(Duration data type\): The duration of the non-overlapping window to apply the aggregator. | pow | Raises each timestamp value to the specified power.Argument: arg \(Decimal data type\) – Power to which to raise each value. | product | Aggregates the selected metric series into a single series that contains the product of all values for each timestamp. NaNs are excluded. If all numbers in the series are NaN, the output is also NaN. | resample | Resamples a time series to either a fixed number of points or from one frequency to another.Use the resample transformation to reduce the number of samples in the result set to more closely match the number of samples that you want to display. Arguments: You can pass various arguments for this transform. Below is a list of each of the possible argument groups. Only one of these argument groups can be passed within a single transform. The following argument groups are delineated by AND/OR. AND meaning the argument is part of the current group; OR meaning it is the start of a new argument group.
OR
OR
AND
OR
AND
OR
AND
OR
AND
AND
round | Rounds the value in each timestamp up to the specified precision: `(value / | root | Calculates the root of each timestamp value using the specified index.Argument: arg \(Decimal data type\) – The index of the root. For example, the following returns the square root of each timestamp: | stddev | Creates a series that contains the standard deviation of values for each timestamp across a set of series. | sub | Subtracts the specified number from the value in each timestamp.Argument: arg \(Number\) – The number to subtract from the value in each timestamp. | sum | Aggregates the selected metric series into one series that contains the sum of all values for each timestamp, excluding any NaNs. If all numbers in the series are NaN, the output is NaN. | timeshift | Shifts the time range by adding the specified offset to a value’s timestamp without modifying the value. Use this transform to shift timestamps to another timezone.Argument: arg \(Duration data type\) – The amount of time to shift by. | top | Returns the specified number of series that have the highest values.Argument: arg \(Integer\) – The number of series to return. For example, the following returns the two time series that contain the highest sets of values. |
cURL requestThe following example shows how to call this endpoint to return a JSON stream for metrics on the mb_demo_drone table. Note: While the objects in this example are expanded to multiple lines for legibility, in an actual result each returned object is on its own line. You can make the same call and return an octet stream by setting Response: The following cURL example uses the CSV format option to stream back the altitude values (stored in the database as "mb_demo_mt_altitude") of the last day for each drone stored in the mb_demo_drone [Drones] table of the Metricbase Demo plugin. In the example, the data is returned in a narrow table format with three columns: the Sys_id of the subject identifying the drone, the time stamp of value, and the altitude value. Output: MetricBase Time Series - POST /now/clotho/putAdds time series data to the MetricBase database. URL formatVersioned URL: Supported request parameters
HeadersThe following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.
Status codesThe following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.
Response body parameters (JSON or XML)
cURL request |