DBT + ClickZetta Lakehouse 快速入门

本指南使用 jaffle-shop-clickzetta 示例项目，带你完成 dbt 接入 ClickZetta Lakehouse 的全流程：安装依赖、配置连接、加载数据、构建模型、运行测试。

jaffle-shop 是 dbt 官方维护的标准示例项目，模拟一家咖啡店的订单数据，包含 6 张原始数据表、6 个 staging 视图、7 张 mart 表，以及 27 个数据质量测试。

前置准备

Python 3.10 或以上（推荐 3.12）
一个可用的 ClickZetta Lakehouse 实例（需要 workspace、vcluster、用户名和密码）

第一步：克隆项目

git clone https://github.com/clickzetta/jaffle-shop-clickzetta.git cd jaffle-shop-clickzetta

第二步：安装 dbt-clickzetta

创建虚拟环境并安装 adapter：

python3 -m venv .venv source .venv/bin/activate # Windows: .venv\Scripts\activate pip install "dbt-clickzetta>=1.7.8"

验证安装：

dbt --version

输出示例：

Core: - installed: 1.10.x Plugins: - clickzetta: 1.6.5 - Up to date!

第三步：配置连接

复制连接模板并填写你的实例信息：

cp profiles.yml.example profiles.yml

编辑

profiles.yml

profiles.yml

，替换尖括号中的占位符：

jaffle_shop: target: dev outputs: dev: type: clickzetta service: <your-service-endpoint> # 例：cn-shanghai-alicloud.api.clickzetta.com，不加 https:// instance: <your-instance-id> workspace: <your-workspace> username: <your-username> password: <your-password> schema: dbt_jaffle vcluster: default

⚠️ 注意：

profiles.yml

profiles.yml

已在

.gitignore

.gitignore

中，不会被提交到 Git，避免密码泄露。

验证连接：

dbt debug --profiles-dir .

所有检查项显示

OK

表示连接成功。

💡 提示：

dbt debug

dbt debug

不验证

vcluster

vcluster

是否存在，填错时要到

dbt seed

dbt seed

阶段才会报错。

vcluster

vcluster

名称可以在 Lakehouse Studio 的计算集群页面确认。

第四步：安装依赖包

dbt deps --profiles-dir .

本项目依赖

dbt_utils

dbt_utils

（1.3.3）和

dbt_date

dbt_date

（0.17.1），安装完成后输出：

Installing dbt-labs/dbt_utils Installed from version 1.3.3 Installing godatadriven/dbt_date Installed from version 0.17.1

第五步：加载原始数据

dbt seed --profiles-dir .

将

seeds/jaffle-data/

seeds/jaffle-data/

下的 6 个 CSV 文件加载到

dbt_jaffle.raw

dbt_jaffle.raw

schema，共约 15 万行，正常约 1 分钟完成：

1 of 6 OK loaded seed file raw.raw_customers ......... INSERT 935 2 of 6 OK loaded seed file raw.raw_items ............. INSERT 90900 3 of 6 OK loaded seed file raw.raw_orders ............ INSERT 61948 4 of 6 OK loaded seed file raw.raw_products .......... INSERT 10 5 of 6 OK loaded seed file raw.raw_stores ............ INSERT 6 6 of 6 OK loaded seed file raw.raw_supplies .......... INSERT 65 Done. PASS=6 WARN=0 ERROR=0 SKIP=0 TOTAL=6

💡 提示：如果中途失败或中断，重跑时加

--full-refresh

--full-refresh

参数清除已写入的数据再重来：

dbt seed --profiles-dir . --full-refresh

第六步：构建模型

dbt run --profiles-dir .

按依赖顺序构建 13 个模型（6 个 staging 视图 + 7 张 mart 表）：

1 of 13 OK created sql table model dbt_jaffle.metricflow_time_spine 2 of 13 OK created sql view model dbt_jaffle.stg_customers 3 of 13 OK created sql view model dbt_jaffle.stg_locations 4 of 13 OK created sql view model dbt_jaffle.stg_order_items 5 of 13 OK created sql view model dbt_jaffle.stg_orders 6 of 13 OK created sql view model dbt_jaffle.stg_products 7 of 13 OK created sql view model dbt_jaffle.stg_supplies 8 of 13 OK created sql table model dbt_jaffle.locations 9 of 13 OK created sql table model dbt_jaffle.products 10 of 13 OK created sql table model dbt_jaffle.order_items 11 of 13 OK created sql table model dbt_jaffle.supplies 12 of 13 OK created sql table model dbt_jaffle.orders 13 of 13 OK created sql table model dbt_jaffle.customers Done. PASS=13 WARN=0 ERROR=0 SKIP=0 TOTAL=13

构建完成后，ClickZetta Lakehouse 的

dbt_jaffle

dbt_jaffle

schema 下会出现以下对象：

对象	类型	说明
`stg_customers` stg_customers	视图	清洗后的客户数据
`stg_locations` stg_locations	视图	清洗后的门店数据
`stg_order_items` stg_order_items	视图	清洗后的订单明细
`stg_orders` stg_orders	视图	清洗后的订单数据
`stg_products` stg_products	视图	清洗后的商品数据
`stg_supplies` stg_supplies	视图	清洗后的物料数据
`customers` customers	表	客户宽表（含消费汇总）
`orders` orders	表	订单宽表（含商品和金额明细）
`order_items` order_items	表	订单明细宽表
`locations` locations	表	门店维度表
`products` products	表	商品维度表
`supplies` supplies	表	物料维度表
`metricflow_time_spine` metricflow_time_spine	表	MetricFlow 时间轴辅助表

第七步：运行数据质量测试

dbt test --profiles-dir .

运行 27 个数据质量测试，覆盖唯一性、非空、引用完整性和业务逻辑校验：

Done. PASS=27 WARN=0 ERROR=0 SKIP=0 TOTAL=27

第八步：查看项目文档（可选）

dbt docs generate --profiles-dir . dbt docs serve

在浏览器中打开

http://localhost:8080

http://localhost:8080

，可以查看完整的数据血缘图和字段说明。

项目结构说明

jaffle-shop-clickzetta/ ├── models/ │ ├── staging/ │ └── marts/ ├── seeds/ │ └── jaffle-data/ ├── macros/ │ └── clickzetta_seed_batch_size.sql ├── profiles.yml.example └── dbt_project.yml

```
models/staging/
```
models/staging/
：原始数据清洗层，物化为视图
```
models/marts/
```
models/marts/
：业务宽表层，物化为表
```
seeds/jaffle-data/
```
seeds/jaffle-data/
：6 个 CSV 原始数据文件
```
macros/clickzetta_seed_batch_size.sql
```
macros/clickzetta_seed_batch_size.sql
：ClickZetta 适配宏，控制每批写入量
```
profiles.yml.example
```
profiles.yml.example
：连接配置模板

常见问题

Q：

dbt debug

dbt debug

报连接失败怎么办？

检查

profiles.yml

profiles.yml

中的

service

service

、

instance

instance

、

workspace

workspace

是否填写正确。

service

service

是 API 端点域名，不是 HTTP URL，不需要加

https://

https://

前缀。

Q：unit test 为什么被禁用？

jaffle-shop 原项目包含 3 个 dbt unit test，其生成的 SQL 使用了

cast(null as string not null)

cast(null as string not null)

语法，ClickZetta 暂不支持在

cast

cast

表达式中声明

not null

not null

约束，因此在

dbt_project.yml

dbt_project.yml

中将 unit test 统一禁用。27 个 data test 全部正常运行。

命令参考

命令	用途
`dbt deps` dbt deps	安装 packages.yml 中声明的依赖包
`dbt seed` dbt seed	将 CSV 文件加载为数据库表
`dbt run` dbt run	编译并执行所有模型
`dbt test` dbt test	运行数据质量测试
`dbt docs generate` dbt docs generate	生成项目文档
`dbt docs serve` dbt docs serve	在本地浏览器中查看文档

DBT + ClickZetta Lakehouse 快速入门

前置准备

第一步：克隆项目

第二步：安装 dbt-clickzetta

第三步：配置连接

第四步：安装依赖包

第五步：加载原始数据

第六步：构建模型

第七步：运行数据质量测试

第八步：查看项目文档（可选）

项目结构说明

常见问题

命令参考

相关文档