Skip to main content

RESTful API V2

About 7 min

RESTful API V2

IoTDB's RESTful services can be used for query, write, and management operations, using the OpenAPI standard to define interfaces and generate frameworks.

Enable RESTful Services

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-system.properties file under the IoTDB installation directory and set enable_rest_service to true to enable the module.

    enable_rest_service=true

Authentication

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"
}

Interface

ping

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 nameparameter typeparameter describe
codeintegerstatus code
messagestringmessage

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.

query

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/v2/query

Parameter Description:

parameter nameparameter typerequiredparameter description
sqlstringyes
row_limitintegernoThe 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 nameparameter typeparameter description
expressionsarrayArray of result set column names for data query, null for metadata query
column_namesarrayArray of column names for metadata query result set, null for data query
timestampsarrayTimestamp column, null for metadata query
valuesarrayA 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/v2/query

{
  "expressions": [
    "root.sg27.s3",
    "root.sg27.s4",
    "root.sg27.s3 + 1"
  ],
  "column_names": 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/v2/query

{
  "expressions": null,
  "column_names": [
    "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/v2/query

{
  "expressions": null,
  "column_names": [
    "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/v2/query

{
  "expressions": null,
  "column_names": [
    "database",
    "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/v2/query

{
  "expressions": null,
  "column_names": [
    "database",
    "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/v2/query

{
  "expressions": null,
  "column_names": [
    "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/v2/query

{
  "expressions": null,
  "column_names": [
    "timeseries",
    "alias",
    "database",
    "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/v2/query

{
  "expressions": null,
  "column_names": [
    "timeseries",
    "alias",
    "database",
    "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/v2/query

{
  "expressions": null,
  "column_names": [
    "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/v2/query

{
  "expressions": null,
  "column_names": [
    "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/v2/query

{
  "expressions": null,
  "column_names": [
    "devices",
    "isAligned"
  ],
  "timestamps": null,
  "values": [
    [
      "root.sg27",
      "root.sg28"
    ],
    [
      "false",
      "false"
    ]
  ]
}

Show devices with database

curl -H "Content-Type:application/json" -H "Authorization:Basic cm9vdDpyb290" -X POST --data '{"sql":"show devices with database"}' http://127.0.0.1:18080/rest/v2/query

{
  "expressions": null,
  "column_names": [
    "devices",
    "database",
    "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/v2/query

{
  "expressions": null,
  "column_names": [
    "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/v2/query

{
  "expressions": [
    "count(root.sg27.s3)",
    "count(root.sg27.s4)"
  ],
  "column_names": 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/v2/query

{
  "expressions": null,
  "column_names": [
    "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/v2/query

{
  "expressions": [
    "count(root.sg27.s3)",
    "count(root.sg27.s4)"
  ],
  "column_names": 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/v2/query

{
  "expressions": null,
  "column_names": [
    "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/v2/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/v2/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/v2/query

{
  "code": 407,
  "message": "select into clauses are not supported."
}

nonQuery

Request method: POST

Request header: application/json

Request path: http://ip:port/rest/v2/nonQuery

Parameter Description:

parameter nameparameter typeparameter describe
sqlstringquery content

Example request:

curl -H "Content-Type:application/json" -H "Authorization:Basic cm9vdDpyb290" -X POST --data '{"sql":"CREATE DATABASE root.ln"}' http://127.0.0.1:18080/rest/v2/nonQuery

Response parameters:

parameter nameparameter typeparameter describe
codeintegerstatus code
messagestringmessage

Sample response:

{
  "code": 200,
  "message": "SUCCESS_STATUS"
}

insertTablet

Request method: POST

Request header: application/json

Request path: http://ip:port/rest/v2/insertTablet

Parameter Description:

parameter nameparameter typeis requiredparameter describe
timestampsarrayyesTime column
measurementsarrayyesThe name of the measuring point
data_typesarrayyesThe data type
valuesarrayyesValue columns, the values in each column can be null
is_alignedbooleanyesWhether to align the timeseries
devicestringyesDevice name

Example request:

curl -H "Content-Type:application/json" -H "Authorization:Basic cm9vdDpyb290" -X POST --data '{"timestamps":[1635232143960,1635232153960],"measurements":["s3","s4"],"data_types":["INT32","BOOLEAN"],"values":[[11,null],[false,true]],"is_aligned":false,"device":"root.sg27"}' http://127.0.0.1:18080/rest/v2/insertTablet

Sample response:

parameter nameparameter typeparameter describe
codeintegerstatus code
messagestringmessage

Sample response:

{
  "code": 200,
  "message": "SUCCESS_STATUS"
}

insertRecords

Request method: POST

Request header: application/json

Request path: http://ip:port/rest/v2/insertRecords

Parameter Description:

parameter nameparameter typeis requiredparameter describe
timestampsarrayyesTime column
measurements_listarrayyesThe name of the measuring point
data_types_listarrayyesThe data type
values_listarrayyesValue columns, the values in each column can be null
devicesstringyesDevice name
is_alignedbooleanyesWhether to align the timeseries

Example request:

curl -H "Content-Type:application/json" -H "Authorization:Basic cm9vdDpyb290" -X POST --data '{"timestamps":[1635232113960,1635232151960,1635232143960,1635232143960],"measurements_list":[["s33","s44"],["s55","s66"],["s77","s88"],["s771","s881"]],"data_types_list":[["INT32","INT64"],["FLOAT","DOUBLE"],["FLOAT","DOUBLE"],["BOOLEAN","TEXT"]],"values_list":[[1,11],[2.1,2],[4,6],[false,"cccccc"]],"is_aligned":false,"devices":["root.s1","root.s1","root.s1","root.s3"]}' http://127.0.0.1:18080/rest/v2/insertRecords

Sample response:

parameter nameparameter typeparameter describe
codeintegerstatus code
messagestringmessage

Sample response:

{
  "code": 200,
  "message": "SUCCESS_STATUS"
}

Configuration

The configuration is located in 'iotdb-system.properties'.

  • Set 'enable_rest_service' to 'true' to enable the module, and 'false' to disable the module. By default, this value is' false '.
enable_rest_service=true
  • This parameter is valid only when 'enable_REST_service =true'. Set 'rest_service_port' to a number (1025 to 65535) to customize the REST service socket port. By default, the value is 18080.
rest_service_port=18080
  • Set 'enable_swagger' to 'true' to display rest service interface information through swagger, and 'false' to do not display the rest service interface information through the swagger. By default, this value is' false '.
enable_swagger=false
  • The maximum number of rows in the result set that can be returned by a query. When the number of rows in the returned result set exceeds the limit, the status code 411 is returned.
rest_query_default_row_size_limit=10000
  • Expiration time for caching customer login information (used to speed up user authentication, in seconds, 8 hours by default)
cache_expire=28800
  • Maximum number of users stored in the cache (default: 100)
cache_max_num=100
  • Initial cache size (default: 10)
cache_init_num=10
  • REST Service whether to enable SSL configuration, set 'enable_https' to' true 'to enable the module, and set' false 'to disable the module. By default, this value is' false '.
enable_https=false
  • keyStore location path (optional)
key_store_path=
  • keyStore password (optional)
key_store_pwd=
  • trustStore location path (optional)
trust_store_path=
  • trustStore password (optional)
trust_store_pwd=
  • SSL timeout period, in seconds
idle_timeout=5000

Copyright © 2024 The Apache Software Foundation.
Apache IoTDB, IoTDB, Apache, the Apache feather logo, and the Apache IoTDB project logo are either registered trademarks or trademarks of The Apache Software Foundation in all countries

Have a question? Connect with us on QQ, WeChat, or Slack. Join the community now.