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

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

pip install clickhouse-connect

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

使用 ClickHouse Connect 连接前，您需要获取 ByteHouse 连接信息，您可参考以下章节获取对应信息。

• Host 地址：集群连接地址，详情请参见获取网络域名。
• Port：端口号，使用 8123。更多端口信息请参见集群连接端口。
• 用户名：ByteHouse 服务的用户名，详情请参见获取账号与密码。
• 密码：ByteHouse 服务的密码，详情请参见获取账号与密码。

获取网络域名

集群连接地址即集群的网关信息。您可登录并进入 ByteHouse 控制台后，单击顶部集群管理，通过集群列表 > 集群详情 > 基本信息路径，查看网络信息模块的网关配置，根据您的环境复制私网或公网地址。

获取账号与密码

ByteHouse 服务的用户名为火山引擎 IAM 账号，您可通过集群管理 > 集群列表 > 集群 > 连接集群路径，查看用户名。
在首次通过 IAM 账号密码登录火山引擎后，系统会自动生成 ByteHouse 初始服务密码。如果密码遗忘或遗失，您可以在集群管理 > 集群列表 > 集群 > 连接集群中，重置并设置新的密码。

连接至 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