ByteHouse HTTP Python Driver--ByteHouse云数仓版-火山引擎

文档中心

导航

ByteHouse HTTP Python Driver

最近更新时间：2025.06.11 11:18:41首次发布时间：2025.04.11 11:19:12

本文介绍如何使用 ByteHouse HTTP Python Driver 驱动连接并访问 ByteHouse 云数仓。

注意事项

请确保您使用的 ByteHouse Connect 和 Python 满足以下版本要求。

软件	版本
ByteHouse Connect 版本	0.8.6
Python 版本	Python 3.10

安装驱动

您可以通过 pip 安装驱动。
```
pip install bytehouse-connect
```
（可选）您也可以安装 cython 包来构建和启用 C/Cython 优化。
```
pip install cython
```

连接 ByteHouse

可参考下面代码样例连接 ByteHouse。

import clickhouse_connect

client = clickhouse_connect.get_client(
    host="tenant-{TENANT_ID}-{REGION}-public.bytehouse.volces.com",
    port=8123,
    username="bytehouse",
    password="{API_KEY}",
    database="{DATABASE}",
    compress=False,
    secure=True,
    verify=False
)

参数	配置要点
host	配置为 ByteHouse 的公网连接域名，其中 {TENANT_ID}、{REGION} 分别为火山引擎主账号的账号 ID 和 ByteHouse 的地域信息，您可以在 ByteHouse 控制台的租户管理>基本信息>网络信息中查看对应信息。详情请参见步骤二：配置网络信息。
port	配置为：8123。
username & password	user：固定配置为 bytehouse。 password：为 ByteHouse 的 <API_Key>，您可以在 ByteHouse 控制台的租户管理>连接信息中获取 API Key。详情请参见获取 API Key。
database	配置为连接 ByteHouse 的数据库名称。
secure & verify	secure：配置为 true verify：配置为 false

使用示例

连接 ByteHouse 后，您可以进行建表、数据读写等 DDL 操作，也可以进行查询设置，以下为简单的操作示例。

示例 1：建表、数据读写

使用client. order方法创建数据表

client.command("CREATE TABLE IF NOT EXISTS test_table (key UInt32, value String, metric Float64) ENGINE = CnchMergeTree() ORDER BY tuple()")

使用client.insert 或 client.query写入/查询数据

row1 = [1000, 'String Value 1000', 5.233]
row2 = [2000, 'String Value 2000', -107.04]
data = [row1, row2]
client.insert('test_table', data, column_names=['key', 'value', 'metric'])

result = client.query('SELECT max(key), avg(metric) FROM test_table')

示例 2：文件写入数据

from clickhouse_connect.driver.tools import insert_file

client.command("CREATE TABLE IF NOT EXISTS test_csv_table (key UInt32, value String) ENGINE = CnchMergeTree() ORDER BY tuple()")
insert_file(client, table='test_csv_table', file_path='data.csv', fmt='CSV')

示例 3：Session 参数设置

您可以通过 settings 参数设置 Session 级别参数，例如设置查询时使用的计算组。

client = clickhouse_connect.get_client(
    host="tenant-{TENANT_ID}-{REGION}-public.bytehouse.volces.com",
    port=8123,
    username="bytehouse",  
    password="{API_KEY}",  
    database="{DATABASE}",
    compress=False,
    secure=True,
    verify=False,
    settings={'virtual_warehouse':'your-vw-id'}
)

示例 4：Query 参数设置

settings = {'max_execution_time': 1000, 'session_id': 'session_1234'}
result = client.query("SELECT 1", settings=settings)