Read Data

Overview

  • This set of api endpoints allows data to be read out of the database. A start and end date, as well as a series are required (id, key, or filter parameters). Each endpoint returns a JSON representation of a DataSet.

  • DataSet

    A DataSet is a range of data for a specific date range of a series. The DataSet returns the series metadata, start and end time, array of datapoints, rollup information (interval, function, and time zone), and a summary object. The summary object contains basic statistics for the range. Current statistics returned are:

    • mean - Average of all datapoints
    • sum - Sum of all datapoints
    • min - Minimum value of all datapoints
    • max - Maximum value of all datapoints
    • stddev - Standard deviation of all datapoints
    • ss - Sum of squares of all datapoints
    • count - Total number of datapoints in the DataSet

  • Operations

    The following read-related operations are supported:

    • Read Data by ID
    • Read Data by Key
    • Read Multiple Series Data

Rollups

  • If the range of data being read is large, TempoDB can rollup the data up at specific intervals to prevent all of the raw data from being streamed. In fact, TempoDB will do this automatically for any range over 2 days. This rollup behavior can be controlled through the REST api.

    The rollups are defined by a folding function and a time interval. For example, if you would like to read a year's worth of data, but are only interested in the maximum value per day, you can have TempoDB roll this data up for you and provide daily maximum values for the year.

    An output time zone can be specified for the rollup as well. This sets the time zone of the datapoints returned. This only really effects rollups where the interval is set to a day or greater. This is required to define the boundary for a day to rollup on. By default, the time zone is set to UTC. If you are presenting data in a time zone other than UTC, you will want to set the time zone parameter.

  • Folding Function

    The folding function specifies how the datapoints are reduced within each interval. The default folding function is mean which returns the mean (average). The following folding functions are supported:

    • mean - Average of all datapoints
    • sum - Sum of all datapoints
    • min - Minimum value of all datapoints
    • max - Maximum value of all datapoints
    • stddev - Standard deviation of all datapoints
    • ss - Sum of squares of all datapoints
    • count - Total number of datapoints in the DataSet
    • range - Maximum value less the minimum value of all datapoints

  • Parameterized Folding Function

    The folding function specifies how the datapoints are reduced within each interval. Currently, the percentile rollup is the only rollup that can be configured with a parameter. The form will be the name of the rollup, a comma and then the desired value. For example, percentile takes an integer number that represents the percentile of interest, so median would be percentile,50.

    • percentile,N - Percentile value of your dataset { Where N is a number from 1 to 99 }

  • Interval

    The interval sets the range of time for each datapoint in the rollup. Intervals are specified by a number and a unit of time, i.e. 6hour or 1day. The supported time units are:

    • min - Minutes
    • hour - Hours
    • day - Days
    • month - Months
    • year - Years

    ISO 8601 Durations are also supported for an interval. Using this format allows for additional rollups on second and week intervals. For example:

    • 6hour would be PT6H
    • 1day would be P1D
    • 1 minute and 15 seconds would be PT1M15S, which could also simply be PT75S
    • 2 weeks would be P2W

  • Time Zones

    A list of supported time zones is available here.

  • Overriding

    The automatic rollup can be overridden by passing raw as the interval.

  • Response

    If a rollup is applied to the request, a rollup object is included in the response DataSet. This object contains information regarding the applied rollup, including the interval (ISO 8601 formatted), the function applied, and the time zone. If no rollup is applied, the rollup object is returned as null.

Read Data by ID

  • Description

    Reads a range of data from a series referenced by id.

  • Resource URL

    GET /series/id/{id}/data/

  • URL Parameters

    • idrequired

      Specifies the id of the series to read data.

      Example Values: 01868c1a2aaf416ea6cd8edd65e7a4b8

  • Querystring parameters

    • startrequired

      Specifies the start date of the dataset. (ISO8601)

      Example Values: 2012-01-08T00:21:54.000+0000

    • endrequired

      Specifies the end date of the dataset. (ISO8601)

      Example Values: 2012-01-09T00:21:54.000+0000

    • functionoptional

      Specifies the folding function for the rollup.

      Example Values: sum, min, max, avg

    • intervaloptional

      Specifies the time interval for the rollup.

      Example Values: 1min, 6min, 1hour, 2day, PT5M, PT6H

    • tzoptional

      Specifies the time zone for the output (valid time zones).

      Example Values: America/Chicago, America/Detroit, America/New_York

  • Request Body

    None

  • Response

    A JSON representation of a DataSet.

  • Side Effects

    None

  • Example Request

    get/series/id/01868c1a2aaf416ea6cd8edd65e7a4b8/data/?start=2012-01-08&end=2012-01-09&interval=6hourresponse
    1. {
    2. "series":{
    3. "id":"01868c1a2aaf416ea6cd8edd65e7a4b8",
    4. "key":"key1",
    5. "name":"",
    6. "tags":[
    7. "temp"
    8. ],
    9. "attributes":{
    10. "temp":"1"
    11. }
    12. },
    13. "start":"2012-01-08T00:00:00.000+0000",
    14. "end":"2012-01-09T00:00:00.000+0000",
    15. "data":[
    16. {"t":"2012-01-08T00:00:00.000+0000","v":4.00},
    17. {"t":"2012-01-08T06:00:00.000+0000","v":3.00},
    18. {"t":"2012-01-08T12:00:00.000+0000","v":2.00},
    19. {"t":"2012-01-08T18:00:00.000+0000","v":3.00}
    20. ],
    21. "rollup":{
    22. "interval":"PT6H",
    23. "function":"avg",
    24. "tz":"UTC",
    25. },
    26. "summary":{
    27. "mean":3.00,
    28. "sum":12.00,
    29. "min":2.00,
    30. "max":4.00,
    31. "stddev":0.8165,
    32. "ss":2.00,
    33. "count":4
    34. }
    35. }

Read Data by Key

  • Description

    Reads a range of data from a series referenced by key.

  • Resource URL

    GET /series/key/{key}/data/

  • URL Parameters

    • key

      Specifies the key of the series to read data.

      Example Values: my-custom-key

  • Querystring parameters

    • startrequired

      Specifies the start date of the dataset. (ISO8601)

      Example Values: 2012-01-08T00:21:54.000+0000

    • endrequired

      Specifies the end date of the dataset. (ISO8601)

      Example Values: 2012-01-09T00:21:54.000+0000

    • functionoptional

      Specifies the folding function for the rollup.

      Example Values: sum, min, max, avg

    • intervaloptional

      Specifies the time interval for the rollup.

      Example Values: 1min, 6min, 1hour, 2day, PT5M, PT6H

    • tzoptional

      Specifies the time zone for the output (valid time zones).

      Example Values: America/Chicago, America/Detroit, America/New_York

  • Request Body

    None

  • Response

    A JSON representation of a DataSet.

  • Side Effects

    None

  • Example Request

    get/series/key/key1/data/?start=2012-01-08&end=2012-01-09&interval=6hourresponse
    1. {
    2. "series":{
    3. "id":"01868c1a2aaf416ea6cd8edd65e7a4b8",
    4. "key":"key1",
    5. "name":"",
    6. "tags":[
    7. "temp"
    8. ],
    9. "attributes":{
    10. "temp":"1"
    11. }
    12. },
    13. "start":"2012-01-08T00:00:00.000+0000",
    14. "end":"2012-01-09T00:00:00.000+0000",
    15. "data":[
    16. {"t":"2012-01-08T00:00:00.000+0000","v":4.00},
    17. {"t":"2012-01-08T06:00:00.000+0000","v":3.00},
    18. {"t":"2012-01-08T12:00:00.000+0000","v":2.00},
    19. {"t":"2012-01-08T18:00:00.000+0000","v":3.00}
    20. ],
    21. "rollup":{
    22. "interval":"PT6H",
    23. "function":"UTC",
    24. "tz":"UTC"
    25. },
    26. "summary":{
    27. "mean":3.00,
    28. "sum":12.00,
    29. "min":2.00,
    30. "max":4.00,
    31. "stddev":0.8165,
    32. "ss":2.00,
    33. "count":4
    34. }
    35. }

Read Multiple Series Data

  • Description

    Reads a range of data from a set of series referenced by the given filter parameters.

  • Resource URL

    GET /data/

  • URL Parameters

    • key

      Specifies the key of the series to read data.

      Example Values: my-custom-key

  • Querystring parameters

    • startrequired

      Specifies the start date of the dataset. (ISO8601)

      Example Values: 2012-01-08T00:21:54.000+0000

    • endrequired

      Specifies the end date of the dataset. (ISO8601)

      Example Values: 2012-01-09T00:21:54.000+0000

    • functionoptional

      Specifies the folding function for the rollup.

      Example Values: sum, min, max, avg

    • intervaloptional

      Specifies the time interval for the rollup.

      Example Values: 1min, 6min, 1hour, 2day, PT5M, PT6H

    • tzoptional

      Specifies the time zone for the output (valid time zones).

      Example Values: America/Chicago, America/Detroit, America/New_York

    • idoptional

      Specifies the series ids to filter on. There can be multiple ids given. The returned list of series is the union of these ids.

      Example Values: 01868c1a2aaf416ea6cd8edd65e4a3ef

    • keyoptional

      Specifies the series keys to filter on. There can be multiple keys given. The returned list of series is the union of these keys.

      Example Values: my-custom-key

    • tagoptional

      Specifies the tags to filter on. There can be multiple tags given. The returned list of series is the intersection of these tags.

      Example Values: temp

    • attroptional

      Specifies the attributes to filter on. There can be multiple attributes given. The returned list of series is the intersection of these attributes.

      Example Values: attr[foo]=bar

  • Request Body

    None

  • Response

    A list of JSON representations of DataSets matching the given filter parameters.

  • Side Effects

    None

  • Example Request

    get/data/?start=2012-01-08&end=2012-01-09&interval=6hour&key=key1&key=key2&key=key3&tag=temp&attr[thermostat]=1response
    1. [
    2. {
    3. "series":{
    4. "id":"01868c1a2aaf416ea6cd8edd65e4a3ef",
    5. "key":"key1",
    6. "name":"",
    7. "tags":[
    8. "temp"
    9. ],
    10. "attributes":{
    11. "thermostat":"1"
    12. }
    13. },
    14. "start":"2012-01-08T00:00:00.000+0000",
    15. "end":"2012-01-09T00:00:00.000+0000",
    16. "data":[
    17. {"t":"2012-01-08T00:00:00.000+0000","v":4.00},
    18. {"t":"2012-01-08T06:00:00.000+0000","v":3.00},
    19. {"t":"2012-01-08T12:00:00.000+0000","v":2.00},
    20. {"t":"2012-01-08T18:00:00.000+0000","v":3.00}
    21. ],
    22. "rollup":{
    23. "interval":"PT6H",
    24. "function":"avg",
    25. "tz":"UTC"
    26. },
    27. "summary":{
    28. "mean":3.00,
    29. "sum":12.00,
    30. "min":2.00,
    31. "max":4.00,
    32. "stddev":0.8165,
    33. "ss":2.00,
    34. "count":4
    35. }
    36. },
    37. {
    38. "series":{
    39. "id":"93ef271a2aaf416eb3cd8edd65e9983a",
    40. "key":"key2",
    41. "name":"",
    42. "tags":[
    43. "temp"
    44. ],
    45. "attributes":{
    46. "thermostat":"1"
    47. }
    48. },
    49. "start":"2012-01-08T00:00:00.000+0000",
    50. "end":"2012-01-09T00:00:00.000+0000",
    51. "data":[
    52. {"t":"2012-01-08T00:00:00.000+0000","v":4.00},
    53. {"t":"2012-01-08T06:00:00.000+0000","v":3.00},
    54. {"t":"2012-01-08T12:00:00.000+0000","v":2.00},
    55. {"t":"2012-01-08T18:00:00.000+0000","v":3.00}
    56. ],
    57. "rollup":{
    58. "interval":"PT6H",
    59. "function":"avg",
    60. "tz":"UTC"
    61. },
    62. "summary":{
    63. "mean":3.00,
    64. "sum":12.00,
    65. "min":2.00,
    66. "max":4.00,
    67. "stddev":0.8165,
    68. "ss":2.00,
    69. "count":4
    70. }
    71. }
    72. ]