ClickZetta SQLAlchemy 适配器

clickzetta-connector

clickzetta-connector

是 SQLAlchemy 的 ClickZetta Lakehouse dialect 适配器，它允许使用 SQLAlchemy 接口编写的代码或上层应用轻松地与 ClickZetta Lakehouse 进行交互。

安装

删除旧版本依赖

如果已安装旧版本的 SDK，请先卸载以避免冲突：

pip uninstall clickzetta-connector clickzetta-connector-python clickzetta-sqlalchemy clickzetta-ingestion-python clickzetta-ingestion-python-v2 -y

卸载前请记录旧版本的包信息，以防需要回退。查看已安装包版本的命令：

pip show clickzetta-connector clickzetta-sqlalchemy clickzetta-ingestion-python clickzetta-ingestion-python-v2 clickzetta-connector-python

通过 pip 安装

clickzetta-connector

clickzetta-connector

：

pip install clickzetta-connector -U

快速入门

执行 SQL 查询

方式一：使用 URL 字符串

from sqlalchemy import create_engine from sqlalchemy import text from urllib.parse import quote_plus

如果密码包含特殊字符（如 @、:、/），需要使用 quote_plus 进行编码：

password = quote_plus("your_password")

创建 ClickZetta Lakehouse 的 SQLAlchemy 引擎实例：

engine = create_engine( f"clickzetta://username:{password}@instance.region_id.api.clickzetta.com/workspace?schema=schema&vcluster=default" )

执行 SQL 查询：

sql = text("SELECT * FROM ecommerce_events_multicategorystore_live;")

使用引擎执行查询：

with engine.connect() as conn: result = conn.execute(sql) for row in result: print(row)

⚠️ 注意：如果密码包含特殊字符（如

、

），必须使用

urllib.parse.quote_plus

urllib.parse.quote_plus

对密码进行编码，否则 URL 会被错误解析。

方式二：使用 URL.create（推荐）

使用

URL.create

URL.create

可以避免手动 URL 编码问题，SQLAlchemy 会自动处理密码中的特殊字符。

from sqlalchemy import create_engine, text from sqlalchemy.engine import URL url = URL.create( drivername='clickzetta', username='your_username', password='your_password', host='instance.region_id.api.clickzetta.com', database='your_workspace', query={ 'virtualcluster': 'default', 'schema': 'public' } ) engine = create_engine(url) with engine.connect() as conn: result = conn.execute(text("SELECT 1")) for row in result: print(row)

⚠️ 注意：

URL.create

URL.create

会自动处理密码中的特殊字符（如

、

），无需手动调用

quote_plus

quote_plus

。

示例：使用 PyGWalker 对 Lakehouse 数据进行可视化分析

PyGWalker 是一个可以将 pandas 和 polars 数据框转换为 Tableau 风格用户界面的工具，用于数据可视化探索。它简化了 Jupyter Notebook 的数据分析和数据可视化工作流程，只需添加一行代码即可实现。

from sqlalchemy import create_engine from sqlalchemy import text import pandas as pd import pygwalker as pyg

创建 ClickZetta Lakehouse 的 SQLAlchemy 引擎实例：

engine = create_engine( "clickzetta://username:password@instance.region_id.api.clickzetta.com/workspace?schema=schema&vcluster=default" )

执行 SQL 查询：

sql = text("SELECT * FROM ecommerce_events_multicategorystore_live;")

使用引擎执行查询并获取结果：

with engine.connect() as conn: result = conn.execute(sql) df = pd.DataFrame(result.fetchall(), columns=result.keys())

使用 PyGWalker 对 DataFrame 进行可视化分析：

walker = pyg.walk(df)

联系我们