Skip to content

T
TDengine

taosdata / TDengine
接近 2 年 前同步成功

通知 1192
Star 22018
Fork 4786
T
TDengine
未验证 提交 72f25355 编写于 作者: sangshuduo's avatar sangshuduo 提交者： GitHub
浏览文件
操作

docs: refine reference en docs (#12593) 

* docs: reference doc in English

[TD-15603]

* docs: reference docs in English

[TD-15603]

* docs: refine reference English docs

[TD-15603]

* docs: refine reference docs

* docs: refine refince docs

* docs: refine reference doc
上级 b2325071
隐藏空白更改
内联 并排
Showing with 34 addition and 32 deletion
docs-cn/14-reference/02-rest-api/02-rest-api.mdx
浏览文件 @ 72f25355
...@@ -4,7 +4,9 @@ title: REST API ...@@ -4,7 +4,9 @@ title: REST API
为支持各种不同类型平台的开发，TDengine 提供符合 REST 设计标准的 API，即 REST API。为最大程度降低学习成本，不同于其他数据库 REST API 的设计方法，TDengine 直接通过 HTTP POST 请求 BODY 中包含的 SQL 语句来操作数据库，仅需要一个 URL。REST 连接器的使用参见[视频教程](https://www.taosdata.com/blog/2020/11/11/1965.html)。 为支持各种不同类型平台的开发，TDengine 提供符合 REST 设计标准的 API，即 REST API。为最大程度降低学习成本，不同于其他数据库 REST API 的设计方法，TDengine 直接通过 HTTP POST 请求 BODY 中包含的 SQL 语句来操作数据库，仅需要一个 URL。REST 连接器的使用参见[视频教程](https://www.taosdata.com/blog/2020/11/11/1965.html)。
注意：与原生连接器的一个区别是，RESTful 接口是无状态的，因此 `USE db_name` 指令没有效果，所有对表名、超级表名的引用都需要指定数据库名前缀。（从 2.2.0.0 版本开始，支持在 RESTful url 中指定 db_name，这时如果 SQL 语句中没有指定数据库名前缀的话，会使用 url 中指定的这个 db_name。从 2.4.0.0 版本开始，RESTful 默认由 taosAdapter 提供，要求必须在 url 中指定 db_name。） :::note
与原生连接器的一个区别是，RESTful 接口是无状态的，因此 `USE db_name` 指令没有效果，所有对表名、超级表名的引用都需要指定数据库名前缀。从 2.2.0.0 版本开始，支持在 RESTful URL 中指定 db_name，这时如果 SQL 语句中没有指定数据库名前缀的话，会使用 URL 中指定的这个 db_name。从 2.4.0.0 版本开始，RESTful 默认由 taosAdapter 提供，要求必须在 URL 中指定 db_name。
:::
## 安装 ## 安装
...@@ -16,11 +18,10 @@ RESTful 接口不依赖于任何 TDengine 的库，因此客户端不需要安 ...@@ -16,11 +18,10 @@ RESTful 接口不依赖于任何 TDengine 的库，因此客户端不需要安
下面以 Ubuntu 环境中使用 curl 工具（确认已经安装）来验证 RESTful 接口的正常。 下面以 Ubuntu 环境中使用 curl 工具（确认已经安装）来验证 RESTful 接口的正常。
下面示例是列出所有的数据库，请把 h1.taosdata.com 和 6041（缺省值）替换为实际运行的 TDengine 服务 fqdn 和端口号： 下面示例是列出所有的数据库，请把 h1.taosdata.com 和 6041（缺省值）替换为实际运行的 TDengine 服务 FQDN 和端口号：
```html ```html
curl -H 'Authorization: Basic cm9vdDp0YW9zZGF0YQ==' -d 'show databases;' curl -H 'Authorization: Basic cm9vdDp0YW9zZGF0YQ==' -d 'show databases;' h1.taosdata.com:6041/rest/sql
h1.taosdata.com:6041/rest/sql
``` ```
返回值结果如下表示验证通过： 返回值结果如下表示验证通过：
...@@ -100,7 +101,7 @@ HTTP 请求的 Header 里需带有身份认证信息，TDengine 支持 Basic 认 ...@@ -100,7 +101,7 @@ HTTP 请求的 Header 里需带有身份认证信息，TDengine 支持 Basic 认
Authorization: Basic <TOKEN> Authorization: Basic <TOKEN>
``` ```
HTTP 请求的 BODY 里就是一个完整的 SQL 语句，SQL 语句中的数据表应提供数据库前缀，例如 \<db_name>.\<tb_name>。如果表名不带数据库前缀，又没有在 url 中指定数据库名的话，系统会返回错误。因为 HTTP 模块只是一个简单的转发，没有当前 DB 的概念。 HTTP 请求的 BODY 里就是一个完整的 SQL 语句，SQL 语句中的数据表应提供数据库前缀，例如 db_name.tb_name。如果表名不带数据库前缀，又没有在 URL 中指定数据库名的话，系统会返回错误。因为 HTTP 模块只是一个简单的转发，没有当前 DB 的概念。
使用 `curl` 通过自定义身份认证方式来发起一个 HTTP Request，语法如下： 使用 `curl` 通过自定义身份认证方式来发起一个 HTTP Request，语法如下：
...@@ -236,7 +237,7 @@ curl http://192.168.0.1:6041/rest/login/root/taosdata ...@@ -236,7 +237,7 @@ curl http://192.168.0.1:6041/rest/login/root/taosdata
### 结果集采用 Unix 时间戳 ### 结果集采用 Unix 时间戳
HTTP 请求 URL 采用 `sqlt` 时，返回结果集的时间戳将采用 Unix 时间戳格式表示，例如 HTTP 请求 URL 采用 `/rest/sqlt` 时，返回结果集的时间戳将采用 Unix 时间戳格式表示，例如
```bash ```bash
curl -H 'Authorization: Basic cm9vdDp0YW9zZGF0YQ==' -d 'select * from demo.d1001' 192.168.0.1:6041/rest/sqlt curl -H 'Authorization: Basic cm9vdDp0YW9zZGF0YQ==' -d 'select * from demo.d1001' 192.168.0.1:6041/rest/sqlt
...@@ -264,7 +265,7 @@ curl -H 'Authorization: Basic cm9vdDp0YW9zZGF0YQ==' -d 'select * from demo.d1001 ...@@ -264,7 +265,7 @@ curl -H 'Authorization: Basic cm9vdDp0YW9zZGF0YQ==' -d 'select * from demo.d1001
### 结果集采用 UTC 时间字符串 ### 结果集采用 UTC 时间字符串
HTTP 请求 URL 采用 `sqlutc` 时，返回结果集的时间戳将采用 UTC 时间字符串表示，例如 HTTP 请求 URL 采用 `/rest/sqlutc` 时，返回结果集的时间戳将采用 UTC 时间字符串表示，例如
```bash ```bash
curl -H 'Authorization: Basic cm9vdDp0YW9zZGF0YQ==' -d 'select * from demo.t1' 192.168.0.1:6041/rest/sqlutc curl -H 'Authorization: Basic cm9vdDp0YW9zZGF0YQ==' -d 'select * from demo.t1' 192.168.0.1:6041/rest/sqlutc
...@@ -298,9 +299,9 @@ HTTP 请求 URL 采用 `sqlutc` 时，返回结果集的时间戳将采用 UTC ...@@ -298,9 +299,9 @@ HTTP 请求 URL 采用 `sqlutc` 时，返回结果集的时间戳将采用 UTC
- httpMaxThreads: 启动的线程数量，默认为 2（2.0.17.0 版本开始，默认值改为 CPU 核数的一半向下取整）。 - httpMaxThreads: 启动的线程数量，默认为 2（2.0.17.0 版本开始，默认值改为 CPU 核数的一半向下取整）。
- restfulRowLimit: 返回结果集（JSON 格式）的最大条数，默认值为 10240。 - restfulRowLimit: 返回结果集（JSON 格式）的最大条数，默认值为 10240。
- httpEnableCompress: 是否支持压缩，默认不支持，目前 TDengine 仅支持 gzip 压缩格式。 - httpEnableCompress: 是否支持压缩，默认不支持，目前 TDengine 仅支持 gzip 压缩格式。
- httpDebugFlag: 日志开关，默认 131。131：仅错误和报警信息，135：调试信息，143：非常详细的调试信息，默认 131。 - httpDebugFlag: 日志开关，默认 131。131：仅错误和报警信息，135：调试信息，143：非常详细的调试信息。
- httpDbNameMandatory: 是否必须在 RESTful url 中指定默认的数据库名。默认为 0，即关闭此检查。如果设置为 1，那么每个 RESTful url 中都必须设置一个默认数据库名，否则无论此时执行的 SQL 语句是否需要指定数据库，都会返回一个执行错误，拒绝执行此 SQL 语句。 - httpDbNameMandatory: 是否必须在 RESTful URL 中指定默认的数据库名。默认为 0，即关闭此检查。如果设置为 1，那么每个 RESTful URL 中都必须设置一个默认数据库名，否则无论此时执行的 SQL 语句是否需要指定数据库，都会返回一个执行错误，拒绝执行此 SQL 语句。
:::note :::note
如果使用 taosd 提供的 REST API, 那么以上配置需要写在 taosd 的配置文件 taos.cfg 中。如果使用 taosAdapter 提供的 REST API, 那么需要参考 taosAdapter [对应的配置方法](/reference/taosadapter/)。 如果使用 taosd 提供的 REST API, 那么以上配置需要写在 taosd 的配置文件 taos.cfg 中。如果使用 taosAdapter 提供的 REST API, 那么需要参考 taosAdapter [对应的配置方法](/reference/taosadapter/)。
::: :::
docs-en/14-reference/02-rest-api/02-rest-api.mdx
浏览文件 @ 72f25355
...@@ -4,7 +4,9 @@ title: REST API ...@@ -4,7 +4,9 @@ title: REST API
To support the development of various types of platforms, TDengine provides an API that conforms to the REST principle, namely REST API. To minimize the learning cost, different from the other database REST APIs, TDengine directly requests the SQL command contained in the request BODY through HTTP POST to operate the database and only requires a URL. To support the development of various types of platforms, TDengine provides an API that conforms to the REST principle, namely REST API. To minimize the learning cost, different from the other database REST APIs, TDengine directly requests the SQL command contained in the request BODY through HTTP POST to operate the database and only requires a URL.
Note: One difference from the native connector is that the REST interface is stateless, so the `USE db_name` command has no effect. All references to table names and super table names need to specify the database name prefix. (Since version 2.2.0.0, it is supported to specify db_name in RESTful URL. If the database name prefix is not specified in the SQL command, the `db_name` specified in the URL will be used. Since version 2.4.0.0, REST service is provided by taosAdapter by default. And it requires that the `db_name` must be specified in the URL.) :::note
One difference from the native connector is that the REST interface is stateless, so the `USE db_name` command has no effect. All references to table names and super table names need to specify the database name prefix. (Since version 2.2.0.0, it is supported to specify db_name in RESTful URL. If the database name prefix is not specified in the SQL command, the `db_name` specified in the URL will be used. Since version 2.4.0.0, REST service is provided by taosAdapter by default. And it requires that the `db_name` must be specified in the URL.)
:::
## Installation ## Installation
...@@ -19,8 +21,7 @@ The following is an Ubuntu environment using the `curl` tool (to confirm that it ...@@ -19,8 +21,7 @@ The following is an Ubuntu environment using the `curl` tool (to confirm that it
The following example lists all databases, replacing `h1.taosdata.com` and `6041` (the default port) with the actual running TDengine service FQDN and port number. The following example lists all databases, replacing `h1.taosdata.com` and `6041` (the default port) with the actual running TDengine service FQDN and port number.
```html ```html
curl -H 'Authorization: Basic cm9vdDp0YW9zZGF0YQ==' -d 'show databases;' curl -H 'Authorization: Basic cm9vdDp0YW9zZGF0YQ==' -d 'show databases;' h1.taosdata.com:6041/rest/sql
h1.taosdata.com:6041/rest/sql
``` ```
The following return value results indicate that the verification passed. The following return value results indicate that the verification passed.
...@@ -100,7 +101,7 @@ TDengine supports both Basic authentication and custom authentication mechanisms ...@@ -100,7 +101,7 @@ TDengine supports both Basic authentication and custom authentication mechanisms
Authorization: Basic <TOKEN> Authorization: Basic <TOKEN>
``` ```
The HTTP request's BODY is a complete SQL command, and the data table in the SQL statement should be provided with a database prefix, e.g., `\<db_name>.\<tb_name>`. If the table name does not have a database prefix and the database name is not specified in the URL, the system will response an error because the HTTP module is a simple forwarder and has no awareness of the current DB. The HTTP request's BODY is a complete SQL command, and the data table in the SQL statement should be provided with a database prefix, e.g., `db_name.tb_name`. If the table name does not have a database prefix and the database name is not specified in the URL, the system will response an error because the HTTP module is a simple forwarder and has no awareness of the current DB.
Use `curl` to initiate an HTTP request with a custom authentication method, with the following syntax. Use `curl` to initiate an HTTP request with a custom authentication method, with the following syntax.
...@@ -236,7 +237,7 @@ Response body: ...@@ -236,7 +237,7 @@ Response body:
### Unix timestamps for result sets ### Unix timestamps for result sets
When the HTTP request URL uses `sqlt`, the timestamp of the returned result set will be in Unix timestamp format, for example: When the HTTP request URL uses `/rest/sqlt`, the returned result set's timestamp value will be in Unix timestamp format, for example:
```bash ```bash
curl -H 'Authorization: Basic cm9vdDp0YW9zZGF0YQ==' -d 'select * from demo.d1001' 192.168.0.1:6041/rest/sqlt curl -H 'Authorization: Basic cm9vdDp0YW9zZGF0YQ==' -d 'select * from demo.d1001' 192.168.0.1:6041/rest/sqlt
...@@ -264,7 +265,7 @@ Response body: ...@@ -264,7 +265,7 @@ Response body:
### UTC format for the result set ### UTC format for the result set
When the HTTP request URL uses `sqlutc`, the timestamp of the returned result set will be expressed as a UTC format, for example: When the HTTP request URL uses `/rest/sqlutc`, the timestamp of the returned result set will be expressed as a UTC format, for example:
```bash ```bash
curl -H 'Authorization: Basic cm9vdDp0YW9zZGF0YQ==' -d 'select * from demo.t1' 192.168.0.1:6041/rest/sqlutc curl -H 'Authorization: Basic cm9vdDp0YW9zZGF0YQ==' -d 'select * from demo.t1' 192.168.0.1:6041/rest/sqlutc
...@@ -298,7 +299,7 @@ Only some configuration parameters related to the RESTful interface are listed b ...@@ -298,7 +299,7 @@ Only some configuration parameters related to the RESTful interface are listed b
- httpMaxThreads: the number of threads to start, default is 2 (the default value is rounded down to half of the CPU cores with version 2.0.17.0 and later versions). - httpMaxThreads: the number of threads to start, default is 2 (the default value is rounded down to half of the CPU cores with version 2.0.17.0 and later versions).
- restfulRowLimit: the maximum number of result sets (in JSON format) to return. The default value is 10240. - restfulRowLimit: the maximum number of result sets (in JSON format) to return. The default value is 10240.
- httpEnableCompress: whether to support compression, the default is not supported. Currently, TDengine only supports the gzip compression format. - httpEnableCompress: whether to support compression, the default is not supported. Currently, TDengine only supports the gzip compression format.
- httpDebugFlag: logging switch, default 131. 131: error and alarm messages only, 135: debug messages, 143: very detailed debug messages, default 131. - httpDebugFlag: logging switch, default is 131. 131: error and alarm messages only, 135: debug messages, 143: very detailed debug messages.
- httpDbNameMandatory: users must specify the default database name in the RESTful URL. The default is 0, which turns off this check. If set to 1, users must put a default database name in every RESTful URL. Otherwise, it will return an execution error and reject this SQL statement, regardless of whether the SQL statement executed at this time requires a specified database. - httpDbNameMandatory: users must specify the default database name in the RESTful URL. The default is 0, which turns off this check. If set to 1, users must put a default database name in every RESTful URL. Otherwise, it will return an execution error and reject this SQL statement, regardless of whether the SQL statement executed at this time requires a specified database.
:::note :::note
......
docs-en/14-reference/03-connector/03-connector.mdx
浏览文件 @ 72f25355
...@@ -46,13 +46,13 @@ Comparing the connector support for TDengine functional features as follows. ...@@ -46,13 +46,13 @@ Comparing the connector support for TDengine functional features as follows.
| **Functional Features** | **Java** | **Python** | **Go** | **C#** | **Node.js** | **Rust** | | **Functional Features** | **Java** | **Python** | **Go** | **C#** | **Node.js** | **Rust** |
| -------------- | -------- | ---------- | ------ | ------ | ----------- | -------- | | -------------- | -------- | ---------- | ------ | ------ | ----------- | -------- |
| **Connection Management** | Support | Support | Support | Support | Support | Support | Support | **Connection Management** | Support | Support | Support | Support | Support | Support | Support |
| Support | Support | Support | Support | Support | Support | Support | Support | Support | **Regular Query** | Support | Support | Support | Support | Support | Support | Support | Support |
| Support | Support | Support | Support | Support | Support | Support | Support | Support | **Continous Query** | Support | Support | Support | Support | Support | Support | Support | Support | Support |
| **Parameter Binding** | Support | Support | Support | Support | Support | Support | Support | **Parameter Binding** | Support | Support | Support | Support | Support | Support | Support |
| Support | Support | Support | Support | Support | Support | Support | Not Supported | **Subscription** | Support | Support | Support | Support | Support | Support | Support | Not Supported |
| **Schemaless** | Support | Support | Support | Support | Support | Support | Support | **Schemaless** | Support | Support | Support | Support | Support | Support | Support |
| **DataFrame** | Not Supported | Support | Not Supported | Not Supported | Not Supported | Not Supported | **DataFrame** | Not Supported | Support | Not Supported | Not Supported | Not Supported | Not Supported |
:::info :::info
The different database framework specifications for various programming languages do not mean that all C/C++ interfaces need a wrapper. The different database framework specifications for various programming languages do not mean that all C/C++ interfaces need a wrapper.
...@@ -62,14 +62,14 @@ The different database framework specifications for various programming language ...@@ -62,14 +62,14 @@ The different database framework specifications for various programming language
| **Functional Features** | **Java** | **Python** | **Go** | **C# (not supported yet)** | **Node.js** | **Rust** | | **Functional Features** | **Java** | **Python** | **Go** | **C# (not supported yet)** | **Node.js** | **Rust** |
| ------------------------------ | -------- | ---------- | -------- | ------------------ | ----------- | -------- | | ------------------------------ | -------- | ---------- | -------- | ------------------ | ----------- | -------- |
| **Connection Management** | Support | Support | Support | N/A | Support | Support | Support | **Connection Management** | Support | Support | Support | N/A | Support | Support | Support |
| Support | Support | N/A | Support | Support | Support | **Regular Query** | Support | Support | N/A | Support | Support | Support |
| Support | Support | N/A | Support | Support | Support | **Continous Query ** | Support | Support | N/A | Support | Support | Support |
| Support | N/A | Support | N/A | Support | N/A | **Parameter Binding** | Not Supported | Not Supported | Not Supported | N/A | Not Supported | Not Supported |
| | N/A | Support | N/A | Support | N/A | **Subscription** | Not Supported | Not Supported | Not Supported | N/A | Not Supported | Not Supported |
| **Schemaless** | Not supported | N/A | Not supported | Not supported | N/A | **Schemaless** | Not supported | Not Supported | Not Supported | N/A | Not Supported | Not supported |
| N/A | Not Supported | Not Supported | N/A | **Bulk Pulling (based on WebSocket) **| Support | Not Supported | N/A | Not Supported | Not Supported |
| **DataFrame** | Not supported | Support | Not supported | N/A | Not supported | Not supported | **DataFrame** | Not supported | Support | Not supported | N/A | Not supported | Not supported |
:::warning :::warning
......
Markdown is supported
0% 或 .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑！
想要评论请 注册 或