Time Series Storage Service

A scalable timeseries storage in Murano

Operations

Storage

Operations

Storage


deleteAll

delete all data of a given solution

Responses
All data deleted - nil

All data deleted

The response to the caller - object
Name Type Description
type string Error type
error string Error message in case of failure
status integer Response code
Example
-- Delete all data of a given solution
local out = Tsdb.deleteAll()
response.message = out

listMetrics

list metrics of a given solution

Arguments
parameters - object - Object containing service call parameters.
Name Type Description
limit integer {..1000} Limit the number of results to return (default: maximum allowed, maximum allowed: 1000)
Default: 1000
next string Optional, the cursor to get next page if still having more data
Responses
Metrics information retrieved - nil

Metrics information retrieved

The response to the caller - object
Name Type Description
type string Error type
error string Error message in case of failure
status integer Response code
Example
-- Get a list of created metrics for a given solution
local out = Tsdb.listMetrics({limit = 10})
response.message = out

-- Use next cursor to fetch next page if found in the result of previous query
local out = Tsdb.listMetrics({limit = 10, next = "switch_2"})
response.message = out

listTags

list tags of a given solution

Arguments
parameters - object - Object containing service call parameters.
Name Type Description
limit integer {..1000} Limit the number of results to return (default: maximum allowed, maximum allowed: 1000)
Default: 1000
next string Optional, the cursor to get next page if still having more data
Responses
Tags information retrieved - nil

Tags information retrieved

The response to the caller - object
Name Type Description
type string Error type
error string Error message in case of failure
status integer Response code
Example
-- Get a list of created tags for a given solution
local out = Tsdb.listTags({limit = 10})
response.message = out

-- Use next cursor to fetch next page if found in the result of previous query
local out = Tsdb.listTags({limit = 10, next = "city_taipei_1_1_true"})
response.message = out

query

Query data points by using any metrics and tags. Support absolute (start_time, end_time) or relative (relative_start, relative_unit) time parameters, which cannot be used at the same time.
The first element in returned data point array is always the timestamp.
You can use fill arguement to indicate the imputation of missing values.
The metric names of columns property in the response will always be in the order specified in the query, except for the timestamp column which is always the first one.

If no time constraints are specified, it will return recent data points up to the maximum limit in recent one week.

Note that only unique timestamped data will be returned, which means if multiple data points were written with exactly the same timestamp in the response, only the last one will be kept.

Arguments
parameters - object - Object containing service call parameters.
Name Type Description
fill integer, string Value to fill for time slots with no data points exist in merge mode.
Supported fill types: null, none, any integer, previous
Default: none
mode string Indicate whether to merge or split the result of each metric.
Supported options: merge, split
Default: merge
tags object One or many tags
epoch string Change returned timestamp of data points to unix epoch format.
Supported units: u (microseconds), ms (milliseconds), s (seconds)
Optional, if not provided, timestamps are returned in RFC3339 UTC with microsecond precision.
limit integer {..1000} Limit the number of data points to return per metric (default: maximum allowed, maximum allowed: 1000)
Default: 1000
metrics [ string ] One or many metrics
end_time integer, string Exclusive UTC ending time range to query, also accept RFC3339 UTC string.
Supported units: u (microseconds), ms (milliseconds), s (seconds)
e.g. 1472547546000000u, 1472547546000ms, 1472547546s, 1472547546, 2016-08-30T08:59:06+00:00
Optional, if not provided, it will use current timestamp in microseonds from server side
order_by string Return results in ascending or descending time order.
Supported options: desc, asc
Default: "desc"
aggregate [ string ] One to many aggregation functions to apply.
Supported functions: avg, min, max, count, sum
String type value can only use count function
start_time integer, string Inclusive UTC starting time range to query, also accept RFC3339 UTC string.
Supported units: u (microseconds), ms (milliseconds), s (seconds)
e.g. 1472547546000000u, 1472547546000ms, 1472547546s, 1472547546, 2016-08-30T08:59:06+00:00
relative_end integer, string A negative integer with time unit to indicate relative end time before now.
Supported units: u (microseconds), ms (milliseconds), s (seconds), m (minutes), h (hours), d (days), w (weeks)
sampling_size string The size of time slots used for downsampling. Must be a positive integer greater than zero.
Supported units: u (microseconds), ms (milliseconds), s (seconds), m (minutes), h (hours), d (days), w (weeks)
Optional, used together with fill arguments.
relative_start integer, string A negative integer with time unit to indicate relative start time before now.
Supported units: u (microseconds), ms (milliseconds), s (seconds), m (minutes), h (hours), d (days), w (weeks)
Default: -7d (last 7 days)
Responses
Query results retrieved - nil

Query results retrieved

The response to the caller - object
Name Type Description
type string Error type
error string Error message in case of failure
status integer Response code
Example
-- Query by Absolute Time Constraint --
-- Get temperature and humidity data points between 2016-08-01 (inclusive) and 2016-09-01 (exclusive) from devices in Minneapolis city and US region
local metrics = {
  "temperature",
  "swtich"
}
local tags = {
  region = "us",
  city = "minneapolis"
}
local out = Tsdb.query({
  metrics = metrics,
  tags = tags,
  start_time = "2016-08-01T00:00:00+00:00",
  end_time = "2016-09-01T00:00:00+00:00",
  fill = "null",
  limit = 50
})
response.message = out

-- Query by Relative Time Constraint --
-- Get temperature data points in recent 3 hours from devices in Taipei city and Asia region (with timestamp in milliseconds format)
local metrics = {"temperature"}
local tags = {
  region = "asia",
  city = "taipei"
}
local out = Tsdb.query({
  metrics = metrics,
  tags = tags,
  relative_start = "-3d",
  epoch = "ms",
  fill = "null",
  limit = 50
})
response.message = out

-- Query without Time Constraint --
-- Get most recent 5 temperature and humidity data points from devices in Minneapolis city and US region
local metrics = {
  "temperature",
  "humidity"
}
local tags = {
  region = "us",
  city = "minneapolis"
}
local out = Tsdb.query({
  metrics = metrics,
  tags = tags,
  limit = 5
})
response.message = out

-- Query by Downsampling --
-- Get humidity data points in recent two days from devices in Taipei city, downsampled by 4-hours time slots
local metrics = {
  "humidity"
}
local tags = {
  city = "taipei"
}
local out = Tsdb.query({
  metrics = metrics,
  tags = tags,
  relative_start = "-2d",
  sampling_size = "4h",
  fill = "none",
  epoch = "ms"
})
response.message = out

-- Aggregation by Downsampling --
-- Get average and count of tire pressure data between 2016-08-15 (inclusive) and 2016-09-01 (exclusive) from devices in Minneapolis city, downsampled by 30-minutes time slots
local metrics = {
  "tire_pressure"
}
local tags = {
  city = "minneapolis"
}
local aggregate = {"avg", "count"}
local out = Tsdb.query({
  metrics = metrics,
  tags = tags,
  start_time = "2016-08-01T00:00:00+00:00",
  end_time = "2016-09-01T00:00:00+00:00",
  aggregate = aggregate,
  sampling_size = "30m",
  fill = "none"
})
response.message = out

write

Write data points to one or many metrics with an optional set of tags and a timestamp down to microsecond precision.

Note that if multiple data points are written with exactly the same timestamp, only the last one will be kept and it overwrites the others.

Arguments
parameters - object - Object containing service call parameters.
Name Type Description
ts integer, string Unix timestamp in microseconds used as the write time for given data point.
Supported units: u (microseconds), ms (milliseconds), s (seconds)
e.g. 1472547546000000u, 1472547546000ms, 1472547546s, 1472547546
Optional, if not provided, it will use the received time in microseconds from server side
tags object Pairs of tag and its value (only text supported)
metrics [ string ] List of metrics
Responses
Data successfully inserted - nil

Data successfully inserted

The response to the caller - object
Name Type Description
type string Error type
error string Error message in case of failure
status integer Response code
Example
-- Write data points of metrics with tags
-- If timestamp is not provided, it will use the received time in microseconds from server side
local metrics = {
  temperature = 37.2,
  humidity = 73,
  switch = "on"
}
local tags = {
  pid = "pzomp8vn4twklnmi",
  identity = "000001",
  region = "us",
  city = "minneapolis"
}
local out = Tsdb.write({
  metrics = metrics,
  tags = tags
})
response.message = out

-- Write data points of metrics with tags and timestamp
local metrics = {
  temperature = 37.2,
  humidity = 73
}
local tags = {
  identity = "000002"
}
local out = Tsdb.write({
  metrics = metrics,
  tags = tags,
  ts = "1476243965s"
})
response.message = out