@clickzetta/cz-cli-darwin-x64 0.3.1

package/bin/skills/lakehouse-doc/references/external-hudi-table.md

@@ -0,0 +1,187 @@
+# HUDI外部表
+>**【预览发布】本功能当前处于公开预览发布阶段。**
+
+HUDI为数据湖中的数据引入了结构化存储层，极大地提升了数据湖的易用性，使其操作体验接近于数据仓库。通过Lakehouse支持的外部表功能，用户能够便捷地访问和操作这些结构化数据。
+
+## 创建HUDI格式外部表
+
+\[创建外部表语法]\(create-external-table.md)
+
+**示例**
+
+```SQL
+--创建conneciton
+CREATE STORAGE CONNECTION if not exists oss_hudi
+    TYPE oss
+    ENDPOINT = 'oss-cn-beijing.aliyuncs.com'
+    access_id = 'xxx'
+    access_key = 'xxxx'
+    comments = 'hudi';
+--创建外部表,使用上面的连接信息
+CREATE EXTERNAL TABLE IF NOT EXISTS sales_data
+(
+  order_id INT,
+  product_id STRING,
+  sale_amount DOUBLE
+)
+PARTITIONED BY (dt STRING)
+USING HUDI
+CONNECTION oss_hudi
+LOCATION 'oss://my-bucket/data/sales'
+COMMENT 'External table for sales data stored in OSS';
+```
+
+## 删除外部表
+
+```SQL
+DROP TABLE [ IF EXISTS ] [schema_name.]<table_name
+```
+
+**参数说明**
+
+* `IF EXISTS`：可选，如果指定的表不存在，系统不会报错。
+* `schema_name`：可选，指定 schema 的名称。如果未指定，默认使用当前用户的 schema。
+* `table_name`：要删除的表名称。
+
+**说明**
+
+* 删除外部表并不会删除数据，因为数据存储在外部系统中，删除操作只会删除表的映射信息。
+
+**示例**
+
+```SQL
+--删除已经创建的外部表
+DROP TABLE sales_data;
+--删除名为 sales_data 的表，如果表不存在，不报错：
+DROP TABLE IF EXISTS sales_data;
+--删除名为 my_schema 下的 sales_data表
+DROP TABLE my_schema.my_table;
+```
+
+## 查看外部表详情
+
+```SQL
+DESC[RIBE] [TABLE] [EXTENDED] table_name;
+```
+
+**参数说明**
+
+* **DESC\\\[RIBE]**：DESC和DESCRIBE可以互换使用，都表示描述表结构的命令。
+* **TABLE**：可选参数，用于指定查看表结构的类型，如BASE TABLE或VIEW等。
+* **EXTENDED**：可选参数，加入此关键字后，可以展示更多扩展信息，如表的创建语句和Location信息等。
+* **table\\\_name**：指定需要查看结构的表名。
+
+## 修改外部表
+
+### 重命名表
+
+通过ALTER TABLE命令，您可以将现有的表重命名为新的表名。
+
+**语法**
+
+```SQL
+ALTER TABLE name RENAME TO new_table_name;
+```
+
+**示例**
+
+```SQL
+ALTER TABLE old_table_name RENAME TO new_table_name;
+```
+
+### 修改表注释
+
+通过ALTER TABLE命令，您可以为表添加或修改注释。
+
+**语法**
+
+```SQL
+ALTER TABLE tbname SET COMMENT '';
+```
+
+**示例**
+
+```SQL
+ALTER TABLE scores SET COMMENT '这是一个成绩表';
+```
+
+## **外部表计费**
+
+* **存储费用**：外部表不产生存储费用，因为数据不存储在 Lakehouse 中。
+* **计算费用**：使用外部表进行计算会消耗计算资源，因此会产生计算费用。
+
+## **外部表权限**
+
+外部表和内部表权限点相同。由于外部表无法执行 INSERT、UPDATE、TRUNCATE、DELETE、UNDROP 等操作，因此没有对应的操作权限点。
+
+* **创建权限**：需要具有创建表（create table）的权限。
+* **删除权限**：需要具有删除（DROP）权限。
+* **读取权限**：需要具有选择（select）权限。
+
+## **使用注意事项**
+
+* **连接配置**： 创建 connection 时，确保 endpoint 配置正确，以便 Lakehouse 能够成功连接。如果 Lakehouse 和对象存储位于同一云服务且在同一区域，通常使用内网地址即可实现网络互通。如果不在同一网络环境，建议使用对象存储的公网地址。
+
+## 具体案例
+
+### 连接阿里云Oss
+
+```SQL
+--创建connection,用于连接对象存储
+CREATE STORAGE CONNECTION  oss_hudi
+    TYPE oss
+    ENDPOINT = 'oss-cn-hangzhou-internal.aliyuncs.com'
+    access_id = 'xxxxxx'
+    access_key = 'xxxxxx'
+    comments = 'hudi'
+    ;
+--使用上面的链接信息，创建外部表
+CREATE    EXTERNAL TABLE pepole_hudi (id int, name string,dt string) 
+USING HUDI 
+CONNECTION oss_hudi 
+PARTITIONED BY (dt ) 
+LOCATION 'oss://bucketmy/hudi-format/uploadhudi/' 
+COMMENT 'external';
+```
+
+### 连接Google GCS
+
+Lakehouse 连接 Google Cloud Storage (GCS) 时，将使用服务账号密钥进行身份验证。请按照以下步骤操作：
+
+1. **获取服务账号密钥**：
+
+* 登录 Google Cloud 控制台。
+* 按照 *[Google Cloud 文档](https://cloud.google.com/docs/authentication/getting-started)* 的指导，创建并下载服务账号的 JSON 密钥文件。
+
+2. **配置 ****`private_key`**** 参数**：
+
+* 打开下载的 JSON 密钥文件，将文件中的私钥内容完整复制
+
+3. **注意**：
+
+* 在配置 `private_key` 时，必须前面添加r,r代表区分大小写，殊字符和 unicode 字符都不会被转义。
+
+```SQL
+--创建connection,用于连接对象存储
+CREATE STORAGE CONNECTION  oss_hudi
+    TYPE gcs
+    private_key=r'{
+  "type": "service_account",
+  "project_id": "PROJECT_ID",
+  "private_key_id": "KEY_ID",
+  "private_key": "-----BEGIN PRIVATE KEY-----\nPRIVATE_KEY\n-----END PRIVATE KEY-----\n",
+  "client_email": "SERVICE_ACCOUNT_EMAIL",
+  "client_id": "CLIENT_ID",
+  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
+  "token_uri": "https://accounts.google.com/o/oauth2/token",
+  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
+  "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/SERVICE_ACCOUNT_EMAIL"
+}';
+--使用上面的链接信息，创建外部表
+CREATE    EXTERNAL TABLE pepole_hudi (id int, name string,dt string) 
+USING HUDI 
+CONNECTION oss_hudi 
+PARTITIONED BY (dt ) 
+LOCATION 'gs://bucketmy/hudi-format/uploadhudi/' 
+COMMENT 'external';
+```

package/bin/skills/lakehouse-doc/references/external-table-guide.md

@@ -0,0 +1,96 @@
+# **外部表简介**
+
+**功能概述：** 外部表是 Lakehouse 的一项特性，它使您能够查询存储在外部系统中的数据，就如同这些数据存储在 Lakehouse 内部一样。这些外部数据并不存储或管理在 Lakehouse 中。
+
+**性能提示：** 由于外部表中的数据存储在 Lakehouse 外部，查询外部表可能比查询存储在本地的表稍慢。为了提升查询效率，建议使用 `INSERT INTO internal_table_name SELECT * FROM external_table_name` 语句或 `COPY INTO` 命令将数据导入到 Lakehouse 中。
+
+## 支持的外部表数据源
+- Kafka 外部表
+- Delta Lake 外部表
+- Hudi 外部表
+## **外部表与 External Schema 的区别**
+
+* **External Schema：** 直接与 Hive 元数据服务（HMS）交互，通过 HMS 接口直接获取 Hive 的元数据信息。
+* **外部表：** 允许用户自定义创建表，指定列内容和表名。
+* **External Schema 限制：** 由于是直接映射 HMS，无法在 External Schema 下直接创建、删除表或重命名表。
+* **外部表优势：** 支持重命名和修改注释等操作，因为它们是在内部 schema 下创建的。
+## 具体案例
+
+### 连接阿里云 OSS
+
+```SQL
+--创建connection,用于连接对象存储
+CREATE STORAGE CONNECTION  oss_delta
+    TYPE oss
+    ENDPOINT = 'oss-cn-hangzhou-internal.aliyuncs.com'
+    access_id = 'xxxxxx'
+    access_key = 'xxxxxx'
+    comments = 'delta'
+    ;
+--使用上面的链接信息，创建外部表
+CREATE    EXTERNAL TABLE pepole_delta (id int, name string,dt string) 
+USING DELTA 
+CONNECTION oss_delta 
+PARTITIONED BY (dt ) 
+LOCATION 'oss://bucketmy/delta-format/uploaddelta/' 
+COMMENT 'edelta-external';
+```
+
+### 连接 Google GCS
+
+Lakehouse 连接 Google Cloud Storage (GCS) 时，将使用服务账号密钥进行身份验证。请按照以下步骤操作：
+
+1. **获取服务账号密钥**：
+   1. 登录 Google Cloud 控制台。
+   2. 按照 *[Google Cloud 文档](https://cloud.google.com/docs/authentication/getting-started)* 的指导，创建并下载服务账号的 JSON 密钥文件。
+
+2. **配置 `private_key` 参数**：
+   1. 打开下载的 JSON 密钥文件，将文件中的私钥内容完整复制。
+
+3. **注意**：
+   1. 在配置 `private_key` 时，在 `private_key` 添加 `r`，表示转义字符不会被转义。
+
+```SQL
+--创建connection,用于连接对象存储
+CREATE STORAGE CONNECTION  oss_delta
+    TYPE gcs
+    private_key=r'{
+  "type": "service_account",
+  "project_id": "PROJECT_ID",
+  "private_key_id": "KEY_ID",
+  "private_key": "-----BEGIN PRIVATE KEY-----\nPRIVATE_KEY\n-----END PRIVATE KEY-----\n",
+  "client_email": "SERVICE_ACCOUNT_EMAIL",
+  "client_id": "CLIENT_ID",
+  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
+  "token_uri": "https://accounts.google.com/o/oauth2/token",
+  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
+  "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/SERVICE_ACCOUNT_EMAIL"
+}';
+--使用上面的链接信息，创建外部表
+CREATE    EXTERNAL TABLE pepole_delta (id int, name string,dt string) 
+USING DELTA 
+CONNECTION oss_delta 
+PARTITIONED BY (dt ) 
+LOCATION 'gs://bucketmy/delta-format/uploaddelta/' 
+COMMENT 'edelta-external';
+```
+
+
+
+## **外部表计费**
+
+* **存储费用：** 外部表不产生存储费用，因为数据不存储在 Lakehouse 中。
+* **计算费用：** 使用外部表进行计算会消耗计算资源，因此会产生计算费用。
+
+## **外部表权限**
+
+外部表和内部表的权限点相同。由于外部表无法执行 INSERT、UPDATE、TRUNCATE、DELETE、UNDROP 等操作，因此没有对应的操作权限点。
+
+* **创建权限：** 需要具有创建表（create table）的权限。
+* **删除权限：** 需要具有删除（drop）权限。
+* **读取权限：** 需要具有选择（select）权限。
+
+## **使用注意事项**
+
+* **连接配置：** 创建 Connection 时，确保 Endpoint 配置正确，以便 Lakehouse 能够成功连接。如果 Lakehouse 和对象存储位于同一云服务且在同一区域，通常使用内网地址即可实现网络互通。如果不在同一网络环境，建议使用对象存储的公网地址。
+

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

@@ -0,0 +1,298 @@
+## **1. 概述**
+
+Lakehouse架构提供了强大的外部对象联邦能力，允许用户在不移动数据的情况下访问和分析存储在多个异构数据源中的数据。本指南详细介绍了外部Catalog、外部Schema和外部表的使用场景、配置方法和最佳实践。
+
+### **1.1 外部对象层次结构**
+
+```Plain
+Catalog(目录) > Schema(模式) > Table(表)
+```
+
+* **外部Catalog**：顶层容器，映射外部数据系统
+* **外部Schema**：中间层容器，类似于数据库
+* **外部表**：底层对象，直接访问外部数据源的数据文件
+
+## **2. 适用场景**
+
+### **2.1 外部Catalog适用场景**
+
+1\. **多数据源统一管理**
+
+* 场景：企业拥有多个数据平台(Hive、Databricks等)
+* 优势：无需数据迁移，直接在Lakehouse中访问所有数据源
+* 应用：数据治理、统一元数据管理
+
+2\. **跨平台数据联邦查询**
+
+* 场景：需要同时分析存储在不同系统中的数据
+* 优势：无需ETL，实时查询多个数据源
+* 应用：跨系统报表、综合分析
+
+3\. **数据湖仓一体架构**
+
+* 场景：构建统一的数据分析平台
+* 优势：兼顾数据湖的灵活性和数据仓库的性能
+* 应用：从历史数据到实时数据的全链路分析
+
+4\. **渐进式数据迁移**
+
+* 场景：分阶段将数据从旧系统迁移到新系统
+* 优势：在迁移过程中保持业务连续性
+* 应用：系统升级、架构转型
+
+### **2.2 外部Schema适用场景**
+
+1\. **Hive\*\*\*\*元数据集成**
+
+* 场景：连接已有的Hive元数据服务(HMS)
+* 优势：复用现有元数据，无需重新定义表结构
+* 应用：大数据平台整合
+
+2\. **数据库级别的访问控制**
+
+* 场景：按照Schema级别分配权限
+* 优势：简化权限管理，提高安全性
+* 应用：多部门数据共享
+
+3\. **外部数据库映射**
+
+* 场景：将外部数据库作为整体引入Lakehouse
+* 优势：保持原有数据组织结构
+* 应用：数据库迁移、跨数据库分析
+
+### **2.3 外部表适用场景**
+
+1\. **对象存储数据直接查询**
+
+* 场景：分析存储在S3/OSS/COS等对象存储中的数据文件
+* 优势：避免数据复制，节省存储空间
+* 应用：日志分析、大文件处理
+
+2\. **流式数据接入**
+
+* 场景：连接Kafka等消息队列系统
+* 优势：实时数据查询和处理
+* 应用：实时监控、事件处理
+
+3\. **数据湖格式支持**
+
+* 场景：访问Delta、Hudi等开源数据湖格式
+* 优势：利用开源生态系统，避免数据孤岛
+* 应用：数据湖构建、开源兼容
+
+4\. **冷热数据分离**
+
+* 场景：将冷数据存储在成本较低的外部存储中
+* 优势：优化存储成本和查询性能
+* 应用：数据归档、成本优化
+
+## **3. 配置指南**
+
+### **3.1 外部Catalog配置**
+
+#### **创建Catalog连接**
+
+```SQL
+-- 创建连接到Databricks的Catalog连接
+CREATE CATALOG CONNECTION IF NOT EXISTS databricks_conn 
+TYPE databricks 
+HOST = 'https://dbc-12345678-9abc.cloud.databricks.com' 
+CLIENT_ID = 'client_id_value' 
+CLIENT_SECRET = 'client_secret_value' 
+ACCESS_REGION = 'us-west-2';
+
+-- 创建连接到Hive的Catalog连接
+CREATE CATALOG CONNECTION IF NOT EXISTS hive_conn
+TYPE hms
+hive_metastore_uris = 'metastore-host'
+storage_connection = 9083;
+```
+
+#### **创建外部Catalog**
+
+```SQL
+-- 基于上面的连接创建外部Catalog
+CREATE EXTERNAL CATALOG databricks_catalog 
+CONNECTION databricks_conn;
+
+CREATE EXTERNAL CATALOG hive_catalog
+CONNECTION hive_conn;
+```
+
+### **3.2 外部Schema配置**
+
+```SQL
+-- 创建映射hive中的databse
+CREATE EXTERNAL SCHEMA external_db_schema 
+CONNECTION hive_catalog 
+OPTIONS ( 'schema'='default');
+```
+
+### **3.3 外部表配置**
+
+```SQL
+-- 创建Delta Lake外部表
+CREATE EXTERNAL TABLE delta_sales
+USING DELTA 
+CONNECTION oss_delta 
+LOCATION 'oss://bucketname/delta-format/sales/' 
+COMMENT 'Delta外部表示例';
+
+-- 创建Kafka外部表
+CREATE EXTERNAL TABLE kafka_messages (
+  key STRING,
+  value STRING,
+  topic STRING,
+  partition INT,
+  offset BIGINT,
+  timestamp BIGINT
+)
+USING KAFKA
+CONNECTION kafka_conn
+OPTIONS (
+  'kafka.bootstrap.servers' = 'broker:9092',
+  'subscribe' = 'test-topic'
+);
+```
+
+## **4. 查询使用**
+
+### **4.1 查询外部Catalog中的表**
+
+```SQL
+-- 使用三层语法查询外部Catalog中的表
+SELECT * FROM databricks_catalog.default.sales 
+WHERE region = 'APAC'
+LIMIT 10;
+
+-- 关联查询外部Catalog和内部表
+SELECT a.customer_id, a.order_total, b.customer_name
+FROM databricks_catalog.sales.orders a
+JOIN internal_schema.customers b
+ON a.customer_id = b.id
+WHERE a.order_date >= '2024-01-01';
+```
+
+### **4.2 查询外部Schema中的表**
+
+```SQL
+-- 查询外部Schema中的表
+SELECT * FROM external_db_schema.customer_table
+WHERE register_date > '2023-01-01';
+```
+
+### **4.3 查询外部表**
+
+```SQL
+-- 查询Delta外部表
+SELECT product, SUM(price) as total_sales
+FROM delta_sales
+WHERE sale_date BETWEEN '2024-01-01' AND '2024-04-30'
+GROUP BY product
+ORDER BY total_sales DESC;
+
+-- 查询Kafka外部表
+SELECT * FROM kafka_messages
+WHERE timestamp > 1715132800000 -- 2024-05-08 00:00:00 UTC
+LIMIT 100;
+```
+
+## **5. 性能优化最佳实践**
+
+### **5.1 数据导入策略**
+
+由于外部表中的数据存储在Lakehouse外部，查询性能可能不如内部表。对于频繁查询的数据，建议导入到内部表：
+
+```SQL
+-- 将外部表数据导入内部表
+INSERT INTO internal_sales_table 
+SELECT * FROM databricks_catalog.sales.orders
+WHERE order_date >= '2024-01-01';
+
+```
+
+### **5.2 分区和筛选**
+
+利用分区信息和筛选条件减少数据扫描量：
+
+```SQL
+-- 使用分区筛选
+SELECT * FROM delta_sales
+WHERE sale_date = '2024-05-15'  -- 此处使用分区字段可大幅提升性能
+AND product = 'Laptop';
+```
+
+## **6. 管理和监控**
+
+### **6.1 查看外部对象**
+
+```SQL
+-- 查看所有Catalog
+SHOW CATALOGS;
+
+-- 查看所有外部Schema
+SHOW SCHEMAS EXTENDED WHERE type='external';
+
+-- 查看外部Schema中的表
+SHOW TABLES IN external_db_schema;
+
+-- 检查外部表结构
+DESCRIBE TABLE delta_sales;
+```
+
+## **7. 典型案例**
+
+### **7.1 数据湖与数据仓库统一查询**
+
+场景：企业同时拥有Hive数据湖和Databricks数据仓库，需要进行跨平台分析。
+
+解决方案：
+
+1. 创建连接到Hive和Databricks的外部Catalog
+2. 使用联邦查询关联两个平台的数据
+3. 构建统一视图提供一致的数据访问层
+
+### **7.2 历史数据归档与查询**
+
+场景：将历史数据归档到对象存储，但仍需要偶尔查询。
+
+解决方案：
+
+1. 将历史数据以Delta或Parquet格式存储在对象存储中
+2. 创建外部表映射归档数据
+3. 按需查询，无需占用主存储空间
+
+### **7.3 实时数据与批处理数据整合**
+
+场景：需要同时分析Kafka中的实时数据和数据仓库中的历史数据。
+
+解决方案：
+
+1. 创建Kafka外部表处理实时数据
+2. 使用联邦查询将实时数据与历史数据关联
+3. 构建实时仪表板展示综合分析结果
+
+## **8. 故障排除**
+
+### **8.1 连接问题**
+
+\- **症状**: 无法连接到外部数据源
+
+\- **解决方案**:
+
+* 检查网络连接和防火墙设置
+* 验证连接凭证是否有效
+* 确认外部服务是否可用
+
+### **8.2 性能问题**
+
+\- **症状**: 外部表查询性能较慢
+
+\- **解决方案**:
+
+* 使用分区过滤减少数据扫描量
+* 考虑将频繁查询的数据导入内部表
+
+## **9. 总结**
+
+Lakehouse的外部对象功能提供了强大的数据联邦能力，使企业能够在不移动数据的情况下整合多个异构数据源。通过合理利用外部Catalog、外部Schema和外部表，可以构建统一的数据分析平台，实现数据湖仓一体化架构，提升数据价值。

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

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