兼容性说明

本文档介绍了 seekdb 向量搜索功能与 Milvus 的数据模型映射关系、SDK 接口兼容性以及相关概念对照说明。

与 Milvus 概念映射

为方便熟知 Milvus 的用户上手 seekdb 向量存储能力，分析两者之间的异同并提供相关概念之间的映射。

数据模型

数据模型层级	Milvus	seekdb	描述
第一层	Shards	Partition	Milvus 通过在模式定义时设置某些列为 `partition_key` 来制定分区规则 seekdb 支持 range/range columns、list/list columns、hash、key 以及二级分区策略
第二层	Partitions	≈Tablet	Milvus 支持在同一个 Shards 中（Shards 通常按照主键进行分区）按照其他列进行分块，以提升读性能 seekdb 则是通过在分区内按照主键排序实现
第三层	Segments	MemTable+SSTable	两者都有转储行为

SDK

本小节介绍 seekdb 向量存储的 SDK —— pyobvector 和 Milvus 的 SDK —— pymilvus 的概念差异。

pyobvector 具有两种使用模式：

pymilvus MilvusClient 轻量兼容模式：该模式兼容了 Milvus 客户端常用的接口，熟悉 Milvus 的用户非常方便地使用本模式，无需概念映射。
SQLAlchemy 扩展模式：该模式可以作为 python SQLAlchemy 的向量功能扩展，保留了关系型数据库的操作模式，需要概念映射进行说明。

pyobvector 具体接口使用文档请参见 pyobvector Python SDK 接口说明。

下表说明 pyobvector SQLAlchemy 扩展模式下和 Milvus SDK 接口的概念映射：

pymilvus	pyobvector	描述
Database	Database	数据库
Collection	Table	表
Field	Column	列
Primary Key	Primary Key	主键
Vector Field	Vector Column	向量列
Index	Index	索引
Partition	Partition	分区
DataType	DataType	数据类型
Metric Type	Distance Function	距离函数
Search	Query	查询
Insert	Insert	插入
Delete	Delete	删除
Update	Update	更新
Batch	Batch	批量操作
Transaction	Transaction	事务
NONE	不支持	NULL 值
BOOL	Boolean	对应 MySQL TINYINT 类型
INT8	Boolean	对应 MySQL TINYINT 类型
INT16	SmallInteger	对应 MySQL SMALLINT 类型
INT32	Integer	对应 MySQL INT 类型
INT64	BigInteger	对应 MySQL BIGINT 类型
FLOAT	Float	对应 MySQL FLOAT 类型
DOUBLE	Double	对应 MySQL DOUBLE 类型
STRING	LONGTEXT	对应 MySQL LONGTEXT 类型
VARCHAR	STRING	对应 MySQL VARCHAR 类型
JSON	JSON	JSON 操作异同点请参见 pyobvector Python SDK 接口说明
FLOAT_VECTOR	VECTOR	向量类型
BINARY_VECTOR	不支持
FLOAT16_VECTOR	不支持
BFLOAT16_VECTOR	不支持
SPARSE_FLOAT_VECTOR	不支持
dynamic_field	无需支持	Milvus 中的隐藏 `$meta` 元数据列 seekdb 显示创建 JSON 类型的列即可

与 Milvus 兼容性

Milvus SDK

除 load_collection()/release_collection()/close() 等需通过 SQLAlchemy 支持外，下述表中所列接口均可兼容：

Collection 操作

接口	描述
create_collection()	根据给定的 Schema 创建一个向量表。
get_collection_stats()	查看数据表统计信息，如记录行数。
describe_collection()	提供向量表的详细元信息。
has_collection()	判断表是否存在。
list_collections()	列出存在的表。
drop_collection()	删除表。

Field 与 Schema 定义

接口	描述
create_schema()	创建一个 Schema 内存结构、添加列定义。
add_field()	使用时调用序列 create_schema->add_field->...->add_field 也可以手动构造一个 FieldSchema 列表，再通过 CollectionSchema 的构造函数来创建 Schema。

向量索引

接口	描述
list_indexes()	列出所有索引。
create_index()	支持一次调用创建多个向量索引，首先通过 prepare_index_params 来初始化一个索引参数列表对象，调用多次 add_index 来设置多个索引参数，最终通过 create_index 来创建索引。
drop_index()	删除向量索引。
describe_index()	获得索引的元数据（Schema）。

向量索引

接口	描述
search()	ANN 查询接口： collection_name：表名 data：查询的向量 filter：筛选操作，等价于 `WHERE` limit：top K output_fields：投影列，等价于 `SELECT` partition_names：分区名（Milvus Lite 不支持） anns_field：索引列名 search_params：向量距离函数名、索引算法相关参数
query()	含 filter 点查询，即 `SELECT ... WHERE ids IN (..., ...) AND <filters>`。
get()	不含 filter 点查询，即 `SELECT ... WHERE ids IN (..., ...)`。
delete()	删除一组向量，`DELETE FROM ... WHERE ids IN (..., ...)`。
insert()	插入一组向量。
upsert()	主键冲突带更新的插入。

collection 元数据同步

接口	描述
load_collection()	将数据库中的表结构(Schema)加载到 Python 应用程序内存中，使应用程序能够以面向对象的方式操作数据库表。是对象关系映射（ORM）框架的一个标准功能。
release_collection()	从 Python 应用程序内存中释放已加载的表结构(Schema)，释放相关资源。这是 ORM 框架的一个标准功能,用于内存管理。
close()	关闭数据库连接，释放相关资源。这是 ORM 框架的标准功能。

pymilvus

数据模型

Milvus 的数据模型分为 Shards->Partitions->Segments 三个级别，与 OceanBase 兼容性对比如下：

Shards 对应于 seekdb 的 Partition 概念。
Partitions 目前 seekdb 无对应概念。
Milvus 支持在同一个 Shards 中（Shards 通常按照主键进行分区）按照其他列进行分块，以提升读性能。seekdb 则是通过在分区内按照主键排序实现。
Segments 类似于 MemTable + SSTable。

Milvus Lite API 兼容性

collection 操作

Milvus create_collection()：

create_collection(
    collection_name: str,
    dimension: int,
    primary_field_name: str = "id",
    id_type: str = DataType,
    vector_field_name: str = "vector",
    metric_type: str = "COSINE",
    auto_id: bool = False,
    timeout: Optional[float] = None,
    schema: Optional[CollectionSchema] = None, # Used for custom setup
    index_params: Optional[IndexParams] = None, # Used for custom setup
    **kwargs,
) -> None

seekdb 兼容说明如下：

collection_name：兼容，实际为 table_name。
dimension：兼容，vector(dim)。
primary_field_name：兼容，主键列名。
id_type：兼容，主键列列类型。
vector_field_name：兼容，向量列名。
auto_id：兼容，auto increment。
timeout：兼容，seekdb通过hint支持。
schema：兼容。
index_params：兼容。

Milvus get_collection_stats()：
```
get_collection_stats(
    collection_name: str, 
    timeout: Optional[float] = None
) -> Dict
```
seekdb 兼容说明如下：
- API 兼容。
- 返回值兼容：{ 'row_count': ... }。

Milvus has_collection()：

has_collection(
    collection_name: str,
    timeout: Optional[float] = None
) -> Bool

seekdb 兼容 Milvus has_collection()。

Milvus drop_collection()：
```
drop_collection(collection_name: str) -> None
```
seekdb 兼容 Milvus drop_collection()。

Milvus rename_collection()：

rename_collection(
    old_name: str,
    new_name: str,
    timeout: Optional[float] = None
) -> None

seekdb 兼容 Milvus rename_collection()。

Schema 相关

Milvus create_schema()：

create_schema(
    auto_id: bool,
    enable_dynamic_field: bool,
    primary_field: str,
    partition_key_field: str,
) -> CollectionSchema

seekdb 兼容说明如下：

auto_id：是否自增主键列，可兼容。
primary_field & partition_key_field：可兼容。

Milvus add_field()：

add_field(
    field_name: str,
    datatype: DataType,
    is_primary: bool,
    max_length: int,
    element_type: str,
    max_capacity: int,
    dim: int,
    is_partition_key: bool,
)

seekdb 兼容 Milvus add_field()。

Insert/Search 相关

Milvus search()：
```
search(
    collection_name: str,
    data: Union[List[list], list],
    filter: str = "",
    limit: int = 10,
    output_fields: Optional[List[str]] = None,
    search_params: Optional[dict] = None,
    timeout: Optional[float] = None,
    partition_names: Optional[List[str]] = None,
    **kwargs,
) -> List[dict]
```
seekdb 兼容说明如下：
- filter：str 表达式，具体使用示例参见：milvus 的过滤说明，大体上和 SQL 的 WHERE 表达式类似。
- search_params：
  - metric_type: 兼容。
  - radius & range filter：RNN 相关，目前不支持。
  - group_by_field：对 ANN 结果进行分组，目前不支持。
  - max_empty_result_buckets：IVF 系列索引使用，目前不支持。
  - ignore_growing：跳过增量部分，直接读取基线索引，目前不支持。
- partition_names：分区读，支持。
- kwargs：
  - offset：搜索结果中要跳过的记录数，目前不支持。
  - round_decimal：对结果进行指定小数位数的四舍五入，目前不支持。

Milvus get()：

get(
    collection_name: str,
    ids: Union[list, str, int],
    output_fields: Optional[List[str]] = None,
    timeout: Optional[float] = None,
    partition_names: Optional[List[str]] = None,
    **kwargs,
) -> List[dict]

seekdb 兼容 Milvus get()。

Milvus delete()

delete(
    collection_name: str,
    ids: Optional[Union[list, str, int]] = None,
    timeout: Optional[float] = None,
    filter: Optional[str] = "",
    partition_name: Optional[str] = "",
    **kwargs,
) -> dict

seekdb 兼容 Milvus delete()。

Milvus insert()

insert(
    collection_name: str,
    data: Union[Dict, List[Dict]],
    timeout: Optional[float] = None,
    partition_name: Optional[str] = "",
) -> List[Union[str, int]]

seekdb 兼容 Milvus insert()。

Milvus upsert()

upsert(
    collection_name: str,
    data: Union[Dict, List[Dict]],
    timeout: Optional[float] = None,
    partition_name: Optional[str] = "",
) -> List[Union[str, int]]

seekdb 兼容 Milvus upsert()。

index 相关

Milvus create_index()

create_index(
    collection_name: str,
    index_params: IndexParams,
    timeout: Optional[float] = None,
    **kwargs,    
)

seekdb 兼容 Milvus create_index()。

Milvus drop_index()

drop_index(
    collection_name: str,
    index_name: str,
    timeout: Optional[float] = None,
    **kwargs,    
)

seekdb 兼容 Milvus drop_index()。

与 MySQL 协议兼容性

request 请求发起方面：API 均通过普通查询 SQL 来实现，不存在兼容性问题。
response 结果集处理方面：只需考虑新增的向量数据元素的处理，目前支持 string 和 bytes 两种元素的解析，即使后续向量数据元素传输方式发生变化，也可通过更新 SDK 完成兼容。

与 Milvus 概念映射​

数据模型​

SDK​

与 Milvus 兼容性​

Milvus SDK​

pymilvus​

数据模型​

Milvus Lite API 兼容性​

collection 操作​

Schema 相关​

Insert/Search 相关​

index 相关​

与 MySQL 协议兼容性​

Contents

与 Milvus 概念映射

数据模型

SDK

与 Milvus 兼容性

Milvus SDK

pymilvus

数据模型

Milvus Lite API 兼容性

collection 操作

Schema 相关

Insert/Search 相关

index 相关

与 MySQL 协议兼容性