dbt-clickzetta

The dbt adapter for ClickZetta Lakehouse.

Installation

# SQL models only (default)
pip install dbt-clickzetta

# Python models (requires ZettaPark)
pip install "dbt-clickzetta[python]"

Requires Python 3.10+ (3.12 recommended) and dbt-core 1.8+.

Note on versions: The legacy dbt-clickzetta 0.2.x series requires dbt-core ~1.5 and is no longer maintained. Use dbt-clickzetta >= 1.6.

Quickstart

1. Configure profiles.yml

my_project:
  target: dev
  outputs:
    dev:
      type: clickzetta
      service: cn-shanghai-alicloud.api.clickzetta.com
      instance: your_instance
      workspace: your_workspace
      username: your_username
      password: your_password
      schema: your_schema
      vcluster: default
      query_tag: "dbt_{{ target.name }}"   # optional

2. Test connection

dbt debug

3. Run your project

dbt run
dbt test
dbt docs generate

See the examples/ directory for complete, runnable examples.

→ 完整功能文档

Supported Features

Feature	Description	Docs
table / view / ephemeral	Standard dbt materializations	materializations.md
incremental	Incremental load: merge / append / insert_overwrite / delete+insert	incremental.md
dynamic_table	Auto-refresh on schedule, no manual scheduling needed	dynamic-table.md
materialized_view	Pre-computed aggregation view	materializations.md
snapshot	SCD Type 2 history tracking	snapshots.md
clone	Zero-copy clone + Time Travel clone	clone.md
Python models	Run Python/ML models via ZettaPark	python-models.md
Table Stream	CDC source: capture INSERT/UPDATE/DELETE	table-stream.md
Indexes	Bloomfilter / Inverted / Vector indexes	materializations.md
Partitioned & clustered tables	Partition by column, cluster by bucket	materializations.md
persist_docs	Sync model/column descriptions to Lakehouse	—
on_schema_change	Handle schema drift in incremental models	incremental.md
grants	Column/table-level access control	—
VCluster per-model	Assign compute cluster per model	incremental.md
query_tag	Tag all queries for job history filtering	observability.md
query_comment	Auto-inject dbt metadata into every SQL (on by default)	observability.md
Utility macros	optimize, undrop, clone, refresh, etc.	utility-macros.md

Connection Parameters

Parameter	Required	Description
type	✅	Must be clickzetta
service	✅	API endpoint, e.g. cn-shanghai-alicloud.api.clickzetta.com
instance	✅	Instance name
workspace	✅	Workspace name
username	✅	Username
password	✅	Password
schema	✅	Default schema
vcluster	✅	VCluster name, e.g. default
connect_retries	❌	Connection retry count (default: 3)
query_tag	❌	Tag applied to every query; visible in job history

Development

git clone https://github.com/clickzetta/dbt-clickzetta.git
cd dbt-clickzetta
pip install -e .

# Unit tests (no connection required)
pytest tests/unit/

# Functional tests (requires a real Lakehouse connection)
cp test.env.example test.env
# Fill in test.env with your connection details
pytest tests/functional/

License

Apache 2.0