跳至主要内容
跳至主要内容
编辑此页

简介

ClickHouse Connect 是一个核心数据库驱动程序，提供与各种 Python 应用程序的互操作性。

  • 主要接口是包 clickhouse_connect.driver 中的 Client 对象。该核心包还包括用于与 ClickHouse 服务器通信的各种辅助类和实用函数，以及用于高级管理插入和选择查询的“上下文”实现。
  • 包 clickhouse_connect.datatypes 提供了一个基本实现和所有非实验性 ClickHouse 数据类型的子类。其主要功能是将 ClickHouse 数据序列化和反序列化为 ClickHouse “Native” 二进制列格式，用于实现 ClickHouse 和客户端应用程序之间最有效的传输。
  • 包 clickhouse_connect.cdriver 中的 Cython/C 类优化了一些最常见的序列化和反序列化操作，与纯 Python 相比，显著提高了性能。
  • 包 clickhouse_connect.cc_sqlalchemy 中有一个 SQLAlchemy 方言，它基于 datatypes 和 dbi 包构建。此实现支持 SQLAlchemy Core 功能，包括带有 JOIN（INNER、LEFT OUTER、FULL OUTER、CROSS）的 SELECT 查询、WHERE 子句、ORDER BY、LIMIT/OFFSET、DISTINCT 操作、带有 WHERE 条件的轻量级 DELETE 语句、表反射以及基本的 DDL 操作（CREATE TABLE、CREATE/DROP DATABASE）。虽然它不支持高级 ORM 功能或高级 DDL 功能，但它提供了强大的查询功能，适用于大多数针对 ClickHouse 的 OLAP 导向数据库的分析工作负载。
  • 核心驱动程序和 ClickHouse Connect SQLAlchemy 实现是将 ClickHouse 连接到 Apache Superset 的首选方法。使用 ClickHouse Connect 数据库连接，或 clickhousedb SQLAlchemy 方言连接字符串。

本文档当前基于 clickhouse-connect 版本 0.9.2。

注意

官方 ClickHouse Connect Python 驱动程序使用 HTTP 协议与 ClickHouse 服务器通信。这支持 HTTP 负载均衡器，并且在具有防火墙和代理的企业环境中效果良好，但与基于原生 TCP 协议相比，压缩率和性能略低，并且不支持某些高级功能，例如查询取消。对于某些用例，您可以考虑使用一个使用原生 TCP 协议的 社区 Python 驱动程序。

需求和兼容性​

Python平台¹ClickHouseSQLAlchemy²Apache SupersetPandasPolars
2.x, <3.9❌Linux (x86)✅<25.x³🟡<1.4.40❌<1.4❌≥1.5✅1.x✅
3.9.x✅Linux (Aarch64)✅25.x³🟡≥1.4.40✅1.4.x✅2.x✅
3.10.x✅macOS (x86)✅25.3.x (LTS)✅≥2.x✅1.5.x✅
3.11.x✅macOS (ARM)✅25.6.x (稳定版)✅2.0.x✅
3.12.x✅Windows✅25.7.x (稳定版)✅2.1.x✅
3.13.x✅25.8.x (LTS)✅3.0.x✅
25.9.x (稳定版)✅

¹ClickHouse Connect 已明确针对所列平台进行了测试。此外，还为 cibuildwheel 项目支持的所有架构构建了未经测试的二进制 wheel（带有 C 优化）。最后，由于 ClickHouse Connect 也可以作为纯 Python 运行，因此源代码安装应适用于任何最新的 Python 安装。

²SQLAlchemy 支持仅限于 Core 功能（查询、基本 DDL）。不支持 ORM 功能。有关详细信息，请参阅 SQLAlchemy 集成支持 文档。

³ClickHouse Connect 通常可以与官方支持范围之外的版本配合使用。

安装​

通过 pip 从 PyPI 安装 ClickHouse Connect

pip install clickhouse-connect

ClickHouse Connect 也可以从源代码安装

  • git clone GitHub 仓库。
  • (可选) 运行 pip install cython 以构建并启用 C/Cython 优化
  • cd 到项目根目录并运行 pip install .

支持策略​

在报告任何问题之前，请更新到最新版本的 ClickHouse Connect。问题应在 GitHub 项目中提交。ClickHouse Connect 的未来版本旨在与发布时积极支持的 ClickHouse 版本兼容。可以在 此处找到积极支持的 ClickHouse 服务器版本。如果您不确定使用哪个版本的 ClickHouse 服务器，请阅读此讨论 此处。我们的 CI 测试矩阵针对最新的两个 LTS 版本和最新的三个稳定版本进行测试。但是，由于 HTTP 协议和 ClickHouse 版本之间的最小破坏性更改，ClickHouse Connect 通常可以与服务器版本在官方支持范围之外的版本配合使用，但与某些高级数据类型的兼容性可能会有所不同。

基本用法​

收集您的连接详细信息​

要使用 HTTP(S) 连接到 ClickHouse，您需要这些信息

参数描述
HOST 和 PORT通常，使用 TLS 时的端口为 8443，不使用 TLS 时的端口为 8123。
数据库名称默认情况下，有一个名为 default 的数据库，使用您要连接的数据库的名称。
USERNAME 和 PASSWORD默认情况下，用户名是 default。使用适合您用例的用户名。

您的 ClickHouse Cloud 服务的详细信息可在 ClickHouse Cloud 控制台中找到。选择一个服务并单击 Connect

选择 HTTPS。连接详细信息显示在一个示例 curl 命令中。

如果您使用的是自托管 ClickHouse，则连接详细信息由您的 ClickHouse 管理员设置。

建立连接​

显示了两个连接到 ClickHouse 的示例

  • 连接到本地主机上的 ClickHouse 服务器。
  • 连接到 ClickHouse Cloud 服务。

使用 ClickHouse Connect 客户端实例连接到本地主机上的 ClickHouse 服务器：​

import clickhouse_connect

client = clickhouse_connect.get_client(host='localhost', username='default', password='password')

使用 ClickHouse Connect 客户端实例连接到 ClickHouse Cloud 服务：​

提示

使用之前收集的连接详细信息。ClickHouse Cloud 服务需要 TLS，因此请使用端口 8443。

import clickhouse_connect

client = clickhouse_connect.get_client(host='HOSTNAME.clickhouse.cloud', port=8443, username='default', password='your password')

与您的数据库交互​

要运行 ClickHouse SQL 命令，请使用客户端 command 方法

client.command('CREATE TABLE new_table (key UInt32, value String, metric Float64) ENGINE MergeTree ORDER BY key')

要插入批量数据，请使用客户端 insert 方法，并使用行和值的二维数组

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'])

要使用 ClickHouse SQL 检索数据，请使用客户端 query 方法

result = client.query('SELECT max(key), avg(metric) FROM new_table')
print(result.result_rows)
# Output: [(2000, -50.9035)]
    © . This site is unofficial and not affiliated with ClickHouse, Inc.