From 60be6be07f476bf1ceff7b9e0a0842b34b67d759 Mon Sep 17 00:00:00 2001
From: Elias Soong <elias.soong@gmail.com>
Date: Fri, 5 Mar 2021 18:01:39 +0800
Subject: [PATCH] [TD-3158] <docs>: add column_meta in RESTful result.

---
 documentation20/cn/08.connector/docs.md | 36 ++++++++++++++++++-------
 1 file changed, 27 insertions(+), 9 deletions(-)

diff --git a/documentation20/cn/08.connector/docs.md b/documentation20/cn/08.connector/docs.md
index 70403382b7..fb50e20e51 100644
--- a/documentation20/cn/08.connector/docs.md
+++ b/documentation20/cn/08.connector/docs.md
@@ -591,7 +591,8 @@ curl -u username:password -d '<SQL>' <ip>:<PORT>/rest/sql
 ```json
 {
     "status": "succ",
-    "head": ["Time Stamp","current", …],
+    "head": ["ts","current", …],
+    "column_meta": [["ts",9,8],["current",6,4], …],
     "data": [
         ["2018-10-03 14:38:05.000", 10.3, …],
         ["2018-10-03 14:38:15.000", 12.6, …]
@@ -602,10 +603,23 @@ curl -u username:password -d '<SQL>' <ip>:<PORT>/rest/sql
 
 说明：
 
-- status: 告知操作结果是成功还是失败
-- head: 表的定义，如果不返回结果集，仅有一列“affected_rows”
-- data: 具体返回的数据，一排一排的呈现，如果不返回结果集，仅[[affected_rows]]
-- rows: 表明总共多少行数据
+- status: 告知操作结果是成功还是失败。
+- head: 表的定义，如果不返回结果集，则仅有一列“affected_rows”。（从 2.0.17 版本开始，建议不要依赖 head 返回值来判断数据列类型，而推荐使用 column_meta。在未来版本中，有可能会从返回值中去掉 head 这一项。）
+- column_meta: 从 2.0.17 版本开始，返回值中增加这一项来说明 data 里每一列的数据类型。具体每个列会用三个值来说明，分别为：列名、列类型、类型长度。例如`["current",6,4]`表示列名为“current”；列类型为 6，也即 float 类型；类型长度为 4，也即对应 4 个字节表示的 float。如果列类型为 binary 或 nchar，则类型长度表示该列最多可以保存的内容长度，而不是本次返回值中的具体数据长度。当列类型是 nchar 的时候，其类型长度表示可以保存的 unicode 字符数量，而不是 bytes。
+- data: 具体返回的数据，一行一行的呈现，如果不返回结果集，那么就仅有[[affected_rows]]。data 中每一行的数据列顺序，与 column_meta 中描述数据列的顺序完全一致。
+- rows: 表明总共多少行数据。
+
+column_meta 中的列类型说明：
+* 1：BOOL
+* 2：TINYINT
+* 3：SMALLINT
+* 4：INT
+* 5：BIGINT
+* 6：FLOAT
+* 7：DOUBLE
+* 8：BINARY
+* 9：TIMESTAMP
+* 10：NCHAR
 
 ### 自定义授权码
 
@@ -651,7 +665,8 @@ curl -H 'Authorization: Basic cm9vdDp0YW9zZGF0YQ==' -d 'select * from demo.d1001
 ```json
 {
     "status": "succ",
-    "head": ["Time Stamp","current","voltage","phase"],
+    "head": ["ts","current","voltage","phase"],
+    "column_meta": [["ts",9,8],["current",6,4],["voltage",4,4],["phase",6,4]],
     "data": [
         ["2018-10-03 14:38:05.000",10.3,219,0.31],
         ["2018-10-03 14:38:15.000",12.6,218,0.33]
@@ -671,8 +686,9 @@ curl -H 'Authorization: Basic cm9vdDp0YW9zZGF0YQ==' -d 'create database demo' 19
 {
     "status": "succ",
     "head": ["affected_rows"],
+    "column_meta": [["affected_rows",4,4]],
     "data": [[1]],
-    "rows": 1,
+    "rows": 1
 }
 ```
 
@@ -691,7 +707,8 @@ curl -H 'Authorization: Basic cm9vdDp0YW9zZGF0YQ==' -d 'select * from demo.d1001
 ```json
 {
     "status": "succ",
-    "head": ["column1","column2","column3"],
+    "head": ["ts","current","voltage","phase"],
+    "column_meta": [["ts",9,8],["current",6,4],["voltage",4,4],["phase",6,4]],
     "data": [
         [1538548685000,10.3,219,0.31],
         [1538548695000,12.6,218,0.33]
@@ -712,7 +729,8 @@ HTTP请求URL采用`sqlutc`时，返回结果集的时间戳将采用UTC时间
 ```json
 {
     "status": "succ",
-    "head": ["column1","column2","column3"],
+    "head": ["ts","current","voltage","phase"],
+    "column_meta": [["ts",9,8],["current",6,4],["voltage",4,4],["phase",6,4]],
     "data": [
         ["2018-10-03T14:38:05.000+0800",10.3,219,0.31],
         ["2018-10-03T14:38:15.000+0800",12.6,218,0.33]
-- 
GitLab