RESTful 服务

IoTDB 的 RESTful 服务可用于查询、写入和管理操作，它使用 OpenAPI 标准来定义接口并生成框架。

开启RESTful 服务

RESTful 服务默认情况是关闭的

  • 开发者

    找到sever模块中org.apache.iotdb.db.conf.rest 下面的IoTDBRestServiceConfig类，修改enableRestService=true即可。

  • 使用者

    找到IoTDB安装目录下面的conf/iotdb-common.properties文件，将 enable_rest_service 设置为 true 以启用该模块。

    1.  enable_rest_service=true

鉴权

除了检活接口 /ping，RESTful 服务使用了基础（basic）鉴权，每次 URL 请求都需要在 header 中携带 'Authorization': 'Basic ' + base64.encode(username + ':' + password)。

示例中使用的用户名为：root，密码为：root，对应的 Basic 鉴权 Header 格式为

  1. Authorization: Basic cm9vdDpyb2901

  • 若用户名密码认证失败，则返回如下信息：

    HTTP 状态码：401

    返回结构体如下

    1. {
    2.   "code": 600,
    3.   "message": "WRONG_LOGIN_PASSWORD_ERROR"
    4. }

  • 若未设置 Authorization，则返回如下信息：

    HTTP 状态码：401

    返回结构体如下

    1. {
    2.   "code": 603,
    3.   "message": "UNINITIALIZED_AUTH_ERROR"
    4. }

接口

ping

ping 接口可以用于线上服务检活。

请求方式：GET

请求路径：http://ipREST API V1 - 图1open in new window:port/ping

请求示例：

  1. $ curl http://127.0.0.1:18080/ping

返回的 HTTP 状态码：

  • 200：当前服务工作正常，可以接收外部请求。
  • 503：当前服务出现异常，不能接收外部请求。

响应参数：

参数名称参数类型参数描述
codeinteger状态码
messagestring信息提示

响应示例：

  • HTTP 状态码为 200 时：

    1. {
    2.   "code": 200,
    3.   "message": "SUCCESS_STATUS"
    4. }

  • HTTP 状态码为 503 时：

    1. {
    2.   "code": 500,
    3.   "message": "thrift service is unavailable"
    4. }

/ping 接口访问不需要鉴权。

query

query 接口可以用于处理数据查询和元数据查询。

请求方式：POST

请求头：application/json

请求路径：http://ipREST API V1 - 图2open in new window:port/rest/v1/query

参数说明:

参数名称参数类型是否必填参数描述
sqlstring是
rowLimitinteger否一次查询能返回的结果集的最大行数。
如果不设置该参数，将使用配置文件的 rest_query_default_row_size_limit 作为默认值。
当返回结果集的行数超出限制时，将返回状态码 411。

响应参数:

参数名称参数类型参数描述
expressionsarray用于数据查询时结果集列名的数组，用于元数据查询时为null
columnNamesarray用于元数据查询结果集列名数组，用于数据查询时为null
timestampsarray时间戳列，用于元数据查询时为null
valuesarray二维数组，第一维与结果集列名数组的长度相同，第二维数组代表结果集的一列

请求示例如下所示：

提示:为了避免OOM问题，不推荐使用select * from root.xx.** 这种查找方式。

请求示例 表达式查询:

  1. 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

响应示例:

  1. {
  2.   "expressions": [
  3.     "root.sg27.s3",
  4.     "root.sg27.s4",
  5.     "root.sg27.s3 + 1"
  6.   ],
  7.   "columnNames": null,
  8.   "timestamps": [
  9.     1635232143960,
  10.     1635232153960
  11.   ],
  12.   "values": [
  13.     [
  14.       11,
  15.       null
  16.     ],
  17.     [
  18.       false,
  19.       true
  20.     ],
  21.     [
  22.       12.0,
  23.       null
  24.     ]
  25.   ]
  26. }

请求示例 show child paths:

  1. 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

响应示例:

  1. {
  2.   "expressions": null,
  3.   "columnNames": [
  4.     "child paths"
  5.   ],
  6.   "timestamps": null,
  7.   "values": [
  8.     [
  9.       "root.sg27",
  10.       "root.sg28"
  11.     ]
  12.   ]
  13. }

请求示例 show child nodes:

  1. 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

响应示例:

  1. {
  2.   "expressions": null,
  3.   "columnNames": [
  4.     "child nodes"
  5.   ],
  6.   "timestamps": null,
  7.   "values": [
  8.     [
  9.       "sg27",
  10.       "sg28"
  11.     ]
  12.   ]
  13. }

请求示例 show all ttl:

  1. 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

响应示例:

  1. {
  2.   "expressions": null,
  3.   "columnNames": [
  4.     "database",
  5.     "ttl"
  6.   ],
  7.   "timestamps": null,
  8.   "values": [
  9.     [
  10.       "root.sg27",
  11.       "root.sg28"
  12.     ],
  13.     [
  14.       null,
  15.       null
  16.     ]
  17.   ]
  18. }

请求示例 show ttl:

  1. 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

响应示例:

  1. {
  2.   "expressions": null,
  3.   "columnNames": [
  4.     "database",
  5.     "ttl"
  6.   ],
  7.   "timestamps": null,
  8.   "values": [
  9.     [
  10.       "root.sg27"
  11.     ],
  12.     [
  13.       null
  14.     ]
  15.   ]
  16. }

请求示例 show functions:

  1. 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

响应示例:

  1. {
  2.   "expressions": null,
  3.   "columnNames": [
  4.     "function name",
  5.     "function type",
  6.     "class name (UDF)"
  7.   ],
  8.   "timestamps": null,
  9.   "values": [
  10.     [
  11.       "ABS",
  12.       "ACOS",
  13.       "ASIN",
  14.       ...
  15.     ],
  16.     [
  17.       "built-in UDTF",
  18.       "built-in UDTF",
  19.       "built-in UDTF",
  20.       ...
  21.     ],
  22.     [
  23.       "org.apache.iotdb.db.query.udf.builtin.UDTFAbs",
  24.       "org.apache.iotdb.db.query.udf.builtin.UDTFAcos",
  25.       "org.apache.iotdb.db.query.udf.builtin.UDTFAsin",
  26.       ...
  27.     ]
  28.   ]
  29. }

请求示例 show timeseries:

  1. 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

响应示例:

  1. {
  2.   "expressions": null,
  3.   "columnNames": [
  4.     "timeseries",
  5.     "alias",
  6.     "database",
  7.     "dataType",
  8.     "encoding",
  9.     "compression",
  10.     "tags",
  11.     "attributes"
  12.   ],
  13.   "timestamps": null,
  14.   "values": [
  15.     [
  16.       "root.sg27.s3",
  17.       "root.sg27.s4",
  18.       "root.sg28.s3",
  19.       "root.sg28.s4"
  20.     ],
  21.     [
  22.       null,
  23.       null,
  24.       null,
  25.       null
  26.     ],
  27.     [
  28.       "root.sg27",
  29.       "root.sg27",
  30.       "root.sg28",
  31.       "root.sg28"
  32.     ],
  33.     [
  34.       "INT32",
  35.       "BOOLEAN",
  36.       "INT32",
  37.       "BOOLEAN"
  38.     ],
  39.     [
  40.       "RLE",
  41.       "RLE",
  42.       "RLE",
  43.       "RLE"
  44.     ],
  45.     [
  46.       "SNAPPY",
  47.       "SNAPPY",
  48.       "SNAPPY",
  49.       "SNAPPY"
  50.     ],
  51.     [
  52.       null,
  53.       null,
  54.       null,
  55.       null
  56.     ],
  57.     [
  58.       null,
  59.       null,
  60.       null,
  61.       null
  62.     ]
  63.   ]
  64. }

请求示例 show latest timeseries:

  1. 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

响应示例:

  1. {
  2.   "expressions": null,
  3.   "columnNames": [
  4.     "timeseries",
  5.     "alias",
  6.     "database",
  7.     "dataType",
  8.     "encoding",
  9.     "compression",
  10.     "tags",
  11.     "attributes"
  12.   ],
  13.   "timestamps": null,
  14.   "values": [
  15.     [
  16.       "root.sg28.s4",
  17.       "root.sg27.s4",
  18.       "root.sg28.s3",
  19.       "root.sg27.s3"
  20.     ],
  21.     [
  22.       null,
  23.       null,
  24.       null,
  25.       null
  26.     ],
  27.     [
  28.       "root.sg28",
  29.       "root.sg27",
  30.       "root.sg28",
  31.       "root.sg27"
  32.     ],
  33.     [
  34.       "BOOLEAN",
  35.       "BOOLEAN",
  36.       "INT32",
  37.       "INT32"
  38.     ],
  39.     [
  40.       "RLE",
  41.       "RLE",
  42.       "RLE",
  43.       "RLE"
  44.     ],
  45.     [
  46.       "SNAPPY",
  47.       "SNAPPY",
  48.       "SNAPPY",
  49.       "SNAPPY"
  50.     ],
  51.     [
  52.       null,
  53.       null,
  54.       null,
  55.       null
  56.     ],
  57.     [
  58.       null,
  59.       null,
  60.       null,
  61.       null
  62.     ]
  63.   ]
  64. }

请求示例 count timeseries:

  1. 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

响应示例:

  1. {
  2.   "expressions": null,
  3.   "columnNames": [
  4.     "count"
  5.   ],
  6.   "timestamps": null,
  7.   "values": [
  8.     [
  9.       4
  10.     ]
  11.   ]
  12. }

请求示例 count nodes:

  1. 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

响应示例:

  1. {
  2.   "expressions": null,
  3.   "columnNames": [
  4.     "count"
  5.   ],
  6.   "timestamps": null,
  7.   "values": [
  8.     [
  9.       4
  10.     ]
  11.   ]
  12. }

请求示例 show devices:

  1. 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

响应示例:

  1. {
  2.   "expressions": null,
  3.   "columnNames": [
  4.     "devices",
  5.     "isAligned"
  6.   ],
  7.   "timestamps": null,
  8.   "values": [
  9.     [
  10.       "root.sg27",
  11.       "root.sg28"
  12.     ],
  13.     [
  14.       "false",
  15.       "false"
  16.     ]
  17.   ]
  18. }

请求示例 show devices with database:

  1. 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/v1/query

响应示例:

  1. {
  2.   "expressions": null,
  3.   "columnNames": [
  4.     "devices",
  5.     "database",
  6.     "isAligned"
  7.   ],
  8.   "timestamps": null,
  9.   "values": [
  10.     [
  11.       "root.sg27",
  12.       "root.sg28"
  13.     ],
  14.     [
  15.       "root.sg27",
  16.       "root.sg28"
  17.     ],
  18.     [
  19.       "false",
  20.       "false"
  21.     ]
  22.   ]
  23. }

请求示例 list user:

  1. 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

响应示例:

  1. {
  2.   "expressions": null,
  3.   "columnNames": [
  4.     "user"
  5.   ],
  6.   "timestamps": null,
  7.   "values": [
  8.     [
  9.       "root"
  10.     ]
  11.   ]
  12. }

请求示例 原始聚合查询:

  1. 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

响应示例:

  1. {
  2.   "expressions": [
  3.     "count(root.sg27.s3)",
  4.     "count(root.sg27.s4)"
  5.   ],
  6.   "columnNames": null,
  7.   "timestamps": [
  8.     0
  9.   ],
  10.   "values": [
  11.     [
  12.       1
  13.     ],
  14.     [
  15.       2
  16.     ]
  17.   ]
  18. }

请求示例 group by level:

  1. 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

响应示例:

  1. {
  2.   "expressions": null,
  3.   "columnNames": [
  4.     "count(root.sg27.*)",
  5.     "count(root.sg28.*)"
  6.   ],
  7.   "timestamps": null,
  8.   "values": [
  9.     [
  10.       3
  11.     ],
  12.     [
  13.       3
  14.     ]
  15.   ]
  16. }

请求示例 group by:

  1. 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

响应示例:

  1. {
  2.   "expressions": [
  3.     "count(root.sg27.s3)",
  4.     "count(root.sg27.s4)"
  5.   ],
  6.   "columnNames": null,
  7.   "timestamps": [
  8.     1635232143960,
  9.     1635232144960,
  10.     1635232145960,
  11.     1635232146960,
  12.     1635232147960,
  13.     1635232148960,
  14.     1635232149960,
  15.     1635232150960,
  16.     1635232151960,
  17.     1635232152960
  18.   ],
  19.   "values": [
  20.     [
  21.       1,
  22.       0,
  23.       0,
  24.       0,
  25.       0,
  26.       0,
  27.       0,
  28.       0,
  29.       0,
  30.       0
  31.     ],
  32.     [
  33.       1,
  34.       0,
  35.       0,
  36.       0,
  37.       0,
  38.       0,
  39.       0,
  40.       0,
  41.       0,
  42.       0
  43.     ]
  44.   ]
  45. }

请求示例 last:

  1. 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

响应示例:

  1. {
  2.   "expressions": null,
  3.   "columnNames": [
  4.     "timeseries",
  5.     "value",
  6.     "dataType"
  7.   ],
  8.   "timestamps": [
  9.     1635232143960
  10.   ],
  11.   "values": [
  12.     [
  13.       "root.sg27.s3"
  14.     ],
  15.     [
  16.       "11"
  17.     ],
  18.     [
  19.       "INT32"
  20.     ]
  21.   ]
  22. }

请求示例 disable align:

  1. 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

响应示例:

  1. {
  2.   "code": 407,
  3.   "message": "disable align clauses are not supported."
  4. }

请求示例 align by device:

  1. 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

响应示例:

  1. {
  2.   "code": 407,
  3.   "message": "align by device clauses are not supported."
  4. }

请求示例 select into:

  1. 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

响应示例:

  1. {
  2.   "code": 407,
  3.   "message": "select into clauses are not supported."
  4. }

nonQuery

请求方式：POST

请求头：application/json

请求路径：http://ipREST API V1 - 图3open in new window:port/rest/v1/nonQuery

参数说明:

参数名称参数类型是否必填参数描述
sqlstring是

请求示例:

  1. 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/v1/nonQuery

响应参数:

参数名称参数类型参数描述
codeinteger状态码
messagestring信息提示

响应示例：

  1. {
  2.   "code": 200,
  3.   "message": "SUCCESS_STATUS"
  4. }

insertTablet

请求方式：POST

请求头：application/json

请求路径：http://ipREST API V1 - 图4open in new window:port/rest/v1/insertTablet

参数说明:

参数名称参数类型是否必填参数描述
timestampsarray是时间列
measurementsarray是测点名称
dataTypesarray是数据类型
valuesarray是值列，每一列中的值可以为 null
isAlignedboolean是是否是对齐时间序列
deviceIdstring是设备名称

请求示例：

  1. 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

响应参数：

参数名称参数类型参数描述
codeinteger状态码
messagestring信息提示

响应示例：

  1. {
  2.   "code": 200,
  3.   "message": "SUCCESS_STATUS"
  4. }

insertRecords

请求方式：POST

请求头：application/json

请求路径：http://ipREST API V1 - 图5open in new window:port/rest/v1/insertRecords

参数说明:

参数名称参数类型是否必填参数描述
timestampsarray是时间列
measurementsListarray是测点名称
dataTypesListarray是数据类型
valuesListarray是值列，每一列中的值可以为 null
deviceIdsstring是设备名称

请求示例：

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

响应参数：

参数名称参数类型参数描述
codeinteger状态码
messagestring信息提示

响应示例：

  1. {
  2.   "code": 200,
  3.   "message": "SUCCESS_STATUS"
  4. }

配置

配置位于 iotdb-common.properties 中。

  • 将 enable_rest_service 设置为 true 以启用该模块，而将 false 设置为禁用该模块。默认情况下，该值为 false。
  1. enable_rest_service=true
  • 仅在 enable_rest_service=true 时生效。将 rest_service_port 设置为数字（1025~65535），以自定义REST服务套接字端口。默认情况下，值为 18080。
  1. rest_service_port=18080
  • 将 ‘enable_swagger’ 设置 ‘true’ 启用swagger来展示rest接口信息, 而设置为 ‘false’ 关闭该功能. 默认情况下，该值为 false。
  1. enable_swagger=false
  • 一次查询能返回的结果集最大行数。当返回结果集的行数超出参数限制时，您只会得到在行数范围内的结果集，且将得到状态码411。
  1. rest_query_default_row_size_limit=10000
  • 缓存客户登录信息的过期时间（用于加速用户鉴权的速度，单位为秒，默认是8个小时）
  1. cache_expire=28800
  • 缓存中存储的最大用户数量（默认是100）
  1. cache_max_num=100
  • 缓存初始容量（默认是10）
  1. cache_init_num=10
  • REST Service 是否开启 SSL 配置，将 enable_https 设置为 true 以启用该模块，而将 false 设置为禁用该模块。默认情况下，该值为 false。
  1. enable_https=false
  • keyStore 所在路径（非必填）
  1. key_store_path=
  • keyStore 密码（非必填）
  1. key_store_pwd=
  • trustStore 所在路径（非必填）
  1. trust_store_path=
  • trustStore 密码（非必填）
  1. trust_store_pwd=
  • SSL 超时时间，单位为秒
  1. idle_timeout=5000