使用 cz-cli 命令行工具连接 Lakehouse

cz-cli 是云器 Lakehouse 的命令行工具，提供连接配置管理、SQL 执行、任务运维等能力。相较于 JDBC 客户端，cz-cli 的特点是用 Profile 管理连接信息——一次配置，后续所有操作自动使用同一套连接参数，无需每次输入 JDBC URL、用户名和密码。

前提条件

1. 已安装 cz-cli（安装指南见 cz-cli 安装配置指南）
2. 已有 Lakehouse 实例并创建了工作空间
3. 你的用户账号已添加到目标工作空间，具备相应权限

配置连接 Profile

Profile 是 cz-cli 保存连接信息的本地配置。一个 Profile 对应一个 Lakehouse 连接环境（实例 + 工作空间 + Schema + VCluster）。建议为生产、测试、UAT 等环境各创建一个 Profile。

方式一：用参数创建 Profile（推荐）

cz-cli profile create <profile_name> \ --service <service> \ --instance <instance> \ --workspace <workspace> \ --schema <schema> \ --vcluster <vcluster> \ --username <用户名> \ --password '<密码>'

参数说明：

--service

--instance

instanceId

--workspace

--schema

SELECT CURRENT_SCHEMA()

--vcluster

DEFAULT

--username

--password

示例：配置阿里云上海生产环境

cz-cli profile create prod_sh \ --service https://cn-shanghai-alicloud.api.clickzetta.com \ --instance f8866243 \ --workspace quick_start \ --schema semantic_model_test \ --vcluster DEFAULT \ --username qiliang \ --password 'your_password'

方式二：通过 Studio 生成连接串创建

在 Studio → 个人设置 → 开发工具 → CLI 页签，选择 PAT 或密码认证方式，点击"生成连接串"，复制后在终端执行即可。

方式三：用 JDBC URL 创建

cz-cli profile create prod \ --jdbc "jdbc:clickzetta://<实例名>.<服务端点>/<workspace名>?username=<用户名>&password=<密码>&schema=<schema>&virtualCluster=<vcluster>"

验证连接

# 查看已创建的 Profile 列表 cz-cli profile list # 指定 Profile 执行查询，验证连接 cz-cli sql "SELECT 1" --profile prod_sh # 将常用 Profile 设为默认，后续命令省略 --profile cz-cli profile use prod_sh

连接后基本操作

执行 SQL

# 查询 cz-cli sql "SELECT * FROM silver.dim_player LIMIT 5" --sync # DDL/DML（需要 --write） cz-cli sql "CREATE TABLE test (id INT)" --sync --write # 执行 SQL 文件 cz-cli sql -f deploy.sql --write

切换环境

# 查看所有 Profile cz-cli profile list # 切换到不同环境 cz-cli profile use prod_sh # 生产 cz-cli profile use uat # UAT cz-cli profile use tencent_sh # 腾讯云上海

各云地域常用端点

https://cn-shanghai-alicloud.api.clickzetta.com

https://ap-shanghai-tencentcloud.api.clickzetta.com

https://ap-beijing-tencentcloud.api.clickzetta.com

https://ap-guangzhou-tencentcloud.api.clickzetta.com

https://cn-north-1-aws.api.clickzetta.com

https://ap-southeast-1-aws.api.singdata.com

常见问题

连接超时或拒绝

检查网络是否能访问 Service 端点（通常需代理/跳板机访问生产环境），确认实例 ID 和 Workspace 名称无误。

Schema 或 VCluster 不存在

cz-cli sql "SHOW SCHEMAS"

cz-cli sql "SHOW VCLUSTERS"

认证失败

确认用户名密码正确。如果使用 PAT 认证，检查 PAT 是否过期（已过期则重新生成）。

相关文档

• cz-cli 安装配置指南 — 安装步骤、PAT 认证、Profile 详细配置
• cz-cli SQL 执行与数据探索 — SQL 执行参数、输出格式控制
• JDBC 驱动连接 — Java 应用接入方式
• 使用命令行客户端连接 — sqlline Java 客户端
• 使用 SQLAlchemy 连接 — Python SQLAlchemy 接入