@clickzetta/cz-cli-darwin-arm64 0.3.19 → 0.3.21

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (40) hide show
  1. package/bin/cz-cli +0 -0
  2. package/bin/skills/clickzetta-access-control/eval_cases.jsonl +1 -1
  3. package/bin/skills/clickzetta-batch-sync-pipeline/eval_cases.jsonl +5 -0
  4. package/bin/skills/clickzetta-cdc-sync-pipeline/eval_cases.jsonl +5 -0
  5. package/bin/skills/clickzetta-dba-guide/SKILL.md +542 -0
  6. package/bin/skills/clickzetta-dba-guide/eval_cases.jsonl +3 -0
  7. package/bin/skills/clickzetta-dw-modeling/eval_cases.jsonl +1 -1
  8. package/bin/skills/clickzetta-dynamic-table/eval_cases.jsonl +5 -0
  9. package/bin/skills/clickzetta-file-import-pipeline/eval_cases.jsonl +5 -0
  10. package/bin/skills/clickzetta-lakehouse-connect/SKILL.md +218 -0
  11. package/bin/skills/clickzetta-lakehouse-connect/eval_cases.jsonl +3 -0
  12. package/bin/skills/clickzetta-lakehouse-connect/evals/evals.json +35 -0
  13. package/bin/skills/clickzetta-lakehouse-connect/references/config-file.md +435 -0
  14. package/bin/skills/clickzetta-lakehouse-connect/references/jdbc.md +478 -0
  15. package/bin/skills/clickzetta-lakehouse-connect/references/python-sdk.md +225 -0
  16. package/bin/skills/clickzetta-lakehouse-connect/references/sqlalchemy.md +468 -0
  17. package/bin/skills/clickzetta-lakehouse-connect/references/zettapark-session.md +445 -0
  18. package/bin/skills/clickzetta-manage-comments/SKILL.md +219 -0
  19. package/bin/skills/clickzetta-manage-comments/eval_cases.jsonl +3 -0
  20. package/bin/skills/clickzetta-metadata/SKILL.md +483 -0
  21. package/bin/skills/clickzetta-metadata/eval_cases.jsonl +5 -0
  22. package/bin/skills/clickzetta-metadata/references/instance-views-reference.md +276 -0
  23. package/bin/skills/clickzetta-metadata/references/metering-views-reference.md +137 -0
  24. package/bin/skills/clickzetta-metadata/references/show-desc-reference.md +326 -0
  25. package/bin/skills/clickzetta-metadata/references/views-reference.md +271 -0
  26. package/bin/skills/clickzetta-oss-ingest-pipeline/eval_cases.jsonl +5 -0
  27. package/bin/skills/clickzetta-overview/SKILL.md +102 -0
  28. package/bin/skills/clickzetta-overview/eval_cases.jsonl +5 -0
  29. package/bin/skills/clickzetta-overview/references/brands-and-endpoints.md +79 -0
  30. package/bin/skills/clickzetta-overview/references/object-model.md +311 -0
  31. package/bin/skills/clickzetta-overview/references/studio-modules.md +173 -0
  32. package/bin/skills/clickzetta-realtime-sync-pipeline/eval_cases.jsonl +5 -0
  33. package/bin/skills/clickzetta-sql-pipeline-manager/eval_cases.jsonl +12 -0
  34. package/bin/skills/clickzetta-table-stream-pipeline/eval_cases.jsonl +5 -0
  35. package/bin/skills/clickzetta-vcluster-manager/eval_cases.jsonl +5 -0
  36. package/bin/skills/clickzetta-volume-manager/eval_cases.jsonl +5 -0
  37. package/bin/skills/cz-cli-inner/SKILL.md +5 -4
  38. package/package.json +1 -1
  39. package/bin/skills/clickzetta-data-ingest-pipeline/SKILL.md +0 -220
  40. package/bin/skills/clickzetta-data-ingest-pipeline/eval_cases.jsonl +0 -5
@@ -0,0 +1,445 @@
1
+ # ZettaPark Session 详细参考
2
+
3
+ > **定位**:ZettaPark 是 ClickZetta Lakehouse 的 DataFrame API 库,提供类似 PySpark/Snowpark 的编程体验。
4
+ > **Python 版本**: 推荐 **Python 3.12**(最低 3.10,不支持 3.9 及以下)
5
+ > 本文档基于 `clickzetta_quickstart/Zettapark/` 目录下的真实代码整理。
6
+
7
+ ## 目录
8
+
9
+ 1. [安装](#1-安装)
10
+ 2. [创建 Session](#2-创建-session)
11
+ 3. [Session 上下文操作](#3-session-上下文操作)
12
+ 4. [核心导入](#4-核心导入)
13
+ 5. [DataFrame 构建](#5-dataframe-构建)
14
+ 6. [DataFrame 转换操作](#6-dataframe-转换操作)
15
+ 7. [操作方法(触发执行)](#7-操作方法触发执行)
16
+ 8. [写入数据](#8-写入数据)
17
+ 9. [关闭 Session](#9-关闭-session)
18
+ 10. [与 Python SDK 对比](#10-与-python-sdk-对比)
19
+ 11. [适用场景](#11-适用场景)
20
+ 12. [常见问题](#12-常见问题)
21
+
22
+ ---
23
+
24
+ ## 1. 安装
25
+
26
+ ```bash
27
+ # 方式 1:venv(Python 内置,推荐)
28
+ python3.12 -m venv .venv
29
+ source .venv/bin/activate # macOS/Linux | .venv\Scripts\activate (Windows)
30
+ pip install clickzetta-zettapark-python -i https://pypi.tuna.tsinghua.edu.cn/simple
31
+
32
+ # 方式 2:pyenv(需要切换 Python 版本时)
33
+ pyenv install 3.12.9 && pyenv local 3.12.9
34
+ python -m venv .venv && source .venv/bin/activate
35
+ pip install clickzetta-zettapark-python -i https://pypi.tuna.tsinghua.edu.cn/simple
36
+
37
+ # 方式 3:conda(数据科学环境)
38
+ conda create -n lakehouse python=3.12 -y && conda activate lakehouse
39
+ pip install clickzetta-zettapark-python -i https://pypi.tuna.tsinghua.edu.cn/simple
40
+ ```
41
+
42
+ 验证安装:
43
+
44
+ ```python
45
+ import clickzetta.zettapark as C
46
+ print(f"ZettaPark version: {C.__version__}")
47
+ ```
48
+
49
+ ---
50
+
51
+ ## 2. 创建 Session
52
+
53
+ ### 2.1 直接使用字典
54
+
55
+ ```python
56
+ from clickzetta.zettapark.session import Session
57
+
58
+ config = {
59
+ "service": "your-region.api.clickzetta.com", # 按实例所在区域填写,参见 SKILL.md 区域地址表
60
+ "username": "my_user",
61
+ "password": "my_password",
62
+ "instance": "my_instance",
63
+ "workspace": "my_workspace",
64
+ "schema": "public",
65
+ "vcluster": "default_ap",
66
+ }
67
+
68
+ session = Session.builder.configs(config).create()
69
+ ```
70
+
71
+ ### 2.2 从 config.json 加载(推荐)
72
+
73
+ 项目中的标准做法是将连接参数存放在 `config.json` 中(参见 `clickzetta_quickstart/Zettapark/config.json`):
74
+
75
+ ```json
76
+ {
77
+ "username": "your_username",
78
+ "password": "your_password",
79
+ "service": "your-region.api.clickzetta.com",
80
+ "instance": "your_instance_id",
81
+ "workspace": "your_workspace",
82
+ "schema": "public",
83
+ "vcluster": "default_ap",
84
+ "sdk_job_timeout": 10,
85
+ "hints": {
86
+ "sdk.job.timeout": 3,
87
+ "query_tag": "Introduction to Zettapark for Python"
88
+ }
89
+ }
90
+ ```
91
+
92
+ 加载并创建 Session:
93
+
94
+ ```python
95
+ import json
96
+ from clickzetta.zettapark.session import Session
97
+
98
+ with open("config.json", "r") as f:
99
+ config = json.load(f)
100
+
101
+ session = Session.builder.configs(config).create()
102
+ ```
103
+
104
+ ### 2.3 使用环境变量
105
+
106
+ ```python
107
+ import os
108
+ from clickzetta.zettapark.session import Session
109
+
110
+ config = {
111
+ "service": os.environ["CLICKZETTA_SERVICE"],
112
+ "username": os.environ["CLICKZETTA_USERNAME"],
113
+ "password": os.environ["CLICKZETTA_PASSWORD"],
114
+ "instance": os.environ["CLICKZETTA_INSTANCE"],
115
+ "workspace": os.environ["CLICKZETTA_WORKSPACE"],
116
+ "schema": os.environ.get("CLICKZETTA_SCHEMA", "public"),
117
+ "vcluster": os.environ.get("CLICKZETTA_VCLUSTER", "default_ap"),
118
+ }
119
+
120
+ session = Session.builder.configs(config).create()
121
+ ```
122
+
123
+ ### 2.4 连接参数说明
124
+
125
+ | 参数 | 必填 | 说明 | 示例 |
126
+ |:--|:--|:--|:--|
127
+ | `service` | ✅ | API 端点(含区域前缀) | `cn-shanghai-alicloud.api.clickzetta.com` |
128
+ | `username` | ✅ | 登录用户名 | `my_user` |
129
+ | `password` | ✅ | 登录密码 | `my_password` |
130
+ | `instance` | ✅ | 实例标识 | `my_instance` |
131
+ | `workspace` | ✅ | 工作空间 | `gharchive` |
132
+ | `schema` | ✅ | 默认 Schema | `public` |
133
+ | `vcluster` | ✅ | 虚拟集群 | `default_ap` |
134
+ | `sdk_job_timeout` | ❌ | SDK 作业超时(秒) | `10` |
135
+ | `hints` | ❌ | 查询提示字典 | `{"sdk.job.timeout": 3}` |
136
+
137
+ ---
138
+
139
+ ## 3. Session 上下文操作
140
+
141
+ 创建 Session 后,可以查询和切换当前上下文:
142
+
143
+ ```python
144
+ # 查询当前 Schema
145
+ current_schema = session.get_current_schema()
146
+ print(f"Current schema: {current_schema}")
147
+
148
+ # 切换 Schema
149
+ session.use_schema("my_other_schema")
150
+
151
+ # 启用 SQL 简化器(可选)
152
+ session.sql_simplifier_enabled = True
153
+
154
+ # 查看可用虚拟集群
155
+ session.sql("SHOW VCLUSTERS").show()
156
+
157
+ # 查看可用 Schema
158
+ session.sql("SHOW SCHEMAS").show()
159
+ ```
160
+
161
+ ---
162
+
163
+ ## 4. 核心导入
164
+
165
+ ZettaPark 提供以下常用模块:
166
+
167
+ ```python
168
+ import clickzetta.zettapark as C
169
+ from clickzetta.zettapark import Session
170
+ from clickzetta.zettapark import functions as F
171
+ from clickzetta.zettapark import Window
172
+ from clickzetta.zettapark import Row
173
+ import clickzetta.zettapark.types as T
174
+ from clickzetta.zettapark.types import IntegerType, StringType, StructType, StructField
175
+ ```
176
+
177
+ ---
178
+
179
+ ## 5. DataFrame 构建
180
+
181
+ ZettaPark 的核心是 DataFrame——一个延迟评估的关系数据集,只在触发操作方法(如 `show()`、`collect()`)时才执行。
182
+
183
+ ### 5.1 从 SQL 查询创建
184
+
185
+ ```python
186
+ df = session.sql("SELECT * FROM my_table LIMIT 10")
187
+ df.show()
188
+ ```
189
+
190
+ ### 5.2 从表创建
191
+
192
+ ```python
193
+ df = session.table("sample_product_data")
194
+ df.show()
195
+ ```
196
+
197
+ ### 5.3 从本地数据创建
198
+
199
+ ```python
200
+ # 单列
201
+ df1 = session.create_dataframe([1, 2, 3, 4]).to_df("a")
202
+ df1.show()
203
+
204
+ # 多列(使用 schema 列表)
205
+ df2 = session.create_dataframe([[1, 2, 3, 4]], schema=["a", "b", "c", "d"])
206
+ df2.show()
207
+
208
+ # 使用 Row 对象
209
+ from clickzetta.zettapark import Row
210
+ df3 = session.create_dataframe([Row(a=1, b=2, c=3, d=4)])
211
+ df3.show()
212
+
213
+ # 使用 StructType 指定完整 Schema
214
+ from clickzetta.zettapark.types import IntegerType, StringType, StructType, StructField
215
+
216
+ schema = StructType([
217
+ StructField("a", IntegerType()),
218
+ StructField("b", StringType()),
219
+ ])
220
+ df4 = session.create_dataframe([[1, "click"], [3, "zetta"]], schema)
221
+ df4.show()
222
+ ```
223
+
224
+ ### 5.4 从范围创建
225
+
226
+ ```python
227
+ df_range = session.range(1, 10, 2).to_df("a")
228
+ df_range.show()
229
+ ```
230
+
231
+ ---
232
+
233
+ ## 6. DataFrame 转换操作
234
+
235
+ DataFrame 操作会被翻译成 SQL 在 Lakehouse 中执行,实现分布式计算。例如:
236
+
237
+ ```python
238
+ df_filtered = df.filter((F.col("a") + F.col("b")) < 10)
239
+ ```
240
+
241
+ 会被翻译为:
242
+
243
+ ```sql
244
+ SELECT `a`, `b` FROM (...) WHERE ((`a` + `b`) < CAST(10 AS INT))
245
+ ```
246
+
247
+ ### 6.1 过滤(filter)
248
+
249
+ ```python
250
+ from clickzetta.zettapark import functions as F
251
+
252
+ # 等值过滤
253
+ df = session.table("sample_product_data").filter(F.col("id") == 1)
254
+ df.show()
255
+
256
+ # 表达式过滤
257
+ df = session.create_dataframe([[1, 3], [2, 10]], schema=["a", "b"])
258
+ df_filtered = df.filter((F.col("a") + F.col("b")) < 10)
259
+ df_filtered.show()
260
+ ```
261
+
262
+ ### 6.2 选择列(select)
263
+
264
+ ```python
265
+ # 使用 F.col()
266
+ df = session.table("sample_product_data").select(
267
+ F.col("id"), F.col("name"), F.col("serial_number")
268
+ )
269
+
270
+ # 使用下标访问
271
+ df_info = session.table("sample_product_data")
272
+ df1 = df_info.select(df_info["id"], df_info["name"], df_info["serial_number"])
273
+
274
+ # 使用属性访问
275
+ df2 = df_info.select(df_info.id, df_info.name, df_info.serial_number)
276
+
277
+ # 使用字符串列名
278
+ df3 = df_info.select("id", "name", "serial_number")
279
+ ```
280
+
281
+ ### 6.3 分组聚合(group_by / agg)
282
+
283
+ ```python
284
+ df_campaign = session.table("CAMPAIGN_SPEND")
285
+
286
+ # 单一聚合
287
+ df_yearly = df_campaign.group_by(F.year("DATE"), "CHANNEL").sum("TOTAL_COST")
288
+ df_yearly.show()
289
+
290
+ # 多重聚合
291
+ df_campaign.group_by(F.year("DATE"), "CHANNEL").agg([
292
+ F.sum("TOTAL_COST").as_("TOTAL_COST"),
293
+ F.avg("TOTAL_COST").as_("AVG_COST"),
294
+ ]).show()
295
+ ```
296
+
297
+ ### 6.4 连接(join)
298
+
299
+ ```python
300
+ df_lhs = session.create_dataframe([["a", 1], ["b", 2]], schema=["key", "value1"])
301
+ df_rhs = session.create_dataframe([["a", 3], ["b", 4]], schema=["key", "value2"])
302
+
303
+ df_lhs.join(
304
+ df_rhs,
305
+ df_lhs.col("key") == df_rhs.col("key")
306
+ ).select(
307
+ df_lhs["key"].as_("key"), "value1", "value2"
308
+ ).show()
309
+ ```
310
+
311
+ 自连接示例:
312
+
313
+ ```python
314
+ import copy
315
+ df = session.table("sample_product_data")
316
+ df_copy = copy.copy(df)
317
+ df_joined = df.join(df_copy, F.col("id") == F.col("parent_id"))
318
+ ```
319
+
320
+ ---
321
+
322
+ ## 7. 操作方法(触发执行)
323
+
324
+ DataFrame 是延迟评估的,以下方法会触发实际执行:
325
+
326
+ | 方法 | 说明 | 示例 |
327
+ |:--|:--|:--|
328
+ | `show(n)` | 打印前 n 行(默认 10) | `df.show()` |
329
+ | `collect()` | 返回所有行的 Row 列表 | `rows = df.collect()` |
330
+ | `to_pandas()` | 转为 Pandas DataFrame | `pd_df = df.to_pandas()` |
331
+ | `queries` | 查看将要执行的 SQL(不触发执行) | `df.queries` |
332
+
333
+ ### 7.1 查看生成的 SQL
334
+
335
+ ```python
336
+ df = session.table("CAMPAIGN_SPEND")
337
+ print(df.queries)
338
+ # {'queries': ['SELECT * FROM CAMPAIGN_SPEND'], 'post_actions': []}
339
+ ```
340
+
341
+ ### 7.2 转为 Pandas DataFrame
342
+
343
+ ```python
344
+ pd_data = df_yearly.to_pandas()
345
+
346
+ # 配合可视化库使用
347
+ import seaborn as sns
348
+ import matplotlib.pyplot as plt
349
+
350
+ fig, ax = plt.subplots(figsize=(16, 5))
351
+ sns.barplot(data=pd_data, x="year", y="total_cost", hue="channel", ax=ax)
352
+ plt.show()
353
+ ```
354
+
355
+ ---
356
+
357
+ ## 8. 写入数据
358
+
359
+ ### 8.1 保存为表
360
+
361
+ ```python
362
+ # 覆盖写入
363
+ df.write.save_as_table("my_table", mode="overwrite")
364
+
365
+ # 追加写入
366
+ df.write.save_as_table("my_temp_table", mode="append")
367
+ ```
368
+
369
+ > **注意**:ClickZetta 不支持 `table_type="transient"` 参数(该参数来自 Snowflake)。如需临时存储,直接使用普通表,并通过 `data_lifecycle` 属性设置 TTL 或手动清理。
370
+
371
+ ### 8.2 通过 SQL 创建表并插入数据
372
+
373
+ ```python
374
+ # 创建表
375
+ session.sql("""
376
+ CREATE TABLE IF NOT EXISTS sample_product_data (
377
+ id INT, parent_id INT, category_id INT,
378
+ name STRING, serial_number STRING, key INT, third INT
379
+ )
380
+ """).collect()
381
+
382
+ # 插入数据
383
+ session.sql("""
384
+ INSERT INTO sample_product_data VALUES
385
+ (1, 0, 5, 'Product 1', 'prod-1', 1, 10),
386
+ (2, 1, 5, 'Product 1A', 'prod-1-A', 1, 20),
387
+ (3, 1, 5, 'Product 1B', 'prod-1-B', 1, 30)
388
+ """).collect()
389
+ ```
390
+
391
+ ---
392
+
393
+ ## 9. 关闭 Session
394
+
395
+ ```python
396
+ session.close()
397
+ ```
398
+
399
+ ---
400
+
401
+ ## 10. 与 Python SDK 对比
402
+
403
+ | 特性 | Python SDK (`clickzetta-connector-python`) | ZettaPark Session (`clickzetta-zettapark-python`) |
404
+ |:--|:--|:--|
405
+ | 返回类型 | Cursor(行级别) | DataFrame |
406
+ | API 风格 | DB-API 2.0 (`connect` → `cursor` → `execute`) | DataFrame API (`Session.builder` → `table` / `sql`) |
407
+ | 适用场景 | 简单 SQL 查询、脚本自动化 | ETL 管道、数据工程、数据探索 |
408
+ | 延迟执行 | 否(立即执行) | 是(调用 `show()` / `collect()` 时执行) |
409
+ | Pandas 集成 | `cursor.fetch_pandas_all()` | `df.to_pandas()` |
410
+ | 写入数据 | 通过 SQL INSERT | `df.write.save_as_table()` |
411
+ | 依赖包 | `clickzetta-connector-python` | `clickzetta-zettapark-python` |
412
+
413
+ ---
414
+
415
+ ## 11. 适用场景
416
+
417
+ - **数据工程 / ETL 管道**:使用 DataFrame 转换链构建数据处理流水线
418
+ - **数据探索**:在 Jupyter Notebook 中交互式分析数据
419
+ - **特征工程**:结合 `group_by`、`agg`、`Window` 函数生成特征
420
+ - **可视化前处理**:通过 `to_pandas()` 转换后配合 matplotlib / seaborn 绑图
421
+ - **批量数据写入**:通过 `save_as_table()` 将处理结果写回 Lakehouse
422
+
423
+ ---
424
+
425
+ ## 12. 常见问题
426
+
427
+ ### Q: ZettaPark 和 PySpark 有什么关系?
428
+
429
+ ZettaPark 提供了类似 PySpark / Snowpark 的 DataFrame API,但底层执行引擎是 ClickZetta Lakehouse。代码风格高度相似,熟悉 PySpark 的开发者可以快速上手。
430
+
431
+ ### Q: `show()` 和 `collect()` 有什么区别?
432
+
433
+ - `show()` 打印格式化的表格输出到控制台,默认显示前 10 行
434
+ - `collect()` 返回所有行的 `Row` 对象列表,适合程序化处理
435
+
436
+ ### Q: 如何查看 DataFrame 将要执行的 SQL?
437
+
438
+ 使用 `df.queries` 属性查看生成的 SQL,不会触发实际执行。
439
+
440
+ ---
441
+
442
+ > **交叉引用**:
443
+ > - 主指南:[SKILL.md](../SKILL.md)
444
+ > - Python SDK 参考:[python-sdk.md](./python-sdk.md)
445
+ > - 配置文件管理:[config-file.md](./config-file.md)
@@ -0,0 +1,219 @@
1
+ ---
2
+ name: clickzetta-manage-comments
3
+ description: >
4
+ 管理 ClickZetta Lakehouse 各类对象的注释(COMMENT),包括增加、修改、删除注释。
5
+ 支持对象:Schema、普通表、外部表、字段、动态表(Dynamic Table)、物化视图(Materialized View)、
6
+ VCluster、Workspace。
7
+ 当用户说"加注释"、"改注释"、"删注释"、"补注释"、"更新注释"、"清除注释"、
8
+ "加 comment"、"补充元数据"、"给表/字段/schema/动态表/物化视图/计算集群/工作空间 加描述/改描述/删描述"、
9
+ "COMMENT 相关操作"、"更新字段说明"时触发。
10
+ 包含 ClickZetta 特有的注释语法(与标准 SQL 不同),以及各对象类型的语法差异和单引号转义处理。
11
+ 务必在用户提到 ClickZetta 注释、元数据补充、字段描述、表说明等场景时使用此 skill。
12
+ Keywords: COMMENT, annotation, table comment, column comment, metadata
13
+ ---
14
+
15
+ # ClickZetta 注释管理
16
+
17
+ ClickZetta 的注释语法与标准 SQL(`COMMENT ON ...`)不同,使用错误语法会直接报错。
18
+ 本 skill 固化了各类对象的增、改、删正确语法。
19
+
20
+ > 增加和修改注释使用完全相同的语法(覆盖写入即可),删除注释通过设置空字符串 `''` 实现,不支持 `NULL`。
21
+
22
+ ---
23
+
24
+ ## 各对象注释语法
25
+
26
+ ### 1. Schema
27
+
28
+ ```sql
29
+ -- 增加 / 修改
30
+ ALTER SCHEMA <schema_name> SET COMMENT '<comment>';
31
+
32
+ -- 删除
33
+ ALTER SCHEMA <schema_name> SET COMMENT '';
34
+ ```
35
+
36
+ ### 2. 普通表 / 外部表(External Table)
37
+
38
+ 两者语法完全相同,统一用 `ALTER TABLE`:
39
+
40
+ ```sql
41
+ -- 表注释:增加 / 修改
42
+ ALTER TABLE <schema_name>.<table_name> SET COMMENT '<comment>';
43
+
44
+ -- 表注释:删除
45
+ ALTER TABLE <schema_name>.<table_name> SET COMMENT '';
46
+
47
+ -- 字段注释:增加 / 修改
48
+ ALTER TABLE <schema_name>.<table_name> CHANGE COLUMN <col_name> COMMENT '<comment>';
49
+
50
+ -- 字段注释:删除
51
+ ALTER TABLE <schema_name>.<table_name> CHANGE COLUMN <col_name> COMMENT '';
52
+ ```
53
+
54
+ > 字段注释**不能**用 `ALTER COLUMN ... COMMENT`,必须用 `CHANGE COLUMN`。
55
+
56
+ ### 3. 动态表(Dynamic Table)
57
+
58
+ 动态表有专属的 `ALTER DYNAMIC TABLE` 语法:
59
+
60
+ ```sql
61
+ -- 表注释:增加 / 修改
62
+ ALTER DYNAMIC TABLE <dt_name> SET COMMENT '<comment>';
63
+
64
+ -- 表注释:删除
65
+ ALTER DYNAMIC TABLE <dt_name> SET COMMENT '';
66
+
67
+ -- 字段注释:增加 / 修改
68
+ ALTER DYNAMIC TABLE <dt_name> CHANGE COLUMN <col_name> COMMENT '<comment>';
69
+
70
+ -- 字段注释:删除
71
+ ALTER DYNAMIC TABLE <dt_name> CHANGE COLUMN <col_name> COMMENT '';
72
+ ```
73
+
74
+ ### 4. 物化视图(Materialized View)
75
+
76
+ 注意:物化视图的注释修改用的是 `ALTER TABLE`,不是 `ALTER MATERIALIZED VIEW`:
77
+
78
+ ```sql
79
+ -- 表注释:增加 / 修改
80
+ ALTER TABLE <mv_name> SET COMMENT '<comment>';
81
+
82
+ -- 表注释:删除
83
+ ALTER TABLE <mv_name> SET COMMENT '';
84
+
85
+ -- 字段注释:增加 / 修改
86
+ ALTER TABLE <mv_name> CHANGE COLUMN <col_name> COMMENT '<comment>';
87
+
88
+ -- 字段注释:删除
89
+ ALTER TABLE <mv_name> CHANGE COLUMN <col_name> COMMENT '';
90
+ ```
91
+
92
+ ### 5. VCluster(计算集群)
93
+
94
+ ```sql
95
+ -- 增加 / 修改
96
+ ALTER VCLUSTER <vc_name> SET COMMENT '<comment>';
97
+
98
+ -- 删除
99
+ ALTER VCLUSTER <vc_name> SET COMMENT '';
100
+ ```
101
+
102
+ ### 6. Workspace(工作空间)
103
+
104
+ ```sql
105
+ -- 增加 / 修改
106
+ ALTER WORKSPACE <ws_name> SET COMMENT '<comment>';
107
+
108
+ -- 删除
109
+ ALTER WORKSPACE <ws_name> SET COMMENT '';
110
+ ```
111
+
112
+ ---
113
+
114
+ ## 不支持 ALTER COMMENT 的对象
115
+
116
+ 以下对象**只能在 CREATE 时**通过 `COMMENT` 参数指定注释,创建后无法通过 ALTER 修改:
117
+
118
+ | 对象 | 说明 |
119
+ |---|---|
120
+ | VIEW(普通视图) | 无 `ALTER VIEW SET COMMENT` 语法;可用 `CREATE OR REPLACE VIEW ... COMMENT '...' AS ...` 更新注释,无需 DROP |
121
+ | FUNCTION / PROCEDURE | 只能在 CREATE 时指定,无 ALTER 修改注释的语法 |
122
+ | VOLUME | 无 ALTER VOLUME SET COMMENT 语法 |
123
+ | PIPE | 无 ALTER PIPE SET COMMENT 语法 |
124
+ | TABLE STREAM | 无 ALTER STREAM SET COMMENT 语法 |
125
+ | USER | `ALTER USER` 只支持 `DEFAULT_VCLUSTER` / `DEFAULT_SCHEMA`,不支持 COMMENT |
126
+ | ROLE | 只能在 `CREATE ROLE ... COMMENT '...'` 时设置 |
127
+ | CONNECTION | 只能在 CREATE CONNECTION 时指定 COMMENT,无 ALTER 修改语法 |
128
+ | INDEX | 只能在 CREATE INDEX 时指定 COMMENT(如 `CREATE BLOOMFILTER INDEX idx ON TABLE t(col) COMMENT '...'`),无 ALTER 修改语法 |
129
+
130
+ 如果用户需要修改这些对象的注释:
131
+ - **VIEW**:使用 `CREATE OR REPLACE VIEW view_name COMMENT '新注释' AS <原查询>` 直接替换,无需 DROP
132
+ - **其他对象**:需要 DROP 后重新 CREATE(注意评估影响)
133
+
134
+ ---
135
+
136
+ ## 常见错误语法(不要使用)
137
+
138
+ | 错误写法 | 正确写法 |
139
+ |---|---|
140
+ | `COMMENT ON TABLE t IS '...'` | `ALTER TABLE t SET COMMENT '...'` |
141
+ | `COMMENT ON SCHEMA s IS '...'` | `ALTER SCHEMA s SET COMMENT '...'` |
142
+ | `ALTER TABLE t ALTER COLUMN c COMMENT '...'` | `ALTER TABLE t CHANGE COLUMN c COMMENT '...'` |
143
+ | `ALTER TABLE t SET COMMENT NULL` | `ALTER TABLE t SET COMMENT ''`(删除用空字符串)|
144
+ | `ALTER MATERIALIZED VIEW mv SET COMMENT '...'` | `ALTER TABLE mv SET COMMENT '...'`(物化视图用 ALTER TABLE)|
145
+
146
+ ---
147
+
148
+ ## 单引号转义
149
+
150
+ 注释内容中如果含有单引号(如 `it's`),需要用两个单引号转义:
151
+
152
+ ```sql
153
+ ALTER TABLE t SET COMMENT 'it''s a player table';
154
+ ```
155
+
156
+ Python 中统一处理:
157
+
158
+ ```python
159
+ comment = comment.replace("'", "''")
160
+ sql = f"ALTER TABLE {schema}.{table} SET COMMENT '{comment}'"
161
+ ```
162
+
163
+ ---
164
+
165
+ ## 批量操作示例
166
+
167
+ ```python
168
+ import clickzetta
169
+
170
+ conn = clickzetta.connect(...)
171
+ cursor = conn.cursor()
172
+
173
+ # 批量修改表注释
174
+ table_comments = {
175
+ "players": "玩家基础信息表 | Steam player profiles",
176
+ "games": "游戏基础信息表 | Game metadata",
177
+ }
178
+ for table, comment in table_comments.items():
179
+ c = comment.replace("'", "''")
180
+ cursor.execute(f"ALTER TABLE my_schema.{table} SET COMMENT '{c}'")
181
+
182
+ # 批量修改字段注释
183
+ col_comments = [
184
+ ("players", "playerid", "玩家唯一标识符 | Unique player ID"),
185
+ ("players", "country", "玩家所在国家 | Player country"),
186
+ ]
187
+ for table, col, comment in col_comments:
188
+ c = comment.replace("'", "''")
189
+ cursor.execute(f"ALTER TABLE my_schema.{table} CHANGE COLUMN {col} COMMENT '{c}'")
190
+
191
+ # 动态表注释
192
+ cursor.execute("ALTER DYNAMIC TABLE my_schema.dt_orders SET COMMENT '订单动态表'")
193
+
194
+ # VCluster 注释
195
+ cursor.execute("ALTER VCLUSTER default SET COMMENT '默认通用计算集群'")
196
+
197
+ cursor.close()
198
+ conn.close()
199
+ ```
200
+
201
+ ---
202
+
203
+ ## 验证注释是否生效
204
+
205
+ ```sql
206
+ DESCRIBE SCHEMA <schema_name>;
207
+ DESCRIBE TABLE <schema_name>.<table_name>;
208
+ DESCRIBE DYNAMIC TABLE <schema_name>.<dt_name>;
209
+ ```
210
+
211
+ ---
212
+
213
+ ## 操作流程
214
+
215
+ 1. 确认目标对象类型(schema / 普通表 / 外部表 / 动态表 / 物化视图 / VCluster / Workspace)
216
+ 2. 如果是不支持 ALTER COMMENT 的对象(VIEW、FUNCTION 等),告知用户只能 DROP + CREATE
217
+ 3. 对注释内容中的单引号做转义
218
+ 4. 执行对应 SQL
219
+ 5. 用 `DESCRIBE` 验证结果
@@ -0,0 +1,3 @@
1
+ {"case_id":"001","type":"should_call","user_input":"怎么给表加注释?字段注释怎么写?","expected_skill":"clickzetta-manage-comments","expected_output_contains":["COMMENT"]}
2
+ {"case_id":"002","type":"should_call","user_input":"动态表和物化视图怎么加注释?语法和普通表一样吗?","expected_skill":"clickzetta-manage-comments","expected_output_contains":["COMMENT","DYNAMIC TABLE"]}
3
+ {"case_id":"003","type":"should_call","user_input":"怎么删除或清空一个字段的注释?","expected_skill":"clickzetta-manage-comments","expected_output_contains":["COMMENT"]}