Series

Overview

  • A series is a sequence of timestamp/value pairs. This sequence of timestamp/value pairs are measurements for a single source of data. For example, a temperature sensor measuring the temperature in a room is modeled by a single series. A thermostat that measures temperature, humidity, and barometric pressure is modeled by three series.

  • Identifiers

    Each series is given a system generated unique identifier. The series can also be created with a supplied key. The series can be accessed by this key. These keys must be unique for each database. For the thermostat example given above, the keys could be named therm1.temp, therm1.humidity, and therm1.press. An important note, series can be automatically created by writing data to them by key (similar to upserting in other databases). A more in depth description is given here.

    Valid characters for the series key are letters, numbers, period, underscore, hyphen, colon and semicolon.

  • Metadata

    Metadata attached to the series is used to relate them. Series can accept a name, a list of tags, and a dictionary of attributes. The name is used to present a human readable display name. The list of tags are used to tag types for the series. The dictionary allows key/value pairs to be attached to the series.

    In the thermostat example above, the temperature series could be tagged with temp, the humidity series with humidity, and the barometric pressure series with press. If your system had multiple thermostats, an attribute of thermostat=1 could be added to each series to group them.

    This flexible tagging and attribute system allows the series to be grouped and tagged in complex ways. The api allows series to be filtered based on these tags and attributes. For instance, to get the series associated with thermostat 1, filter on the attribute thermostat=1. To find all of the temperature sensors, filter on tag temp.

  • Auto Creation of Metadata

    To help with adding metadata, the series key is parsed using the following conventions and tags and attributes are added automatically:

    • The key is split on periods (.).
    • Each split string is added as a tag, except for the last item.
    • If the string contains a colon (:), the string is split on the colon. The first half is used as an attribute key and the second half as the value.

    For example the following key creates these tags and attributes:

    key
    1. building:1.floor:2.pressure.1
    tags
    1. ["pressure"]
    attributes
    1. {
    2. "building":"1",
    3. "floor":"2"
    4. }

    Strings separated by periods also imply hierarchy (like the path in a file system) and are used for navigation on the management console views.

  • Operations

    The following series related operations are supported:

    • Create series
    • Get a specific series
    • List all series
    • Update series metadata

Create Series

  • Description

  • Resource URL

    post/series/

  • URL Parameters

    None

  • Querystring parameters

    None

  • Request Body

    Optional: A dictionary containing the requested key. Allowed characters in key are regex [a-zA-Z0-9\.:;\-_]+ (numbers, letters, underscore, hyphen, period, colon, semicolon, no spaces).

    Ex. {"key": "your-custom-key"}

  • Response

    The newly created series.

    Note: Keys must be unique. If requesting a key that already exists, a 409 Conflict will be returned.

  • Side Effects

    A new series is created.

  • Example Request

    post/series/post data
    1. {"key":"my-custom-key"}
    response
    1. {
    2. "id":"01868c1a2aaf416ea6cd8edd65e7a4b8",
    3. "key":"my-custom-key",
    4. "name":"",
    5. "tags":[],
    6. "attributes":{}
    7. }

Get Series

  • Description

    Returns a JSON representation of a series. The series can be accessed by either id or key.

  • Resource URL

    get/series/id/{id}/
    get/series/key/{key}/

  • URL Parameters

    None

  • Querystring parameters

    None

  • Request Body

    None

  • Response

    A JSON representation of the requested series.

    A 403 Forbidden is returned if the series can't be found.

  • Side Effects

    None

  • Example Request

    get/series/id/01868c1a2aaf416ea6cd8edd65e7a4b8/response
    1. {
    2. "id":"01868c1a2aaf416ea6cd8edd65e7a4b8",
    3. "key":"key1",
    4. "name":"",
    5. "tags":[
    6. "temp"
    7. ],
    8. "attributes":{
    9. "temp":"1"
    10. }
    11. }

List Series

  • Description

    Lists all of the series in the database, with an optional filter. The filter is specified through the optional querystring parameters.

  • Resource URL

    get/series/

  • URL Parameters

    None

  • Querystring Parameters

    • 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

    An array of dictionaries. If a series does not have a key specified, the key will be returned as the series id.

  • Side Effects

    None

  • Example Request

    A call to list all series with the tag temp and attribute thermostat=1 from the list of keys [key1, key2, key3] is expressed as:

    get /series/?key=key1&key=key2&key=key3&tag=temp&attr[thermostat]=1response
    1. [
    2. {
    3. "id":"01868c1a2aaf416ea6cd8edd65e4a3ef",
    4. "key":"key1",
    5. "name":"",
    6. "tags":[
    7. "temp"
    8. ],
    9. "attributes":{
    10. "thermostat":"1"
    11. }
    12. },
    13. {
    14. "id":"93ef271a2aaf416eb3cd8edd65e9983a",
    15. "key":"key2",
    16. "name":"",
    17. "tags":[
    18. "temp"
    19. ],
    20. "attributes":{
    21. "thermostat":"1"
    22. }
    23. }
    24. ]

Update Series

  • Description

    Updates the metadata for a series. The request body for the request is a JSON representation of the series. All attributes for the series are replaced by the updated version. The simplest way to use this method is through a read-modify-write cycle, i.e. get a series, modify it and then write is back.

  • Resource URL

    put/series/id/{id}/
    put/series/key/{key}/

  • URL Parameters

    • id

      Specifies the series to update by id.

      Example Values: 01868c1a2aaf416ea6cd8edd65e4a3ef

    • key

      Specifies the series to update by key.

      Example Values: my-custom-key

  • Querystring parameters

    None

  • Request Body

    A JSON representation of the updated series.

  • Response

    Returns a JSON respresentation of the updated series.

  • Side Effects

    None

  • Example Request

    put/series/key/my-custom-key/put data
    1. {
    2. "id":"01868c1a2aaf416ea6cd8edd65e7a4b8",
    3. "key":"my-custom-key",
    4. "name":"Temperature 1",
    5. "tags":[],
    6. "attributes":{}
    7. }
    response
    1. {
    2. "id":"01868c1a2aaf416ea6cd8edd65e7a4b8",
    3. "key":"my-custom-key",
    4. "name":"Temperature 1",
    5. "tags":[],
    6. "attributes":{}
    7. }