1960 lines
55 KiB
Markdown
1960 lines
55 KiB
Markdown
SDK 准备
|
||
更新时间：2024-03-27
|
||
安装 Python SDK
|
||
环境准备
|
||
运行环境
|
||
Python SDK工具包支持在Python 3.7及以上的环境运行。
|
||
源码下载
|
||
若您需要Python SDK源码，可从如下两处下载：
|
||
Github地址：https://github.com/baidu/pymochow
|
||
Gitee地址：https://gitee.com/baidu/pymochow
|
||
安装和卸载
|
||
我们推荐通过pip来安装和卸载Python SDK，方法如下：
|
||
安装
|
||
您可以在命令行执行如下命令完成Python SDK的安装：
|
||
Shell复制
|
||
pip install pymochow
|
||
卸载
|
||
您可以在命令行中执行如下命令完成Python SDK的卸载：
|
||
Shell复制
|
||
pip uninstall pymochow
|
||
|
||
|
||
初始化客户端代码
|
||
在开始SDK使用之前，您可以预先查看创建实例快速入门，获取实例的Endpoint和API Key。然后在Python代码中根据配置创建出一个MochowClient对象，即可使用该对象提供的各类接口与后端数据库进行交互。代码示例如下：
|
||
Python复制
|
||
import pymochow
|
||
from pymochow.configuration import Configuration
|
||
from pymochow.auth.bce_credentials import BceCredentials
|
||
|
||
account = 'root'
|
||
api_key = '$您的账户API密钥'
|
||
endpoint = '$您的实例访问端点' # 例如：'http://127.0.0.1:5287'
|
||
|
||
# 根据配置创建一个MochowClient对象
|
||
config = Configuration(credentials=BceCredentials(account, api_key),
|
||
endpoint=endpoint)
|
||
client = pymochow.MochowClient(config)
|
||
|
||
|
||
Database 操作
|
||
更新时间：2024-03-20
|
||
创建数据库
|
||
功能介绍
|
||
新建一个库，用于进一步创建各类数据表。
|
||
请求示例
|
||
Python复制
|
||
import pymochow
|
||
from pymochow.configuration import Configuration
|
||
from pymochow.auth.bce_credentials import BceCredentials
|
||
|
||
account = 'root'
|
||
api_key = '$您的账户API密钥'
|
||
endpoint = '$您的实例访问端点' # 例如：'http://127.0.0.1:5287'
|
||
|
||
config = Configuration(credentials=BceCredentials(account, api_key),
|
||
endpoint=endpoint)
|
||
client = pymochow.MochowClient(config)
|
||
db = client.create_database("db_test")
|
||
client.close()
|
||
请求参数
|
||
参数
|
||
参数类型
|
||
是否必选
|
||
参数配置
|
||
database_name
|
||
String
|
||
是
|
||
指定库的名称。库名称命名要求如下：
|
||
1. 支持大小写字母、数字以及_特殊字符，必须以字母开头；
|
||
2. 长度限制为1~255。
|
||
返回参数
|
||
参数
|
||
参数类型
|
||
参数含义
|
||
database
|
||
Database
|
||
库对象。
|
||
|
||
|
||
删除数据库
|
||
功能介绍
|
||
删除指定的目标数据库，仅支持删除空库，不支持对尚有表存在的库进行递归删除，即删除之前需提前删除该数据库中的所有表，否则报错。
|
||
请求示例
|
||
Python复制
|
||
import pymochow
|
||
from pymochow.configuration import Configuration
|
||
from pymochow.auth.bce_credentials import BceCredentials
|
||
|
||
account = 'root'
|
||
api_key = '$您的账户API密钥'
|
||
endpoint = '$您的实例访问端点' # 例如：'http://127.0.0.1:5287'
|
||
|
||
config = Configuration(credentials=BceCredentials(account, api_key),
|
||
endpoint=endpoint)
|
||
client = pymochow.MochowClient(config)
|
||
db = client.drop_database("db_test")
|
||
client.close()
|
||
请求参数
|
||
参数
|
||
参数类型
|
||
是否必选
|
||
参数配置
|
||
database_name
|
||
String
|
||
是
|
||
指定库的名称。
|
||
|
||
|
||
查询数据库列表
|
||
功能介绍
|
||
查询数据库列表。
|
||
请求示例
|
||
Python复制
|
||
import pymochow
|
||
from pymochow.configuration import Configuration
|
||
from pymochow.auth.bce_credentials import BceCredentials
|
||
|
||
account = 'root'
|
||
api_key = '$您的账户API密钥'
|
||
endpoint = '$您的实例访问端点' # 例如：'http://127.0.0.1:5287'
|
||
|
||
config = Configuration(credentials=BceCredentials(account, api_key),
|
||
endpoint=endpoint)
|
||
client = pymochow.MochowClient(config)
|
||
db_list = client.list_databases()
|
||
client.close()
|
||
返回参数
|
||
参数
|
||
参数类型
|
||
参数含义
|
||
databases
|
||
List<Database>
|
||
库对象列表。
|
||
|
||
|
||
Table 操作
|
||
更新时间：2025-03-10
|
||
创建表
|
||
功能介绍
|
||
在指定的库中新建一个表。
|
||
请求示例
|
||
Python复制
|
||
import pymochow
|
||
from pymochow.configuration import Configuration
|
||
from pymochow.auth.bce_credentials import BceCredentials
|
||
from pymochow.model.schema import Schema, Field, SecondaryIndex, VectorIndex, HNSWParams, AutoBuildPeriodical
|
||
from pymochow.model.enum import FieldType, IndexType, MetricType, TableState
|
||
from pymochow.model.table import Partition
|
||
|
||
account = 'root'
|
||
api_key = '$您的账户API密钥'
|
||
endpoint = '$您的实例访问端点' # 例如：'http://127.0.0.1:5287'
|
||
|
||
config = Configuration(credentials=BceCredentials(account, api_key),
|
||
endpoint=endpoint)
|
||
client = pymochow.MochowClient(config)
|
||
|
||
db = client.database("db_test")
|
||
|
||
fields = []
|
||
fields.append(Field("id", FieldType.STRING, primary_key=True,
|
||
partition_key=True, auto_increment=False, not_null=True))
|
||
fields.append(Field("bookName", FieldType.STRING, not_null=True))
|
||
fields.append(Field("author", FieldType.STRING))
|
||
fields.append(Field("vector", FieldType.FLOAT_VECTOR, not_null=True, dimension=3))
|
||
indexes = []
|
||
indexes.append(
|
||
VectorIndex(
|
||
index_name="vector_idx",
|
||
index_type=IndexType.HNSW,
|
||
field="vector",
|
||
metric_type=MetricType.L2,
|
||
params=HNSWParams(m=32, efconstruction=200),
|
||
auto_build=True,
|
||
auto_build_index_policy=AutoBuildPeriodical(5000, "2026-01-01 12:00:00")
|
||
)
|
||
)
|
||
indexes.append(SecondaryIndex(index_name="book_name_idx", field="bookName"))
|
||
|
||
table = db.create_table(
|
||
table_name="book_vector",
|
||
replication=3,
|
||
partition=Partition(partition_num=3),
|
||
schema=Schema(fields=fields, indexes=indexes)
|
||
)
|
||
|
||
client.close()
|
||
请求参数
|
||
Table参数
|
||
参数
|
||
参数类型
|
||
是否必选
|
||
参数含义
|
||
table_name
|
||
String
|
||
是
|
||
指定表的名称。表的命名要求如下：
|
||
1. 仅支持大小写字母、数字以及下划线（_），且必须以字母开头；
|
||
2. 长度限制为1~255。
|
||
replication
|
||
Int
|
||
是
|
||
单个分区的总副本数（含主副本），取值范围为[1,10]。
|
||
若需要完整的高可用特性，副本总数需>=3。
|
||
需要注意的是：总副本数需要小于等于数据节点的数量，否则无法正常建表。
|
||
partition
|
||
Int
|
||
是
|
||
表的分区数量，取值范围为[1, 1000]。
|
||
若非FLAT索引，则建议将单个分区的记录总数控制在100万到1000万之间，过大过小都不太合适。
|
||
schema
|
||
Schema
|
||
是
|
||
表的Schema信息。
|
||
enable_dynamic_field
|
||
Boolean
|
||
否
|
||
表是否支持自动增加字段，默认值为False。
|
||
description
|
||
String
|
||
否
|
||
表的描述信息。
|
||
Schema参数
|
||
参数
|
||
参数类型
|
||
是否必选
|
||
参数含义
|
||
fields
|
||
List<Field>
|
||
是
|
||
指定表的字段详情列表。
|
||
indexes
|
||
List<Index>
|
||
是
|
||
表的索引详情列表。
|
||
Field参数
|
||
参数
|
||
参数类型
|
||
是否必选
|
||
参数含义
|
||
field_name
|
||
String
|
||
是
|
||
字段名称。
|
||
field_type
|
||
FieldType
|
||
是
|
||
字段数据类型。当前支持如下类型：BOOL、INT8、UINT8、INT16、UINT16、INT32、UINT32、INT64、UINT64、FLOAT、DOUBLE、DATE、DATETIME、TIMESTAMP、STRING、BINARY、UUID、TEXT、TEXT_GBK、TEXT_GB18030、ARRAY和FLOAT_VECTOR。
|
||
各数据类型的详细定义和约束请参见数据类型。
|
||
primary_key
|
||
Boolean
|
||
否
|
||
是否为主键，默认值为False。
|
||
当前已支持多主键，详情参见多主键。
|
||
主键字段不支持如下类型：BOOL、FLOAT、DOUBLE和FLOAT_VECTOR。
|
||
partition_key
|
||
Boolean
|
||
否
|
||
是否为分区键，默认值为False。
|
||
当前仅支持单一字段作为分区键，分区键可以是主键，也可以不是主键，但一张表只能有一个分区键，每行记录都会根据分区键的取值哈希映射到不同的分区。
|
||
分区键字段不支持如下类型：BOOL、FLOAT、DOUBLE、ARRAY和FLOAT_VECTOR。
|
||
auto_increment
|
||
Boolean
|
||
否
|
||
是否自增主键，默认值为False。
|
||
仅适用于类型为UINT64的主键字段，非主键字段请勿填写属性值。
|
||
not_null
|
||
Boolean
|
||
否
|
||
是否非空，默认值为False。
|
||
不可以为空值的字段包括：主键字段、分区键字段、向量字段和索引键字段。
|
||
dimension
|
||
Int
|
||
否
|
||
向量维度。仅当字段类型为FLOAT_VECTOR时，才需要指定该参数。
|
||
Index参数
|
||
参数
|
||
参数类型
|
||
是否必选
|
||
参数含义
|
||
vector_index
|
||
VectorIndex
|
||
否
|
||
向量索引对象。
|
||
secondary_index
|
||
SecondaryIndex
|
||
否
|
||
标量二级索引对象。
|
||
filtering_index
|
||
FilteringIndex
|
||
否
|
||
过滤索引对象。在带有过滤条件的检索场景中，为过滤的标量字段添加索引，可以显著加速检索过程，从而有效提升检索性能。
|
||
inverted_index
|
||
InvertedIndex
|
||
否
|
||
倒排索引对象。
|
||
VectorIndex参数
|
||
参数
|
||
参数类型
|
||
是否必选
|
||
参数含义
|
||
index_name
|
||
String
|
||
是
|
||
索引名称。
|
||
index_type
|
||
IndexType
|
||
是
|
||
向量索引类型。当前支持如下索引类型：
|
||
HNSW：HNSW向量索引。
|
||
FLAT：暴力检索类型，适用于数据量较小的场景。
|
||
PUCK：百度自研搜索算法，适用于超大规模数据量场景。
|
||
HNSWPQ：HNSWPQ向量索引。
|
||
field
|
||
String
|
||
是
|
||
索引作用于的目标字段名称。
|
||
metric_type
|
||
MetricType
|
||
是
|
||
向量之间距离度量算法类型。当前支持如下距离类型：
|
||
L2：欧几里得距离
|
||
IP：内积距离
|
||
COSINE：余弦距离
|
||
|
||
注：当使用COSINE距离时，用户需要自行对相关向量进行归一化操作，未经归一化的向量将导致search结果不准确
|
||
params
|
||
Params
|
||
是
|
||
向量构建索引所需参数。
|
||
HNSW索引构建参数，主要包含如下两个参数：
|
||
1. m：表示每个节点在检索构图中可以连接多少个邻居节点。取值为[4, 128]；
|
||
2. efconstruction：搜索时，指定寻找节点邻居遍历的范围。数值越大构图效果越好，构图时间越长。取值为[8, 1024]。
|
||
FLAT索引不含构建参数。
|
||
PUCK索引构建参数，主要包含如下两个参数：
|
||
1. coarseClusterCount：索引中粗聚类中心的个数；
|
||
2. fineClusterCount：每个粗聚类中心下细聚类中心个数。
|
||
HNSWPQ索引构建参数，主要包含如下四个参数：
|
||
1. m：表示每个节点在检索构图中可以连接多少个邻居节点。取值为[4, 128]；
|
||
2. efconstruction：搜索时，指定寻找节点邻居遍历的范围。数值越大构图效果越好，构图时间越长。取值为[8, 1024]；
|
||
3. NSQ：表示量化子空间个数，取值为[1, dim]，并且要求NSQ | dim；
|
||
4. sampleRate：kmeans训练原始数据的抽样比率，取值为[0.0, 1.0]，抽样总数 10000 + (rowCount - 10000)*sampleRate
|
||
auto_build
|
||
Boolean
|
||
否
|
||
是否自动构建索引，默认为False。
|
||
auto_build_index_policy
|
||
AutoBuildPolicy
|
||
否
|
||
自动构建索引策略，当前支持如下策略:
|
||
AutoBuildTiming：定时构建，指定构建的时间，构建一次，不会重复构建。例如AutoBuildTiming("2026-09-11 23:07:00")，时间格式支持UTC及LOCAL。注意：此参数在 1.2 之后才支持。
|
||
AutoBuildPeriodical：周期性构建，每过period_s秒构建一次索引，可重复构建。可以指定从某个时间点开始，例如AutoBuildPeriodical(24 * 3600, "2026-09-11 23:07:00")。周期不能低于3600，时间格式支持LOCAL以及UTC。
|
||
AutoBuildRowCountIncrement：增量行数构建。Tablet（不是table）增加或者减少指定的行数时会自动构建一次索引，可重复构建，支持具体行数以及百分比，只需传入一种即可，也可传入两种，触发其中之一便会开始构建。例如AutoBuildRowCountIncrement(row_count_increment = 10000, row_count_increment_ratio = 0.5)。增量行数不低于10000，增量行数百分比需要大于0。
|
||
SecondaryIndex参数
|
||
参数
|
||
参数类型
|
||
是否必选
|
||
参数含义
|
||
index_name
|
||
String
|
||
是
|
||
索引名称。
|
||
field
|
||
String
|
||
是
|
||
索引作用于的目标字段名称。
|
||
FilteringIndex
|
||
参数
|
||
参数类型
|
||
是否必选
|
||
参数含义
|
||
index_name
|
||
String
|
||
是
|
||
索引名称。
|
||
fields
|
||
List<FilteringIndexField>
|
||
是
|
||
索引作用于的目标字段名称。
|
||
FilteringIndexField
|
||
参数
|
||
参数类型
|
||
是否必选
|
||
参数含义
|
||
field
|
||
String
|
||
是
|
||
索引作用于的目标字段名称。
|
||
|
||
支持以下通配符：
|
||
@SCALAR，表示所有标量列，包括后续通过动态列添加的标量列。
|
||
indexStructureType
|
||
String
|
||
否
|
||
选择FILTERING索引的内存结构。支持的类型如下：
|
||
|
||
DEFAULT：默认结构
|
||
BITMAP：BITMAP结构，适用于值的种类较少的列，如性别、年龄等
|
||
|
||
indexStructureType的缺省值为DEFAULT。如果指定了通配符@SCALAR，则使用@SCALAR字段中的indexStructureType作为缺省值。
|
||
InvertedIndex
|
||
参数
|
||
参数类型
|
||
是否必选
|
||
参数含义
|
||
index_name
|
||
String
|
||
是
|
||
索引名称。
|
||
fields
|
||
List<String>
|
||
是
|
||
索引作用于的目标字段名称。
|
||
params
|
||
InvertedIndexParams
|
||
是
|
||
倒排索引参数
|
||
field_attributes
|
||
List<InvertedIndexFieldAttribute>
|
||
否
|
||
指定建立倒排索引的列是否需要分词(默认是会分词)，参数顺序应与'fields'里列名一一对应。目前支持以下选项:
|
||
|
||
ATTRIBUTE_ANALYZED
|
||
ATTRIBUTE_NOT_ANALYZED
|
||
InvertedIndexParams
|
||
参数
|
||
参数类型
|
||
是否必选
|
||
参数含义
|
||
analyzer
|
||
InvertedIndexAnalyzer
|
||
否
|
||
指定倒排索引的分词器。 目前支持以下三种:
|
||
|
||
ENGLISH_ANALYZER : 英文分词器
|
||
CHINESE_ANALYZER: 中文分词器
|
||
DEFAULT_ANALYZER: 默认分词器，适用于英文、中文、中英文混合等场景，建议使用
|
||
parse_mode
|
||
InvertedIndexParseMode
|
||
否
|
||
分词器的分词模式。
|
||
|
||
COARSE_MODE: 较粗粒度，基于不产生歧义的较大粒度进行切分，适宜于对语义表达能力要求较高的应用
|
||
FINE_MODE: 细粒度模式，基于语义完整的最小粒度进行切分
|
||
返回参数
|
||
参数
|
||
参数类型
|
||
参数含义
|
||
table
|
||
Table
|
||
创建的表对象。
|
||
|
||
|
||
删除表
|
||
功能介绍
|
||
删除指定的表。
|
||
请求示例
|
||
Python复制
|
||
import pymochow
|
||
from pymochow.configuration import Configuration
|
||
from pymochow.auth.bce_credentials import BceCredentials
|
||
|
||
account = 'root'
|
||
api_key = '$您的账户API密钥'
|
||
endpoint = '$您的实例访问端点' # 例如：'http://127.0.0.1:5287'
|
||
|
||
config = Configuration(credentials=BceCredentials(account, api_key),
|
||
endpoint=endpoint)
|
||
client = pymochow.MochowClient(config)
|
||
|
||
db = client.database("db_test")
|
||
db.drop_table("book_vector")
|
||
|
||
client.close()
|
||
请求参数
|
||
参数
|
||
参数类型
|
||
是否必选
|
||
参数含义
|
||
table_name
|
||
String
|
||
是
|
||
指定表的名称。
|
||
|
||
|
||
查询指定表详情
|
||
功能介绍
|
||
查询指定表的详情。
|
||
请求示例
|
||
Python复制
|
||
import pymochow
|
||
from pymochow.configuration import Configuration
|
||
from pymochow.auth.bce_credentials import BceCredentials
|
||
|
||
account = 'root'
|
||
api_key = '$您的账户API密钥'
|
||
endpoint = '$您的实例访问端点' # 例如：'http://127.0.0.1:5287'
|
||
|
||
config = Configuration(credentials=BceCredentials(account, api_key),
|
||
endpoint=endpoint)
|
||
client = pymochow.MochowClient(config)
|
||
|
||
db = client.database("db_test")
|
||
table = db.table("book_vector")
|
||
|
||
client.close()
|
||
请求参数
|
||
参数
|
||
参数类型
|
||
是否必选
|
||
参数含义
|
||
table_name
|
||
String
|
||
是
|
||
指定表的名称。
|
||
返回参数
|
||
参数
|
||
参数类型
|
||
参数含义
|
||
table
|
||
Table
|
||
表对象。
|
||
Table参数
|
||
参数
|
||
参数类型
|
||
参数含义
|
||
database_name
|
||
String
|
||
库的名称。
|
||
table_name
|
||
String
|
||
表的名称。
|
||
replication
|
||
Int
|
||
单个分区的总副本数（含主副本）。
|
||
partition
|
||
Int
|
||
表的分区数量。
|
||
schema
|
||
Schema
|
||
表的Schema信息。
|
||
enable_dynamic_field
|
||
Boolean
|
||
表是否支持自动增加字段。
|
||
description
|
||
String
|
||
表的描述信息。
|
||
create_time
|
||
Int
|
||
表的创建时间。
|
||
state
|
||
TableState
|
||
表的当前状态，取值如下：
|
||
CREATING：表处于创建中
|
||
NORMAL：表状态正常
|
||
DELETING：表正在被删除
|
||
aliases
|
||
List<String>
|
||
表的别名列表。
|
||
|
||
|
||
查询表的列表
|
||
功能介绍
|
||
查询指定库包含的所有表。
|
||
请求示例
|
||
Python复制
|
||
import pymochow
|
||
from pymochow.configuration import Configuration
|
||
from pymochow.auth.bce_credentials import BceCredentials
|
||
|
||
account = 'root'
|
||
api_key = '$您的账户API密钥'
|
||
endpoint = '$您的实例访问端点' # 例如：'http://127.0.0.1:5287'
|
||
|
||
config = Configuration(credentials=BceCredentials(account, api_key),
|
||
endpoint=endpoint)
|
||
client = pymochow.MochowClient(config)
|
||
|
||
db = client.database("db_test")
|
||
tables = db.list_table()
|
||
|
||
client.close()
|
||
请求参数
|
||
参数
|
||
参数类型
|
||
是否必选
|
||
参数含义
|
||
database_name
|
||
String
|
||
是
|
||
库的名称。
|
||
返回参数
|
||
参数
|
||
参数类型
|
||
参数含义
|
||
tables
|
||
List<Table>
|
||
表对象列表。
|
||
|
||
|
||
查询指定表的统计信息
|
||
功能介绍
|
||
查询指定表的统计信息。
|
||
请求示例
|
||
Python复制
|
||
import pymochow
|
||
from pymochow.configuration import Configuration
|
||
from pymochow.auth.bce_credentials import BceCredentials
|
||
|
||
account = 'root'
|
||
api_key = '$您的账户API密钥'
|
||
endpoint = '$您的实例访问端点' # 例如：'http://127.0.0.1:5287'
|
||
|
||
config = Configuration(credentials=BceCredentials(account, api_key),
|
||
endpoint=endpoint)
|
||
client = pymochow.MochowClient(config)
|
||
|
||
db = client.database("db_test")
|
||
table = db.table("book_vector")
|
||
table_stats = table.stats()
|
||
|
||
client.close()
|
||
请求参数
|
||
参数
|
||
参数类型
|
||
是否必选
|
||
参数含义
|
||
database_name
|
||
String
|
||
是
|
||
库的名称。
|
||
table_name
|
||
String
|
||
是
|
||
表的名称。
|
||
返回参数
|
||
参数
|
||
参数类型
|
||
参数含义
|
||
rowCount
|
||
Int
|
||
记录数。
|
||
memorySizeInByte
|
||
Int
|
||
内存大小。
|
||
diskSizeInByte
|
||
Int
|
||
磁盘大小。
|
||
|
||
Row 操作
|
||
更新时间：2025-08-05
|
||
插入记录
|
||
功能介绍
|
||
将一条或者一批记录插入到指定的表中。插入语义为Insert，若记录的主键已存在，则插入失败并报错。当插入一批时，该接口暂不支持批次的原子性。
|
||
请求示例
|
||
Python复制
|
||
import pymochow
|
||
from pymochow.configuration import Configuration
|
||
from pymochow.auth.bce_credentials import BceCredentials
|
||
from pymochow.model.table import Row
|
||
|
||
account = 'root'
|
||
api_key = '$您的账户API密钥'
|
||
endpoint = '$您的实例访问端点' # 例如：'http://127.0.0.1:5287'
|
||
|
||
config = Configuration(credentials=BceCredentials(account, api_key),
|
||
endpoint=endpoint)
|
||
client = pymochow.MochowClient(config)
|
||
|
||
db = client.database("db_test")
|
||
|
||
table = db.table("book_vector")
|
||
rows = [
|
||
Row(id='0001',
|
||
vector=[0.2123, 0.21, 0.213],
|
||
bookName='西游记'),
|
||
]
|
||
table.insert(rows)
|
||
|
||
client.close()
|
||
请求参数
|
||
参数
|
||
参数类型
|
||
是否必选
|
||
参数含义
|
||
rows
|
||
List<Row>
|
||
是
|
||
插入的记录列表。
|
||
|
||
|
||
插入或更新记录
|
||
功能介绍
|
||
将一条或者一批记录插入到指定的表中。插入语义为Upsert（Insert or else Update），即，当记录的主键不存在时，则正常插入，若发现主键已存在，则用新的记录覆盖旧的记录。当插入一批时，该接口暂不支持批次的原子性。该接口可用于批量迁移/灌库等场景。
|
||
请求示例
|
||
Python复制
|
||
import pymochow
|
||
from pymochow.configuration import Configuration
|
||
from pymochow.auth.bce_credentials import BceCredentials
|
||
from pymochow.model.table import Row
|
||
|
||
account = 'root'
|
||
api_key = '$您的账户API密钥'
|
||
endpoint = '$您的实例访问端点' # 例如：'http://127.0.0.1:5287'
|
||
|
||
config = Configuration(credentials=BceCredentials(account, api_key),
|
||
endpoint=endpoint)
|
||
client = pymochow.MochowClient(config)
|
||
|
||
db = client.database("db_test")
|
||
|
||
table = db.table("book_vector")
|
||
rows = [
|
||
Row(id='0001',
|
||
vector=[0.2123, 0.21, 0.213],
|
||
bookName='西游记'),
|
||
]
|
||
table.upsert(rows)
|
||
|
||
client.close()
|
||
请求参数
|
||
参数
|
||
参数类型
|
||
是否必选
|
||
参数含义
|
||
rows
|
||
List<Row>
|
||
是
|
||
待插入记录列表。
|
||
|
||
|
||
更新记录
|
||
功能介绍
|
||
更新表中指定记录的一个或多个标量字段的值
|
||
请求示例
|
||
Python复制
|
||
import pymochow
|
||
from pymochow.configuration import Configuration
|
||
from pymochow.auth.bce_credentials import BceCredentials
|
||
account = 'root'
|
||
api_key = '$您的账户API密钥'
|
||
endpoint = '$您的实例访问端点' # 例如：'http://127.0.0.1:5287'
|
||
config = Configuration(credentials=BceCredentials(account, api_key),
|
||
endpoint=endpoint)
|
||
client = pymochow.MochowClient(config)
|
||
db = client.database("db_test")
|
||
table = db.table("book_vector")
|
||
primary_key = {'id': '0001'}
|
||
update_fields = {'bookName': '红楼梦'}
|
||
table.update(primary_key=primary_key, update_fields=update_fields)
|
||
client.close()
|
||
请求参数
|
||
参数
|
||
参数类型
|
||
是否必选
|
||
参数含义
|
||
primary_key
|
||
Json
|
||
是
|
||
指定记录的主键值。
|
||
partition_key
|
||
Json
|
||
否
|
||
指定记录的分区键值。
|
||
如果该表的分区键和主键是同一个键，则不需要填写分区键值。只有在有主键值的情况下，分区键值才会生效。
|
||
update_fields
|
||
Json
|
||
是
|
||
待更新的字段列表及其新值。
|
||
不允许更新主键、分区键和向量字段。
|
||
|
||
|
||
删除记录
|
||
功能介绍
|
||
删除表中的指定记录。
|
||
请求示例
|
||
Python复制
|
||
import pymochow
|
||
from pymochow.configuration import Configuration
|
||
from pymochow.auth.bce_credentials import BceCredentials
|
||
|
||
account = 'root'
|
||
api_key = '$您的账户API密钥'
|
||
endpoint = '$您的实例访问端点' # 例如：'http://127.0.0.1:5287'
|
||
|
||
config = Configuration(credentials=BceCredentials(account, api_key),
|
||
endpoint=endpoint)
|
||
client = pymochow.MochowClient(config)
|
||
|
||
db = client.database("db_test")
|
||
|
||
table = db.table("book_vector")
|
||
primary_key = {'id': '0001'}
|
||
table.delete(primary_key) # 基于主键的查询删除
|
||
table.delete(filter="id=='0001'") # 基于标量字段的过滤删除
|
||
|
||
client.close()
|
||
请求参数
|
||
参数
|
||
参数类型
|
||
是否必选
|
||
参数含义
|
||
primary_key
|
||
Json
|
||
否
|
||
指定记录的主键值。
|
||
partition_key
|
||
Json
|
||
否
|
||
指定记录的分区键值。
|
||
如果该表的分区键和主键是同一个键，则不需要填写分区键值。只有在有主键值的情况下，分区键值才会生效。
|
||
filter
|
||
String
|
||
否
|
||
删除的标量过滤条件。
|
||
当要删除全部记录，可设置为"*"；Filter表达式语法参照SQL的WHERE子句语法进行设计，其详细描述和使用示例请参见Filter条件表达式。必须填写主键值或过滤条件，二者有且仅能选其一。
|
||
|
||
|
||
标量查询
|
||
功能介绍
|
||
基于主键值进行点查。
|
||
请求示例
|
||
Python复制
|
||
import pymochow
|
||
from pymochow.configuration import Configuration
|
||
from pymochow.auth.bce_credentials import BceCredentials
|
||
|
||
account = 'root'
|
||
api_key = '$您的账户API密钥'
|
||
endpoint = '$您的实例访问端点' # 例如：'http://127.0.0.1:5287'
|
||
|
||
config = Configuration(credentials=BceCredentials(account, api_key),
|
||
endpoint=endpoint)
|
||
client = pymochow.MochowClient(config)
|
||
|
||
db = client.database("db_test")
|
||
|
||
table = db.table("book_vector")
|
||
primary_key = {'id': '0001'}
|
||
projections = ["id", "bookName"]
|
||
res = table.query(primary_key=primary_key, projections=projections)
|
||
|
||
client.close()
|
||
请求参数
|
||
参数
|
||
参数类型
|
||
是否必选
|
||
参数含义
|
||
primary_key
|
||
Json
|
||
是
|
||
指定记录的主键值。
|
||
partition_key
|
||
Json
|
||
否
|
||
指定记录的分区键值。
|
||
如果该表的分区键和主键是同一个键，则不需要填写分区键值。
|
||
projections
|
||
List<String>
|
||
否
|
||
投影字段列表，默认为空，为空时查询结果默认返回所有标量字段。
|
||
retrieve_vector
|
||
Boolean
|
||
否
|
||
是否返回结果记录中的向量字段值，默认为False。
|
||
read_consistency
|
||
ReadConsistency
|
||
否
|
||
查询请求的一致性级别，取值为：
|
||
EVENTUAL（默认值）：最终一致性，查询请求会随机发送给分片的所有副本；
|
||
STRONG：强一致性，查询请求只会发送给分片主副本。
|
||
|
||
|
||
批量标量查询
|
||
功能介绍
|
||
基于主键值的批量点查操作。
|
||
请求示例
|
||
Python复制
|
||
import pymochow
|
||
from pymochow.configuration import Configuration
|
||
from pymochow.auth.bce_credentials import BceCredentials
|
||
from pymochow.model.table import BatchQueryKey
|
||
|
||
account = 'root'
|
||
api_key = 'your_api_key'
|
||
endpoint = 'you_endpoint' #example http://127.0.0.1:8511
|
||
|
||
config = Configuration(credentials=BceCredentials(account, api_key),
|
||
endpoint=endpoint)
|
||
client = pymochow.MochowClient(config)
|
||
|
||
db = client.database("db_test")
|
||
table = db.table("book_vector")
|
||
keys = [BatchQueryKey({'id':'0001'}),
|
||
BatchQueryKey({'id':'0002'})]
|
||
projections = ["id", "bookName"]
|
||
res = table.batch_query(keys=keys, projections=projections)
|
||
client.close()
|
||
请求参数
|
||
参数
|
||
参数类型
|
||
是否必选
|
||
参数含义
|
||
keys
|
||
List<BatchQueryKey>
|
||
是
|
||
目标记录的主键及分区键
|
||
projections
|
||
List<String>
|
||
否
|
||
投影字段列表，默认为空，为空时查询结果默认返回所有标量字段。
|
||
retrieve_vector
|
||
Boolean
|
||
否
|
||
是否返回结果记录中的向量字段值，默认为False。
|
||
read_consistency
|
||
ReadConsistency
|
||
否
|
||
查询请求的一致性级别，取值为：
|
||
EVENTUAL（默认值）：最终一致性，查询请求会随机发送给分片的所有副本；
|
||
STRONG：强一致性，查询请求只会发送给分片主副本。
|
||
BatchQueryKey 参数
|
||
参数
|
||
参数类型
|
||
是否必选
|
||
参数含义
|
||
primary_key
|
||
Json
|
||
是
|
||
目标记录的主键
|
||
partition_key
|
||
Json
|
||
否
|
||
目标记录的分区键值。
|
||
如该表的分区键和主键是同一个键，则不需要填写分区键值。
|
||
|
||
|
||
标量过滤查询
|
||
功能介绍
|
||
基于标量属性过滤查询记录。
|
||
请求示例
|
||
Python复制
|
||
import pymochow
|
||
from pymochow.configuration import Configuration
|
||
from pymochow.auth.bce_credentials import BceCredentials
|
||
from pymochow.model.enum import ReadConsistency
|
||
|
||
account = 'root'
|
||
api_key = 'your_api_key'
|
||
endpoint = 'you_endpoint' #example http://127.0.0.1:8511
|
||
|
||
config = Configuration(credentials=BceCredentials(account, api_key),
|
||
endpoint=endpoint)
|
||
client = pymochow.MochowClient(config)
|
||
|
||
db = client.database("db_test")
|
||
table = db.table("book_vector")
|
||
|
||
projections = ["id", "bookName"]
|
||
marker = {'id': 50}
|
||
filter = 'id < 100'
|
||
table.select(filter=filter, marker=marker, projections=projections, read_consistency=ReadConsistency.EVENTUAL, limit=10)
|
||
|
||
client.close()
|
||
请求参数
|
||
参数
|
||
参数类型
|
||
是否必选
|
||
参数含义
|
||
filter
|
||
String
|
||
否
|
||
检索的标量过滤条件，表示仅在符合过滤条件的候选集中进行检索，默认为空。Filter表达式语法参照SQL的WHERE子句语法进行设计，其详细描述和使用示例请参见Filter条件表达式。
|
||
marker
|
||
Json
|
||
否
|
||
查询的分页起始点，用于控制分页查询返回结果的起始位置，方便用户对数据进行分页展示和浏览，用户不填时，默认从第一条符合条件的记录开始返回。
|
||
projections
|
||
List<String>
|
||
否
|
||
投影字段列表，默认为空，为空时查询结果默认返回所有标量字段。
|
||
read_consistency
|
||
String
|
||
否
|
||
查询请求的一致性级别，取值为：
|
||
EVENTUAL（默认值）：最终一致性，查询请求会随机发送给分片的所有副本；
|
||
STRONG：强一致性，查询请求只会发送给分片主副本。
|
||
limit
|
||
Int
|
||
否
|
||
查询返回的记录条数，在进行分页查询时，即每页的记录条数。
|
||
默认为10，取值范围[1, 1000]。
|
||
|
||
|
||
向量TopK检索
|
||
功能介绍
|
||
基于向量字段值的KNN或ANN TopK检索操作，支持通过标量字段值进行过滤。
|
||
请求示例
|
||
Python复制
|
||
import pymochow
|
||
from pymochow.configuration import Configuration
|
||
from pymochow.auth.bce_credentials import BceCredentials
|
||
from pymochow.model.table import VectorTopkSearchRequest, FloatVector, VectorSearchConfig
|
||
|
||
account = 'root'
|
||
api_key = 'your_api_key'
|
||
endpoint = 'you_endpoint' #example http://127.0.0.1:8511
|
||
|
||
config = Configuration(credentials=BceCredentials(account, api_key),
|
||
endpoint=endpoint)
|
||
client = pymochow.MochowClient(config)
|
||
|
||
db = client.database("db_test")
|
||
table = db.table("book_vector")
|
||
request = VectorTopkSearchRequest(vector_field="vector", vector=FloatVector([0.3123, 0.43, 0.213]),
|
||
limit=10, filter="bookName='三国演义'", config=VectorSearchConfig(ef=200))
|
||
res = table.vector_search(request=request)
|
||
client.close()
|
||
请求参数
|
||
参数
|
||
参数类型
|
||
是否必选
|
||
参数含义
|
||
request
|
||
VectorTopkSearchRequest
|
||
是
|
||
检索请求参数描述信息。
|
||
partition_key
|
||
Json
|
||
否
|
||
目标记录的分区键值，如果该表的分区键和主键是同一个键，则不需要填写分区键值。
|
||
需要注意的是，如果没有指定分区键值，那么该检索请求可能会退化为在该表所有分片上都执行的MPP检索。
|
||
projections
|
||
List<String>
|
||
否
|
||
投影字段列表，默认为空，为空时检索结果返回所有标量字段。
|
||
read_consistency
|
||
ReadConsistency
|
||
否
|
||
检索请求的一致性级别，取值为：
|
||
EVENTUAL（默认值）：最终一致性，查询请求会随机发送给分片的所有副本；
|
||
STRONG：强一致性，查询请求只会发送给分片主副本。
|
||
VectorTopkSearchRequest参数
|
||
参数
|
||
参数类型
|
||
是否必选
|
||
参数含义
|
||
vector_field
|
||
String
|
||
是
|
||
检索的指定向量字段名称。
|
||
vector
|
||
FloatVector
|
||
是
|
||
检索的目标向量字段值。
|
||
limit
|
||
Int
|
||
否
|
||
返回最接近目标向量的向量记录数量，相当于TopK的K值，默认为50。
|
||
filter
|
||
String
|
||
否
|
||
检索的标量过滤条件，表示仅在符合过滤条件的候选集中进行检索，默认为空。Filter表达式语法参照SQL的WHERE子句语法进行设计，其详细描述和使用示例请参见Filter条件表达式。
|
||
config
|
||
VectorSearchConfig
|
||
否
|
||
向量检索算法的运行参数
|
||
VectorSearchConfig参数
|
||
参数
|
||
参数类型
|
||
是否必选
|
||
适用算法
|
||
参数含义
|
||
ef
|
||
Int
|
||
否
|
||
HNSW、HNSWPQ
|
||
检索过程的动态候选列表的大小。
|
||
pruning
|
||
Boolean
|
||
否
|
||
HNSW、HNSWPQ
|
||
检索过程中是否开启剪枝优化。
|
||
search_coarse_count
|
||
Int
|
||
否
|
||
PUCK
|
||
检索过程粗聚类中心候选集大小。
|
||
|
||
|
||
向量范围检索
|
||
功能介绍
|
||
基于向量字段值的KNN或ANN范围检索操作，支持通过标量字段值进行过滤。向量范围检索当前支持 HNSW、HNSWPQ，不支持 PUCK。
|
||
请求示例
|
||
Python复制
|
||
import pymochow
|
||
from pymochow.configuration import Configuration
|
||
from pymochow.auth.bce_credentials import BceCredentials
|
||
from pymochow.model.table import VectorRangeSearchRequest, FloatVector, VectorSearchConfig
|
||
|
||
account = 'root'
|
||
api_key = 'your_api_key'
|
||
endpoint = 'you_endpoint' #example http://127.0.0.1:8511
|
||
|
||
config = Configuration(credentials=BceCredentials(account, api_key),
|
||
endpoint=endpoint)
|
||
client = pymochow.MochowClient(config)
|
||
|
||
db = client.database("db_test")
|
||
table = db.table("book_vector")
|
||
request = VectorRangeSearchRequest(vector_field="vector", vector=FloatVector([0.3123, 0.43, 0.213]),
|
||
distance_range=(0, 20), limit=10, filter="bookName='三国演义'", config=VectorSearchConfig(ef=200))
|
||
res = table.vector_search(request=request)
|
||
client.close()
|
||
请求参数
|
||
参数
|
||
参数类型
|
||
是否必选
|
||
参数含义
|
||
request
|
||
VectorRangeSearchRequest
|
||
是
|
||
检索请求参数描述信息。
|
||
partition_key
|
||
Json
|
||
否
|
||
目标记录的分区键值，如果该表的分区键和主键是同一个键，则不需要填写分区键值。
|
||
需要注意的是，如果没有指定分区键值，那么该检索请求可能会退化为在该表所有分片上都执行的MPP检索。
|
||
projections
|
||
List<String>
|
||
否
|
||
投影字段列表，默认为空，为空时检索结果返回所有标量字段。
|
||
read_consistency
|
||
ReadConsistency
|
||
否
|
||
检索请求的一致性级别，取值为：
|
||
EVENTUAL（默认值）：最终一致性，查询请求会随机发送给分片的所有副本；
|
||
STRONG：强一致性，查询请求只会发送给分片主副本。
|
||
VectorRangeSearchRequest参数
|
||
参数
|
||
参数类型
|
||
是否必选
|
||
参数含义
|
||
vector_field
|
||
String
|
||
是
|
||
检索的指定向量字段名称。
|
||
vector
|
||
FloatVector
|
||
是
|
||
检索的目标向量字段值。
|
||
distance_range
|
||
Tuple[Float, Float]
|
||
是
|
||
范围检索场景中的最近距离与最远距离，最近距离在前，取值约束如下:
|
||
任意距离算法下，distanceFar都必须大于等于distanceNear，不支持小于；
|
||
当索引距离为L2时，distanceFar和distanceNear仅支持正数；
|
||
当索引距离为COSINE时，distanceFar和distanceNear的取值范围为[-1.0, 1.0]；
|
||
distanceFar与distanceNear需要成对出现。
|
||
limit
|
||
int
|
||
否
|
||
返回最接近目标向量的向量记录数量，相当于TopK的K值，默认为50。
|
||
filter
|
||
String
|
||
否
|
||
检索的标量过滤条件，表示仅在符合过滤条件的候选集中进行检索，默认为空。Filter表达式语法参照SQL的WHERE子句语法进行设计，其详细描述和使用示例请参见Filter条件表达式。
|
||
config
|
||
VectorSearchConfig
|
||
否
|
||
向量检索算法的运行参数
|
||
VectorSearchConfig参数
|
||
参数
|
||
参数类型
|
||
是否必选
|
||
适用算法
|
||
参数含义
|
||
ef
|
||
Int
|
||
否
|
||
HNSW、HNSWPQ
|
||
检索过程的动态候选列表的大小。
|
||
pruning
|
||
Boolean
|
||
否
|
||
HNSW、HNSWPQ
|
||
检索过程中是否开启剪枝优化。
|
||
search_coarse_count
|
||
Int
|
||
否
|
||
PUCK
|
||
检索过程粗聚类中心候选集大小。
|
||
|
||
|
||
批量向量检索
|
||
功能介绍
|
||
基于多个向量字段值的KNN或ANN检索操作，支持通过标量字段值进行过滤。仅适用于多节点标准版，不支持单节点免费测试版。
|
||
请求示例
|
||
Python复制
|
||
import pymochow
|
||
from pymochow.configuration import Configuration
|
||
from pymochow.auth.bce_credentials import BceCredentials
|
||
from pymochow.model.table import VectorBatchSearchRequest, FloatVector, VectorSearchConfig
|
||
|
||
account ='root'
|
||
api_key ='$您的账户API密钥'
|
||
endpoint ='$您的实例访问端点'# 例如：'http://127.0.0.1:5287'
|
||
|
||
config = Configuration(credentials=BceCredentials(account, api_key),
|
||
endpoint=endpoint)
|
||
client = pymochow.MochowClient(config)
|
||
|
||
db = client.database("db_test")
|
||
table = db.table("book_vector")
|
||
request = VectorBatchSearchRequest(vector_field="vector",
|
||
vectors=[FloatVector([1, 0.21, 0.213, 0]),
|
||
FloatVector([1, 0.32, 0.513, 0])],
|
||
limit=10, filter="bookName='三国演义'",
|
||
config=VectorSearchConfig(ef=200))
|
||
res = table.vector_search(request=request)
|
||
|
||
client.close()
|
||
请求参数
|
||
参数
|
||
参数类型
|
||
是否必选
|
||
参数含义
|
||
request
|
||
VectorBatchSearchRequest
|
||
是
|
||
检索请求参数描述信息。
|
||
partition_key
|
||
Json
|
||
否
|
||
目标记录的分区键值，如果该表的分区键和主键是同一个键，则不需要填写分区键值。
|
||
需要注意的是，如果没有指定分区键值，那么该检索请求可能会退化为在该表所有分片上都执行的MPP检索。
|
||
projections
|
||
List<String>
|
||
否
|
||
投影字段列表，默认为空，为空时检索结果返回所有标量字段。
|
||
read_consistency
|
||
ReadConsistency
|
||
否
|
||
检索请求的一致性级别，取值为：
|
||
EVENTUAL（默认值）：最终一致性，查询请求会随机发送给分片的所有副本；
|
||
STRONG：强一致性，查询请求只会发送给分片主副本。
|
||
VectorBatchSearchRequest参数
|
||
参数
|
||
参数类型
|
||
是否必选
|
||
参数含义
|
||
vector_field
|
||
String
|
||
是
|
||
检索的指定向量字段名称。
|
||
vectors
|
||
List<FloatVector>
|
||
是
|
||
检索的目标向量字段值。
|
||
limit
|
||
Int
|
||
否
|
||
返回最接近目标向量的向量记录数量，相当于TopK的K值，默认为50。
|
||
distance_range
|
||
Tuple[Float, Float]
|
||
否
|
||
范围检索场景中的最近距离与最远距离，最近距离在前，取值约束如下:
|
||
任意距离算法下，distanceFar都必须大于等于distanceNear，不支持小于；
|
||
当索引距离为L2时，distanceFar和distanceNear仅支持正数；
|
||
当索引距离为COSINE时，distanceFar和distanceNear的取值范围为[-1.0, 1.0]；
|
||
distanceFar与distanceNear需要成对出现。
|
||
filter
|
||
String
|
||
否
|
||
检索的标量过滤条件，表示仅在符合过滤条件的候选集中进行检索，默认为空。Filter表达式语法参照SQL的WHERE子句语法进行设计，其详细描述和使用示例请参见Filter条件表达式。
|
||
config
|
||
VectorSearchConfig
|
||
否
|
||
向量检索算法的运行参数
|
||
VectorSearchConfig参数
|
||
参数
|
||
参数类型
|
||
是否必选
|
||
适用算法
|
||
参数含义
|
||
ef
|
||
Int
|
||
否
|
||
HNSW、HNSWPQ
|
||
检索过程的动态候选列表的大小。
|
||
pruning
|
||
Boolean
|
||
否
|
||
HNSW、HNSWPQ
|
||
检索过程中是否开启剪枝优化。
|
||
search_coarse_count
|
||
Int
|
||
否
|
||
PUCK
|
||
检索过程粗聚类中心候选集大小。
|
||
|
||
|
||
全文检索
|
||
功能介绍
|
||
基于关键字的全文检索，支持通过标量字段值进行过滤。
|
||
请求示例
|
||
Python复制
|
||
import pymochow
|
||
from pymochow.configuration import Configuration
|
||
from pymochow.auth.bce_credentials import BceCredentials
|
||
from pymochow.model.table import BM25SearchRequest
|
||
|
||
account = 'root'
|
||
api_key = 'your_api_key'
|
||
endpoint = 'you_endpoint' #example http://127.0.0.1:8511
|
||
|
||
config = Configuration(credentials=BceCredentials(account, api_key),
|
||
endpoint=endpoint)
|
||
client = pymochow.MochowClient(config)
|
||
|
||
db = client.database("db_test")
|
||
table = db.table("book_vector")
|
||
request = BM25SearchRequest(index_name="book_segment_inverted_idx",
|
||
search_text="吕布",
|
||
limit=10,
|
||
filter="bookName='三国演义'")
|
||
res = table.bm25_search(request=request)
|
||
logger.debug("res: {}".format(res))
|
||
client.close()
|
||
请求参数
|
||
参数
|
||
参数类型
|
||
是否必选
|
||
参数含义
|
||
request
|
||
BM25SearchRequest
|
||
是
|
||
全文检索的详细参数。
|
||
partition_key
|
||
Json
|
||
否
|
||
目标记录的分区键值，如果该表的分区键和主键是同一个键，则不需要填写分区键值。
|
||
需要注意的是，如果没有指定分区键值，那么该检索请求可能会退化为在该表所有分片上都执行的MPP检索。
|
||
projections
|
||
List<String>
|
||
否
|
||
投影字段列表，默认为空，为空时检索结果返回所有标量字段。
|
||
read_consistency
|
||
ReadConsistency
|
||
否
|
||
检索请求的一致性级别，取值为：
|
||
EVENTUAL（默认值）：最终一致性，查询请求会随机发送给分片的所有副本；
|
||
STRONG：强一致性，查询请求只会发送给分片主副本。
|
||
BM25SearchRequest参数
|
||
参数
|
||
参数类型
|
||
是否必选
|
||
参数含义
|
||
index_name
|
||
String
|
||
是
|
||
倒排索引的名字。
|
||
search_text
|
||
String
|
||
是
|
||
全文检索的检索表达式，UTF-8编码，几种常见用法:
|
||
content:数据库 ----> 在content这列搜索"数据库"关键字
|
||
content: 百度VectorDB数据库 -----> 在content这列匹配"百度VectorDB数据库"中任意关键字
|
||
content: "百度VectorDB数据库" -----> 搜索短语"百度VectorDB数据库"
|
||
content: 百度 AND content: VectorDB ----> 在content这列同时匹配"百度"、"VectorDB" 关键字
|
||
content: 百度 OR content: VectorDB. -----> 在content这列匹配"百度"、"VectorDB"的任意一个
|
||
|
||
更多用法见全文检索表达式。
|
||
limit
|
||
int
|
||
否
|
||
指定返回相关性最高的条目数。
|
||
filter
|
||
String
|
||
否
|
||
检索的标量过滤条件，表示仅在符合过滤条件的候选集中进行检索，默认为空。Filter表达式语法参照SQL的WHERE子句语法进行设计，其详细描述和使用示例请参见Filter条件表达式。
|
||
全文检索表达式
|
||
检索类型
|
||
用法
|
||
例子
|
||
例子含义
|
||
备注
|
||
关键词检索
|
||
field_name: keyword
|
||
field_name: (keyword_1, keyword_2)
|
||
title:数据库
|
||
title:(数据库 百度)
|
||
在title这列搜索“数据库”关键字
|
||
在title这列搜索“数据库”、"百度"关键字，满足任意一个即可
|
||
关键词检索
|
||
keyword
|
||
keyword_1 AND keyword_2
|
||
数据库
|
||
数据库 AND 百度
|
||
在content 这列上搜索"数据库"关键字
|
||
在content 这列上搜索，要求同时包括"数据库"、"百度" 关键字
|
||
只适用于在单列上建立倒排索引的情况，如在content 这列上建立倒排索引
|
||
复合检索: AND/OR
|
||
query_1 AND query_2
|
||
query_1 OR query_2
|
||
(query_1 OR query_2) AND query_3
|
||
title:数据库 AND title:百度
|
||
title:数据库 OR title:百度
|
||
(title:数据库 OR title:百度) AND content:VectorDB
|
||
在title这列搜索, 要求同时包括"数据库"、"百度" 这2个关键字
|
||
在title这列搜索, 要求包括"数据库"、"百度" 任意一个
|
||
在title这列搜索, 要求包括"数据库"、"百度" 任意一个，同时content列包含"VectorDB"关键字
|
||
Phrase检索
|
||
field_name:"phrase"
|
||
title:"百度VectorDB数据库"
|
||
在title这里搜索短语"百度VectorDB数据库"
|
||
短语必须使用""双引号
|
||
Match检索
|
||
field_name:statement
|
||
content:百度VectorDB的优缺点
|
||
在content这列搜索"百度VectorDB的优缺点"的任意词，匹配词数量越多，相关性得分越高
|
||
prefix检索
|
||
field_name:keyword*
|
||
title:数据*
|
||
在title这列检索，包含以"数据"为前缀词的文档
|
||
更改查询权重
|
||
field_name:keyword^boost
|
||
title:数据库^2 OR content:百度
|
||
title包括"数据库"关键字，或content包含“百度”关键字，最后计算相关性得分是，title列匹配的文档权重系数为2， content 列匹配的权重系数为1.0
|
||
不设置boost的话，默认权重都是1.0
|
||
全文检索表达式会将一些特殊字符用于专用目的，如想在表达式中匹配一些特殊字符，需要用\符号进行转义。当前被征用特殊字符包括:
|
||
+ - && || ! ( ) { } [ ] ^ " ~ * ? : \
|
||
以"百度自研的向量数据库:VectorDB"这个表达式为例，表达式解释器会认为想在"百度自研的向量数据库" 这列上搜索"VectorDB"，这就违背了使用者的初衷，为此需要把表达式写成"百度自研的向量数据库:VectorDB"
|
||
|
||
|
||
混合检索
|
||
功能介绍
|
||
同时进行关键字全文检索和向量检索，检索结果融合排序后返回，也支持通过标量属性进行过滤。
|
||
请求示例
|
||
Python复制
|
||
import pymochow
|
||
from pymochow.configuration import Configuration
|
||
from pymochow.auth.bce_credentials import BceCredentials
|
||
from pymochow.model.table import VectorTopkSearchRequest, BM25SearchRequest, FloatVector, VectorSearchConfig, HybridSearchRequest
|
||
|
||
account = 'root'
|
||
api_key = 'your_api_key'
|
||
endpoint = 'you_endpoint' #example http://127.0.0.1:8511
|
||
|
||
config = Configuration(credentials=BceCredentials(account, api_key),
|
||
endpoint=endpoint)
|
||
client = pymochow.MochowClient(config)
|
||
|
||
db = client.database("db_test")
|
||
table = db.table("book_vector")
|
||
|
||
bm25_request = BM25SearchRequest(index_name="book_segment_inverted_idx",
|
||
search_text="吕布")
|
||
vector_request = VectorTopkSearchRequest(vector_field="vector", vector=FloatVector[0.3123, 0.43, 0.213],
|
||
limit=10, filter=None, config=VectorSearchConfig(ef=200))
|
||
|
||
hybrid_search_request = HybridSearchRequest(vector_request=vector_request,
|
||
bm25_request=bm25_request,
|
||
vector_weight=0.5,
|
||
bm25_weight=0.5,
|
||
limit=10,
|
||
filter="bookName='三国演义'")
|
||
res = table.hybrid_serch(request=hybrid_search_request)
|
||
logger.debug("res: {}".format(res))
|
||
client.close()
|
||
请求参数
|
||
参数
|
||
参数类型
|
||
是否必选
|
||
参数含义
|
||
request
|
||
HybridSearchRequest
|
||
是
|
||
混合检索的详细参数。
|
||
partition_key
|
||
Json
|
||
否
|
||
目标记录的分区键值，如果该表的分区键和主键是同一个键，则不需要填写分区键值。
|
||
需要注意的是，如果没有指定分区键值，那么该检索请求可能会退化为在该表所有分片上都执行的MPP检索。
|
||
projections
|
||
List<String>
|
||
否
|
||
投影字段列表，默认为空，为空时检索结果返回所有标量字段。
|
||
read_consistency
|
||
ReadConsistency
|
||
否
|
||
检索请求的一致性级别，取值为：
|
||
EVENTUAL（默认值）：最终一致性，查询请求会随机发送给分片的所有副本；
|
||
STRONG：强一致性，查询请求只会发送给分片主副本。
|
||
HybridSearchRequest参数
|
||
参数
|
||
参数类型
|
||
是否必选
|
||
参数含义
|
||
vector_request
|
||
VectorTopkSearchRequest 或 VectorRangeSearchRequest 或 VectorBatchSearchRequest
|
||
是
|
||
向量检索的详细参数
|
||
bm25_request
|
||
BM25SearchRequest
|
||
是
|
||
全文检索的详细参数
|
||
vector_weight
|
||
Float
|
||
否
|
||
向量检索结果在混合检索中所占权重，默认0.5
|
||
bm25_weight
|
||
Float
|
||
否
|
||
全文检索结果在混合检索中所占比重，默认0.5
|
||
limit
|
||
Int
|
||
否
|
||
返回的最相关条目数
|
||
filter
|
||
String
|
||
否
|
||
检索的标量过滤条件，表示仅在符合过滤条件的候选集中进行检索，默认为空。Filter表达式语法参照SQL的WHERE子句语法进行设计，其详细描述和使用示例请参见Filter条件表达式。
|
||
|
||
|
||
SearchIterator
|
||
功能介绍
|
||
SearchIterator 提供了一种分页获取搜索结果的机制。在 SearchIterator 请求中，limit参数用于指定当前分页的返回结果数量。通过多次调用迭代器，可以突破单次检索的 topK 数量限制，逐步获取完整的结果集。对于 topK 值较大的搜索请求，推荐使用 SearchIterator 来实现结果的分批次获取。
|
||
请求示例
|
||
Python复制
|
||
import pymochow
|
||
from pymochow.configuration import Configuration
|
||
from pymochow.auth.bce_credentials import BceCredentials
|
||
from pymochow.model.table import VectorTopkSearchRequest, FloatVector, VectorSearchConfig
|
||
|
||
account = 'root'
|
||
api_key = 'your_api_key'
|
||
endpoint = 'you_endpoint' #example http://127.0.0.1:8511
|
||
|
||
config = Configuration(credentials=BceCredentials(account, api_key),
|
||
endpoint=endpoint)
|
||
client = pymochow.MochowClient(config)
|
||
|
||
db = client.database("db_test")
|
||
table = db.table("book_vector")
|
||
|
||
request = VectorTopkSearchRequest(
|
||
vector_field="vector",
|
||
vector=FloatVector([1, 0.21, 0.213, 0]),
|
||
limit=1000,
|
||
config=VectorSearchConfig(ef=2000))
|
||
|
||
iterator = table.search_iterator(request=request, batch_size=1000, total_size=10000) # 初始化 SearchIterator
|
||
|
||
while True:
|
||
rows = iterator1.next() # 获取下一批检索结果
|
||
if not rows:
|
||
break
|
||
logger.debug("rows:{}".format(rows))
|
||
|
||
iterator1.close() # 释放 iterator
|
||
|
||
client.close()
|
||
接口描述
|
||
Table.search_iterator
|
||
功能：初始化 SearchIterator 对象。
|
||
参数：
|
||
参数名
|
||
参数类型
|
||
是否必选
|
||
参数含义
|
||
request
|
||
VectorTopkSearchRequest 或 MultiVectorSearchRequest
|
||
是
|
||
检索请求参数描述信息。
|
||
batch_size
|
||
Int
|
||
是
|
||
每批次检索获取记录条数
|
||
total_size
|
||
Int
|
||
是
|
||
获取记录总条数
|
||
partition_key
|
||
Json
|
||
否
|
||
目标记录的分区键值，如果该表的分区键和主键是同一个键，则不需要填写分区键值。
|
||
需要注意的是，如果没有指定分区键值，那么该检索请求可能会退化为在该表所有分片上都执行的MPP检索。
|
||
projections
|
||
List<String>
|
||
否
|
||
投影字段列表，默认为空，为空时检索结果返回所有标量字段。
|
||
read_consistency
|
||
ReadConsistency
|
||
否
|
||
检索请求的一致性级别，取值为：
|
||
EVENTUAL（默认值）：最终一致性，查询请求会随机发送给分片的所有副本；
|
||
STRONG：强一致性，查询请求只会发送给分片主副本。
|
||
返回类型：SearchIterator。
|
||
SearchIterator.next
|
||
功能：执行检索，并返回检索结果。当返回结果为空，说明 SearchIterator 执行结束。
|
||
参数：无。
|
||
返回类型：List<Row>。
|
||
SearchIterator.close
|
||
功能：释放 SearchIterator。执行 close 后，不应该再调用 next。
|
||
参数：无。
|
||
返回类型：无。
|
||
限制
|
||
仅支持 HNSW、HNSWPQ 索引类型。
|
||
仅支持向量TopK检索（VectorTopkSearch）、多向量检索（MultiVectorSearch），不支持向量范围检索（VectorRangeSearch）、批量向量检索（VectorBatchSearch）、全文检索（BM25Search）、混合检索（HybridSearch）。
|
||
对于 MultiVectorSearch，仅支持 ws融合排序算法。
|
||
|
||
Index 操作
|
||
更新时间：2024-12-11
|
||
创建索引
|
||
功能介绍
|
||
为指定表和指定字段新建索引，当前仅支持新建向量索引。
|
||
请求示例
|
||
Python复制
|
||
import pymochow
|
||
from pymochow.configuration import Configuration
|
||
from pymochow.auth.bce_credentials import BceCredentials
|
||
from pymochow.model.schema import SecondaryIndex, VectorIndex, HNSWParams, AutoBuildPeriodical
|
||
from pymochow.model.enum import IndexType, MetricType
|
||
|
||
account = 'root'
|
||
api_key = '$您的账户API密钥'
|
||
endpoint = '$您的实例访问端点' # 例如：'http://127.0.0.1:5287'
|
||
|
||
config = Configuration(credentials=BceCredentials(account, api_key),
|
||
endpoint=endpoint)
|
||
client = pymochow.MochowClient(config)
|
||
|
||
db = client.database("db_test")
|
||
|
||
indexes = []
|
||
indexes.append(
|
||
VectorIndex(
|
||
index_name="vector_idx",
|
||
index_type=IndexType.HNSW,
|
||
field="vector",
|
||
metric_type=MetricType.L2,
|
||
params=HNSWParams(m=32, efconstruction=200),
|
||
auto_build=True,
|
||
auto_build_index_policy=AutoBuildPeriodical(5000, "2026-01-01 12:00:00")
|
||
)
|
||
)
|
||
|
||
table = db.table("book_vector")
|
||
table.create_indexes(indexes)
|
||
|
||
client.close()
|
||
请求参数
|
||
参数
|
||
参数类型
|
||
是否必选
|
||
参数含义
|
||
indexes
|
||
List<Index>
|
||
是
|
||
索引列表。
|
||
Index参数
|
||
请参见建表操作的索引参数描述。
|
||
|
||
|
||
删除索引
|
||
功能介绍
|
||
删除指定索引，当前不支持删除构建中的向量索引。
|
||
请求示例
|
||
Python复制
|
||
import pymochow
|
||
from pymochow.configuration import Configuration
|
||
from pymochow.auth.bce_credentials import BceCredentials
|
||
|
||
account = 'root'
|
||
api_key = '$您的账户API密钥'
|
||
endpoint = '$您的实例访问端点' # 例如：'http://127.0.0.1:5287'
|
||
|
||
config = Configuration(credentials=BceCredentials(account, api_key),
|
||
endpoint=endpoint)
|
||
client = pymochow.MochowClient(config)
|
||
|
||
db = client.database("db_test")
|
||
|
||
table = db.table("book_vector")
|
||
table.drop_index("vector_idx")
|
||
|
||
client.close()
|
||
请求参数
|
||
参数
|
||
参数类型
|
||
是否必选
|
||
参数含义
|
||
index_name
|
||
String
|
||
是
|
||
指定索引的名称。
|
||
|
||
|
||
重建向量索引
|
||
功能介绍
|
||
重建指定索引，当前仅支持重建向量索引。
|
||
请求示例
|
||
Python复制
|
||
import pymochow
|
||
from pymochow.configuration import Configuration
|
||
from pymochow.auth.bce_credentials import BceCredentials
|
||
|
||
account = 'root'
|
||
api_key = '$您的账户API密钥'
|
||
endpoint = '$您的实例访问端点' # 例如：'http://127.0.0.1:5287'
|
||
|
||
config = Configuration(credentials=BceCredentials(account, api_key),
|
||
endpoint=endpoint)
|
||
client = pymochow.MochowClient(config)
|
||
|
||
db = client.database("db_test")
|
||
|
||
table = db.table("book_vector")
|
||
table.rebuild_index(index_name="vector_idx")
|
||
|
||
client.close()
|
||
请求参数
|
||
参数
|
||
参数类型
|
||
是否必选
|
||
参数含义
|
||
index_name
|
||
String
|
||
是
|
||
向量索引的名称。
|
||
|
||
|
||
查询索引详情
|
||
功能介绍
|
||
查询指定索引的详情。
|
||
请求示例
|
||
Python复制
|
||
import pymochow
|
||
from pymochow.configuration import Configuration
|
||
from pymochow.auth.bce_credentials import BceCredentials
|
||
|
||
account = 'root'
|
||
api_key = '$您的账户API密钥'
|
||
endpoint = '$您的实例访问端点' # 例如：'http://127.0.0.1:5287'
|
||
|
||
config = Configuration(credentials=BceCredentials(account, api_key),
|
||
endpoint=endpoint)
|
||
client = pymochow.MochowClient(config)
|
||
|
||
db = client.database("db_test")
|
||
|
||
table = db.table("book_vector")
|
||
index = table.describe_index(index_name="vector_idx")
|
||
|
||
client.close()
|
||
请求参数
|
||
参数
|
||
参数类型
|
||
是否必选
|
||
参数含义
|
||
index_name
|
||
String
|
||
是
|
||
指定索引的名称。
|
||
返回参数
|
||
参数
|
||
参数类型
|
||
参数含义
|
||
index
|
||
Index
|
||
Index对象
|
||
Index参数
|
||
参数
|
||
参数类型
|
||
参数含义
|
||
vector_index
|
||
VectorIndex
|
||
向量索引对象。
|
||
secondary_index
|
||
SecondaryIndex
|
||
标量二级索引对象。
|
||
filtering_index
|
||
FilteringIndex
|
||
过滤索引对象。在带有过滤条件的检索场景中，为过滤的标量字段添加索引，可以显著加速检索过程，从而有效提升检索性能。
|
||
inverted_index
|
||
InvertedIndex
|
||
倒排索引对象。
|
||
VectorIndex参数
|
||
参数
|
||
参数类型
|
||
参数含义
|
||
index_name
|
||
String
|
||
索引名称。
|
||
index_type
|
||
IndexType
|
||
索引类型。
|
||
field
|
||
String
|
||
索引作用于的字段名称。
|
||
metric_type
|
||
MetricType
|
||
向量之间距离度量算法类型。取值如下：
|
||
L2：欧几里得距离
|
||
IP：内积距离
|
||
COSINE：余弦距离
|
||
|
||
注：当使用COSINE距离时，用户需要自行对相关向量进行归一化操作，未经归一化的向量将导致search结果不准确
|
||
autoBuild
|
||
Bool
|
||
是否有自动构建索引策略。
|
||
autoBuildPolicy
|
||
AutoBuildPolicy
|
||
自动构建索引策略参数
|
||
policyType：策略类型，有如下几种类型:
|
||
periodical，周期性构建索引。
|
||
rowCountIncrement，根据tablet行增长数自动构建索引。
|
||
timing，定时构建索引
|
||
periodInSecond：周期性构建索引的秒数，只在周期性构建索引策略类型时返回。
|
||
timing：字符串类型，返回定时构建的时间，只在定时构建索引策略类型时返回
|
||
rowCountIncrement：返回触发构建时增长的行数以及百分比，只在行增长数构建索引类型时返回。
|
||
params
|
||
Params
|
||
向量索引构建参数。
|
||
state
|
||
IndexState
|
||
索引状态。取值如下：
|
||
BUILDING：表示索引正在构建中
|
||
NORMAL：表示索引已完成构建并处于正常状态
|
||
SecondaryIndex参数
|
||
参数
|
||
参数类型
|
||
参数含义
|
||
index_name
|
||
String
|
||
索引名称
|
||
field
|
||
String
|
||
索引作用于的字段名称。
|
||
FilteringIndex
|
||
参数
|
||
参数类型
|
||
参数含义
|
||
index_name
|
||
String
|
||
索引名称
|
||
fields
|
||
List
|
||
索引作用于的字段名称。
|
||
InvertedIndex
|
||
参数
|
||
参数类型
|
||
参数含义
|
||
index_name
|
||
String
|
||
索引名称
|
||
fields
|
||
List
|
||
索引作用于的字段名称。
|
||
params
|
||
InvertedIndexParams
|
||
倒排索引参数。
|
||
field_attributes
|
||
List
|
||
指定建立倒排索引的列是否需要分词(默认是会分词)，参数顺序应与'fields'里列名一一对应。目前支持以下选项:
|
||
|
||
ATTRIBUTE_ANALYZED
|
||
ATTRIBUTE_NOT_ANALYZED
|
||
InvertedIndexParams
|
||
参数
|
||
参数类型
|
||
参数含义
|
||
analyzer
|
||
InvertedIndexAnalyzer
|
||
指定倒排索引的分词器。 目前支持以下三种:
|
||
|
||
ENGLISH_ANALYZER : 英文分词器
|
||
CHINESE_ANALYZER: 中文分词器
|
||
DEFAULT_ANALYZER: 默认分词器，适用于英文、中文、中英文混合等场景，建议使用
|
||
parse_mode
|
||
InvertedIndexParseMode
|
||
分词器的分词模式。
|
||
|
||
COARSE_MODE: 较粗粒度，基于不产生歧义的较大粒度进行切分，适宜于对语义表达能力要求较高的应用
|
||
FINE_MODE: 细粒度模式，基于语义完整的最小粒度进行切分
|
||
修改索引
|
||
功能介绍
|
||
修改向量索引信息，目前只支持修改autoBuild属性。
|
||
请求示例
|
||
Plain Text复制
|
||
import pymochow
|
||
import time
|
||
|
||
from pymochow.configuration import Configuration
|
||
from pymochow.auth.bce_credentials import BceCredentials
|
||
from pymochow.model.schema import Schema, Field, SecondaryIndex, VectorIndex, HNSWParams, AutoBuildTiming, AutoBuildPeriodical, AutoBuildRowCountIncrement
|
||
from pymochow.model.enum import FieldType, IndexType, MetricType, ServerErrCode
|
||
from pymochow.model.enum import TableState, IndexState
|
||
from pymochow.model.table import Partition, Row, AnnSearch, HNSWSearchParams
|
||
|
||
if __name__ == "__main__":
|
||
account = 'root'
|
||
api_key = '$您的API密钥'
|
||
endpoint = '$您的实例端点' #例如：'http://127.0.0.1:5287'
|
||
config = Configuration(credentials=BceCredentials(account, api_key),
|
||
endpoint=endpoint)
|
||
client = pymochow.MochowClient(config)
|
||
database = 'book'
|
||
table_name = 'book_segments'
|
||
|
||
db = client.create_database(database)
|
||
fields = []
|
||
fields.append(Field("id", FieldType.STRING, primary_key=True,
|
||
partition_key=True, auto_increment=False, not_null=True))
|
||
fields.append(Field("bookName", FieldType.STRING, not_null=True))
|
||
fields.append(Field("vector", FieldType.FLOAT_VECTOR, not_null=True, dimension=3))
|
||
|
||
db.create_table(
|
||
table_name=table_name,
|
||
replication=2,
|
||
partition=Partition(partition_num=3),
|
||
schema=Schema(fields=fields, indexes=[])
|
||
)
|
||
while True:
|
||
time.sleep(2)
|
||
table = db.describe_table(table_name)
|
||
if table.state == TableState.NORMAL:
|
||
break
|
||
|
||
table = db.table('book_segments')
|
||
indexes = []
|
||
vindex = VectorIndex(index_name="vector_idx",
|
||
index_type=IndexType.HNSW,
|
||
field="vector", metric_type=MetricType.L2,
|
||
params=HNSWParams(m=32, efconstruction=200))
|
||
indexes.append(vindex)
|
||
table.create_indexes(indexes)
|
||
table.modify_index(index_name="vector_idx", auto_build=True,
|
||
auto_build_index_policy=AutoBuildTiming("2024-06-06 00:00:00"))
|
||
请求参数
|
||
参数
|
||
参数类型
|
||
是否必选
|
||
参数含义
|
||
index_name
|
||
String
|
||
是
|
||
索引列表。
|
||
auto_build
|
||
Boolean
|
||
是
|
||
是否自动构建索引，默认为False。
|
||
auto_build_index_policy
|
||
AutoBuildPolicy
|
||
否
|
||
自动构建索引策略，当前支持如下策略:
|
||
AutoBuildTiming：定时构建，指定构建的时间，构建一次，不会重复构建。例如AutoBuildTiming("2026-09-11 23:07:00")，时间格式支持UTC及LOCAL。
|
||
AutoBuildPeriodical：周期性构建，每过period_s秒构建一次索引，可重复构建。可以指定从某个时间点开始，例如AutoBuildPeriodical(24 * 3600, "2026-09-11 23:07:00")。周期不能低于3600，时间格式支持LOCAL以及UTC。
|
||
AutoBuildRowCountIncrement：增量行数构建。Tablet（不是table）增加或者减少指定的行数时会自动构建一次索引，可重复构建，支持具体行数以及百分比，只需传入一种即可，也可传入两种，触发其中之一便会开始构建。例如AutoBuildRowCountIncrement(row_count_increment = 10000, row_count_increment_ratio = 0.5)。增量行数不低于10000，增量行数百分比需要大于0。 |