简介
ClickHouse Connect 是一个用于与 ClickHouse 数据库交互的 Python 驱动程序,提供了高效的数据序列化和反序列化功能。它支持通过 HTTP 协议与 ClickHouse 服务器通信,适用于多种应用场景。
ClickHouse Connect 的主要特点
- Client 对象 :
clickhouse_connect.driver
包中的Client
对象是与 ClickHouse 服务器交互的主要接口。 - 数据类型支持 :
clickhouse_connect.datatypes
包提供了 ClickHouse 数据类型的基本实现,支持序列化和反序列化。 - Cython/C 优化 :
clickhouse_connect.cdriver
包中的 Cython/C 优化提高了序列化和反序列化的性能。 - SQLAlchemy 支持 :
clickhouse_connect.cc_sqlalchemy
包提供了有限的 SQLAlchemy 方言,主要用于查询功能。
安装 ClickHouse Connect
bash
pip install clickhouse-connect
基本用法
连接到 ClickHouse
要连接到 ClickHouse,需要提供以下信息:
- HOST 和 PORT: 默认端口为 8123(HTTP)或 8443(HTTPS)。
- 数据库名称 : 默认数据库为
default
。 - 用户名和密码 : 默认用户名为
default
。
python
import clickhouse_connect
# 连接到本地 ClickHouse 服务器
client = clickhouse_connect.get_client(host='localhost', username='default', password='password')
# 连接到 ClickHouse 云服务
client = clickhouse_connect.get_client(host='HOSTNAME.clickhouse.cloud', port=8443, username='default', password='your_password')
执行 SQL 命令
使用 command
方法执行 SQL 命令:
python
# 创建表
client.command('CREATE TABLE new_table (key UInt32, value String, metric Float64) ENGINE MergeTree ORDER BY key')
# 插入数据
row1 = [1000, 'String Value 1000', 5.233]
row2 = [2000, 'String Value 2000', -107.04]
data = [row1, row2]
client.insert('new_table', data, column_names=['key', 'value', 'metric'])
# 查询数据
result = client.query('SELECT max(key), avg(metric) FROM new_table')
print(result.result_rows)
参数绑定
支持两种参数绑定方式:服务器端绑定 和客户端绑定。
python
# 服务器端绑定示例
parameters = {'table': 'my_table', 'v1': datetime.datetime(2022, 10, 1, 15, 20, 5)}
client.query('SELECT * FROM {table:Identifier} WHERE date >= {v1:DateTime} AND string ILIKE {v2:String}', parameters=parameters)
# 客户端绑定示例
parameters = {'v1': datetime.datetime(2022, 10, 1, 15, 20, 5)}
client.query('SELECT * FROM some_table WHERE date >= %(v1)s AND string ILIKE %(v2)s', parameters=parameters)
高级用法
流式查询
ClickHouse Connect 支持流式查询,通过 query_row_block_stream
等方法以块形式返回数据。
python
with client.query_row_block_stream('SELECT * FROM hits') as stream:
for block in stream:
for row in block:
# 处理每行数据
print(row)
使用 NumPy 和 Pandas
可以使用 query_np
和 query_df
方法直接返回 NumPy 数组或 Pandas DataFrame。
python
import numpy as np
import pandas as pd
# 返回 NumPy 数组
result_np = client.query_np('SELECT * FROM hits')
print(result_np)
# 返回 Pandas DataFrame
result_df = client.query_df('SELECT * FROM hits')
print(result_df)
时区处理
ClickHouse Connect 支持时区处理,可以通过 query_tz
参数指定时区。
python
result = client.query('SELECT * FROM hits', query_tz='America/New_York')
总结
ClickHouse Connect 提供了一个强大的 Python 接口来与 ClickHouse 数据库交互,支持高效的数据序列化、流式查询以及时区处理等功能。通过其灵活的参数绑定和支持多种数据类型,ClickHouse Connect 适用于各种数据分析和处理场景。