@clickzetta/cz-cli-darwin-x64 0.3.1

package/bin/skills/lakehouse-doc/references/JSON.md

@@ -0,0 +1,423 @@
+# JSON数据格式简介
+
+JSON（JavaScript Object Notation）是一种轻量级、易于阅读和编写的半结构化数据格式。它基于JavaScript的一个子集，但是JSON是独立于语言的，许多编程语言都有JSON数据格式的解析和生成代码。JSON格式使用文本表示简单的数据结构，如对象、数组、字符串、数字和布尔值。JSON格式具有良好的可读性和简洁性，使其成为理想的数据交换格式。
+
+# LakeHouse中的JSON类型
+
+在LakeHouse中，JSON类型的数据可以高效地存储和查询。JSON数据在LakeHouse中会被解析，并根据数据的实际结构进行优化存储。以下是LakeHouse中JSON类型的一些特点：
+
+1. 查询性能：使用JSON类型相比于String类型在查询性能上有明显优势，因为LakeHouse会对JSON数据进行列裁剪，减少不必要的数据扫描。
+2. 数据重排：解析过程中，JSON对象的数据可能会被重新排序，因此输入和输出的JSON数据可能在键的顺序上不一致。
+3. 数字解析：解析JSON数字时，LakeHouse会优先尝试将其解析为bigint类型。如果数字超出bigint的范围，则会将其解析为double类型。需要注意的是，double类型可能会有精度损失。
+4. 错误处理：使用函数解析JSON数据时，LakeHouse会进行校验。对于非法的JSON字符串，会返回NULL值；而在声明JSON常量时，非法的JSON字符串会导致错误。
+
+此外，LakeHouse在写入过程中会根据实际的JSON Schema，将出现频次高的字段按照列存储的方式存储，以提高存储和查询效率。例如：
+
+```SQL
+CREATE TABLE json_table AS
+SELECT  parse_json(s) as j
+FROM VALUES
+('{"id": 1, "value": "200"}'),
+('{"id": 2, "value": "300"}'),
+('{"id": 3, "value": "400", "extra": 1}'),
+('{"value": "100"}') as t(s);
+```
+
+1. 对于上面的数据，LakeHouse 检测出 id 和 value 出现频次高，分别适合用 bigint 和 string 类型列式存储，则会在内部以类似 struct\<id:bigint, value:string> 的结构存储。在后续的查询过程中，如果只读取id字段且转换为bigint，如`SELECT json_extract_bigint(j, '$.id')`，则可以直接按列读取 id 字段，并消除类型转换的开销。
+2. 对于出现频次低的 extra 字段，则保留 json 结构且用更加紧凑的表示存储，避免产生过于稀疏的数据。
+
+**限制**
+
+* 不支持对JSON类型的比较操作，也不支持对JSON类型进行`ORDER BY`、`GROUP BY`或作为`JOIN`的key等。
+* 不支持作为cluster key、primary key、partition key
+* JSON字符串最大长度为16 MB。批量、实时导入时对字段进行长度校验。如果您导入数据时有大于16MB的数据您可以修改表的Properties来修改如下将json长度设置为32MB
+```
+ALTER TABLE table_name SET PROPERTIES("cz.storage.write.max.json.bytes"="33554432");
+```
+
+
+## 创建JSON列的表
+
+要创建包含JSON类型列的表，可以使用以下SQL语句：
+
+```sql
+CREATE TABLE json_example
+(
+    id bigint,
+    data json
+);
+```
+
+## 构建JSON数据
+
+### JSON常量
+
+在SQL查询中，可以使用JSON常量来表示JSON数据。例如：
+
+```sql
+SELECT
+JSON 'null',
+JSON '1',
+JSON '3.14',
+JSON 'true',
+JSON 'false',
+JSON '{"id":11,"name":"Lakehouse"}',
+JSON '[0, 1]';
+
+-- !query output
++-------------+----------+-------------+-------------+--------------+-------------------------------------+---------------+
+| JSON 'null' | JSON '1' | JSON '3.14' | JSON 'true' | JSON 'false' | JSON '{"id":11,"name":"Lakehouse"}' | JSON '[0, 1]' |
++-------------+----------+-------------+-------------+--------------+-------------------------------------+---------------+
+| null        | 1        | 3.14        | true        | false        | {"id":11,"name":"Lakehouse"}        | [0,1]         |
++-------------+----------+-------------+-------------+--------------+-------------------------------------+---------------+
+```
+
+
+### 语法
+
+```SQL
+--键名访问JSON对象中的字段
+json_column['key']['key']...
+--通过索引访问JSON数组中的元素
+json_array[index]
+```
+
+**参数说明**
+
+* json\_column:表示一个JSON字段，类型为JSON对象。通过键名（`key`），指定为字符串，来定位并检索JSON对象内的特定数据字段。使用单个方括号`[]`可以访问对象的一级字段；而嵌套使用双方括号`[][]`则能够深入检索对象的二级或更深层次的字段。
+* json\_array:数组类型的JSON，用来根据index访问 JSON array的元素，起始值为0
+
+#### 案例
+
+取出json一级结构
+
+```SQL
+SELECT parse_json(s)['firstName'] as j
+      FROM VALUES ('{ "firstName": "John", "lastName": "doe", "age": 26, "address": { "streetAddress": "naist street", "city": "Nara", "postalCode": "630-0192" }, "phoneNumbers": [ { "type": "iPhone", "number": "0123-4567-8888" }, { "type": "home", "number": "0123-4567-8910", "extra": [] } ] }'),
+                  ('{ "firstName": "Ada", "lastName": "doe", "age": 20, "address": { "streetAddress": "naist street", "city": "Nara", "postalCode": "630-0192" }, "address2": {"city": "NewYork"}, "phoneNumbers": [ { "type": "iPhone", "number": "0123-4567-8888" }, { "type": "home", "number": "0123-4567-8910", "extra": [1,2,3] } ] }')
+                 as t(s);
+```
+
+取出json二级结构
+
+```SQL
+SELECT parse_json(s)['address']['streetAddress'] as j
+      FROM VALUES ('{ "firstName": "John", "lastName": "doe", "age": 26, "address": { "streetAddress": "naist street", "city": "Nara", "postalCode": "630-0192" }, "phoneNumbers": [ { "type": "iPhone", "number": "0123-4567-8888" }, { "type": "home", "number": "0123-4567-8910", "extra": [] } ] }'),
+                  ('{ "firstName": "Ada", "lastName": "doe", "age": 20, "address": { "streetAddress": "naist street", "city": "Nara", "postalCode": "630-0192" }, "address2": {"city": "NewYork"}, "phoneNumbers": [ { "type": "iPhone", "number": "0123-4567-8888" }, { "type": "home", "number": "0123-4567-8910", "extra": [1,2,3] } ] }')
+                 as t(s);
+```
+
+取出json数组中的元素
+
+```SQL
+SELECT parse_json(s)['phoneNumbers'][0]['number'] as j
+      FROM VALUES ('{ "firstName": "John", "lastName": "doe", "age": 26, "address": { "streetAddress": "naist street", "city": "Nara", "postalCode": "630-0192" }, "phoneNumbers": [ { "type": "iPhone", "number": "0123-4567-8888" }, { "type": "home", "number": "0123-4567-8910", "extra": [] } ] }'),
+                  ('{ "firstName": "Ada", "lastName": "doe", "age": 20, "address": { "streetAddress": "naist street", "city": "Nara", "postalCode": "630-0192" }, "address2": {"city": "NewYork"}, "phoneNumbers": [ { "type": "iPhone", "number": "0123-4567-8888" }, { "type": "home", "number": "0123-4567-8910", "extra": [1,2,3] } ] }')
+                 as t(s);
+```
+
+
+
+### 使用函数
+
+### 使用函数(将STRING格式的JSON转化为字符串)
+
+`parse_json`函数可以将String类型的JSON字符串解析为JSON类型。例如：
+
+```SQL
+SELECT parse_json(s) is null, parse_json(s)
+FROM VALUES ('null'),
+            ('1'),
+            ('3.14'),
+            ('true'),
+            ('false'),
+            ('{"id":11,"name":"Lakehouse"}'),
+            ('[0, 1]'),
+            (''),
+            ('invalid') as t(s);
++-------------------------+------------------------------+
+| (parse_json(s)) IS NULL |        parse_json(s)         |
++-------------------------+------------------------------+
+| false                   | null                         |
+| false                   | 1                            |
+| false                   | 3.14                         |
+| false                   | true                         |
+| false                   | false                        |
+| false                   | {"id":11,"name":"Lakehouse"} |
+| false                   | [0,1]                        |
+| true                    | null                         |
+| true                    | null                         |
++-------------------------+------------------------------+
+```
+
+* 如果parse_json的参数为非法json字符串，则返回SQL null，is null的结果为true
+* 如果输入字符串为`'null'`，则它会被解释为JSON null值，is null的结果为false
+
+### json_array/json_object
+
+类似array/named\_struct，可以根据已有的数据构造出对应的json类型
+
+```SQL
+SELECT json_array(), json_array(NULL),json_array(NULL::int, 1, TRUE, FALSE, NULL::int, "a", 1.2, 1.3d);
++----------------+--------------------+--------------------------------------------------------------------------------------+
+| `json_array`() | `json_array`(NULL) | `json_array`(CAST(NULL AS int), 1, true, false, CAST(NULL AS int), 'a', 1.2BD, 1.3d) |
++----------------+--------------------+--------------------------------------------------------------------------------------+
+| []             | [null]             | [null,1,true,false,null,"a","1.2",1.3]                                               |
++----------------+--------------------+--------------------------------------------------------------------------------------+
+
+SELECT json_object(), json_object('k', NULL), json_object('k1', json_array(1, "a"), "k2", array(1, 2, 3));
+-- !query output
++-----------------+--------------------------+-------------------------------------------------------------------+
+| `json_object`() | `json_object`('k', NULL) | `json_object`('k1', `json_array`(1, 'a'), 'k2', `array`(1, 2, 3)) |
++-----------------+--------------------------+-------------------------------------------------------------------+
+| {}              | {"k":null}               | {"k1":[1,"a"],"k2":[1,2,3]}                                       |
++-----------------+--------------------------+-------------------------------------------------------------------+
+```
+
+## 类型转换
+
+在LakeHouse中，可以使用`::json`或`CAST`函数将其他类型转换为JSON类型。以下是一些类型转换的例子：
+| Json       | SQL           |
+| ---------- | ------------- |
+| Object     | Struct        |
+| Array      | Array         |
+| String     | string        |
+| Number     | bigint/double |
+| true/false | bool          |
+| Null       | 无对应类型         |
+| 无对应类型      | binary        |
+
+* 不存在于表格中的类型转换，会先将其转换为可以转换的类型（大多数情况为string类型），再转换为目标类型，例如cast(1.2 as json) 1.2为decimal类型，会先转换为string类型，进一步转换为json类型，结果是JSON '"1.2"'，而不是JSON '1.2'。
+* 需要注意的是cast(string as json)的语义和parse\_json(string)的语义并不一致,parse\_json 会尝试将 JSON 字符串解析成 JSON 对象，如果JSON格式不正确，则会生成 NULL而cast(string to json)**会将字符串整体当做JSON中的string类型,所以如果您是一个json格式字符串转化时应该使用parse_json**
+具体案例
+
+```SQL
+-- xx::json 等价于 cast(xxx as json)
+
+SELECT 0::json;
+-- !query output
++-----------------+
+| CAST(0 AS json) |
++-----------------+
+| 0               |
++-----------------+
+
+SELECT 1.2F::json;
+-- !query output
++--------------------+
+| CAST(1.2F AS json) |
++--------------------+
+| 1.2000000476837158 |
++--------------------+
+
+SELECT 1.2::json;
+-- !query output
++---------------------+
+| CAST(1.2BD AS json) |
++---------------------+
+| "1.2"               |
++---------------------+
+
+SELECT 's'::json;
++-------------------+
+| CAST('s' AS json) |
++-------------------+
+| "s"               |
++-------------------+
+
+SELECT (timestamp '2020-10-10 00:00:00') ::json;
++----------------------------------------------+
+| CAST(timestamp'2020-10-10 00:00:00' AS json) |
++----------------------------------------------+
+| "2020-10-10 00:00:00"                        |
++----------------------------------------------+
+
+SELECT (date '2020-10-10') ::json;
++---------------------------------+
+| CAST(DATE '2020-10-10' AS json) |
++---------------------------------+
+| "2020-10-10"                    |
++---------------------------------+
+
+SELECT array(1, 2, 3) ::json;
++--------------------------------+
+| CAST(`array`(1, 2, 3) AS json) |
++--------------------------------+
+| [1,2,3]                        |
++--------------------------------+
+
+SELECT array(1, null, 3) ::json;
++-----------------------------------+
+| CAST(`array`(1, NULL, 3) AS json) |
++-----------------------------------+
+| [1,null,3]                        |
++-----------------------------------+
+
+SELECT map("a", 2, "b", 4)::json, map("a", 2, "b", null) ::json;
++-----------------------------------+--------------------------------------+
+| CAST(map('a', 2, 'b', 4) AS json) | CAST(map('a', 2, 'b', NULL) AS json) |
++-----------------------------------+--------------------------------------+
+| {"a":2,"b":4}                     | {"a":2,"b":null}                     |
++-----------------------------------+--------------------------------------+
+
+SELECT struct(1, 2, 3, 4)::json, struct(1, 2, 3, null::int) ::json;
++---------------------------------------+--------------------------------------------------+
+|   CAST(struct(1, 2, 3, 4) AS json)    | CAST(struct(1, 2, 3, CAST(NULL AS int)) AS json) |
++---------------------------------------+--------------------------------------------------+
+| {"col1":1,"col2":2,"col3":3,"col4":4} | {"col1":1,"col2":2,"col3":3,"col4":null}         |
++---------------------------------------+--------------------------------------------------+
+SELECT null::json;
++--------------------+
+| CAST(NULL AS json) |
++--------------------+
+| null               |
++--------------------+
+
+SELECT j::string, j::char(2), j::bigint, j::double, j::decimal(9, 4), j::boolean, j::json, j::array<int>
+from values (json '123'),
+            (json '1.23'),
+            (json 'null'),
+            (json 'true'),
+            (json 'false'),
+            (json '"abc"'),
+            (json '{"a":2}'),
+            (json '[1,2]') t(j);
+-- !query output
++-------------------+--------------------+-------------------+-------------------+-------------------------+--------------------+-----------------+-----------------------+
+| CAST(j AS string) | CAST(j AS char(2)) | CAST(j AS bigint) | CAST(j AS double) | CAST(j AS decimal(9,4)) | CAST(j AS boolean) | CAST(j AS json) | CAST(j AS array<int>) |
++-------------------+--------------------+-------------------+-------------------+-------------------------+--------------------+-----------------+-----------------------+
+| 123               | 12                 | 123               | 123.0             | 123.0000                | true               | 123             | null                  |
+| 1.23              | 1.                 | 1                 | 1.23              | 1.2300                  | true               | 1.23            | null                  |
+| null              | null               | null              | null              | null                    | null               | null            | null                  |
+| true              | tr                 | 1                 | 1.0               | 1.0000                  | true               | true            | null                  |
+| false             | fa                 | 0                 | 0.0               | 0.0000                  | false              | false           | null                  |
+| abc               | ab                 | null              | null              | null                    | null               | "abc"           | null                  |
+| {"a":2}           | {"                 | null              | null              | null                    | null               | {"a":2}         | null                  |
+| [1,2]             | [1                 | null              | null              | null                    | null               | [1,2]           | [1,2]                 |
++-------------------+--------------------+-------------------+-------------------+-------------------------+--------------------+-----------------+-----------------------+
+```
+
+需要注意的是，`cast(string as json)`和`parse_json(string)`的语义并不一致。`parse_json`会尝试将JSON字符串解析成JSON对象，如果JSON格式不正确，则会生成NULL；而`cast(string to json)`会将字符串整体当做JSON中的string类型。
+
+```SQL
+SELECT parse_json(s), s::json, s::json::string
+FROM VALUES ('{"id":11, "name": "Lakehouse"}') as t(s);
++------------------------------+----------------------------------------+---------------------------------+
+|        parse_json(s)         |            CAST(s AS json)             | CAST(CAST(s AS json) AS string) |
++------------------------------+----------------------------------------+---------------------------------+
+| {"id":11,"name":"Lakehouse"} | "{\"id\":11, \"name\": \"Lakehouse\"}" | {"id":11, "name": "Lakehouse"}  |
++------------------------------+----------------------------------------+---------------------------------+
+```
+
+# 使用SDK（igs/bulkload）写入JSON
+
+Lakehouse 支持给 JSON 类型的列写入 String 类型的字符串，系统在导入的时候会自动将字符串解析成 JSON 类型，如果用户输入了不符合 JSON 规范或者 CZ 不支持的 JSON 字符串，系统会报错并停止导入。
+
+# 导出JSON数据
+
+Lakehouse 支持以字符串的形式导出 JSON 数据。
+
+# 查询JSON数据
+
+查询JSON数据需要使用`json_extract`系列函数，通过JSON path获取需要的数据。以下是一些查询JSON数据的例子：
+
+* json\_extract
+* json\_extract\_boolean
+* json\_extract\_float
+* json\_extract\_double
+* json\_extract\_int
+* json\_extract\_bigint
+* json\_extract\_string
+* json\_extract\_date
+* json\_extract\_timestamp
+
+### json path规范
+
+json\_extract的第二个参数为json path，可以参考[json path规范](<https://goessner.net/articles/JsonPath/>)
+
+* "$"表示根元素
+* ".key"或者"\['key']" 用来查找json object中的key。特殊的，"\[\*]"表示获取所有的value,要求必须是单引号
+* "\[index]" 用来根据index访问 json array的元素，起始值为0。特殊的，"\[\*]"表示所有的元素
+
+```SQL
+SELECT json_extract(j, "$[0]"),
+       json_extract(j, "$[1]"),
+       json_extract(j, "$[*]")
+FROM VALUES (JSON '["a", 1, null]') as t(j);
++-------------------------+-------------------------+-------------------------+
+| json_extract(j, '$[0]') | json_extract(j, '$[1]') | json_extract(j, '$[*]') |
++-------------------------+-------------------------+-------------------------+
+| "a"                     | 1                       | ["a",1,null]            |
++-------------------------+-------------------------+-------------------------+
+
+
+SELECT json_extract(j, "$.key"),
+       json_extract(j, "$['key.with.dot']"),
+       json_extract(j, "$[*]")
+FROM VALUES (JSON '{"key":1, "key.with.dot":2}') as t(j);
++--------------------------+----------------------------------------+-------------------------+
+| json_extract(j, '$.key') | json_extract(j, '$[\'key.with.dot\']') | json_extract(j, '$[*]') |
++--------------------------+----------------------------------------+-------------------------+
+| 1                        | 2                                      | [1,2]                   |
++--------------------------+----------------------------------------+-------------------------+
+
+SELECT json_extract(j, '$.*.city'),
+       json_extract(j, '$.phoneNumbers[*]'),
+       json_extract(j, '$.phoneNumbers[*].extra'),
+       json_extract(j, '$.phoneNumbers[*].extra[*]'),
+       json_extract(j, '$.*[*].extra[*]')
+FROM (SELECT parse_json(s) as j
+      FROM VALUES ('{ "firstName": "John", "lastName": "doe", "age": 26, "address": { "streetAddress": "naist street", "city": "Nara", "postalCode": "630-0192" }, "phoneNumbers": [ { "type": "iPhone", "number": "0123-4567-8888" }, { "type": "home", "number": "0123-4567-8910", "extra": [] } ] }'),
+                  ('{ "firstName": "Ada", "lastName": "doe", "age": 20, "address": { "streetAddress": "naist street", "city": "Nara", "postalCode": "630-0192" }, "address2": {"city": "NewYork"}, "phoneNumbers": [ { "type": "iPhone", "number": "0123-4567-8888" }, { "type": "home", "number": "0123-4567-8910", "extra": [1,2,3] } ] }'),
+                  ('{} ') as t(s));
++-----------------------------+---------------------------------------------------------------------------------------------------------+--------------------------------------------+-----------------------------------------------+------------------------------------+
+| json_extract(j, '$.*.city') |                                  json_extract(j, '$.phoneNumbers[*]')                                   | json_extract(j, '$.phoneNumbers[*].extra') | json_extract(j, '$.phoneNumbers[*].extra[*]') | json_extract(j, '$.*[*].extra[*]') |
++-----------------------------+---------------------------------------------------------------------------------------------------------+--------------------------------------------+-----------------------------------------------+------------------------------------+
+| ["Nara"]                    | [{"number":"0123-4567-8888","type":"iPhone"},{"extra":[],"number":"0123-4567-8910","type":"home"}]      | [[]]                                       | null                                          | null                               |
+| ["Nara","NewYork"]          | [{"number":"0123-4567-8888","type":"iPhone"},{"extra":[1,2,3],"number":"0123-4567-8910","type":"home"}] | [[1,2,3]]                                  | [1,2,3]                                       | [1,2,3]                            |
+| null                        | null                                                                                                    | null                                       | null                                          | null                               |
++-----------------------------+---------------------------------------------------------------------------------------------------------+--------------------------------------------+-----------------------------------------------+------------------------------------+
+```
+
+# 其他JSON函数
+
+json\_valid用来验证一个string类型的数据是否可以转换为json类型
+
+```SQL
+SELECT json_valid('hello'),
+       json_valid('"hello"'),
+       json_valid('null'),
+       json_valid('{}'),
+       json_valid('[]'),
+       json_valid('{"a": "b"}'),
+       json_valid('[1, "a"]');
++---------------------+-----------------------+--------------------+------------------+------------------+--------------------------+------------------------+
+| json_valid('hello') | json_valid('"hello"') | json_valid('null') | json_valid('{}') | json_valid('[]') | json_valid('{"a": "b"}') | json_valid('[1, "a"]') |
++---------------------+-----------------------+--------------------+------------------+------------------+--------------------------+------------------------+
+| false               | true                  | true               | true             | true             | true                     | true                   |
++---------------------+-----------------------+--------------------+------------------+------------------+--------------------------+------------------------+
+```
+
+# 性能对比
+
+构造的数据为1000多万条这样格式`{"address":"89695 Lind Common, Kellymouth, AK 61747","email":"``danita.weber@gmail.com``","name":"Golda Shields"}`，使用where进行过滤查询
+
+使用string查询，执行时间为20.4s。
+
+```SQL
+create table bulkload_data_string(data string);
+select get_json_object(data,'$.email') from bulkload_data_string where get_json_object(data,'$.email')='danita.weber@gmail.com'
+;
+```
+
+![](.topwrite/assets/image_1712910635623.png)
+
+使用json存储数据执行时间为531ms,因为读取的时候进行列裁剪数据大小也会减少,如下图只需要读取153MB数据，string类型需要全量读取454MB数据
+
+```SQL
+create table bulkload_data(json string);
+select json_extract_string(data,'$.name') from bulkload_data where json_extract_string(data,'$.email')='danita.weber@gmail.com'
+;
+```
+
+![](.topwrite/assets/image_1712910703239.png)

package/bin/skills/lakehouse-doc/references/JSON_DataType.md

@@ -0,0 +1,49 @@
+# JSON 数据处理
+
+## 创建schema\table
+
+```
+CREATE SCHEMA IF NOT EXISTS clickzetta_demo_json_schema;
+use schema clickzetta_demo_json_schema;
+create table if not exists clickzetta_demo_json_schema.user_infor(info json);
+insert into table  clickzetta_demo_json_schema.user_infor values
+  (JSON '{"name": "张三","age": 25,"gender": "男","email": "zhangsan@example.com","phone": "13812xxx","address": "北京市朝阳区"}'),
+  (JSON '{"name": "李四","age": 23, "gender": "女","email": "lisi@example.com","phone": "139876xxx1","address": "上海市浦东新区"}'),
+  (JSON '{"name": "王五", "age": 27,"gender": "男","email": "wangwu@example.com","phone": "1376xxxxx8","address": "广州市天河区"}'),
+  (JSON '{"name": "赵六","age": 24,"gender": "女","email": "zhaoliu@example.com","phone": "1369xxxx2","address": "深圳市南山区"}'),
+  (JSON '{"name": "孙七","age": 26, "gender": "男","email": "sunqi@example.com","phone": "1351xxxx679","address": "杭州市西湖区"}'),
+  (JSON '{"name": "周八","age": 22,"gender": "女","email": "zhouba@example.com","phone": "1347xxxx19","address": "南京市鼓楼区"}'),
+  (JSON '{"name": "吴九","age": 28,"gender": "男","email": "wujiu@example.com","phone": "13345xxxx01","address": "成都市武侯区"}'),
+  (JSON '{"name": "郑十","age": 21,"gender": "女","email": "zhengshi@example.com","phone": "1326xxx123","address": "重庆市渝北区"}'),
+  (JSON '{"name": "陈十一","age": 29,"gender": "男","email": "chenshiyi@example.com","phone": "131xxxx789","address": "西安市碑林区"}'),
+  (JSON '{"name": "林十二", "age": 20,"gender": "女","email": "linshier@example.com","phone": "130xxxx5432","address": "厦门市思明区"}');
+```
+
+## 使用json\_extract解析数据
+
+```
+select json_extract_string(info,"$.address") as address,
+      json_extract_int(info,"$.age") as age,
+      json_extract_string(info,"$.email") as email
+from clickzetta_demo_json_schema.user_infor;
+```
+
+![](.topwrite/assets/image_1718703925062.png)
+
+## 清理
+
+```
+drop schema if exists clickzetta_demo_json_schema;
+```
+
+## Congratulations, it's done.
+
+Please enojoy and learn more!
+
+## 附录
+
+### 下载Zeppelin Notebook源文件
+
+本文代码也提供运行在[Zeppelin](eco_integration/Zeppelin.md)的版本，你如果想直接运行本文代码，请按照文档说明安装[Zeppelin](eco_integration/Zeppelin.md)。
+
+[03.JSON数据处理.ipynb](https://github.com/yunqiqiliang/clickzetta_quickstart/blob/main/zeppelin_notebook/03.JSON%E6%95%B0%E6%8D%AE%E5%A4%84%E7%90%86.ipynb)

package/bin/skills/lakehouse-doc/references/KAFKA_Storage_connection.md

@@ -0,0 +1 @@
+^

package/bin/skills/lakehouse-doc/references/Kafka_connection.md

@@ -0,0 +1,36 @@
+## 功能概述
+
+> **【预览发布】** 本功能当前处于公开预览阶段。
+
+本文主要介绍如何在 SQL 中创建与 Kafka 消息队列系统连接的外部表。通过定义外部表，可以方便地从 Kafka 中读取数据流，并将这些数据作为表进行查询和分析。
+
+## 创建存储连接
+
+首先，需要创建一个存储连接，用于连接到 Kafka 服务器。目前不支持需要客户端证书的连接方式。
+
+### 语法
+
+```SQL
+CREATE STORAGE CONNECTION connection_name
+    TYPE kafka
+    BOOTSTRAP_SERVERS = ['server1:port1', 'server2:port2', ...]
+    SECURITY_PROTOCOL = 'PLAINTEXT';
+```
+
+### 参数说明
+
+* **connection_name**: 连接的名称，用于后续引用。
+* **TYPE**: 连接类型，此处为 `kafka`。
+* **BOOTSTRAP_SERVERS**: Kafka 集群的地址列表，格式为 `['host1:port1', 'host2:port2', ...]`。
+* **SECURITY_PROTOCOL**: 安全协议，可以是 `PLAINTEXT` 等。
+
+### 示例
+
+```SQL
+CREATE STORAGE CONNECTION test_kafka_conn
+    TYPE kafka
+    BOOTSTRAP_SERVERS = ['47.99.48.62:9092']
+    SECURITY_PROTOCOL = 'PLAINTEXT';
+```
+
+^

package/bin/skills/lakehouse-doc/references/Key_Concepts.md

@@ -0,0 +1,112 @@
+# 云器 Lakehouse 基本概念
+
+欢迎使用云器 Lakehouse！本章节将为您详细介绍云器 Lakehouse 中的基本概念，帮助您更好地理解和使用本产品。
+
+## 账户（Account）
+
+云器的账户代表与云器公司建立商业关系的组织或个人（一般为企业账户），涵盖账户注册、服务开通等行为。账户是您使用云器产品服务、付费、获取服务支持的基本实体对象。注册时，系统会自动生成全局唯一的账户名，作为您在云器产品中的唯一标识。
+
+* 账户负责充值、出账单、费用支付以及订购/变更云器产品；
+* 所有企业或个人在云器产品上开通的服务实例及其资源对象都归属于特定账户。
+
+## 账户 URL
+
+每个账户都有一个唯一的账户 URL，用于访问管理中心。您需要使用该账户下的有效用户名和密码登录。账户 URL 的格式为：`<account_name>.accounts.clickzetta.com`。例如，以下链接中的 `0256c297` 即为账户名称：`0267c297.accounts.clickzetta.com`。
+
+## 用户（User）
+
+在账户注册成功后，您可以创建多个用户共同使用同一个账户内的资源。不同用户间可以通过权限控制分配可使用的数据和资源。
+
+## 服务实例（Lakehouse Instance）
+
+Lakehouse 服务实例是云器 Lakehouse 产品服务的载体。开通 Lakehouse 服务时，您需要根据指定的云服务商和地域，在您的账户下创建生成服务实例。一个账户下可以创建一个或多个服务实例（当前阶段默认开放单个服务实例的创建）。
+
+服务实例内采用统一元数据管理数据对象、计算资源、作业任务，并在统一权限体系下使用数据集成、开发调度、运维监控、数据目录等工具进行应用构建和数据管理。服务实例具备区域属性，其计算、数据和其他服务资源均在此云服务商的区域内。不同服务实例间默认相互隔离。
+
+![示意图](![](.topwrite/assets/Lakehouse服务实例.png =640))
+
+## 工作空间（Workspace）
+
+工作空间是用于组织 Lakehouse 资源对象（数据对象、计算资源、用户等），并提供配套的数据开发能力（数据集成、数据开发、数据运维）的逻辑对象。您可以在一个服务实例下创建多个工作空间。工作空间之间默认隔离，用户需加入工作空间，才可使用工作空间内的对象。通过跨工作空间授权的方式，实现同一实例下不同工作空间内对象的共享。如何管理和使用工作空间，可以参考[此文档](worksapce-manage.md)。
+
+## 计算资源（Virtual Cluster）
+
+计算资源由多实例虚拟计算集群和运行在集群中的计算服务构成，为您的作业提供计算环境，包括 CPU、内存以及临时存储。详见[此文档](virtual-cluster.md)。
+
+## 数据源（Data Source）
+
+数据源保存了数据存储的链接串信息，例如数据库的地址、访问用户名、密码等。数据源可用于配置数据同步任务或进行数据分析时引用、消费数据。详见[此文档](config-datasource.md)。
+
+## Schema
+
+在工作空间内，Schema 是一组数据库对象的命名空间，包括表、视图等。您可以在一个工作空间内包含多个命名各异的 Schema 对象。
+
+## 表（Table）
+
+表是格式化的二维数据表格。
+
+## 视图（View）
+
+视图是一种虚拟存在的表，不在数据库中实际存在。在使用时，视图会动态生成。
+
+## 物化视图（Materialized View）
+
+物化视图是一种特殊的视图，与普通视图不同，物化视图在数据库中实际存在，并占用存储资源。详见[此文档](materialized_ddl.md)。
+
+## Lakehouse Studio
+
+Lakehouse Studio 是一个以 Web 方式提供的集成开发和管理工具集合，也是 Lakehouse 原生提供的图形化操作界面，旨在为用户提供丰富的一站式功能和直观便捷的操作体验。通过浏览器登录并进入 Lakehouse Studio 后，可以在界面上轻松地操作和使用各项产品功能，比如上传/导入或同步数据、开发 SQL 任务、调度运行、配置监控告警、进行运维操作、管理用户和权限等。相较于通过 JDBC 协议连接或使用 CLI 命令行工具访问，Lakehouse Studio 可以提供更为丰富的原生功能，并且更加方便易用。详见[此文档](studio_manual.md)。
+
+## 任务开发
+
+任务开发是一站式的集成大数据开发环境。您可以在此进行任务开发、调试运行、配置调度以及提交发布等操作，完成整个大数据汇聚、加工、处理、分析的关键流程。在左侧导航菜单中，点击“开发”后可以进入 Web IDE 的主界面。详见[此文档](task_development.md)。
+
+## 任务组
+
+任务组是开发板块内用于管理一组任务的虚拟业务管理组。您可以使用任务组对一系列任务进行组织编排，包括添加/创建任务节点、创建任务节点之间的依赖关系，配置任务组参数、统一批量提交的操作。详见[此文档](task_group.md)。
+
+## 运维中心
+
+运维中心提供对任务和实例的运维管理操作。它集中管理手动触发执行的任务、周期调度的任务及其对应的实例。详见[此文档](task-instance-maintenance.md)。
+
+## 数据目录
+
+数据目录是连接数据提供者和数据消费者的桥梁。它基于表的元数据信息构建，并提供全局检索和过滤功能，便于快速查找表和查看详情，为数据消费提供协助。详见[此文档](data_catalog.md)。
+
+## 工作流（Workflow）
+
+工作流是由一个或多个通过依赖关系连接的任务组成的数据加工作业流。工作流指定了任务的运行环境和资源。作业可以按需执行、周期性执行或被事件触发执行。
+
+## 工作流实例（Workflow Instance）
+
+当工作流任务被触发执行时，会生成工作流实例。工作流实例包含实例化的时间戳和任务状态，由调度系统根据触发条件创建。
+
+## 任务（Task）
+
+任务是原子的数据开发任务，如数据同步任务、SQL 任务、Python 任务、SHELL 任务等。任务以文件方式创建、保存和组织管理。
+
+### Lakehouse SQL 任务
+
+指 Lakehouse 中通过 Web 端数据开发功能或 CLI、JDBC 连接等生成的 SQL 查询任务。如何开发和调度一个Lakehouse SQL任务，可以参考[此文档](taskdevelop.md)。
+
+### 同步任务
+
+指数据同步类型的任务。用户通过配置同步数据源和目标数据表生成同步任务。同步任务也消耗计算资源，并进行计量。同步任务包含离线同步任务和实时同步任务两大类。详见[此文档](data-integration.md)。
+
+### Python任务
+
+Python任务是指可以编写和运行Python代码的任务类型。对于许多数据分析和处理场景，特别是 BI+AI 分析场景，结合使用 Python 和 SQL，可以极大提高效率。 在云器 Lakehouse 里，通过提供 Python 脚本的任务类型，来运行 Python 代码。详见[此文档](Python_Task.md)。
+
+### JDBC任务
+
+JDBC 任务是数据开发中的一类重要任务节点，通过它可以编写 SQL 代码来连接支持 JDBC 协议的数据源，实现数据的增删改查等操作。详见[此文档](jdbc_task.md)。
+
+## 任务实例（Task Instance）
+
+数据开发任务在手动执行或定时调度执行时生成的具体执行实例。
+
+***
+
+通过 [此文档](object_model_design.md) 可以查看更多概念和对象模型设计。
+
+^