本文介绍如何在 Python 开发环境使用 ClickHouse Connect 连接并访问 ByteHouse 企业版。

建议使用 Python 3.10 或更高版本。

推荐使用 ClickHouse Connect v0.8.17。

执行以下命令，安装 ClickHouse Connect。

pip install clickhouse-connect

您可参考 ClickHouse Connect 官方文档，了解更多安装方式。

使用 ClickHouse Connect 连接 ByteHouse 前，您需要获取 ByteHouse 连接信息。ByteHouse 企业版当前支持应用通过 IAM 子用户或数据库用户连接至 ByteHouse，常用连接信息获取方式说明如下，更多连接信息说明请参见获取集群连接信息。

ByteHouse 企业版 IAM 子用户和数据库用户的差别说明如下：

更多 IAM 用户和数据库用户的介绍请参见：权限模型、子用户管理、数据库用户管理。

连接至 ByteHouse

可参考下面代码示例设置 ByteHouse 连接信息，请使用获取 ByteHouse 连接信息中获取的连接信息替换命令中的 host、port、username、password 等参数值。

import clickhouse_connect

client = clickhouse_connect.get_client(host='xxxxxxx-public.bytehouse-ce.volces.com', port=8123, username='{user}', password='{password}', secure=False)

参数说明：

• secure：表示是否使用加密连接（HTTPS/TLS）。

使用示例

通过 ClickHouse Connect 连接至 ByteHouse 后，您可以执行创建表、数据查询、插入等操作。

创建表

使用 client.command 命令执行 SQL 命令。

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

插入数据

使用 client.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'])

查询数据

使用 client.query 查询数据。

result = client.query('SELECT max(key), avg(metric) FROM new_table')
result.result_rows
Out[13]: [(2000, -50.9035)]

使用 InsertContexts 插入数据

ClickHouse Connect 的所有插入操作都通过 InsertContext 执行。InsertContext 包含通过 client.insert 插入的所有参数值。此外，在创建 InsertContext 时，ClickHouse Connect 会获取 Native 格式插入所需的列数据类型信息。复用 InsertContext 执行多次插入，可避免重复的预查询操作，从而显著提升插入效率和执行速度。
您可使用 client.create_insert_context 获取 InsertContext 信息。需要注意的是，复用 InsertContext 时只能修改其 data 属性。

test_data = [[1, 'v1', 'v2'], [2, 'v3', 'v4']]
ic = test_client.create_insert_context(table='test_table', data='test_data')
client.insert(context=ic)
assert client.command('SELECT count() FROM test_table') == 2
new_data = [[3, 'v5', 'v6'], [4, 'v7', 'v8']]
ic.data = new_data
client.insert(context=ic)
qr = test_client.query('SELECT * FROM test_table ORDER BY key DESC')
assert qr.row_count == 4
assert qr[0][0] == 4