本文介绍了如何通过 Python API 连接至 ByteHouse 并使用向量检索。
from clickhouse_connect import get_client
client = get_client(host="server", # server ip
port=8123, # server http port
user="bytehouse", # user
password="password", # password
compress='zstd', # compress method, zstd recommanded
send_receive_timeout=1000) # connect timeout
参数说明
参数项 | 是否必填 | 配置说明 |
---|---|---|
| 是 | 服务器 IP 地址或域名。配置为 ByteHouse 的公网连接域名,您可以在 ByteHouse 控制台的 集群管理 > 集群列表 > 集群 > 基本信息 中查看对应信息。详情请参见集群连接地址。 |
| 是 | 配置为 8123。 |
| 是 | 固定配置为 bytehouse。 |
| 是 | 在首次通过 IAM 账号密码登录火山引擎后,系统会自动生成 ByteHouse 初始服务密码。您可联系管理员获取。如果密码丢失或遗忘,可重置连接密码。 |
| 是 | 定义数据压缩方式,支持设置为 zstd、lz4、False。
|
| 否 | 设置单次请求的超时时间,单位为秒。 |
定义建表 schema。
schema = f"""\
CREATE TABLE IF NOT EXISTS {database}.{table}(
id UInt64,
embedding Array(Float32),
CONSTRAINT cons_vec_len CHECK length(embedding) = {dim},
INDEX vec_idx embedding TYPE HNSW('METRIC={metric.upper()}, DIM={dim}')
) ENGINE = {engine} ORDER BY id\
"""
参数说明
参数项 | 是否必填 | 配置说明 |
---|---|---|
| 是 | 向量字段,存储浮点数数组。 |
| 是 | 定义向量的维度值为 {dim},用于确保数据一致性,避免因维度不匹配导致索引异常。 |
| 是 | 声明要创建的索引及索引的列名。示例中,
|
| 是 | 定义使用的索引算法,支持设置为 HNSW、HNSW_SQ、FLAT、IVF_FLAT、IVF_PQ、IVF_SQ。
|
| 是 | 数据库引擎,可设置为 MergeTree、HaMergeTree 或 HaUniqueMergeTree。 |
| 是 | 按 |
执行建表语句。
client.command(schema)
数据预处理。
# embeddings(list[list[float]])指向量列表
# ids(list[int])指向量对应的唯一标识
data = zip(ids, embeddings)
values = [list(elem) for elem in data]
参数说明
参数项 | 是否必填 | 配置说明 |
---|---|---|
| 是 | 数据预处理,将 |
| 是 | 数据预处理,将每个元组转换为列表,最终得到列表的列表。 |
插入数据。
client.insert(f'{database}.{table}', values, column_names=['id', 'embedding'],
column_type_names=['UInt64', 'Array(Float32)'])
参数说明
参数项 | 是否必填 | 配置说明 |
---|---|---|
| 是 | 定义需要插入的数据。 |
| 是 | 定义目标表名。 |
| 是 | 二维列表,表示多行数据。每行数据的顺序必须与 |
| 是 | 指定列名的顺序。 |
| 是 | 指定列的类型。 |
构建查询语句。
# query: list[float]
q_str = f"""
SELECT id
FROM {database}.{collection}
ORDER BY {metric}Distance(embedding, {str(query)})
LIMIT {k}
settings enable_new_ann=1, hnsw_ef_s={search_param["ef"]}
"""
参数说明
参数项 | 是否必填 | 配置说明 |
---|---|---|
| 是 | 指定目标表名。 |
| 是 | 定义距离函数,支持设置为 |
| 是 | 返回最相似的前 |
| 是 | 示例中配置的 settings 参数说明如下,其他可配置的 settings 参数详见Settings 参数:
|
执行查询。
results = client.query(q_str)
解析结果并提取结果 ID。
result_ids = [int(id) for id in results.result_columns[0]]
from clickhouse_driver import Client
client = Client(host="server", # server ip
port=9000, # server tcp port
user="test", # user
password="password", # password
connect_timeout=3000,
send_receive_timeout=3000) # connect timeout
参数说明
参数项 | 是否必填 | 配置说明 |
---|---|---|
| 是 | 服务器 IP 地址或域名。配置为 ByteHouse 的公网连接域名,您可以在 ByteHouse 控制台的 集群管理 > 集群列表 > 集群 > 基本信息 中查看对应信息。详情请参见集群连接地址。 |
| 是 | 配置为 9000。 |
| 是 | 固定配置为 bytehouse。 |
| 是 | 在首次通过 IAM 账号密码登录火山引擎后,系统会自动生成 ByteHouse 初始服务密码。您可联系管理员获取。如果密码丢失或遗忘,可重置连接密码。 |
| 是 | 定义数据压缩方式,支持设置为 zstd、lz4、False。
|
| 否 | 设置单次请求的超时时间,单位为秒。 |
定义建表 schema。
schema = f"""\
CREATE TABLE IF NOT EXISTS {database}.{table}(
id UInt64,
embedding Array(Float32),
CONSTRAINT cons_vec_len CHECK length(embedding) = {dim},
INDEX vec_idx embedding TYPE HNSW('METRIC={metric.upper()}, DIM={dim}')
) ENGINE = {engine} ORDER BY id\
"""
参数说明
参数项 | 是否必填 | 配置说明 |
---|---|---|
| 是 | 自定义数据库和表名。 |
| 是 | 向量字段,存储浮点数数组。 |
| 是 | 定义向量的维度值为 {dim},用于确保数据一致性,避免因维度不匹配导致索引异常。 |
| 是 | 声明要创建的索引及索引的列名。示例中,
|
| 是 | 定义使用的索引算法,支持设置为 HNSW、HNSW_SQ、FLAT、IVF_FLAT、IVF_PQ、IVF_SQ。
|
| 是 | 数据库引擎,可设置为 MergeTree、HaMergeTree 或 HaUniqueMergeTree。 |
| 是 | 按 |
执行建表语句。
client.execute(schema)
数据预处理。
# embeddings(list[list[float]]): list of embeddings
# ids(list[int]): list of ids
data = zip(ids, embeddings)
values = [list(elem) for elem in data]
参数说明
参数项 | 是否必填 | 配置说明 |
---|---|---|
| 是 | 数据预处理步骤,将 |
| 是 | 数据预处理步骤,将每个元组转换为列表,最终得到列表的列表。 |
插入数据。
client.execute(f'INSERT INTO {database}.{table} (id, embedding) VALUES', values)
参数说明
参数项 | 是否必填 | 配置说明 |
---|---|---|
| 是 | 定义需要插入的数据。 |
| 是 | 定义目标表名及需要插入的字段及其值。
|
| 是 | 二维列表,表示多行数据。每行数据的顺序必须与 |
构建查询语句。
# query: list[float]
q_str = f"""
SELECT id
FROM {database}.{collection}
ORDER BY {metric}Distance(embedding, {str(query)})
LIMIT {k}
settings enable_new_ann=1, hnsw_ef_s={search_param["ef"]}
"""
参数说明
参数项 | 是否必填 | 配置说明 |
---|---|---|
| 是 | 指定目标表名。 |
| 是 | 定义距离函数,支持设置为 |
| 是 | 返回最相似的前 |
| 是 | 示例中配置的 settings 参数说明如下,其他可配置的 settings 参数详见Settings 参数:
|
执行查询。
results = client.query(q_str)
解析结果并提取结果 ID。
result_ids = [int(i) for (i,) in results]