IoTDB's RESTful services can be used for query, write, and management operations, using the OpenAPI standard to define interfaces and generate frameworks.
RESTful services are disabled by default.
Developer
Find the IoTDBrestServiceConfig
class under org.apache.iotdb.db.conf.rest
in the sever module, and modify enableRestService=true
.
User
Find the conf/iotdb.rest.properties
file under the IoTDB installation directory and set enable_rest_service
to true
to enable the module.
enable_rest_service=true
Except the liveness probe API /ping
, RESTful services use the basic authentication. Each URL request needs to carry 'Authorization': 'Basic ' + base64.encode(username + ':' + password)
.
The username used in the following examples is: root
, and password is: root
.
And the authorization header is
Authorization: Basic cm9vdDpyb2901
If a user authorized with incorrect username or password, the following error is returned:
HTTP Status Code:401
HTTP response body:
{ "code": 600, "message": "WRONG_LOGIN_PASSWORD_ERROR" }
If the Authorization
header is missing,the following error is returned:
HTTP Status Code:401
HTTP response body:
{ "code": 603, "message": "UNINITIALIZED_AUTH_ERROR" }
The /ping
API can be used for service liveness probing.
Request method: GET
Request path: http://ip:port/ping
The user name used in the example is: root, password: root
Example request:
$ curl http://127.0.0.1:18080/ping
Response status codes:
200
: The service is alive.503
: The service cannot accept any requests now.Response parameters:
parameter name | parameter type | parameter describe |
---|---|---|
code | integer | status code |
message | string | message |
Sample response:
With HTTP status code 200
:
{ "code": 200, "message": "SUCCESS_STATUS" }
With HTTP status code 503
:
{ "code": 500, "message": "thrift service is unavailable" }
/ping
can be accessed without authorization.
The query interface can be used to handle data queries and metadata queries.
Request method: POST
Request header: application/json
Request path: http://ip:port/rest/v1/query
Parameter Description:
parameter name | parameter type | required | parameter description |
---|---|---|---|
sql | string | yes | |
rowLimit | integer | no | The maximum number of rows in the result set that can be returned by a query. If this parameter is not set, the rest_query_default_row_size_limit of the configuration file will be used as the default value. When the number of rows in the returned result set exceeds the limit, the status code 411 will be returned. |
Response parameters:
parameter name | parameter type | parameter description |
---|---|---|
expressions | array | Array of result set column names for data query, null for metadata query |
columnNames | array | Array of column names for metadata query result set, null for data query |
timestamps | array | Timestamp column, null for metadata query |
values | array | A two-dimensional array, the first dimension has the same length as the result set column name array, and the second dimension array represents a column of the result set |
Examples:
Tip: Statements like select * from root.xx.**
are not recommended because those statements may cause OOM.
Expression query
curl -H "Content-Type:application/json" -H "Authorization:Basic cm9vdDpyb290" -X POST --data '{"sql":"select s3, s4, s3 + 1 from root.sg27 limit 2"}' http://127.0.0.1:18080/rest/v1/query
{ "expressions": [ "root.sg27.s3", "root.sg27.s4", "root.sg27.s3 + 1" ], "columnNames": null, "timestamps": [ 1635232143960, 1635232153960 ], "values": [ [ 11, null ], [ false, true ], [ 12.0, null ] ] }
Show child paths
curl -H "Content-Type:application/json" -H "Authorization:Basic cm9vdDpyb290" -X POST --data '{"sql":"show child paths root"}' http://127.0.0.1:18080/rest/v1/query
{ "expressions": null, "columnNames": [ "child paths" ], "timestamps": null, "values": [ [ "root.sg27", "root.sg28" ] ] }
Show child nodes
curl -H "Content-Type:application/json" -H "Authorization:Basic cm9vdDpyb290" -X POST --data '{"sql":"show child nodes root"}' http://127.0.0.1:18080/rest/v1/query
{ "expressions": null, "columnNames": [ "child nodes" ], "timestamps": null, "values": [ [ "sg27", "sg28" ] ] }
Show all ttl
curl -H "Content-Type:application/json" -H "Authorization:Basic cm9vdDpyb290" -X POST --data '{"sql":"show all ttl"}' http://127.0.0.1:18080/rest/v1/query
{ "expressions": null, "columnNames": [ "storage group", "ttl" ], "timestamps": null, "values": [ [ "root.sg27", "root.sg28" ], [ null, null ] ] }
Show ttl
curl -H "Content-Type:application/json" -H "Authorization:Basic cm9vdDpyb290" -X POST --data '{"sql":"show ttl on root.sg27"}' http://127.0.0.1:18080/rest/v1/query
{ "expressions": null, "columnNames": [ "storage group", "ttl" ], "timestamps": null, "values": [ [ "root.sg27" ], [ null ] ] }
Show functions
curl -H "Content-Type:application/json" -H "Authorization:Basic cm9vdDpyb290" -X POST --data '{"sql":"show functions"}' http://127.0.0.1:18080/rest/v1/query
{ "expressions": null, "columnNames": [ "function name", "function type", "class name (UDF)" ], "timestamps": null, "values": [ [ "ABS", "ACOS", "ASIN", ... ], [ "built-in UDTF", "built-in UDTF", "built-in UDTF", ... ], [ "org.apache.iotdb.db.query.udf.builtin.UDTFAbs", "org.apache.iotdb.db.query.udf.builtin.UDTFAcos", "org.apache.iotdb.db.query.udf.builtin.UDTFAsin", ... ] ] }
Show timeseries
curl -H "Content-Type:application/json" -H "Authorization:Basic cm9vdDpyb290" -X POST --data '{"sql":"show timeseries"}' http://127.0.0.1:18080/rest/v1/query
{ "expressions": null, "columnNames": [ "timeseries", "alias", "storage group", "dataType", "encoding", "compression", "tags", "attributes" ], "timestamps": null, "values": [ [ "root.sg27.s3", "root.sg27.s4", "root.sg28.s3", "root.sg28.s4" ], [ null, null, null, null ], [ "root.sg27", "root.sg27", "root.sg28", "root.sg28" ], [ "INT32", "BOOLEAN", "INT32", "BOOLEAN" ], [ "RLE", "RLE", "RLE", "RLE" ], [ "SNAPPY", "SNAPPY", "SNAPPY", "SNAPPY" ], [ null, null, null, null ], [ null, null, null, null ] ] }
Show latest timeseries
curl -H "Content-Type:application/json" -H "Authorization:Basic cm9vdDpyb290" -X POST --data '{"sql":"show latest timeseries"}' http://127.0.0.1:18080/rest/v1/query
{ "expressions": null, "columnNames": [ "timeseries", "alias", "storage group", "dataType", "encoding", "compression", "tags", "attributes" ], "timestamps": null, "values": [ [ "root.sg28.s4", "root.sg27.s4", "root.sg28.s3", "root.sg27.s3" ], [ null, null, null, null ], [ "root.sg28", "root.sg27", "root.sg28", "root.sg27" ], [ "BOOLEAN", "BOOLEAN", "INT32", "INT32" ], [ "RLE", "RLE", "RLE", "RLE" ], [ "SNAPPY", "SNAPPY", "SNAPPY", "SNAPPY" ], [ null, null, null, null ], [ null, null, null, null ] ] }
Count timeseries
curl -H "Content-Type:application/json" -H "Authorization:Basic cm9vdDpyb290" -X POST --data '{"sql":"count timeseries root.**"}' http://127.0.0.1:18080/rest/v1/query
{ "expressions": null, "columnNames": [ "count" ], "timestamps": null, "values": [ [ 4 ] ] }
Count nodes
curl -H "Content-Type:application/json" -H "Authorization:Basic cm9vdDpyb290" -X POST --data '{"sql":"count nodes root.** level=2"}' http://127.0.0.1:18080/rest/v1/query
{ "expressions": null, "columnNames": [ "count" ], "timestamps": null, "values": [ [ 4 ] ] }
Show devices
curl -H "Content-Type:application/json" -H "Authorization:Basic cm9vdDpyb290" -X POST --data '{"sql":"show devices"}' http://127.0.0.1:18080/rest/v1/query
{ "expressions": null, "columnNames": [ "devices", "isAligned" ], "timestamps": null, "values": [ [ "root.sg27", "root.sg28" ], [ "false", "false" ] ] }
Show devices with storage group
curl -H "Content-Type:application/json" -H "Authorization:Basic cm9vdDpyb290" -X POST --data '{"sql":"show devices with storage group"}' http://127.0.0.1:18080/rest/v1/query
{ "expressions": null, "columnNames": [ "devices", "storage group", "isAligned" ], "timestamps": null, "values": [ [ "root.sg27", "root.sg28" ], [ "root.sg27", "root.sg28" ], [ "false", "false" ] ] }
List user
curl -H "Content-Type:application/json" -H "Authorization:Basic cm9vdDpyb290" -X POST --data '{"sql":"list user"}' http://127.0.0.1:18080/rest/v1/query
{ "expressions": null, "columnNames": [ "user" ], "timestamps": null, "values": [ [ "root" ] ] }
Aggregation
curl -H "Content-Type:application/json" -H "Authorization:Basic cm9vdDpyb290" -X POST --data '{"sql":"select count(*) from root.sg27"}' http://127.0.0.1:18080/rest/v1/query
{ "expressions": [ "count(root.sg27.s3)", "count(root.sg27.s4)" ], "columnNames": null, "timestamps": [ 0 ], "values": [ [ 1 ], [ 2 ] ] }
Group by level
curl -H "Content-Type:application/json" -H "Authorization:Basic cm9vdDpyb290" -X POST --data '{"sql":"select count(*) from root.** group by level = 1"}' http://127.0.0.1:18080/rest/v1/query
{ "expressions": null, "columnNames": [ "count(root.sg27.*)", "count(root.sg28.*)" ], "timestamps": null, "values": [ [ 3 ], [ 3 ] ] }
Group by
curl -H "Content-Type:application/json" -H "Authorization:Basic cm9vdDpyb290" -X POST --data '{"sql":"select count(*) from root.sg27 group by([1635232143960,1635232153960),1s)"}' http://127.0.0.1:18080/rest/v1/query
{ "expressions": [ "count(root.sg27.s3)", "count(root.sg27.s4)" ], "columnNames": null, "timestamps": [ 1635232143960, 1635232144960, 1635232145960, 1635232146960, 1635232147960, 1635232148960, 1635232149960, 1635232150960, 1635232151960, 1635232152960 ], "values": [ [ 1, 0, 0, 0, 0, 0, 0, 0, 0, 0 ], [ 1, 0, 0, 0, 0, 0, 0, 0, 0, 0 ] ] }
Last
curl -H "Content-Type:application/json" -H "Authorization:Basic cm9vdDpyb290" -X POST --data '{"sql":"select last s3 from root.sg27"}' http://127.0.0.1:18080/rest/v1/query
{ "expressions": null, "columnNames": [ "timeseries", "value", "dataType" ], "timestamps": [ 1635232143960 ], "values": [ [ "root.sg27.s3" ], [ "11" ], [ "INT32" ] ] }
Disable align
curl -H "Content-Type:application/json" -H "Authorization:Basic cm9vdDpyb290" -X POST --data '{"sql":"select * from root.sg27 disable align"}' http://127.0.0.1:18080/rest/v1/query
{ "code": 407, "message": "disable align clauses are not supported." }
Align by device
curl -H "Content-Type:application/json" -H "Authorization:Basic cm9vdDpyb290" -X POST --data '{"sql":"select count(s3) from root.sg27 align by device"}' http://127.0.0.1:18080/rest/v1/query
{ "code": 407, "message": "align by device clauses are not supported." }
Select into
curl -H "Content-Type:application/json" -H "Authorization:Basic cm9vdDpyb290" -X POST --data '{"sql":"select s3, s4 into root.sg29.s1, root.sg29.s2 from root.sg27"}' http://127.0.0.1:18080/rest/v1/query
{ "code": 407, "message": "select into clauses are not supported." }
Request method: POST
Request header: application/json
Request path: http://ip:port/rest/v1/nonQuery
Parameter Description:
parameter name | parameter type | parameter describe |
---|---|---|
sql | string | query content |
Example request:
curl -H "Content-Type:application/json" -H "Authorization:Basic cm9vdDpyb290" -X POST --data '{"sql":"set storage group to root.ln"}' http://127.0.0.1:18080/rest/v1/nonQuery
Response parameters:
parameter name | parameter type | parameter describe |
---|---|---|
code | integer | status code |
message | string | message |
Sample response:
{ "code": 200, "message": "SUCCESS_STATUS" }
Request method: POST
Request header: application/json
Request path: http://ip:port/rest/v1/insertTablet
Parameter Description:
parameter name | parameter type | is required | parameter describe |
---|---|---|---|
timestamps | array | yes | Time column |
measurements | array | yes | The name of the measuring point |
dataTypes | array | yes | The data type |
values | array | yes | Value columns, the values in each column can be null |
isAligned | boolean | yes | Whether to align the timeseries |
deviceId | boolean | yes | Device name |
Example request:
curl -H "Content-Type:application/json" -H "Authorization:Basic cm9vdDpyb290" -X POST --data '{"timestamps":[1635232143960,1635232153960],"measurements":["s3","s4"],"dataTypes":["INT32","BOOLEAN"],"values":[[11,null],[false,true]],"isAligned":false,"deviceId":"root.sg27"}' http://127.0.0.1:18080/rest/v1/insertTablet
Sample response:
parameter name | parameter type | parameter describe |
---|---|---|
code | integer | status code |
message | string | message |
Sample response:
{ "code": 200, "message": "SUCCESS_STATUS" }
The configuration is located in ‘iotdb-rest.properties’.
enable_rest_service=true
rest_service_port=18080
411
is returned.rest_query_default_row_size_limit=10000
cache_expire=28800
cache_max_num=100
cache_init_num=10
enable_https=false
key_store_path=
key_store_pwd=
trust_store_path=
trust_store_pwd=
idle_timeout=5000