Time Series Database:Query multi-value data

Request

Endpoint

Request body parameters

Subquery parameters

Each object in the queries array supports the following parameters:

Field query parameters

Each object in the fields array supports the following parameters:

A single query can include at most 200 field values across all subqueries. To count: add up the number of field values across all fields arrays in all subqueries.

Timestamp units

TSDB determines the timestamp unit from the numeric value:

These rules apply to /api/put, /api/mput, /api/query, and /api/mquery.

To query data at a single point in time, set start and end to the same value. For example: "start": 1356998400, "end": 1356998400.

Sample request

POST /api/mquery

{
  "start": 1346846400,
  "end": 1346846411,
  "msResolution": true,
  "queries": [
    {
      "metric": "wind",
      "fields": [
        {
          "field": "speed",
          "aggregator": "sum",
          "downsample": "2s-last",
          "alias": "speed_sum"
        },
        {
          "field": "*",
          "aggregator": "sum",
          "downsample": "2s-count",
          "where": "speed>10"
        }
      ]
    }
  ]
}

Downsampling

Downsampling aggregates data over fixed time intervals, reducing the number of returned data points. Use it when querying long time ranges where per-second granularity is unnecessary.

Expression format

<interval><units>-<aggregator>[-fill policy]

`interval`: A numeric value such as 5 or 60. Use 0all to aggregate all data points in the range into a single value.

`units`:

Add c to use calendar alignment (for example, 1dc represents the 24-hour period from 00:00 of the current day). Without c, timestamps align using: aligned timestamp = data timestamp − (data timestamp % interval).

`aggregator` options:

The rfirst, rlast, rmin, and rmax operators cannot be used with a fill policy.

Time window expansion

After specifying downsample, TSDB automatically extends the query range by one interval on each side. For example, if the range is [1346846401, 1346846499] and the interval is 5m, the actual query range becomes [1346846101, 1346846799].

Fill policy

When a time bucket contains no data points, a fill policy determines what value to report for that bucket.

Fixed fill policy

Append a fixed value to the format using #:

<interval><units>-<aggregator>-fixed#<number>

The fixed value can be positive or negative. Examples: 1h-sum-fixed#6, 1h-avg-fixed#-8.

Downsampling examples

Three valid downsampling expressions: 1m-avg, 1h-sum-zero, 1h-sum-near.

Aggregator

After downsampling, multiple timelines may share aligned timestamps. The aggregator merges those timelines into one by aggregating values at each timestamp. If only one timeline exists, no aggregation is performed.

Interpolation

When aggregating multiple timelines, if a timeline has no value at an aligned timestamp and another timeline does, TSDB interpolates a value for the missing timeline. This only applies when no fill policy is set.

The interpolation method depends on the aggregator:

Delta operator

When delta is set to true, the value in each dps key-value pair is replaced by the calculated delta (Vt − Vt-1).

`deltaOptions` parameters

Example

{
  "start": 1346046400,
  "end": 1347056500,
  "queries": [
    {
      "metric": "sys.cpu.0",
      "aggregator": "none",
      "downsample": "5s-avg",
      "delta": true,
      "deltaOptions": {
        "counter": true,
        "counterMax": 100
      },
      "dpValue": ">=50",
      "tags": {
        "host": "localhost",
        "appName": "hitsdb"
      }
    }
  ]
}

Pagination with limit and offset

Use limit and offset to paginate results across multiple timelines.

• limit: Maximum data points per timeline per page. 0 means no limit (default).

• offset: Number of data points to skip per timeline.

Example: To return data points ranked 1001 to 1500, set limit to 500 and offset to 1000.

{
  "start": 1346846400,
  "end": 1346846411,
  "msResolution": true,
  "queries": [
    {
      "metric": "wind",
      "fields": [
        {
          "field": "*",
          "aggregator": "sum",
          "downsample": "2s-count"
        }
      ],
      "filters": [
        {
          "filter": "IOTE_8859_0005|IOTE_8859_0004",
          "tagk": "sensor",
          "type": "literal_or"
        }
      ],
      "limit": 500,
      "offset": 1000
    }
  ]
}

Filters

Filters select which timelines to include in a query based on tag values. The filters parameter conflicts with tags — if both appear in the JSON, the one at the latter position takes effect.

Filter object parameters

Filter types

You can also specify filters using tag shorthand:

• tagk = *: Groups all tag values for that key and aggregates per distinct value.

• tagk = tagv1|tagv2: Groups tagv1 values together and tagv2 values together.

Example with filters

{
  "start": 1346846400,
  "end": 1346846411,
  "msResolution": true,
  "queries": [
    {
      "metric": "wind",
      "fields": [
        {
          "field": "speed",
          "aggregator": "none",
          "alias": "column_speed"
        },
        {
          "field": "*",
          "aggregator": "none",
          "alias": "column_"
        }
      ],
      "filters": [
        {
          "filter": "IOTE_8859_0005|IOTE_8859_0004",
          "tagk": "sensor",
          "type": "literal_or"
        }
      ]
    }
  ]
}

Response

A successful query returns HTTP 200 with a JSON array.

Response fields

Example: aggregator set to `none`

Returns one result object per matched timeline (no aggregation across sensors):

[
  {
    "metric": "wind",
    "columns": [
      "timestamp",
      "column_speed",
      "column_description",
      "column_direction",
      "column_level",
      "column_speed"
    ],
    "tags": {
      "city": "hangzhou",
      "country": "china",
      "province": "zhejiang",
      "sensor": "IOTE_8859_0005"
    },
    "aggregatedTags": [],
    "values": [
      [1346846406000, null, "Fresh breeze", "East", 0.5, null],
      [1346846407000, null, "Fresh breeze", "South", 1.5, null]
    ]
  },
  {
    "metric": "wind",
    "columns": [
      "timestamp",
      "column_speed",
      "column_description",
      "column_direction",
      "column_level",
      "column_speed"
    ],
    "tags": {
      "city": "hangzhou",
      "country": "china",
      "province": "zhejiang",
      "sensor": "IOTE_8859_0004"
    },
    "aggregatedTags": [],
    "values": [
      [1346846400000, 40.4, "Fresh breeze", "East", 0.4, 40.4],
      [1346846401000, 41.4, "Fresh breeze", "South", 1.4, 41.4],
      [1346846402000, 42.4, "Fresh breeze", "West", 2.4, 42.4],
      [1346846403000, 43.4, "Fresh breeze", "North", 3.4, 43.4]
    ]
  }
]

Example: aggregator set to `avg`

Returns average wind speed and level aggregated across all sensors in the city:

[
  {
    "metric": "wind",
    "columns": ["timestamp", "avg_level", "avg_speed"],
    "tags": {
      "city": "hangzhou"
    },
    "aggregatedTags": ["country", "province", "sensor"],
    "values": [
      [1346846400000, 0.25, 40.25],
      [1346846401000, 1.25, 41.25],
      [1346846402000, 2.5, 42.5],
      [1346846411000, 5.5, null]
    ]
  }
]

Query hints

A query hint tells TSDB which tag indexes to use (or skip) when resolving timelines, reducing response time when the set of timelines targeted by one set of tags is a known subset of another.

Format

Specify tag key names under hint.tagk with values 0 (skip index) or 1 (use index). All values in a single hint must be either all 0 or all 1 — mixing them returns an error.

Hint scoped to a subquery

{
  "queries": [
    {
      "metric": "demo.mf",
      "tags": {
        "sensor": "IOTE_8859_0001",
        "city": "hangzhou",
        "province": "zhejiang",
        "country": "china"
      },
      "fields": ["speed"],
      "hint": {
        "tagk": { "dc": 1 }
      }
    }
  ]
}

Hint scoped to the entire query

{
  "queries": [
    {
      "metric": "demo.mf",
      "tags": {
        "sensor": "IOTE_8859_0001",
        "city": "hangzhou",
        "province": "zhejiang",
        "country": "china"
      },
      "fields": ["speed"]
    }
  ],
  "hint": {
    "tagk": { "dc": 1 }
  }
}

Error: mixing 0 and 1 in the same hint

{
  "start": 1346846400,
  "end": 1346846400,
  "queries": [
    {
      "aggregator": "none",
      "metric": "sys.cpu.nice",
      "tags": {
        "dc": "lga",
        "host": "web01"
      }
    }
  ],
  "hint": {
    "tagk": {
      "dc": 1,
      "host": 0
    }
  }
}

Returns:

{
  "error": {
    "code": 400,
    "message": "The value of hint should only be 0 or 1, and there should not be both 0 and 1",
    "details": "TSQuery(start_time=1346846400, end_time=1346846400, subQueries[TSSubQuery(metric=sys.cpu.nice, filters=[filter_name=literal_or, tagk=dc, literals=[lga], group_by=true, filter_name=literal_or, tagk=host, literals=[web01], group_by=true], tsuids=[], agg=none, downsample=null, ds_interval=0, rate=false, rate_options=null, delta=false, delta_options=null, top=0, granularity=null, granularityDownsample=null, explicit_tags=explicit_tags, index=0, realTimeSeconds=-1, useData=auto, limit=0, offset=0, dpValue=null, preDpValue=null, startTime=1346846400000, endTime=1346846400000, Query_ID=null)] padding=false, no_annotations=false, with_global_annotations=false, show_tsuids=false, ms_resolution=false, options=[])"
  }
}

Error: invalid hint value

{
  "start": 1346846400,
  "end": 1346846400,
  "queries": [
    {
      "aggregator": "none",
      "metric": "sys.cpu.nice",
      "tags": {
        "dc": "lga",
        "host": "web01"
      }
    }
  ],
  "hint": {
    "tagk": {
      "dc": 100
    }
  }
}

Returns:

{
  "error": {
    "code": 400,
    "message": "The value of hint can only be 0 or 1, and it is detected that '100' is passed in",
    "details": "TSQuery(start_time=1346846400, end_time=1346846400, subQueries[TSSubQuery(metric=sys.cpu.nice, filters=[filter_name=literal_or, tagk=dc, literals=[lga], group_by=true, filter_name=literal_or, tagk=host, literals=[web01], group_by=true], tsuids=[], agg=none, downsample=null, ds_interval=0, rate=false, rate_options=null, delta=false, delta_options=null, top=0, granularity=null, granularityDownsample=null, explicit_tags=explicit_tags, index=0, realTimeSeconds=-1, useData=auto, limit=0, offset=0, dpValue=null, preDpValue=null, startTime=1346846400000, endTime=1346846400000, Query_ID=null)] padding=false, no_annotations=false, with_global_annotations=false, show_tsuids=false, ms_resolution=false, options=[])"
  }
}