Data API Introduction

Last Updated：2021-11-02

Write Data Points

Method	API	Instruction
POST	/v1/datapoint	Write data points

Request Parameters

Parameter name	Parameter type	Required	Instruction
datapoints	List<Datapoint>	Required	datapoint lists, arrays of datapoint objects

Datapoint Objects

Parameter name	Parameter type	Required	Instruction
metric	String	Required	Metric name
field	String	Optional	Name of the field, the default name is value. Different fields support different data type writings. For the same field, if the value of a data type is written, the same field is not allowed to write other data types
tags	Object	Required	All the tags corresponding to the data point. A pair of key-values in the object represents the key value of a tag
type	String	Required	Long/Double/String/Bytes are acceptable now. Bytes is a special type, which means that value is a String encoded by base64. When stored in TSDB, it will be inversely encoded into byte array for storage
timestamp	Int	Optional	Unix timestamp is measured in milliseconds; If timestamp is empty and value is not empty, time stamp will automatically fill in the current time of the system; If the number of bits of timestamp is less than or equal to 10 bits, the accuracy will be considered as seconds and automatically multiplied by 1000; A choice must be made between timestamp + value and values
value	Int/Double/String	Optional	The value of data point must be either timestamp + value or values. When metric, field, tags, and timestamp are all written the same, the value written later overwrites the value written first
values	List<List<Any>>	Optional	For the same data point of metric + tags, payload can be reduced by combining into a list of values. Values is a two-dimensional array, and one dimension in it must be two elements. The first element is timestamp, a unix time stamp, with type Int, and the second element is value, with type Int/Double/String. If the timestamp number of bits is less than or equal to 10 bits, the precision is considered to be seconds and automatically multiplied by 1000

Request Example
Field {database} in the HOST represents the name of the database

POST /v1/datapoint HTTP/1.1
HOST: {database}.tsdb.iot.gz.baidubce.com
Authorization: {authorization}
Content-Type: application/json; charset=utf-8
x-bce-date: 2016-06-08T16:49:51Z

{
    "datapoints": [{
        "metric": "cpu_idle",
        "tags": {
            "host": "server1",
            "rack": "rack1"
        },
        "type": "Long",
        "timestamp": 1465376157007,
        "value": 51
    }, {
        "metric": "cpu_idle",
        "tags": {
            "host": "server2",
            "rack": "rack2"
        },
        "type": "Long",
        "values": [
            [1465376269769, 67],
            [1465376325057, 60]
        ]
    }]
}

Return Example

HTTP/1.1 204 No Content
x-bce-request-id: 72492aee-1470-46d0-8a4d-0dab7b8e67b7

Get Metric Lists

Method	API	Instruction
GET	/v1/metric	Get all the metric lists in the database

Return Parameters

Parameter name	Parameter type	Instruction
metrics	List<String>	Metric list

Request Example

GET /v1/metric HTTP/1.1
Host: {database}.tsdb.iot.gz.baidubce.com
Authorization: {authorization}
Content-Type: application/json; charset=utf-8
x-bce-date: 2016-06-08T16:49:51Z

Return Example

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
x-bce-request-id: 72492aee-1470-46d0-8a4d-0dab7b8e67b7

{
    "metrics": [
        "cpu_idle",
        "mem_used"
    ]
}

Get Field Lists

Method	API	Instruction
GET	/v1/metric/{metric}/field	Get the field list of metric in the database

Return Parameters

Parameter name	Parameter type	Instruction
fields	Object	In the field list, each key of an Object corresponds to a key of a field, and each value of an Object is of type Object, indicating the type of the field

Request Example

GET /v1/metric/wind/field HTTP/1.1
Host: {database}.tsdb.iot.gz.baidubce.com
Authorization: {authorization}
Content-Type: application/json; charset=utf-8
x-bce-date: 2016-06-08T16:49:51Z

Return Example

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
x-bce-request-id: 72492aee-1470-46d0-8a4d-0dab7b8e67b7

{
    "fields": {
        "power": {
            "type": "String"
            },
        "direction": {
            "type": "Number"
        }
    }
}

Get Tag Lists

Method	API	Instruction
GET	/v1/metric/{metric}/tag?start=0&end=1562573168000	Get the key and value lists of all tags corresponding to metric

Request Parameters

Parameter name	Parameter type	Required	Instruction
metric	String	Required	Metric name
start	Int	Optional	Query all tags for a period of time, this is the start time, and the default is 0
end	Int	Optional	Query all tags for a period of time, this is the end time, and the default is 2⁶³ - 1

Return Parameters

Parameter name	Parameter type	Instruction
tags	Object	In the Tag list, each key of an Object corresponds to a key of a tag, and each value of an Object is of type List < String >, which represents the list of all values of the tag

Request Example

GET /v1/metric/cpu_idle/tag HTTP/1.1
Host: {database}.tsdb.iot.gz.baidubce.com
Authorization: {authorization}
Content-Type: application/json; charset=utf-8
x-bce-date: 2016-06-08T16:49:51Z

Return Example

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
x-bce-request-id: 72492aee-1470-46d0-8a4d-0dab7b8e67b7

{
    "tags": {
        "host": ["server1", "server2"],
        "rack": ["rack1", "rack2"]
    }
}

Query Data Points

Notes:

If a single query lasts more than 50s, the system will automatically terminate the query. If a query timeout occurs, the following measures can be taken to optimize the query: 1. Reduce the number of queries in a single request 2. Shorten the interval between starting and ending time in a single query 3. Reduce the number of time series involved in a single query 4. Preprocess the data

Method	API	Instruction
GET	/v1/datapoint?query={json}	Query data point, and query parameter encoded in query parameter
PUT	/v1/datapoint?query	Query data point, and query parameter in the body

Request Parameters

Parameter name	Parameter type	Required	Instruction
queries	List<Query>	Required	Query Condition List, an array of Query objects
disablePresampling	Boolean	Optional	Whether to disable preprocessing result query？The default setting is false

Query Objects

Parameter name	Parameter type	Required	Instruction
metric	String	Required	Name of metric to query
field	String	Optional	Name of the field of metric to query, and the default name is value
fields	List<String>	Optional	Field list of metric need to query. Because there is a conflict between fields and field, they can not coexist.
tags	List<String>	Optional	Key list of the tag of the metric to query
filters	Object	Required	Filter condition with type Filters
groupBy	List<Query>	Optional	Group condition, an array of GroupBy objects
offset	Int	Optional	For data paging, the offset of the data point returned from query is 0 by default if it is not filled in
limit	Int	Optional	The number limit of returned data point is 1,000,000 by default if it is not filled in
aggregators	List<Aggregator>	Optional	Aggregation condition, an array of Aggregator objects
order	String	Optional	Asc and Desc are supported, and Asc is the default
fill	Object	Optional	Interpolation option is with type Fill. Interpolation only acts on the original data, and interpolation is performed separately for each time series
fills	List<Fill>	Optional	Multiple fill options, arrays of Fill objects. Because there is a conflict between fills and fill, they can not coexist. If there are multiple fills for the same field, then only the first fill is effective for this field, for example, the first fill is for all fill and the second fill is for a fill, then only the first fill is effective for a
marker	String	Optional	For paging queries, return from marker, using the nextMarker value returned from the previous query

Filters Objects

Parameter name	Parameter type	Required	Instruction
start	Int/String	Required	The start time can be either absolute time (i.e. time stamp, type Int, in milliseconds) or relative time (type String, such as "5 days ago"). For absolute time, if the number of bits is less than or equal to 10 bits, the accuracy will be considered as seconds and automatically multiplied by 1000. Note: When or is included, the outermost start cannot be entered, and the internal start of a single filter is required.
end	Int/String	Optional	The end time can be absolute time or relative time, and the default is 2⁶³ - 1. For absolute time, if the number of bits is less than or equal to 10 bits, the accuracy will be considered as seconds and automatically multiplied by 1000
tags	Object	Optional	It can be an Object. Each key of an Object corresponds to a key of a tag, and each value of an Object is of type List < String >, which represents the value list to match with the tag It can be an array of TagFilter objects
value	String	Optional	The value filtering of single field query is divided into symbol and value Symbols support =, !=, >, <, >=and<= Values allow Number (including long and double), String, and Tag, where String is enclosed in single quotation marks; Tag is the key of the tag, without single quotation marks, and will be automatically resolved to the corresponding type during filtering (for example, the type of field is Number, and the value of the tag will be resolved to Number), for example: "> 111" or "< 11.1" or "= 'abc'" or "> threshold"
fields	List<FieldFilter>	Optional	Value filtering for multi-field queries, array of FieldFilter objects. Because there is a conflict between fields and value, they can not coexist.
or	List<Filters>	Optional	Because there is a conflict between or filter query condition and or and other query condition, they can not coexist.

FieldFilter Objects

Parameter name	Parameter type	Required	Instruction
field	String	Required	Field name of metric need to filter
value	String	Required	The value filtering of multiple field queries is divided into symbol and value Symbols support =, !=, >, <, >=and<= Values allow Number (including long and double), String, and Tag, where String is enclosed in single quotation marks; Tag is the key of the tag, without single quotation marks, and will be automatically resolved to the corresponding type during filtering (for example, the type of field is Number, and the value of the tag will be resolved to Number), for example: "> 111" or "< 11.1" or "= 'abc'" or "> threshold"

TagFilter Objects

Parameter name	Parameter type	Required	Instruction
tag	String	Required	Key of the tag of the metric to filter
in	List<String>	Optional	The value list of tags that can be included, that is, the value of tag only needs to be anyone of in. Cannot exist with notIn and like at the same time
notIn	List<String>	Optional	The value list of tag to filter, that is, the value of tag cannot be any one of notIn. Cannot exist with in and like at the same time
like	String	Optional	Rules to match, "%" matches any number of characters, "_" matches a single character, and escape character is " / "; It cannot coexist with in and notIn

GroupBy Objects

Parameter name	Parameter type	Required	Instruction
name	String	Required	Grouping method, currently only Tag is supported
tags	List<String>	Optional	Which tags are grouped by, required when name is Tag

Aggregator Objects

Parameter name	Parameter type	Required	Instruction
name	String	Required	Aggregation methods, currently Avg, Dev, Count, First, Last, LeastSquares, Max, Min, Percentile, Sum, Diff, Div, Scale, Rate, and AdjacentUnique are supported
sampling	String	Optional	The length of sampling time, such as "10 minutes". The query of natural calendar alignment is supported. The character "c", such as "1 hc", needs to be added to the time unit. Please refer to the time unit page for details. Required when the name is Avg, Dev, Count, First, Last, LeastSquares, Max, Min, Percentile, and Sum. If not, sampling is the whole query time range.
percentile	Double	Optional	Percentage's value range is (0, 1], for example, 0.1 means 10%. Required when the name is Percentile
divisor	Double	Optional	Divisor, required when the name is Div
factor	Double	Optional	Factor, required when the name is Scale
timeUnit	String	Optional	Time unit, required when the name is Rate

The rules for calendar alignment are as follows:

If the time range of the query is from 12:12:12.000 on June 15 to 11:11:11.000 September 17, and the sampling cycle is one month through the "Natural Calendar Alignment" query, 4 values are generated.

The first value is the aggregate value from 12:12:12.000 on June 15 to 23:59:59.999 on June 30,

The second value is the aggregate value from 00:00:00.000 on July 1 to 23:59:59.999 on July 31,

The third value is the aggregate value from 00:00:00.000 on August 1 to 23:59:59.999 on August 31,

The fourth value is the aggregate value from 00:00:00.000 on September 1 to 11:11:11.000 on September 17.

Fill Objects

Parameter name	Parameter type	Required	Instruction
type	String	Required	Fill type currently support Linear, Previous and Fixed
interval	String	Required	Fill interval. If a time series has no value in this interval, fill will be performed. Please refer to Time Unit for format
maxWriteInterval	String	Optional	Max Write Interval. The maximum data writing interval for a time series (there must be a value in this interval) is 0 by default. Please refer to Time Unit for format. The system will attempt to find points from (start-maxWriteInterval) to start and end to (end + maxWriteInterval). If there is no point from (start-maxWriteInterval) to start, the missing point before the first point between start and end will be filled by the value of the first point; If there is no point from end to (end + maxWriteInterval), the missing point after the last point between start and end will be filled by the value of the last point. When the type is Fixed, the parameter will be ignored
value	Int/Double/String	Optional	The fixed value filled by fixed value fill is required when the type is Fixed
field	String	Optional	For the field to interpolate, if this parameter is not filled in, all the fields will be filled by default

Return Parameters

Parameter name	Parameter type	Instruction
results	List<Result>	The result list should match the queries, and is an array composed of Result objects

Result Objects

Parameter name	Parameter type	Instruction
metric	String	Metric name of the result
field	String	Field name of the result
fields	List<String>	Field list of the result
tags	List<String>	Tag list of the result
rawCount	Int	Number of original data points
consumedCount	Int	Number of data points scanned for billing
groups	List<Group>	Group list of the result, an array of Group objects
truncated	Boolean	Whether all the data has been returned? True means there is still data behind it, false means there is no data behind it, and the default is false When groupBy or Aggregators are used, there is no such item
nextMarker	String	Used for paging query to obtain the marker value to pass for the next batch of data. It is only available when truncated is true
presamplingRuleId	String	Pre-processing rule hits the ID, if there is no parameter means it does not hit

Group Objects

Parameter name	Parameter type	Instruction
groupInfos	List<GroupInfo>	Information of the group, an array of GroupInfo objects
values	List<List<Any>>	The sequence of time and values is a two-dimensional array. The first element is timestamp, with type Int, and the following elements are value corresponding to field, with the number of fields and type Int/Double/String. The following elements are value corresponding to tag, with the number of tags and type String.

GroupInfo Objects

Parameter name	Parameter type	Instruction
name	String	Grouping method, currently only Tag is supported
tags	Object	In the tag of the group, a pair of key-values in the Object represents the key-value of a tag, which is available when the name is Tag

Single Domain Request Example

PUT /v1/datapoint?query HTTP/1.1
Host: {database}.tsdb.iot.gz.baidubce.com
Authorization: {authorization}
Content-Type: application/json; charset=utf-8
x-bce-date: 2016-06-08T16:49:51Z

{
    "queries": [{
        "metric": "cpu_idle",
        "field": "test",
        "filters": {
            "start": "1 hour ago",
            "tags": {
                "host": ["server1", "server2"]
            },
            "value": ">= 10"
        },
        "groupBy": [{
            "name": "Tag",
            "tags": ["rack"]
        }],
        "limit": 1000,
        "aggregators": [{
            "name": "Sum",
            "sampling": "10 minutes"
        }]    
    }],
    "disablePresampling": false
}

Single Domain Return Example

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
x-bce-request-id: 72492aee-1470-46d0-8a4d-0dab7b8e67b7

{
    "results": [{
        "metric": "cpu_idle",
        "field": "test",
        "rawCount": 1000,
        "groups": [{
            "groupInfos": [{
                "name": "Tag",
                "tags": {
                    "rack": "rack1"
                }
            }],
            "values": [
                [1465718968506, 10],
                [1465718985346, 12],
                [1465718992879, 15]
            ]
        }],
        "presamplingRuleId": "21"
    }]
}

Multiple-Domain Request Example

PUT /v1/datapoint?query HTTP/1.1
Host: {database}.tsdb.iot.gz.baidubce.com
Authorization: {authorization}
Content-Type: application/json; charset=utf-8
x-bce-date: 2016-06-08T16:49:51Z

{
    "queries": [{
        "metric": "cpu_idle",
        "fields": ["field1","field2"],
        "tags": ["rack"],
        "filters": {
            "fields": [{
                    "field": "field1",
                    "value": ">= 10"
                },{
                    "field": "field2",
                    "value": "<= 10"
            }],
            "start": "1 hour ago",
            "tags": {
                "host": ["server1", "server2"]
            },
        },
        "groupBy": [{
            "name": "Tag",
            "tags": ["rack"]
        }],
        "limit": 1000,
        "aggregators": [{
            "name": "Sum",
            "sampling": "10 minutes"
        }]
    }],
    "disablePresampling": false
}

Multiple-Domain Return Example

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
x-bce-request-id: 72492aee-1470-46d0-8a4d-0dab7b8e67b7

{
    "results": [{
        "metric": "cpu_idle",
        "fields": ["field1","field2"],
        "tags": ["rack"],
        "rawCount": 1000,
        "groups": [{
            "groupInfos": [{
                "name": "Tag",
                "tags": {
                    "rack": "rack1"
                }
            }],
            "values": [
                [1465718968506, 10, 1.0, "rack1"],
                [1465718985346, 12, 2.0, "rack1"],
                [1465718992879, 15, 11.0, "rack1"]
            ]
        }],
    }]
}

Or Query Request Example

PUT /v1/datapoint?query HTTP/1.1
Host: {database}.tsdb.iot.gz.baidubce.com
Authorization: {authorization}
Content-Type: application/json; charset=utf-8
x-bce-date: 2016-06-08T16:49:51Z

{
    "queries": [{
        "metric": "cpu_idle",
        "fields": ["field1","field2"],
        "tags": ["rack"],
        "filters": {
            "or": [{
                "fields": [{
                        "field": "field1",
                        "value": ">= 10"
                    },{
                        "field": "field2",
                        "value": "<= 10"
                 }],
                "start": "1 hour ago"
            },{
                "tags":[{
                     "tag": "rack",
                     "in": ["rack1", "rack2"]
                 }],
                "start": "2 hour ago"
            }]
        },
        "groupBy": [{
            "name": "Tag",
            "tags": ["rack"]
        }],
        "limit": 1000,
        "aggregators": [{
            "name": "Sum",
            "sampling": "10 minutes"
        }]
    }]
    "disablePresampling": false
}

Or Query Return Example

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
x-bce-request-id: 72492aee-1470-46d0-8a4d-0dab7b8e67b7

{
    "results": [{
        "metric": "cpu_idle",
        "fields": ["field1","field2"],
        "tags": ["rack"],
        "rawCount": 1000,
        "groups": [{
            "groupInfos": [{
                "name": "Tag",
                "tags": {
                    "rack": "rack1"
                }
            }],
            "values": [
                [1465718968506, 10, 1.0, "rack1"],
                [1465718985346, 12, 2.0, "rack1"],
                [1465718992879, 15, 11.0, "rack1"]
            ]
        }],
    }]
}

Interpolation Request Example

PUT /v1/datapoint?query HTTP/1.1
Host: {database}.tsdb.iot.gz.baidubce.com
Authorization: {authorization}
Content-Type: application/json; charset=utf-8
x-bce-date: 2016-06-08T16:49:51Z

{
    "queries": [{
        "metric": "cpu_idle",
        "filters": {
            "start": "1 hour ago"
            "tags": {
                "host": ["server1"]
            }
        },
        "fill": {
            "type": "Linear",
            "interval": "5 minutes",
            "maxWriteInterval": "30 minutes"
        }
    }]
}

Interpolation Return Example

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
x-bce-request-id: 72492aee-1470-46d0-8a4d-0dab7b8e67b7

{
    "results": [{
        "metric": "cpu_idle",
        "field": "value",
        "rawCount": 2,
        "groups": [{
            "groupInfos": [],
            "values": [
                [1499072400000, 20.4],
                [1499072700000, 17.85],
                [1499073000000, 15.3],
                [1499073300000, 22.95],
                [1499073600000, 30.6],
                [1499073900000, 38.25],
                [1499074200000, 45.9],
                [1499074500000, 53.55],
                [1499074800000, 61.2],
                [1499075100000, 61.2],
                [1499075400000, 61.2],
                [1499075700000, 61.2]
            ]
        }]
    }]
}

Tag Match Request Example

PUT /v1/datapoint?query HTTP/1.1
Host: {database}.tsdb.iot.gz.baidubce.com
Authorization: {authorization}
Content-Type: application/json; charset=utf-8
x-bce-date: 2016-06-08T16:49:51Z

{
    "queries": [{
        "metric": "cpu_idle",
        "tags": ["tag1"],
        "filters": {
            "start": "1 hour ago"
            "tags": [{
                "tag": "tag1",
                "like": "value%"
            }]
        }
    }]
}

Tag Match Return Example

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
x-bce-request-id: 72492aee-1470-46d0-8a4d-0dab7b8e67b7

{
    "results": [{
        "metric": "cpu_idle",
        "field": "value",
        "tags": ["tag1"],
        "rawCount": 2,
        "groups": [{
            "groupInfos": [],
            "values": [
                [1499072400000, 20.4, "value1"],
                [1499072700000, 17.85, "value2"]
            ]
        }]
    }]
}

SQL Query Interface

Method	API	Instruction
GET	/v1/row?sql={statement}	Use ANSI SQL to query time series data

Request Parameters

Parameter name	Parameter type	Required	Instruction
sql	String	Required	ASIC syntax SQL query statement, Eg. Select * from metric requires url encode when placed in the get request

Return Parameters

Parameter name	Parameter type	Instruction
Columns	List<Column>	Schema information of the SQL query, an array of Column objects
rows	List<List<Object>>	Result list of the SQL Query, a two-dimensional array of Query objects

Column Objects

Parameter name	Parameter type	Instruction
name	String	Colume name

Request Example

GET /v1/row?sql=select%20%2A%20from%20metric HTTP/1.1
Host: {database}.tsdb.iot.gz.baidubce.com
Authorization: {authorization}
Content-Type: application/json; charset=utf-8
x-bce-date: 2016-06-08T16:49:51Z

Return Example

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
x-bce-request-id: 72492aee-1470-46d0-8a4d-0dab7b8e67b7

{
    "columns": [{
        "name": "time"
    },{
        "name": "field1",
    },{
        "name": "tag1"
    }],
    "rows": [
        [1499072400000, 20.4, "value1"],
        [1499072700000, 17.85, "value2"]
    ]
}

Introduction

Management API Introduction

百度智能云

Time-Spatial Database

Data API Introduction

Write Data Points

Get Metric Lists

Get Field Lists

Get Tag Lists

Query Data Points

SQL Query Interface