@clickzetta/cz-cli-darwin-x64 0.3.1

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

@@ -0,0 +1,225 @@
+# 云器Lakehouse计费说明
+
+## 1. 计费方式概述
+
+云器Lakehouse是基于云原生建设的一体化数据平台，平台会记录你在数据集成、数据分析、存储和网络传输等场景下消耗的资源，并按照计算、存储、网络三种类型，根据服务发生的云平台和地域，向您收取相应的费用。
+
+云器Lakehouse的计费主要基于以下几个方面：
+
+* **计算资源**：计算资源的计费单元为**CRU**\***时**，1CRU\*时代表在每个云平台的每个服务区域以同样的算力运行1小时。你在云器Lakehouse使用同步型、分析型、通用型计算集群所进行数据集成或数据分析，使用Python、Shell脚本处理的任务，以及系统自动处理的自动物化视图（Auto\_MV)、数据压缩、作业任务调度等操作均会产生计算资源的使用。我们会根据实际消耗的算力使用量进行计量计费。
+* **存储资源**：存储资源的计费单元为GiB，根据你在云器Lakehouse上实际使用的存储容量进行计费。以下场景会占用存储容量：
+  1）在Lakehouse中以表、物化视图等形式存储的数据；
+  2）数据表生命周期内已删除但未清理的数据；
+  3）查询结果的缓存。其中第2、第3项当前仅计量，暂免收费。
+* **数据传输**：数据传输的计费单元为GB，根据数据传输的量进行计费。以下场景会产生数据传输费用：通过公网的数据查询，数据查询结果的全量下载，以云器Lakehouse为数据源向其他数据源传输数据。数据传输流量可能通过Internet、跨VPC的网络连接、专线或者其他网络连通方式产生。其中针对Internet网络流量，仅计量从云器Lakehouse流出的数据传输量，上传数据至云器Lakehouse不收费。
+
+## 2. 计费方式
+
+**按需计费**
+
+在云器Lakehouse中，各类资源均是灵活扩展、按需使用的，你只需按照实际使用的资源量进行付费。其中：
+
+**计算资源**计费按秒统计每一台计算集群实例的开机至关机的时间，按照CRU进行计量，并换算成法定货币为单位的账单；
+
+**存储资源**以全天所有数据（包含数据表当前数据、历史版本数据，查询结果缓存等）存储容量的平均值计费；
+
+**网络传输**费用按照实际产生的网络流量计费，其中Internet网络流量费用以流出Lakehouse方向的流量计费。
+
+由于不同云平台、不同区域下，资源的价格不同，计算、存储和网络每单位的单价也会存在差异。具体价格请参考“云器Lakehouse价格表”，以系统内实际账单为准。
+
+你可以通过“管理中心”-“计费账单”页面查看资源使用情况及费用明细。其中计算资源和数据传输费用每小时进行一次计量和扣费，存储资源以全天24小时采样的容量平均值，每天进行一次计量和扣费。
+
+**包年预付费**
+
+云器Lakehouse也可为企业客户提供指定资源规格，按年预付费的计费方式。包年预付费时，计算和存储资源的单价可提供相应折扣。详情请联系云器销售人员。
+
+## 3. 计费原理
+
+### 3.1 计算资源计费
+
+计算资源的计费项包括：通用型计算集群、分析型计算集群、同步型计算集群、调度任务和serverless作业5种。各计费项的计费原理如下：
+
+* **通用型计算集群**
+
+当通用型计算集群启动至“运行中”状态，即开始根据集群的规格大小和实例数，产生对应的CRU消耗，当该计算集群进入“停止中”状态，则停止产生CRU消耗。
+
+^
+
+通用型计算集群的规格及对应的每小时CRU消耗如下：
+
+| **计算集群规格** | **每小时CRU消耗**（CRU\*时） |
+| ---------- | -------------------- |
+| 1          | 1                    |
+| 2          | 2                    |
+| 3          | 3                    |
+| 4          | 4                    |
+| 5          | 5                    |
+| ...        | ...                  |
+| 256        | 256                  |
+
+* **分析型计算集群**
+
+分析型计算集群的计费原理与通用型计算集群相同，从“运行中”状态的开始时间开始计量，直至进入“停止中”状态。
+
+分析型计算集群在规格的基础上，增加了“实例”的弹缩。当通过自动弹缩扩容出1个实例，即会增加一个同等规格计算集群的消耗。
+
+下表为分析型计算集群1到5个实例时，每小时CRU消耗，更多实例数以此类推：
+
+| **计算集群规格** | **1个实例**
**每小时消耗** | **2个实例**
**每小时消耗** | **3个实例**
**每小时消耗** | **4个实例**
**每小时消耗** | **5个实例**
**每小时消耗** |
+| ---------- | ---------------------- | ---------------------- | ---------------------- | ---------------------- | ---------------------- |
+| 1          | 1 CRU\*时               | 2 CRU\*时               | 3 CRU\*时               | 4 CRU\*时               | 5 CRU\*时               |
+| 2          | 2 CRU\*时               | 4 CRU\*时               | 6 CRU\*时               | 8 CRU\*时               | 10 CRU\*时              |
+| 4          | 4 CRU\*时               | 8 CRU\*时               | 12 CRU\*时              | 16 CRU\*时              | 20 CRU\*时              |
+| 8          | 8 CRU\*时               | 16 CRU\*时              | 24 CRU\*时              | 32 CRU\*时              | 40 CRU\*时              |
+| 16         | 16 CRU\*时              | 32 CRU\*时              | 48 CRU\*时              | 64 CRU\*时              | 80 CRU\*时              |
+| 32         | 32 CRU\*时              | 64 CRU\*时              | 96 CRU\*时              | 128 CRU\*时             | 160 CRU\*时             |
+| 64         | 64 CRU\*时              | 128 CRU\*时             | 192 CRU\*时             | 256 CRU\*时             | 320 CRU\*时             |
+| 128        | 128 CRU\*时             | 256 CRU\*时             | 384 CRU\*时             | 512 CRU\*时             | 640 CRU\*时             |
+| 256        | 256 CRU\*时             | 512 CRU\*时             | 768 CRU\*时             | 1024 CRU\*时            | 1280 CRU\*时            |
+
+* **同步型计算集群**
+
+同步型计算集群主要用于提交离线集成和实时集成任务。多个集成任务可提交至同1个同步型计算集群中，以复用资源。同步型计算集群的计费原理与通用型计算集群相同，从“运行中”状态的开始时间开始计量，直至进入“停止中”状态。当前“同步型计算集群”处于试运行状态，暂时以同步型计算集群中执行的数据集成作业为单位，分别计入至“离线集成”和“实时集成”两个计费项中。“同步型计算集群”正式运行后，数据集成费用合并至同步型计算集群计费项中。
+
+同步型计算集群的规格及对应的每小时CRU消耗如下：
+
+| **计算集群规格** | **每小时CRU消耗** |
+| ---------- | ------------ |
+| 0.25       | 0.25 CRU\*时  |
+| 0.5        | 0.5 CRU\*时   |
+| 1          | 1 CRU\*时     |
+| 2          | 2 CRU\*时     |
+| 3          | 3 CRU\*时     |
+| 4          | 4 CRU\*时     |
+| 5          | 5 CRU\*时     |
+| ...        | ...          |
+| 256        | 256 CRU\*时   |
+
+* **任务调度**
+
+任务调度包含两个场景：运行python、shell等脚本，以及离线或实时数据集成任务中的作业提交和调度管理。
+
+运行python、shell等脚本时，系统会根据脚本运行的资源配置，启动对应的计算资源。以启动执行脚本的计算资源为开始，脚本执行结束为终止，计量这个时间段内使用的计算资源，以CRU\*时为单位生成计费账单。
+在离线数据集成任务运行时，云器Lakehouse会提供少量计算资源用于作业提交和调度管理，这部分资源会在离线集成任务启动时开始使用（作业排队等待过程中不会消耗），并在离线集成任务进行时持续存在。因此，该计算资源的消耗会被计量，并以CRU\*时为单位生成计费账单。
+在实时数据集成任务运行时，云器Lakehouse会提供少量计算资源用于作业提交和调度管理，这部分资源会在实时集成任务启动时使用，在任务正式运行后结束。在这段时间内的计算资源消耗会被计量，并以CRU\*时为单位生成计费账单。
+
+* **Serverless作业**
+
+Serverless作业指无需用户主动创建计算集群实例，而由云器Lakehouse提供公共计算资源处理客户计算需求的作业统称。包含查询作业调度、数据压缩、自动物化视图等。
+
+### 3.2 存储资源计费
+
+存储费用根据您在Lakehouse平台实际使用的存储容量进行计量计费。当您在Lakehouse数仓中写入数据后，写入的数据及其部分元数据信息即在Lakehouse中占用存储容量。Lakehouse将统计您的数据实际占用的存储用量，于1天之内多次采样，并以当天采样存储容量的平均值，作为当天的存储容量计量数值，进行计量计费。
+
+当你使用Lakehouse的Time Travel功能时，为了保障数据的多版本、可恢复，Lakehouse会自动为您的数据进行多版本备份存储。此时产生的多版本备份数据将产生相应存储费用，以存储容量单价收费。
+
+当你进行SQL查询时，为降低重复查询的计算资源消耗，会对查询结果进行缓存，以存储成本换取计算资源的节省。这部分存储使用会计入“结果缓存（Result Cache）”，以存储容量单价收费。
+
+### 3.3 数据传输计费
+
+当你使用数据集成等功能，批量从Lakehouse通过公网下载、导出数据时，会产生Internet网络传输费用。Internet网络传输以实际产生的传输数据量进行计量，并计算费用。
+
+你从其他数据源通过Internet网络向Lakehouse上传数据产生的网络传输流量，不会产生网络传输费用。
+
+如果你使用了专线、Private Link或其他网络产品实现跨云厂商、跨地域或跨VPC网络打通时，网络打通本身会产生费用。这部分费用根据网络打通方式不同，产生在云器Lakehouse侧的由云器收取，在你的云平台账号中产生的费用由云平台直接收取。
+
+### 3.4 其他云资源计费
+
+云器Lakehouse在进行元数据管理，解析sql语句、生成查询计划、调度和分配查询任务，以及对数据文件进行合并、清理等操作时，均会消耗云资源。云器Lakehouse会对这些云资源的消耗进行计量，当前限时免费。开始收费前1个月将提前通知。
+
+## 4. 定价
+
+### **4.1 CRU\*时价格**
+
+| 云厂商 | 区域  | 版本  | 单价             |
+| --- | --- | --- | -------------- |
+| 阿里云 | 上海  | 标准版 | 3.5元/CRU\*时    |
+|     | 新加坡 | 标准版 | 0.8 美元/CRU\*时  |
+| 腾讯云 | 北京  | 标准版 | 3.5元/CRU\*时    |
+|     | 上海  | 标准版 | 3.5元/CRU\*时    |
+|     | 广州  | 标准版 | 3.5元/CRU\*时    |
+| AWS | 北京  | 标准版 | 9.95元/CRU\*时   |
+|     | 新加坡 | 标准版 | 1.24 美元/CRU\*时 |
+
+说明：除标准版（Standard Edition）外，平台还提供企业版（Enterprise Edition），具备更完善的数据治理与数据安全功能。企业版的 CRU\*hour 单价将高于标准版，具体价格及方案请联系商务代表。
+
+### **4.2 存储容量价格**
+
+| 云厂商 | 区域  | 版本  | 存储容量价格        |
+| --- | --- | --- | ------------- |
+| 阿里云 | 上海  | 标准版 | 0.12元/GiB/月   |
+|     | 新加坡 | 标准版 | 0.017美元/GiB/月 |
+| 腾讯云 | 北京  | 标准版 | 0.12元/GiB/月   |
+|     | 上海  | 标准版 | 0.12元/GiB/月   |
+|     | 广州  | 标准版 | 0.12元/GiB/月   |
+| AWS | 北京  | 标准版 | 0.195元/GiB/月  |
+|     | 新加坡 | 标准版 | 0.025美元/GiB/月 |
+
+当前，数据多版本和结果缓存费用限时免费。开始收费前1个月将提前通知。
+
+### **4.3 数据传输价格**
+
+| 云厂商 | 区域  | 版本  | Internet数据传输价格 |
+| --- | --- | --- | -------------- |
+| 阿里云 | 上海  | 标准版 | 0.8元/GB        |
+|     | 新加坡 | 标准版 | 0.081美元/GB     |
+| 腾讯云 | 北京  | 标准版 | 0.8元/GB        |
+|     | 上海  | 标准版 | 0.8元/GB        |
+|     | 广州  | 标准版 | 0.8元/GB        |
+| AWS | 北京  | 标准版 | 0.933元/GB      |
+|     | 新加坡 | 标准版 | 0.12美元/GB      |
+
+^
+
+## 5. 常见场景下的费用示例
+
+**通用型计算集群费用示例**
+
+以阿里云上海企业版服务实例为例：
+
+* 一个规格为2CRU的通用型计算集群，运行1小时，CRU\*时单价为3.5元，该计算集群运行1小时的费用为： 1小时\*2CRU\*3.5元/CRU\*时 = 7元
+* 一个规格为1CRU的通用型计算集群，运行1分20秒，CRU\*时单价为3.5元，该计算集群运行产生的费用为：1.33分钟/60分钟\*1CRU\*3.5元/CRU\*时=0.078元
+* 一个规格为1CRU的通用型计算集群，运行30秒，CRU\*时单价为3.5元，该计算集群运行产生的费用为：0.5分钟/60分钟\*1CRU\*3.5元/CRU\*时=0.029元 。
+
+**分析型计算集群费用示例**
+
+以阿里云上海企业版服务实例为例：
+
+* 一个规格为2CRU的分析型集群，分别以1个实例运行了30分钟，又以2个实例运行了30分钟，当CRU\*时单价为3.5元，该计算集群运行产生的费用为：
+
+  30分钟/60分钟\*1CRU\*1个实例\*3.5元/CRU\*时 + 30分钟/60分钟\*1CRU\*2个实例\*3.5元/CRU\*时 = 1.75元 + 3.5元 = 5.25元
+
+**同步型计算集群价格费用示例**
+
+以阿里云上海企业版服务实例为例：
+
+* 一个规格为2CRU的同步型集群，运行1小时，当CRU\*时单价为3.5元，该计算集群运行1小时的费用为： 1小时\*2CRU\*3.5元/CRU\*时 = 7元
+
+**离线集成任务费用示例**
+
+离线集成任务不单独收费，而是收取任务提交至的同步型计算集群的运行费用。离线集成任务可自动唤起同步型计算集群。一般估算离线集成任务时，可按照：5个单并发的离线集成任务可用满一个规格为0.25的同步型计算集群资源来估算离线集成任务。
+
+* 假设阿里云上海一个企业版服务实例的一个单并发离线集成任务运行10分钟，其消耗的算力约为：1/5 CRU \* 10分钟/60分钟 = 0.033 CRU\*时;
+* 因离线集成任务会唤起同步型计算集群，假设阿里云上海一个企业版服务实例的同步型计算集群的规格为1 CRU，10分钟任务结束后自动关闭，则产生的费用为：1CRU\*10分钟/60分钟\*3.5元/CRU\*时 = 0.58元；
+
+此时该规格为1 CRU的同步型计算集群还未用满，再提交4个单并发离线集成任务，假设均运行10分钟，其产生的费用仍为 0.58元。因此，尽量复用同步型计算集群的资源，同时避免使用过大规格的同步型计算集群能有效节省计算资源费用。
+
+**实时集成任务费用示例**
+
+实时集成任务不单独收费，而是收取任务提交至的同步型计算集群的运行费用。实时集成任务需要将其所在的同步型计算集群一直保持“运行”状态。因此需要选择尽量贴近实时集成任务所需的资源量创建同步型计算集群规格，避免资源浪费。可按照：16个单并发的实时集成任务可用满一个规格为1CRU的同步型计算集群资源来估算。
+
+**Python脚本任务费用示例**
+
+Python脚本任务执行时，会根据任务执行时长和消耗的计算资源进行计费。一般情况下，一个Python脚本执行1小时时，所使用的计算资源为0.125 CRU\*小时。
+
+* 假设阿里云上海一个企业版服务实例的一个Python脚本任务执行时间为10分钟，其产生的费用为：0.125CRU\*时\*10分钟/60分钟\*3.5元/CRU\*时=0.073元。
+
+**存储容量费用示例**
+
+* 假设在阿里云上海一个企业版服务实例的工作空间下，全天的存储容量低点为910GiB，高点1100GiB，全天平均值为1000GiB，则当天存储容量为：1000 GiB \* 0.12元/GiB/月 /30天 = 4元
+
+**网络传输价格示例**
+
+* 假设在阿里云上海一个企业版服务实例下，1小时产生的Internet下行流量为10 GB，则该小时的Internet网络传输费用为：10GB\*0.8元/GB=8元
+
+^

package/bin/skills/lakehouse-doc/references/primary key.md

@@ -0,0 +1,86 @@
+# Clickzetta Lakehouse约束属性概述
+
+Clickzetta Lakehouse支持多种约束属性，以满足用户在数据写入、更新和维护过程中的需求。本文档将详细介绍Clickzetta Lakehouse的约束属性，并通过实例演示如何使用这些属性。
+
+## ANSI SQL约束属性
+
+ANSI SQL约束属性主要涉及以下几个方面：
+
+1. **ENFORCED | NOT ENFORCED**：指定是否强制执行约束。ENFORCED表示强制执行约束，NOT ENFORCED表示不强制执行约束。
+2. **DEFERRABLE | NOT DEFERRABLE**：指定延迟执行和非延迟执行。DEFERRABLE表示可以延迟执行约束，NOT DEFERRABLE表示立即执行约束。
+3. **INITIALLY { DEFERRED | IMMEDIATE** }：指定校验的时机。如果约束属性为NOT DEFERRABLE，则只能是INITIALLY IMMEDIATE。
+
+### 使用示例
+
+假设我们有一个订单表`orders`，其中包含以下字段：
+
+- `order_id`：订单ID，为主键。
+- `customer_id`：客户ID，为外键。
+- `order_date`：订单日期。
+- `total_amount`：订单总金额。
+
+我们可以为`orders`表定义以下约束：
+
+```sql
+CREATE TABLE orders (
+  order_id INT PRIMARY KEY ENFORCED,
+  customer_id INT REFERENCES customers DEFERRABLE INITIALLY DEFERRED,
+  UNIQUE (customer_id, order_date) ENFORCED
+);
+```
+
+在这个例子中，我们为`order_id`指定了ENFORCED属性，以确保每个订单都有一个唯一的ID。对于`customer_id`，我们使用了DEFERRABLE和INITIALLY DEFERRED属性，允许在插入数据时暂时违反外键约束。最后，我们为`customer_id`和`order_date`定义了一个唯一约束，以确保每个客户在同一天只能有一个订单。
+
+## 扩展的约束状态
+
+Clickzetta Lakehouse扩展的约束状态主要用于主键、外键和唯一键。这些约束状态包括：
+
+1. **ENABLE | DISABLE**：指定约束是禁用还是启动。ENABLE表示启动约束，DISABLE表示禁用约束。
+2. **VALIDATE | NOVALIDATE**：指定是否验证表上已有的数据，并创建索引。VALIDATE表示需要验证并创建索引，NOVALIDATE表示不需要验证和创建索引。
+3. **RELY | NORELY**：当指定NOVALIDATE为RELY时，查询优化器会使用此属性，提高查询性能。
+
+### 使用示例
+
+假设我们有一个销售记录表`sales`，其中包含以下字段：
+
+- `sale_id`：销售记录ID，为主键。
+- `product_id`：产品ID，为外键。
+- `sale_date`：销售日期。
+- `amount`：销售金额。
+
+我们可以为`sales`表定义以下约束：
+
+```sql
+CREATE TABLE sales (
+  sale_id INT PRIMARY KEY ENABLE VALIDATE RELY,
+  product_id INT REFERENCES products DISABLE NOVALIDATE NORELY
+);
+```
+
+在这个例子中，我们为`sale_id`指定了ENABLE、VALIDATE和RELY属性，以确保每个销售记录都有一个唯一的ID，并在插入数据时验证外键约束。对于`product_id`，我们使用了DISABLE、NOVALIDATE和NORELY属性，表示在插入数据时不验证外键约束，同时查询优化器可以提高查询性能。
+
+## 云器Lakehouse约束属性
+
+云器Lakehouse约束属性为ENABLE VALIDATE RELY，强制执行约束校验。需要注意的是，这种约束属性只支持使用Java SDK进行写入，不支持使用SQL进行插入。
+
+### 使用示例
+
+假设我们有一个用户表`users`，其中包含以下字段：
+
+- `user_id`：用户ID，为主键。
+- `username`：用户名。
+- `email`：电子邮件地址。
+
+我们可以使用Java SDK为`users`表定义以下约束：
+
+```java
+Table table = session.getTable("users");
+TableSchema schema = table.getSchema();
+PrimaryKeyConstraint primaryKeyConstraint = new PrimaryKeyConstraint("user_id");
+schema.addConstraint(primaryKeyConstraint);
+UniqueConstraint uniqueConstraint = new UniqueConstraint("username");
+schema.addConstraint(uniqueConstraint);
+session.createTable("users", schema, true);
+```
+
+在这个例子中，我们使用Java SDK创建了一个`users`表，并为其定义了一个主键约束和一个唯一约束。这些约束将强制执行，确保每个用户都有一个唯一的ID和用户名。由于使用了云器Lakehouse约束属性，我们无法通过SQL插入数据，只能使用Java SDK进行写入。

package/bin/skills/lakehouse-doc/references/primary-key.md

@@ -0,0 +1,187 @@
+# lakehouse 主键使用说明
+
+## 主键约束概述
+
+**主键（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;
+-- 此时插入成功，因为主键值 1 和 2 均未重复
+insert into test_primary values(1,"1");
+insert into test_primary values(2,"1");
+-- 插入失败，因为主键值 1 已存在
+insert into test_primary values(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 进行的写入操作将不会受到主键唯一性约束的限制，这可能导致数据中出现主键重复的情况。因此，在选择此种模式时，您需要对数据的写入来源和写入方式进行考虑和管理，以避免潜在的数据质量问题。
+
+# 主键表创建语法
+
+* 不带分区或分桶的主键表
+
+```
+CREATE TABLE pk_table
+(
+    id int,
+    col string,
+PRIMARY KEY (id)
+);
+CREATE TABLE pk_table
+(
+    id int PRIMARY KEY,
+    col string
+);
+```
+
+* 带分桶的主键表。
+  1. **未指定 DISABLE NOVALIDATE RELY 时**：
+
+     * Cluster Key 必须包含主键列
+     * 排序键必须包含主键
+  2. **指定 DISABLE NOVALIDATE RELY 时**：
+
+     * Cluster Key 可不包含主键列
+     * 排序键可不包含主键
+
+```
+--指定DISABLE NOVALIDATE RELY
+CREATE TABLE pk_table
+(
+    id int,
+    col string,
+    cluster_key string,
+    PRIMARY key (id) DISABLE NOVALIDATE RELY
+) 
+CLUSTERED BY ( cluster_key)  INTO 16 BUCKETS;
+--不指定DISABLE NOVALIDATE RELY
+CREATE TABLE pk_table
+(
+    id int,
+    col string,
+    cluster_key string,
+    PRIMARY key (id)
+) 
+CLUSTERED BY (id, cluster_key) SORTED BY (id) INTO 16 BUCKETS;
+
+
+```
+
+* 带主键的分区表。
+  1. **未指定 DISABLE NOVALIDATE RELY 时**：
+     * Partition Key 必须包含主键列
+  2. **指定 DISABLE NOVALIDATE RELY 时**：
+     * Partition Key 可不包含主键列
+
+```
+--指定DISABLE NOVALIDATE RELY
+CREATE TABLE pk_table
+(
+    id int,
+    col string,
+    pt string,
+    PRIMARY key (id)DISABLE NOVALIDATE RELY
+) PARTITIONED BY (pt);
+--不指定DISABLE NOVALIDATE RELY
+CREATE TABLE pk_table
+(
+    id int,
+    col string,
+    pt string,
+    PRIMARY key (id, pt)
+) PARTITIONED BY (pt);
+```
+
+# 使用注意事项
+
+**类型选择建议**
+
+* 优先使用数值类型（如 int/bigint 等）
+* 避免使用变长类型（如 string/varchar），以减少索引空间占用
+* 禁止使用浮点数类型（float/double）
+* 禁止使用嵌套类型
+  **约束条件**
+* 主键列必须定义为 NOT NULL
+* 不支持 Schema Evolution（表结构变更后主键不可修改）
+
+# 使用案例
+
+## 创建表
+
+在创建Lakehouse表时，需要指定主键。CDC写入会根据主键进行数据去重，以确保数据的准确性。创建的主键表不支持SQL操作，只能通过实时写入流进行数据写入。创建的主键表不支持也不支持使用SQL添加列和修改列。以下是一个创建表的示例：
+
+```sql
+CREATE TABLE igs_test_upsert (
+    id int PRIMARY KEY,
+    event varchar(100),
+    event_time STRING
+);
+```
+
+## SDK实时写入流
+
+### 创建实时写入流
+
+使用SDK创建实时写入流，需要指定操作类型（CDC）和相关选项。以下是一个创建实时写入流的示例：
+
+```java
+RowStream stream = client.newRealtimeStreamBuilder()
+    .operate(RowStream.RealtimeOperate.CDC)
+    .options(options)
+    .schema(schema)
+    .table(table)
+    .build(); // 关闭流，释放流资源，必须调用
+stream.close();
+```
+
+### 指定操作类型
+
+根据需求，可以指定不同的操作类型：
+
+* `Stream.Operator.UPSERT`：插入或更新行。如果目标行不存在，则插入；如果已存在，则更新。
+* `Stream.Operator.DELETE_IGNORE`：删除行。如果目标行不存在，则自动忽略。
+
+### 使用原生Java Sdk写入
+
+```java
+Row row = stream.createRow(Stream.Operator.UPSERT); // 插入或更新行
+Row rowToDelete = stream.createRow(Stream.Operator.DELETE_IGNORE); // 删除行
+```
+
+## 使用Lakehouse实时同步功能写入
+
+参考文档[多表实时同步](<multitable_realtime_sync.md>)
+
+## 使用FLINK CONNECTOR写入
+
+Flink connector是基于RealtimeStream SDK封装的，用于实现实时数据同步。查看[Flink Connector](<flink-write-connector.md>)
+
+## 参考
+
+[Java实时编程接口](java_reference/realtime-upload.md)
+
+[使用Java SDK读取Kafka数据实时上传数据](use-java-sdk-releatime-uploaddata.md)
+
+[云器Lakehouse多表实时同步实现CDC](czguide-intro-to-cdc-using-clickzetta-rtsync-dynamic-tables.md)