Python 与 ClickHouse Connect 集成：基础知识和实践

简介

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 适用于各种数据分析和处理场景。