@clickzetta/cz-cli-darwin-x64 0.3.1

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

@@ -0,0 +1,151 @@
+## 概述
+
+Lakehouse 提供了标准的 Apache Iceberg Catalog REST API 接口，允许外部计算引擎（如 Apache Spark）通过统一的 REST 协议访问和查询存储在 Lakehouse 数据湖（如对象存储 OSS）中的 Iceberg 表。这使得在保持数据统一存储的同时，能够灵活选择不同的计算引擎进行数据分析。
+
+## 核心特性
+
+* **标准兼容**：兼容 Apache Iceberg REST Catalog 规范
+* **引擎支持**：支持 Spark 计算引擎
+* **权限委托**：通过 vended-credentials 模式管理存储访问权限
+* **多云支持**：支持阿里云 OSS（后续版本支持 AWS S3、腾讯云 COS 等）
+
+## 使用限制
+
+**数据类型兼容性**
+
+当通过 Spark 引擎访问 ClickZetta Lakehouse 表时，存在以下数据类型限制：
+
+暂不支持的数据类型：
+
+* **整数类型**：`SMALLINT`, `TINYINT`
+* **半结构化类型**：`JSON`
+* **向量类型**：`VECTOR`
+
+## 快速开始
+
+### 前置要求
+
+1. 云器 Lakehouse 实例的账号和密码
+
+2. 目标计算引擎环境：Spark 3.5+
+
+3. 必要的依赖包：
+
+   1. Apache Iceberg 库（Scala 2.12 / Spark 3.5.x）`：org.apache.iceberg:iceberg-spark-runtime-3.5_2.12:1.6.1`
+
+   2. 对应云对象存储的 SDK（如阿里云 OSS：`com.aliyun.oss:aliyun-sdk-oss:3.18.1`）
+
+### PySpark 集成示例
+
+#### 环境准备
+
+```Python
+import os
+import base64
+from pyspark.sql import SparkSession
+# 设置 SPARK_HOME 环境变量（根据实际安装路径调整）
+os.environ['SPARK_HOME'] = '/path/to/pyspark'
+```
+
+连接云器 Lakehouse 的认证配置
+
+```Python
+# 配置认证信息
+username = "your_username"
+password = "your_password"
+
+# 生成 Basic Authentication header
+credentials = f"{username}:{password}"
+encoded_bytes = base64.b64encode(credentials.encode("utf-8"))
+encoded_str = encoded_bytes.decode("utf-8")
+auth_header = f"Basic {encoded_str}"
+```
+
+创建 Spark Session
+
+```Python
+spark = SparkSession.builder \
+    .appName('IcebergCatalogIntegration') \
+    .config("spark.jars.packages", "org.apache.iceberg:iceberg-spark-runtime-3.5_2.12:1.6.1," + "com.aliyun.oss:aliyun-sdk-oss:3.18.1") \
+    .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
+    .config('spark.sql.defaultCatalog', 'clickzetta_catalog') \
+    .config('spark.sql.catalog.clickzetta_catalog', 'org.apache.iceberg.spark.SparkCatalog') \
+    .config('spark.sql.catalog.clickzetta_catalog.type', 'rest') \
+    .config("spark.sql.catalog.clickzetta_catalog.header.instanceName", "your_instance_id") \
+    .config("spark.sql.catalog.clickzetta_catalog.header.Workspace", "your_workspace") \
+    .config('spark.sql.catalog.clickzetta_catalog.uri','https://api.clickzetta.com/api/v1/catalog/iceberg-rest') \
+    .config("spark.sql.catalog.clickzetta_catalog.header.Authorization", auth_header) \
+    .config("spark.sql.catalog.clickzetta_catalog.io-impl", "org.apache.iceberg.aliyun.oss.OSSFileIO") \
+    .config("spark.sql.catalog.clickzetta_catalog.oss.endpoint", "oss-cn-hangzhou.aliyuncs.com") \
+    .config('spark.sql.catalog.clickzetta_catalog.header.X-Iceberg-Access-Delegation','vended-credentials') \
+    .config("spark.sql.catalog.clickzetta_catalog.default-namespace", "public") \
+    .config("spark.sql.catalog.clickzetta_catalog.metrics-reporter-impl", "org.apache.iceberg.metrics.LoggingMetricsReporter") \
+    .getOrCreate()
+```
+
+使用示例
+
+```Python
+# 查看所有命名空间（schemas）
+spark.sql("SHOW NAMESPACES IN clickzetta_catalog").show()
+
+# 查看指定命名空间中的表
+spark.sql("SHOW TABLES IN clickzetta_catalog.public").show()
+
+# 查看表结构
+spark.sql("DESCRIBE TABLE clickzetta_catalog.public.your_table").show()
+
+# 查询数据
+df = spark.sql("SELECT * FROM clickzetta_catalog.public.your_table LIMIT 10")df.show()
+
+# 使用 DataFrame API
+table_df = spark.table("clickzetta_catalog.public.your_table")
+table_df.filter("column_name > 100").select("col1", "col2").show()
+```
+
+## 配置参数详解
+
+| 参数 (Parameter)                                                           | 描述 (Description)                                                                                                                                          | 示例值 (Example Value)                                                                                                                                              | 是否必需 (Required?) |
+| ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- |
+| Spark与Iceberg基础配置                                                        |                                                                                                                                                           |                                                                                                                                                                  |                  |
+| spark.jars.packages                                                      | 用于指定 Spark 会话在启动时需要从 Maven 中央仓库自动下载的依赖包。这里包含了 Iceberg 的 Spark 运行时和与阿里云 OSS 交互所需的 SDK。                                                                     | org.apache.iceberg\:iceberg-spark-runtime-3.5\_2.12:1.6.1,com.aliyun.oss\:aliyun-sdk-oss:3.18.1                                                                  | 是                |
+| spark.sql.extensions                                                     | 用于向 Spark SQL 注入 Iceberg 的扩展功能。这使得 Spark 能够解析和执行 Iceberg 特有的 DDL 和 DML 语句（例如 CREATE TABLE ... USING iceberg）。                                             | org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions                                                                                                | 是                |
+| Lakehouse REST Catalog 核心配置                                              |                                                                                                                                                           |                                                                                                                                                                  |                  |
+| spark.sql.catalog.clickzetta\_catalog                                    | 固定值。注册一个名为 clickzetta\_catalog 的新目录，并指定其实现类为 Iceberg 的 SparkCatalog。这是定义一个 Iceberg Catalog 的入口点。                                                          | org.apache.iceberg.spark.SparkCatalog                                                                                                                            | 是                |
+| spark.sql.catalog.clickzetta\_catalog.type                               | 固定值。指定 clickzetta\_catalog 的类型为 rest。这告诉 Iceberg 该 Catalog 是一个通过 REST API 进行通信的远程服务。                                                                      | rest                                                                                                                                                             | 是                |
+| spark.sql.catalog.clickzetta\_catalog.uri                                | REST Catalog 服务的 API 端点地址。Spark 将向此 URL 发送所有元数据管理请求（如创建表、获取表信息等）。                                                                                         | https://{endpoint}/api/v1/catalog/iceberg-rest。endpoint 取值请参考[文档](https://www.yunqi.tech/documents/Supported_Cloud_Platforms)                                    | 是                |
+| spark.sql.catalog.clickzetta\_catalog.header.instanceName                | 发送到 REST Catalog 的自定义 HTTP 请求头。用于向 ClickZetta 服务标识您的特定实例。                                                                                                 | your\_instance\_id (请替换为您的实例 ID)                                                                                                                                  | 是                |
+| spark.sql.catalog.clickzetta\_catalog.header.Workspace                   | 发送到 REST Catalog 的自定义 HTTP 请求头。用于在您的 ClickZetta 实例中指定要操作的工作空间。                                                                                            | your\_workspace (请替换为您的工作空间名称)                                                                                                                                   | 是                |
+| spark.sql.catalog.clickzetta\_catalog.header.Authorization               | 用于 API 认证的授权令牌。通常是一个 Bearer 令牌，用于验证客户端身份。此值应通过安全的方式获取和传递。                                                                                                 | auth\_header (一个包含认证信息的变量)，如："Basic VUFUX1RFU1Q6QWJjZDEyMzQ1Ng=="                                                                                                | 是                |
+| spark.sql.catalog.clickzetta\_catalog.header.X-Iceberg-Access-Delegation | 这是一个特殊的请求头，用于启用凭证代理（Vended Credentials）模式。设置为 vended-credentials 表示客户端（Spark）期望 Catalog 服务返回用于访问底层存储（OSS）的临时安全凭证。这是一种更安全的访问模式，避免了在客户端暴露长期有效的云存储密钥。        | vended-credentials                                                                                                                                               | 是                |
+| 数据存储 (OSS) 配置                                                            |                                                                                                                                                           |                                                                                                                                                                  |                  |
+| spark.sql.catalog.clickzetta\_catalog.io-impl                            | 指定用于读写数据文件（如 Parquet, ORC）的 FileIO 实现。这里使用 OSSFileIO 来与阿里云 OSS 进行交互。                                                                                      | org.apache.iceberg.aliyun.oss.OSSFileIO                                                                                                                          | 是                |
+| spark.sql.catalog.clickzetta\_catalog.oss.endpoint                       | 阿里云对象存储服务 (OSS) 的区域端点。客户端将通过此地址访问 OSS 存储桶。                                                                                                                | [oss-cn-hangzhou.aliyuncs.com](http://oss-cn-hangzhou.aliyuncs.com) (可根据您的 OSS 存储桶所在区域修改，请参考[文档](https://help.aliyun.com/zh/oss/user-guide/regions-and-endpoints)) | 是                |
+| 可选/辅助配置                                                                  |                                                                                                                                                           |                                                                                                                                                                  |                  |
+| spark.sql.defaultCatalog                                                 | 设置 Spark SQL 的默认 Catalog。设置后，执行 SQL 查询时无需在表名前显式指定 Catalog 名称（例如，可以直接使用 `SELECT * FROM my_table` 而不是 `SELECT * FROM clickzetta_catalog.public.my_table`）。 | clickzetta\_catalog                                                                                                                                              | 否                |
+| spark.sql.catalog.clickzetta\_catalog.default-namespace                  | 设置 clickzetta\_catalog 内部的默认命名空间（或称为数据库/Schema）。如果设置了此项，在未指定命名空间时，表操作将默认在此命名空间下进行。                                                                        | public                                                                                                                                                           | 否 (但推荐)          |
+| spark.sql.catalog.clickzetta\_catalog.metrics-reporter-impl              | 配置 Iceberg 指标（Metrics）的报告器实现。LoggingMetricsReporter 会将操作指标（如扫描耗时、文件数量等）输出到 Spark 的日志中，便于调试和性能分析。                                                          | org.apache.iceberg.metrics.LoggingMetricsReporter                                                                                                                | 否                |
+
+## 故障排查
+
+### 常见问题及解决方案
+
+1. **认证失败**
+
+   1. 检查用户名和密码是否正确。
+   2. 确认 Base64 编码是否正确。
+   3. 验证账号是否有相应权限。
+
+2. **连接超时**
+
+   1. 检查网络连接。
+   2. 确认 API 端点地址是否正确。
+   3. 调整超时参数。
+
+3. **表不存在**
+
+   1. 确认 workspace 和 namespace 设置正确。
+   2. 使用 `SHOW TABLES` 确认表名。
+   3. 检查用户权限。
+
+^

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

@@ -0,0 +1,105 @@
+# 通过Private Link和SSH结合来同步VPC内的RDS数据
+
+## 1. 适用场景
+
+Lakehouse Studio **数据集成** 通过 VPC 网络同步 RDS 的数据，可解决公网传输带来的如下问题：
+
+* 数据延迟高
+* 公网流量成本高
+* 不安全/不合规
+
+## 2. 历史方案优缺点总结
+
+* **纯 Private Link 方案**：不支持连接 RDS 实例，只支持 ECS 上自建的 MySQL。
+* **VPC Peering 验证走通**：但是会暴露双方内网环境，有安全风险，不建议使用。
+* **通过 IGS SDK**：通过 Private Link 支持把数据推送到 Lakehouse，但是导入调度策略需要客户自己负责，无法集成到 workflow 中。
+* **纯 SSH TUNNEL**：中间一段需要走公网，能解决 RDS 暴露公网的安全问题，但是不能解决公网流量问题。
+
+## 3. 本方案简介
+
+本方案是 Private Link 与 SSH Tunnel 两种方式相结合的方案。
+
+网络架构图（以阿里云上为例）：
+
+![](.topwrite/assets/whiteboard_exported_image.png)
+
+（客户环境也可在同 Region 的其他可用区）
+
+默认由**终端节点**侧承担开销，计费项有两个，具体可参考 [计费规则](https://help.aliyun.com/document_detail/198081.html?spm=a2c4g.120462.0.0.462f29e3tnGfMO#section-4zx-gat-sg7)。
+
+## 4. 配置方法（示例）：
+
+### Step1：环境准备
+
+**客户侧环境**：
+
+* VPC：杭州 H：专有网络 **VPC\_Customr**: [vpc-bp1qmyayneio4mlyoyeb7](https://vpc.console.aliyun.com/vpc/cn-hangzhou/vpcs/vpc-bp1qmyayneio4mlyoyeb7?type=base)，网段: `172.16.0.0/12`
+* RDS：杭州 H：私网地址：\`\` （`rm-bp15gq963ic327h8f.mysql.rds.aliyuncs.com`）
+* ECS：杭州 H：私网 IP 地址 `172.16.12.182`
+
+**Lakehouse 侧**：
+
+CZ Studio UAT 环境数据集成 EMR 集群所在 VPC 和 VWS：杭州 H
+
+| SQL vpc-bp1jvn\*\*\*\*\*\*\*\*\*\*\*u  vsw-bp1rp\*\*\*\*\*\*\*\*\*\*\*\*cii |
+| --------------------------------------------------------------------------- |
+
+CZ UAT 环境阿里云主账号：`138************83`
+
+### Step 2：在 ECS 上创建 SSH 端口转发
+
+在客户网络环境中，创建一台与 RDS 互通的 ECS，在此机器上创建端口转发：访问该 ECS 的 12345 端口，会被转发到 RDS 的 3306 端口。
+
+```Shell
+ssh -CfNg -L 12345:rm-bp15gq963ic327h8f.mysql.rds.aliyuncs.com:3306 root@127.0.0.1 -p22
+
+##验证：
+ps aux | grep ssh
+```
+
+![](.topwrite/assets/c417a0f96d/e4dc75c9ba552ccaca172ab265aeeb5dbc67505e.png)
+
+***
+
+### Step 3：创建负载均衡 CLB
+
+* 进入负载均衡 SLB 控制台 -> 左侧 **传统型负载均衡 CLB（原 SLB）** -> **创建传统型负载均衡**
+
+* 创建监听如下：
+  ![](.topwrite/assets/c417a0f96d/c4ec47d374f0564f96375d460e06a2b096c64688.png)
+
+* 在标签页 **默认服务器组** 中添加 Step 2 中的 ECS，前端端口为 22（自定义），后端端口为转发到 RDS 的端口，本案例中为 12345。
+
+### Step 4：客户侧：创建终端节点服务
+
+* 进入 VPC 控制台，选择与 CZ 数据集成集群相同的 Region，左侧 **终端节点服务** -> **创建终端节点服务**
+* **服务资源类型 -> 传统型负载均衡 CLB**（与 Step1 一致），选择可用区 \*\*杭州 可用区H，\*\*在下拉框中选择 step1 中创建的 CLB 实例，自动接收端点连接：是，其它默认
+* 进入该终端节点服务：在 **服务白名单** 中，添加云器环境主账号：`1384322691904283`
+
+  ![](.topwrite/assets/c417a0f96d/fc469bdcdf20cda3bca8b56dfa9d4b66b010e090.png)
+
+### Step 5：Lakehouse 侧创建终端节点
+
+* 进入 VPC 控制台，选择与 CZ 数据集成集群相同的 Region，在左侧菜单中选择 **终端节点**。
+* 在终端节点页面，系统会自动发现 Step 4 中创建的终端节点服务，选择对应的 **专有网络** 后，确认创建；
+* 在客户侧和 Lakehouse 侧的**终端节点服务**和**终端节点**的**终端节点连接**信息中，可以获取域名。
+
+### **验证**：
+
+**Lakehouse Studio 数据集成**：
+
+在数据源配置中，使用如下 JDBC URL：`jdbc:mysql://ep-bp1iabb21a27719ca8a2-cn-hangzhou-h.epsrv-bp1n7rvc8qbpudxk69fr.cn-hangzhou.privatelink.aliyuncs.com:22/mysql`
+
+![](.topwrite/assets/c417a0f96d/edb20aeb52d76a06e65943c74983bd38b00dac5e.jpeg)
+
+终端节点服务绑定的 CLB 监听端口为 22，后端绑定的 ECS 资源端口为 12345；
+
+![](.topwrite/assets/c417a0f96d/d0297891972911f184c690e7585cff01aaa5943f.jpeg)
+
+MySQL 控制台：
+
+![](.topwrite/assets/c417a0f96d/3b17582b28ae004533c8998acf76c2a7cee76bc5.jpeg)
+
+数据集成验证：导入成功
+
+![](.topwrite/assets/20240520-211021.jpeg)

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

@@ -0,0 +1,40 @@
+# 云服务和地域支持
+
+## 地域支持
+
+云器 Lakehouse 作为一款 SaaS 化的数据管理与分析服务，充分利用云上基础设施，为用户提供高效、便捷的服务体验。我们致力于满足客户与业务系统在不同云服务商及地域的数据打通与集成需求。
+
+目前，云器 Lakehouse 已在以下云服务商及地域提供服务，并计划扩展更多：
+
+| 云服务商 | 地域       | 区域代码                      |
+| ---- | -------- | ------------------------- |
+| 阿里云  | 华东2（上海）  | cn-shanghai-alicloud      |
+| 腾讯云  | 华东地区（上海） | ap-shanghai-tencentcloud  |
+| 腾讯云  | 华北地区（北京） | ap-beijing-tencentcloud   |
+| 腾讯云  | 华南地区（广州） | ap-guangzhou-tencentcloud |
+| 亚马逊云 | 北京       | cn-north-1-aws            |
+
+## 服务域名
+
+当您注册云器 Lakehouse 账户后，系统会自动分配一个唯一的账户名称。在进行账户管理时，您需要使用该账户名称登录账户中心。在账户中心，管理员可以为您在指定的云服务商及区域开通并创建 Lakehouse 服务实例。请注意，Lakehouse 服务实例名称是全局唯一的。
+
+| 服务                           | 子服务             | 域名                                                                           |
+| ---------------------------- | --------------- | ---------------------------------------------------------------------------- |
+| 账户控制台                        | 账户管理中心          | accounts.app.clickzetta.com&#xA;\<account\_name>.accounts.app.clickzetta.com |
+| 账户控制台                        | 账户管理中心          | accounts.clickzetta.com&#xA;\<account\_name>.accounts.clickzetta.com         |
+| 产品Web控制台                     | Lakehouse实例控制台  | \<instance\_name>.app.clickzetta.com                                         |
+|                              | Lakehouse工作空间列表 | \<instance\_name>.app.lakehouse.clickzetta.com/workspace                     |
+| Lakehouse JDBC URL           |                 | jdbc\:clickzetta://\<instance\_name>.\<region\_id>.api.clickzetta.com/       |
+| Lakehouse Streaming API Host |                 | \<instance\_name>.streamingapi.clickzetta.com                                |
+
+JDBC域名&服务地址(Endpoint)详细列表
+
+| 云服务商 | 地域       | region\_id(区域代码)          | JDBC域名                                                                             | Endpoint                                     |
+| ---- | -------- | ------------------------- | ---------------------------------------------------------------------------------- | -------------------------------------------- |
+| 阿里云  | 华东2（上海）  | cn-shanghai-alicloud      | jdbc\:clickzetta://\<instance\_name>.cn-shanghai-alicloud.api.clickzetta.com/      | cn-shanghai-alicloud.api.clickzetta.com      |
+| 腾讯云  | 华东地区（上海） | ap-shanghai-tencentcloud  | jdbc\:clickzetta://\<instance\_name>.ap-southeast-1-alicloud.api.clickzetta.com/   | ap-shanghai-tencentcloud.api.clickzetta.com  |
+| 腾讯云  | 华北地区（北京） | ap-beijing-tencentcloud   | jdbc\:clickzetta://\<instance\_name>.ap-beijing-tencentcloud.api.clickzetta.com/   | ap-beijing-tencentcloud.api.clickzetta.com   |
+| 腾讯云  | 华南地区（广州） | ap-guangzhou-tencentcloud | jdbc\:clickzetta://\<instance\_name>.ap-guangzhou-tencentcloud.api.clickzetta.com/ | ap-guangzhou-tencentcloud.api.clickzetta.com |
+| 亚马逊云 | 北京       | cn-north-1-aws            | jdbc\:clickzetta://\<instance\_name>.cn-north-1-aws.api.clickzetta.com/            | cn-north-1-aws.api.clickzetta.com            |
+
+说明：账户名称\<account\_name>和实例名称\<instance\_name>的创建和获取，请参考[开通使用](LoggingIn.md)。

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

@@ -0,0 +1,49 @@
+# Table（表）
+
+在云器Lakehouse中，Table（表）是存储数据的基本单位，它是数据库中组织数据的核心结构。Lakehouse 的表设计为列式存储，这种存储方式在处理分析型查询时表现出极高的效率，因为它允许查询只读取需要的列数据，而不是整行数据。这种存储结构特别适合于数据仓库和大数据分析场景，可以显著提高数据处理的速度。
+
+## 表的约束
+
+表的约束用于确保表中数据的完整性和准确性。在Lakehouse中，支持多种类型的约束，包括但不限于：
+
+### NOT NULL
+
+**NOT NULL** 约束确保列中的值不能为NULL。这是在创建表时设置的，一旦设置，该约束将不可去除，以确保列中始终有有效数据。
+
+### PRIMARY KEY
+
+**主键（PRIMARY KEY）** 用于确保表中每条记录的唯一性。在大数据场景下，由于数据量通常非常庞大，为了保证数据的唯一性而对所有 key 进行逐一检查是不现实且低效的，因此一般不推荐在大数据环境中使用主键约束。然而，Lakehouse 仍提供了对主键的支持，以便在特定场景下满足数据完整性的需求。在 Lakehouse 架构中，定义了主键的表在进行实时数据写入时，系统将自动根据主键值进行数据去重，这对于变更数据捕获（CDC）场景尤为重要。例如，您可以实时地将MySQL数据库的binlog日志同步到Lakehouse，确保数据的一致性。设置完主键后，需要通过 [实时数据接口](java_reference/realtime-upload.md) 来处理数据。在 CDC 实时写入过程中，系统将依据主键自动进行数据去重，以维护数据的准确性和完整性。
+
+#### Lakehouse 主键支持及默认行为
+
+Lakehouse 支持两种直接指定主键（primary key）的方式，且在默认情况下，其行为设置为 `ENABLE VALIDATE RELY`。这意味着，当您在创建表时指定了主键，并且没有特别指定其他行为时，系统会自动启用对主键的验证和依赖关系。
+
+在这种默认行为下，无论是实时写入操作还是通过 SQL 进行的数据写入，系统都会依据所定义的主键进行去重处理。如果尝试插入与现有主键值重复的记录，系统将拒绝执行该插入操作，以确保主键的唯一性。例如：
+
+```sql
+create table test_primary(id int primary key,name string);
+desc extended test_primary;
+insert into test_primary values(1,"1");
+insert into test_primary values(2,"1");
+-- 此时插入成功，因为主键值 1 和 2 均未重复
+insert into test_primary values(1,"1");
+-- 插入失败，因为主键值 1 已存在
+select * from test_primary;
+```
+
+从上述示例可以看出，在默认的 `ENABLE VALIDATE RELY` 模式下，系统严格维护主键的唯一性，无论是单条记录插入还是批量插入，都会进行主键冲突检查。
+
+#### 自定义主键行为
+
+如果您根据实际业务需求，希望在插入数据时仅由实时写入机制进行主键去重，而通过 SQL 写入时则不执行去重操作，可以通过将主键行为设置为 `disable NOVALIDATE RELY` 来实现。以下是具体的操作示例：
+
+```sql
+create table test_primary_di(id int primary key disable NOVALIDATE RELY ,name string);
+insert into test_primary_di values(1,"1");
+insert into test_primary_di values(2,"1");
+-- 此时插入成功，主键检查按预期执行
+insert into test_primary_di values(1,"1");
+-- 插入成功，因为在 disable NOVALIDATE RELY 模式下，SQL 写入不进行主键去重
+```
+
+需要注意的是，在 `disable NOVALIDATE RELY` 模式下，虽然实时写入仍会依据主键进行去重，但通过 SQL 进行的写入操作将不会受到主键唯一性约束的限制，这可能导致数据中出现主键重复的情况。因此，在选择此模式时，您需要对数据的写入来源和写入方式进行审慎的考虑和管理，以避免潜在的数据质量问题。

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

@@ -0,0 +1,56 @@
+# TIMESTAMP
+
+`TIMESTAMP` 类型用于表示日期和时间戳，可以包含时区信息。默认情况下，时间戳表示为本地时间（TIMESTAMP_LTZ）。所有操作都在当前会话的时区中执行，输出结果也以当前 Lakehouse 所在服务的时区为准。支持用户输入多种格式的时间戳，并自动转换为`TIMESTAMP`类型。输出结果为字符串格式，格式为 `'yyyy-MM-dd HH:mm:ss'`。如果用户输入包含毫秒，则输出结果也会包含毫秒。最大精度支持到微秒（µs），实际精度取决于写入时的时间戳精度。
+
+## 语法
+```
+TIMESTAMP | TIMESTAMP_LTZ
+```
+
+## 示例
+1. 使用默认时间戳格式：
+```
+SELECT TIMESTAMP '2022-12-31 00:00:00';
+SELECT TIMESTAMP_LTZ '2022-12-31 00:00:00';
+```
+2. 使用不同格式的时间戳：
+```
+SELECT TIMESTAMP '2022-12-31 00:00:00.123'; -- 包含毫秒
++------------------------------------+
+
+| TIMESTAMP'2022-12-31 00:00:00.123' |
+
++------------------------------------+
+
+| 2022-12-31 00:00:00.123            |
+
++------------------------------------+
+
+SELECT TIMESTAMP '2022-12-31T00:00:00.123Z'; -- ISO 8601 格式，包含时区信息
++-------------------------------------+
+
+| TIMESTAMP'2022-12-31T00:00:00.123Z' |
+
++-------------------------------------+
+
+| 2022-12-31 08:00:00.123             |
+
++-------------------------------------+
+
+
+```
+3. 将字符串转换为时间戳类型：
+```
+SELECT CAST('2022-12-31 00:00:00' AS TIMESTAMP);
+SELECT CAST('2022-12-31 00:00:00' AS TIMESTAMP_LTZ);
+```
+4. 使用不同的精度选项：
+```
+SELECT TIMESTAMP  '2022-12-31 00:00:00.123456'; -- 微秒精度
+SELECT TIMESTAMP  '2022-12-31 00:00:00.123'; -- 毫秒精度
+SELECT TIMESTAMP  '2022-12-31 00:00:00'; -- 秒精度
+```
+
+## 注意事项
+- 在进行时间戳转换时，请注意时区差异可能导致的误差。
+- 请确保输入的时间戳格式与系统支持的格式相匹配，以免出现错误。

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

@@ -0,0 +1,207 @@
+# Lakehouse Time Travel功能简介
+
+Lakehouse的Time Travel功能允许用户在定义的时间段内的任何时间点访问历史数据，包括已更改或删除的数据。Lakehouse Time Travel功能收取存储费用，并将默认保留周期为一天。请注意，如果设置的时间更长，存储费用会增加。
+
+## 应用场景
+
+1. 恢复可能被意外或有意删除的数据。
+2. 复制和备份过去关键点的数据。
+3. 分析指定时间段内的数据变化。
+## Time Travel保留期限设置
+
+Time Travel保留期限决定了您可以访问多久以前的数据。例如，如果Time Travel保留期限设置为7天，那么您可以访问过去7天内的任何时间点的数据。超过7天后，您将无法使用Time Travel访问过期的数据，且数据会被物理删除。
+Lakehouse表的历史状态默认保留周期1天（24小时），您可以通过Time Travel查询1天内的历史版本。
+
+如需保留更长周期的历史版本，您可以为每个表设置不同的数据保留周期，以满足不同的业务需求。num的设置范围为0-90。
+
+  * ```SQL
+    ALTER TABLE tablename SET PROPERTIES ('data_retention_days'='num');
+    ```
+## TIMETRAVEL查询语法
+
+```sql
+SELECT 
+    table_identifier TIMESTAMP AS OF timestamp_expression
+```
+
+通过使用TIMESTAMP AS OF子句，用户可以指定具体的时间点，查询保留期内表历史记录中指定点的精确位置或紧邻指定点之前的数据。Timestamp\_expression是一个返回时间戳类型表达式的参数，例如：
+
+* `'2023-11-07 14:49:18'`，即可强制转换为时间戳的字符串。
+* `CAST('2023-11-07 14:49:18' AS TIMESTAMP)`。
+* `CURRENT_TIMESTAMP() - INTERVAL 12 HOURS`。12小时之前的版本
+* 任何本身是时间戳类型或可强制转换为时间戳的表达式。
+
+## 查询说明
+
+* 通过指定时间点，用户可以查询到指定时间的版本数据。
+* 查询的时间点不能早于表创建时间，也不能超出数据保留周期。如果指定的时间点超出范围，将报错。
+* 如果timestamp\_expression是未来时间，也会报错，因为未来的数据是不可用的。
+
+## 权限要求
+
+* 用户需要拥有对表的SELECT权限。
+
+## 使用限制
+
+* View不支持Time Travel查询。
+* 不支持外部schema。
+* RealtimeStream实时写入未提交的数据不支持Time Travel查询，因为RealtimeStream为了提供实时查询功能，会优先写入到临时区，方便快速查询。而Time Travel查询历史版本是依靠查询提交记录，因此暂时无法查询RealtimeStream实时写入未提交的数据。
+
+## 具体案例
+
+### 分析指定时间段内的数据
+
+```sql
+CREATE TABLE birds (
+    id INT,
+    name VARCHAR(50),
+    wingspan_cm FLOAT,
+    colors STRING
+);
+
+INSERT INTO birds (id, name, wingspan_cm, colors) VALUES
+    (1, 'Sparrow', 15.5, 'Brown'),
+    (2, 'Blue Jay', 20.2, 'Blue'),
+    (3, 'Cardinal', 22.1, 'Red'),
+    (4, 'Robin', 18.7, 'Red","Brown');
+
+-- 插入更多数据
+INSERT INTO birds (id, name, wingspan_cm, colors) VALUES
+    (5, 'Hummingbird', 8.2, 'Green'),
+    (6, 'Penguin', 99.5, 'Black", "White'),
+    (7, 'Eagle', 200.8, 'Brown'),
+    (8, 'Owl', 105.3, 'Gray'),
+    (9, 'Flamingo', 150.6, 'Pink'),
+    (10, 'Pelican', 180.4, 'White');
+--查看版本
+DESC HISTORY birds;
++---------+-------------------------+------------+-------------+----------+----+
+| version |          time           | total_rows | total_bytes |   user   |  o |
++---------+-------------------------+------------+-------------+----------+----+
+| 3       | 2024-12-23 16:41:47.831 | 10         | 5786        | UAT_TEST | IN |
+| 2       | 2024-12-23 16:36:04.426 | 4          | 2859        | UAT_TEST | IN |
+| 1       | 2024-12-23 16:36:04.233 | 0          | 0           | UAT_TEST | CR |
++---------+-------------------------+------------+-------------+----------+----+
+-- 等待五分钟后查询
+SELECT * FROM birds TIMESTAMP AS OF timestamp'2024-12-23 16:36:04.426';
++----+----------+-------------+-------------+
+| id |   name   | wingspan_cm |   colors    |
++----+----------+-------------+-------------+
+| 1  | Sparrow  | 15.5        | Brown       |
+| 2  | Blue Jay | 20.2        | Blue        |
+| 3  | Cardinal | 22.1        | Red         |
+| 4  | Robin    | 18.7        | Red","Brown |
++----+----------+-------------+-------------+
+```
+
+### 指定版本的数据和其他表做join
+
+```
+DROP TABLE students;
+DROP TABLE scores;
+CREATE TABLE students (name string, class string);
+INSERT INTO students (name, class) VALUES
+('Alice', 'A'),
+('Bob', 'B');
+CREATE TABLE scores (name string, score int);
+INSERT INTO scores (name, score) VALUES
+('Alice', 90),
+('Bob', 80),
+('Carol', 85),
+('David', 95);
+
+--等待1分钟插入
+INSERT INTO students (name, class) VALUES
+('Carol', 'A'),
+('David', 'C');
+--查看版本
+DESC HISTORY  students;
++---------+-------------------------+------------+-------------+----------+----+
+| version |          time           | total_rows | total_bytes |   user   |  o |
++---------+-------------------------+------------+-------------+----------+----+
+| 3       | 2024-12-23 16:17:01.792 | 4          | 3884        | UAT_TEST | IN |
+| 2       | 2024-12-23 16:15:22.957 | 2          | 1939        | UAT_TEST | IN |
+| 1       | 2024-12-23 16:15:22.829 | 0          | 0           | UAT_TEST | CR |
++---------+-------------------------+------------+-------------+----------+----+
+--当前版本查询
+SELECT students.name, students.class, scores.score
+FROM students 
+INNER JOIN scores
+ON students.name = scores.name;
++-------+-------+-------+
+| name  | class | score |
++-------+-------+-------+
+| Carol | A     | 85    |
+| Bob   | B     | 80    |
+| David | C     | 95    |
+| Alice | A     | 90    |
++-------+-------+-------+
+--使用students 2024-12-23 16:15:22.957的版本
+SELECT students.name, students.class, scores.score
+FROM students timestamp as of '2024-12-23 16:15:22.957'
+INNER JOIN scores
+ON students.name = scores.name;
++-------+-------+-------+
+| name  | class | score |
++-------+-------+-------+
+| Alice | A     | 90    |
+| Bob   | B     | 80    |
++-------+-------+-------+
+
+```
+
+### 恢复可能被意外或有意删除的数据
+
+模拟删除数据：
+
+```sql
+CREATE TABLE birds (
+    id INT,
+    name VARCHAR(50),
+    wingspan_cm FLOAT,
+    colors STRING
+);
+
+INSERT INTO birds (id, name, wingspan_cm, colors) VALUES
+    (1, 'Sparrow', 15.5, 'Brown'),
+    (2, 'Blue Jay', 20.2, 'Blue'),
+    (3, 'Cardinal', 22.1, 'Red'),
+    (4, 'Robin', 18.7, 'Red","Brown');
+
+-- 删除数据
+TRUNCATE TABLE birds;
+
+-- 查看数据是否还存在
+SELECT * FROM birds; -- 数据已经被删除
+```
+
+运行历史查看truncate时间：
+
+![truncate\_time](.topwrite/assets/image_1699363617476.png)
+
+恢复数据：
+
+```sql
+-- 查看删除之前的数据，根据上面运行历史执行的时间，设置time travel版本
+SELECT * FROM birds TIMESTAMP AS OF '2023-11-07 14:49:18';
+
+-- 恢复数据
+INSERT OVERWRITE TABLE birds
+SELECT * FROM birds TIMESTAMP AS OF '2023-11-07 14:49:18';
+```
+
+## 复制和备份过去关键点的数据。
+
+可以将指定时间点的数据备份到另一张表中
+
+```
+CREATE    TABLE birds_backup AS
+SELECT    *
+FROM      birds TIMESTAMP AS OF '2023-11-20 15:48:40';
+
+SELECT    *
+FROM      birds_backup;
+
+```
+
+