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