概述

OceanBase SeekDB 是 OceanBase 团队全新研发的 AI 原生数据库产品，基于 OceanBase 数据库核心引擎打造，专门针对 AI 应用场景进行了深度优化和功能增强。SeekDB 在保留 OceanBase 强大关系型数据处理能力的同时，集成了完整的向量检索、全文检索、混合搜索和 AI Functions 等关键 AI 功能，为现代 AI 应用提供统一的存储和检索基础设施。

SeekDB 的设计理念是极简部署、高效运行、开发者友好。它能够在仅 1 核 CPU 和 1GB 内存的极低资源配置下运行，启动时间仅需数秒，无需复杂的配置流程，真正实现了"开箱即用"的开发体验。资料来源：README.md

核心特性

🚀 极简部署，为开发者和 AI 智能体而生

SeekDB 支持两种部署模式：客户端/服务端模式适合生产环境和企业级应用，嵌入式模式则适合个人开发、原型验证和边缘计算场景。资料来源：package/wheel/README.md

🐚 快速演进的 AI 能力

#### 向量索引 (Vector Indexing)

SeekDB 提供高性能的多维向量数据检索能力，支持海量向量处理。通过灵活的访问接口（SQL/Python/Java），开发者可以轻松实现语义搜索、相似度匹配等 AI 应用场景。

-- 创建带有向量列的表
CREATE TABLE articles (
    id INT PRIMARY KEY,
    title TEXT,
    content TEXT,
    embedding VECTOR(384),  -- 384维向量列
    VECTOR INDEX idx_vec (embedding) WITH(DISTANCE=l2, TYPE=hnsw, LIB=vsag)
);

向量索引支持的距离度量包括：

资料来源：src/objit/include/objit/common/ob_item_type.h

#### 全文索引 (Full-Text Indexing)

SeekDB 提供智能文本搜索能力，支持多语言分词、相关性排序和模糊搜索：

CREATE TABLE articles (
    id INT PRIMARY KEY,
    title TEXT,
    content TEXT,
    FULLTEXT INDEX idx_fts(content) WITH PARSER ik
);

-- 使用全文搜索
SELECT * FROM articles 
WHERE MATCH(content) AGAINST('keywords' IN NATURAL LANGUAGE MODE);

#### 混合搜索 (Hybrid Search)

SeekDB 支持对多模态数据进行统一查询，将向量检索和标量搜索相结合，通过智能排序返回最优结果：

SELECT
    title,
    content,
    l2_distance(embedding, '[query_embedding]') AS vector_distance,
    MATCH(content) AGAINST('your keywords' IN NATURAL LANGUAGE MODE) AS text_score
FROM articles
WHERE MATCH(content) AGAINST('your keywords' IN NATURAL LANGUAGE MODE)
ORDER BY vector_distance APPROXIMATE
LIMIT 10;

#### AI Functions

SeekDB 内置丰富的 AI 函数，简化 AI 应用开发：

资料来源：deps/oblib/src/lib/ob_name_def.h

🧱 MySQL 兼容与强大 HTAP 能力

SeekDB 完全兼容标准 MySQL 协议，支持使用 MySQL 生态工具进行无缝替换，同时具备强大的 HTAP（混合事务/分析处理）能力，支持在单一系统中同时处理事务和分析工作负载。

系统架构

graph TB
    subgraph "客户端层"
        Python_SDK["🐍 Python SDK<br/>(pyseekdb)"]
        SQL_Client["📊 SQL 客户端"]
        Java_SDK["☕ Java SDK"]
    end

    subgraph "SeekDB 核心引擎"
        Query_Processor["🔍 查询处理器"]
        Vector_Index["📐 向量索引引擎<br/>(VSAG + HNSW)"]
        FullText_Index["📝 全文索引引擎<br/>(IK 分词器)"]
        Storage_Engine["💾 存储引擎"]
    end

    subgraph "部署模式"
        Embedded["🔌 嵌入式模式<br/>(单进程)"]
        Server["🌐 服务端模式<br/>(C/S 架构)"]
        OceanBase["🗄️ OceanBase 集群模式"]
    end

    Python_SDK --> Embedded
    Python_SDK --> Server
    Python_SDK --> OceanBase
    SQL_Client --> Server
    SQL_Client --> OceanBase
    
    Query_Processor --> Vector_Index
    Query_Processor --> FullText_Index
    Query_Processor --> Storage_Engine
    
    Embedded --> Query_Processor
    Server --> Query_Processor
    OceanBase --> Query_Processor

使用场景

📖 RAG 与知识检索

大型语言模型的能力受限于训练数据。RAG（检索增强生成）通过引入及时且可信的外部知识来提升回答质量、减少幻觉。SeekDB 通过以下能力增强搜索准确性：

• 向量搜索实现语义理解
• 全文搜索覆盖精确关键词
• 混合搜索结合两者优势
• 多级访问控制保障数据隐私

适用场景：企业问答系统、客服机器人、行业洞察分析、个人知识库。

🔍 语义搜索引擎

传统关键词搜索难以捕捉用户意图。SeekDB 利用向量搜索理解语义含义，连接文本、图像等多模态数据：

• 商品搜索
• 图文搜索
• 以图搜商品

🎯 智能体 AI 应用

智能体 AI 需要记忆、规划、感知和推理能力。SeekDB 为智能体提供统一的基础设施：

• 元数据管理
• 向量/文本/混合查询
• 多模态数据处理
• RAG 支持
• 内置 AI 函数与推理
• 完善的隐私控制

适用场景：个人助手、企业自动化、垂直领域智能体、智能体平台。

📱 端侧与边缘 AI 应用

从移动设备到车载系统、工业终端，边缘设备在受限的计算和存储条件下运行。SeekDB 的轻量化架构支持嵌入式和微服务模式，在低资源占用下提供完整 SQL、JSON 和混合搜索能力。

适用场景：个人助手、车载系统、AI 教育、陪伴机器人、医疗设备。

快速开始

安装

#### Python SDK 安装

pip install seekdb

或使用最新版本：

pip install -U pyseekdb

资料来源：package/wheel/README.md

#### RPM 包安装（Linux）

rpm -ivh seekdb-{version}.x86_64.rpm

Python SDK 使用

import pyseekdb
from pyseekdb import DefaultEmbeddingFunction

# ==================== 连接模式选择 ====================

# 模式1: 嵌入式模式 (本地 SeekDB)
client = pyseekdb.Client(
    path="./seekdb.db",
    database="test"
)

# 模式2: 服务端模式 (连接远程 SeekDB 服务器)
# client = pyseekdb.Client(
#     host="127.0.0.1",
#     port=2881,
#     database="test",
#     user="root",
#     password=""
# )

# 模式3: OceanBase 服务器模式
# client = pyseekdb.Client(
#     host="127.0.0.1",
#     port=2881,
#     tenant="test",
#     user="your_user",
#     password="your_password"
# )

# ==================== 创建 Collection ====================
# 带 embedding function 的 collection - 嵌入向量自动生成
embedding_fn = DefaultEmbeddingFunction()

collection = client.create_collection(
    name="my_collection",
    dimension=384,
    embedding_function=embedding_fn
)

# ==================== 添加数据 ====================
documents = [
    "Artificial intelligence is transforming the world",
    "Python is a popular programming language",
    "Vector databases enable semantic search",
    "Neural networks are inspired by the human brain",
    "Natural language processing helps computers understand text"
]

ids = ["id1", "id2", "id3", "id4", "id5"]

collection.add(
    ids=ids,
    documents=documents,  # 嵌入向量将自动生成
    metadatas=[
        {"category": "AI", "index": 0},
        {"category": "Programming", "index": 1},
        {"category": "Database", "index": 2},
        {"category": "AI", "index": 3},
        {"category": "NLP", "index": 4}
    ]
)

# ==================== 查询数据 ====================
query_text = "artificial intelligence and machine learning"

results = collection.query(
    query_texts=query_text,  # 查询文本将自动转换为向量
    n_results=3  # 返回最相似的3个文档
)

print(f"查询: '{query_text}'")
print(f"找到 {len(results['ids'][0])} 条结果")

# ==================== 关闭连接 ====================
client.close()

SQL 使用

使用 SQLAlchemy 或其他 MySQL 兼容工具访问数据：

import sqlalchemy

# 创建连接
engine = sqlalchemy.create_engine("mysql+pymysql://user:pass@host:2881/test")

with engine.connect() as conn:
    result = conn.execute(sqlalchemy.text("SELECT * FROM articles"))
    for row in result:
        print(row)

版本信息

当前最新版本：V1.3.0

V1.3.0 是一个重大版本，引入异步索引和新一代 Change Stream 增量框架，将写入与索引构建解耦，实现极致的数据摄取吞吐量和稳定的查询性能。

平台支持

系统要求

• CPython 3.8+
• 最低配置：1 核 CPU + 1GB 内存

社区与贡献

SeekDB 是开源项目，欢迎社区贡献！贡献领域包括但不限于：

• 代码开发
• 文档完善
• 测试覆盖
• 观测性增强
• 工具链建设
• 生态系统集成

社区热门议题包括：

许可协议

SeekDB 采用 Apache 2.0 开源许可证。

另请参阅

• Python SDK 文档
• SQL 参考手册
• 部署指南
• API 参考
• 贡献指南

概述

OceanBase SeekDB 是由 OceanBase 团队开发的全新 AI 原生数据库产品，基于 OceanBase 数据库内核构建，专为 AI 应用场景设计。SeekDB 支持向量索引、全文索引、混合搜索和 AI 函数等核心 AI 功能，同时保持了极低的资源占用——最低可在仅 1 核 CPU 和 1GB 内存的环境下运行，支持秒级启动。

SeekDB 提供两种部署模式：

资料来源：package/wheel/README.md

系统要求

硬件要求

SeekDB 经过资源优化，可在极低配置环境下运行，但生产环境建议使用推荐配置以获得更好的性能表现。

软件要求

#### 操作系统支持

SeekDB 目前支持以下操作系统平台：

• Linux x86_64
• Linux aarch64 (ARM64)

资料来源：package/wheel/README.md

#### Python 环境要求

安装 Python SDK 前，请确保系统已安装符合要求的 Python 运行环境：

# 检查 Python 版本
python3 --version

# 建议使用 pip 安装或升级 pip
pip install --upgrade pip

资料来源：package/wheel/lib/setup.py:31-39

安装方式

方式一：pip 安装（推荐）

pip 是 Python 官方推荐的包管理工具，也是安装 SeekDB 最简单快捷的方式。

#### 安装命令

# 安装最新稳定版
pip install seekdb

# 或安装最新版本（开发版）
pip install -U pyseekdb

#### 验证安装

安装完成后，可通过以下方式验证 SeekDB 是否安装成功：

import seekdb

# 打开数据库
seekdb.open()

# 创建连接
conn = seekdb.connect()

# 测试查询
cursor = conn.cursor()
cursor.execute("SELECT 1")
result = cursor.fetchone()
print(f"SeekDB 安装成功: {result}")

# 关闭连接
conn.close()

资料来源：package/wheel/README.md

方式二：RPM 包安装

对于企业级部署场景，SeekDB 提供 RPM 包安装方式，适用于需要系统级集成或批量部署的环境。

#### 下载 RPM 包

从 OceanBase 官方渠道获取最新版本的 RPM 包：

seekdb-{版本号}.rpm

例如，v1.3.0 版本的 RPM 包名为：

seekdb-1.3.0.0-100000092026051510.x86_64.rpm

资料来源：package/wheel/README.md

#### 安装 RPM 包

使用 rpm 命令安装 SeekDB：

# 安装 RPM 包
sudo rpm -ivh seekdb-{版本号}.rpm

# 或升级已安装的包
sudo rpm -Uvh seekdb-{版本号}.rpm

#### 卸载 RPM 包

如需卸载 SeekDB：

sudo rpm -e seekdb

方式三：源码编译安装

对于需要自定义构建或参与 SeekDB 开发的用户，可以从源码编译安装。

#### 前提条件

编译 SeekDB 需要以下工具：

#### 编译步骤

详细的源码编译说明请参考开发者文档：

• 英文版构建指南
• 中文版构建指南

部署模式配置

SeekDB 支持多种部署模式，可根据实际需求选择合适的部署方式。

嵌入式模式

嵌入式模式将 SeekDB 直接嵌入到应用程序进程中，无需独立的数据库服务器进程，适合单机应用或开发测试环境。

import pyseekdb

# 使用嵌入式模式连接本地 SeekDB
client = pyseekdb.Client(
    path="./seekdb.db",  # 数据库文件路径
    database="test"       # 数据库名称
)

# 执行查询
cursor = client.cursor()
cursor.execute("CREATE TABLE test (id INT, data TEXT)")
cursor.execute("INSERT INTO test VALUES (1, 'hello')")
cursor.execute("SELECT * FROM test")
results = cursor.fetchall()
print(results)

client.close()

特点：

• 零外部依赖部署
• 最低资源占用（可低至 1 核 CPU + 1GB 内存）
• 数据存储在本地文件系统
• 适合 AI 应用原型开发

资料来源：package/wheel/README.md

客户端/服务器模式

客户端/服务器模式通过独立的 SeekDB 服务器进程提供服务，支持多客户端并发访问。

import pyseekdb

# 连接到 SeekDB 服务器
client = pyseekdb.Client(
    host="127.0.0.1",     # 服务器地址
    port=2881,            # 服务器端口
    database="test",      # 数据库名称
    user="root",          # 用户名
    password=""           # 密码（默认空）
)

# 执行查询
cursor = client.cursor()
cursor.execute("SELECT * FROM oceanbase.DBA_OB_USERS")
results = cursor.fetchall()
print(results)

client.close()

服务器启动：

SeekDB 服务器的启动方式因安装方式不同而异：

# 如果通过 RPM 安装，可能已注册为系统服务
sudo systemctl start seekdb

# 或手动启动
seekdb --server --port 2881

特点：

• 支持多客户端并发访问
• 数据集中管理
• 适合生产环境部署
• 可通过网络远程访问

OceanBase 集成模式

SeekDB 可以与 OceanBase 数据库深度集成，利用 OceanBase 的分布式能力实现企业级部署。

import pyseekdb

# 连接到 OceanBase 模式的 SeekDB
client = pyseekdb.Client(
    host="127.0.0.1",
    port=2881,
    tenant="test",        # OceanBase 租户名
    user="root",
    password=""
)

# 执行 SQL 操作
cursor = client.cursor()
cursor.execute("SHOW DATABASES")
databases = cursor.fetchall()

client.close()

资料来源：package/wheel/README.md

数据库配置

基本配置参数

SeekDB 提供丰富的配置选项以满足不同场景需求：

SQL 兼容配置

SeekDB 兼容标准 MySQL 协议，支持以下数据类型：

资料来源：src/objit/include/objit/common/ob_item_type.h:1-25

快速入门示例

以下示例展示如何使用 SeekDB 创建一个简单的向量搜索应用：

import pyseekdb
from pyseekdb import DefaultEmbeddingFunction

# 1. 创建客户端连接
client = pyseekdb.Client(
    path="./seekdb.db",
    database="test"
)

# 2. 创建集合（Collection）
collection = client.create_collection(
    name="my_collection",
    embedding_function=DefaultEmbeddingFunction()
)

# 3. 添加数据
documents = [
    "人工智能正在改变世界",
    "Python 是一种流行的编程语言",
    "向量数据库支持语义搜索"
]
ids = ["doc1", "doc2", "doc3"]

collection.add(
    ids=ids,
    documents=documents
)

# 4. 查询数据
results = collection.query(
    query_texts="AI 和机器学习",
    n_results=2
)

print(f"查询结果: {results}")

# 5. 关闭连接
client.close()

常见问题与解决方案

1. 安装失败

问题：pip 安装时报错 ImportError 或 ModuleNotFoundError

解决方案：

# 升级 pip 和 setuptools
pip install --upgrade pip setuptools wheel

# 重新安装
pip uninstall pyseekdb seekdb
pip install seekdb

2. 连接失败

问题：无法连接到 SeekDB 服务器

解决方案：

• 确认服务器进程已启动
• 检查防火墙设置
• 验证端口号配置正确
• 确认数据库名称存在

3. 性能问题

问题：查询响应慢

解决方案：

• 增加系统内存
• 为向量列创建索引
• 使用混合查询优化搜索
• 考虑从嵌入式模式切换到服务器模式

许可证

SeekDB 采用 Apache 2.0 开源许可证，可免费用于商业和非商业项目。

资料来源：package/wheel/lib/setup.py:35

版本信息

当前最新版本为 v1.3.0，该版本引入了基于 Change Stream 增量框架的异步索引，将写入与索引构建解耦，提供极致的摄入吞吐量和稳定的查询性能。

相关文档

• 开发者构建指南（英文）
• 开发者构建指南（中文）
• Python SDK 使用指南
• GitHub 仓库主页

参与贡献

SeekDB 是一个开源项目，欢迎社区贡献者参与开发和改进。如有任何问题或建议，请通过以下方式联系我们：

• 在 GitHub Issues 提交问题
• 参与 社区讨论
• 提交 Pull Request 贡献代码

概述

SeekDB 是由 OceanBase 团队开发的 AI Native 数据库产品，构建于 OceanBase 数据库核心引擎之上，专门针对 AI 应用场景进行了深度优化和功能扩展。SeekDB 在保留 OceanBase 强大 HTAP 能力的同时，添加了全面的向量索引、全文索引、混合搜索和 AI Functions 等关键 AI 功能。

SeekDB 的核心设计目标是降低 AI 应用的开发门槛，支持在仅有 1 核 CPU 和 1GB 内存的极低资源配置下运行，具备秒级启动的快速初始化能力，并同时支持客户端/服务器模式和嵌入式部署模式。资料来源：README.md

核心架构设计

架构层次概览

SeekDB 采用分层架构设计，从底层到顶层依次为：存储引擎层、查询引擎层、SQL 解析层和 SDK 接口层。这种设计确保了各层之间的职责清晰，便于独立演进和优化。

graph TB
    subgraph SDK层["SDK 接口层"]
        A1[Python SDK<br/>pyseekdb]
        A2[SQLAlchemy]
        A3[HTTP API]
    end
    
    subgraph SQL层["SQL 解析与执行层"]
        B1[SQL Parser<br/>MySQL 兼容模式]
        B2[PL/SQL Parser]
        B3[表达式引擎]
        B4[优化器]
    end
    
    subgraph 查询引擎层["查询引擎层"]
        C1[向量查询引擎]
        C2[全文搜索引擎]
        C3[混合查询引擎]
        C4[AI Functions]
    end
    
    subgraph 存储引擎层["存储引擎层"]
        D1[行存储引擎]
        D2[列存储引擎]
        D3[向量索引<br/>HNSW/VSAG]
        D4[全文索引]
        D5[RoaringBitmap]
    end
    
    A1 --> B1
    A2 --> B1
    A3 --> B1
    B1 --> B2
    B1 --> B3
    B2 --> B4
    B3 --> B4
    B4 --> C1
    B4 --> C2
    B4 --> C3
    B4 --> C4
    C1 --> D1
    C2 --> D4
    C3 --> D1
    C3 --> D2
    C3 --> D3
    D1 --> D2
    D3 --> D1

数据类型体系

SeekDB 继承并扩展了 OceanBase 的数据类型体系，支持丰富的 SQL 标准类型和 AI 场景特有的数据类型。资料来源：src/objit/include/objit/common/ob_item_type.h:1-50

graph LR
    A[用户数据] --> B{数据类型}
    B --> C[标量数据]
    B --> D[向量数据]
    B --> E[JSON数据]
    B --> F[空间数据]
    
    C --> C1[INT/VARCHAR<br/>等标准类型]
    D --> D1[VECTOR索引<br/>HNSW/VSAG]
    E --> E1[JSON函数<br/>JSON_SEARCH等]
    F --> F1[GEOMETRY<br/>空间索引]

SQL 兼容性层

MySQL 兼容模式

SeekDB 的 SQL Parser 完全兼容 MySQL 语法，支持标准 SQL 语句和 MySQL 特有的语法扩展。资料来源：src/sql/parser/non_reserved_keywords_mysql_mode.c:1-50

支持的 MySQL 关键字包括：

• 数据定义语言（DDL）：CREATE, ALTER, DROP, TRUNCATE
• 数据操作语言（DML）：SELECT, INSERT, UPDATE, DELETE
• 事务控制：START TRANSACTION, COMMIT, ROLLBACK
• 索引管理：CREATE INDEX, DROP INDEX
• 向量操作：CROSS, COSINE, COUNT 等向量计算相关关键字

PL/SQL 扩展

SeekDB 支持 PL/SQL 过程式扩展，提供更强大的业务逻辑处理能力。资料来源：src/pl/parser/pl_non_reserved_keywords_mysql_mode.c:1-50

查询引擎架构

向量查询引擎

SeekDB 的向量查询引擎是 AI 场景的核心组件，支持大规模向量数据的高效检索。资料来源：README.md

向量索引类型：

向量表创建示例：

CREATE TABLE articles (
    id INT PRIMARY KEY,
    title TEXT,
    content TEXT,
    embedding VECTOR(384),
    FULLTEXT INDEX idx_fts(content) WITH PARSER ik,
    VECTOR INDEX idx_vec (embedding) WITH(DISTANCE=l2, TYPE=hnsw, LIB=vsag)
) ORGANIZATION = HEAP;

全文搜索引擎

SeekDB 提供智能全文搜索能力，支持多语言分词、相关性排序和模糊搜索。资料来源：README.md

全文索引特性：

• 多语言分词器支持（包括中文 IK 分词器）
• relevance ranking 相关性排序
• 模糊搜索支持
• 自然语言模式和布尔模式

混合查询引擎

混合查询引擎将向量搜索与标量搜索统一起来，支持复杂的 AI 应用场景。

graph LR
    A[用户查询] --> B[查询解析]
    B --> C[查询分解]
    C --> D1[向量查询]
    C --> D2[全文查询]
    C --> D3[标量查询]
    D1 --> E[结果合并]
    D2 --> E
    D3 --> E
    E --> F[智能排序]
    F --> G[返回结果]

混合查询示例：

SELECT
    title,
    content,
    l2_distance(embedding, '[query_embedding]') AS vector_distance,
    MATCH(content) AGAINST('your keywords' IN NATURAL LANGUAGE MODE) AS text_score
FROM articles
WHERE MATCH(content) AGAINST('your keywords' IN NATURAL LANGUAGE MODE)
ORDER BY vector_distance APPROXIMATE
LIMIT 10;

AI Functions

SeekDB 内置丰富的 AI 函数，简化 AI 应用开发。资料来源：README.md

JSON 处理架构

JSON Schema 验证

SeekDB 提供完整的 JSON Schema 验证功能，支持对 JSON 文档结构进行严格验证。资料来源：src/share/json_type/ob_json_schema.cpp:1-50

支持的 JSON Schema 关键字：

JSON 表达式下推优化

SeekDB 的表达式引擎支持 JSON 表达式的查询下推优化，减少数据传输量。资料来源：src/sql/engine/expr/ob_expr_json_func_helper.cpp:1-50

graph TB
    A[JSON查询表达式] --> B{下推条件检查}
    B -->|JSON列为列引用| C1[检查路径表达式]
    B -->|非列引用| C2[不支持下推]
    C1 --> D{路径可下推?}
    D -->|是| E[生成下推计划]
    D -->|否| F[返回执行器]
    E --> G[存储层执行]
    F --> H[应用层执行]

下推条件：

• JSON 文档必须是列引用
• 路径表达式必须是常量
• 返回类型必须是常量
• 不支持 ASCII 模式修改

部署架构

嵌入式模式

SeekDB 的嵌入式模式允许将数据库直接嵌入到应用程序中，无需独立部署数据库服务。资料来源：package/wheel/lib/setup.py:1-50

graph LR
    A[应用程序] --> B[Python SDK<br/>pyseekdb]
    B --> C[libseekdb_python<br/>C++ 扩展模块]
    C --> D[(SeekDB<br/>嵌入式数据库)]
    
    style D fill:#90EE90

嵌入式模式特点：

• 单文件数据库，无外部依赖
• 支持 Python 3.8-3.14
• 零配置启动
• 适用于边缘设备和轻量级应用

客户端/服务器模式

SeekDB 支持传统的客户端/服务器部署模式，适合需要多客户端访问的场景。

graph TB
    subgraph 客户端层
        A1[Python 应用]
        A2[Java 应用]
        A3[其他客户端]
    end
    
    subgraph 服务器层
        B[SeekDB Server<br/>端口 2881]
    end
    
    subgraph 存储层
        C[(SeekDB<br/>数据库文件)]
    end
    
    A1 --> B
    A2 --> B
    A3 --> B
    B --> C

OceanBase 云端模式

SeekDB 可以连接到 OceanBase 云端服务，实现边缘到云端的统一数据管理。资料来源：README.md

Python SDK 架构

SDK 包结构

SeekDB Python SDK 采用分层设计，提供了简洁易用的 Python 接口。资料来源：package/wheel/lib/__init__.py:1-30

连接管理

import pyseekdb

# 嵌入式模式
client = pyseekdb.Client(
    path="./seekdb.db",
    database="test"
)

# 服务器模式
client = pyseekdb.Client(
    host="127.0.0.1",
    port=2881,
    database="test",
    user="root",
    password=""
)

嵌入函数支持

SeekDB SDK 支持嵌入函数（Embedding Function），可以自动将文本转换为向量表示。资料来源：README.md

from pyseekdb import DefaultEmbeddingFunction

# 创建默认嵌入函数
embedding_function = DefaultEmbeddingFunction()

# 添加带嵌入的文档
collection.add(
    ids=ids,
    documents=documents,  # 嵌入自动生成
    metadatas=metadatas
)

# 使用文本查询
results = collection.query(
    query_texts="artificial intelligence",  # 自动转换为向量
    n_results=3
)

错误处理体系

SeekDB 继承 OceanBase 的错误码体系，与 MySQL 协议保持兼容。资料来源：src/share/mysql_errno.h:1-50

常见 JSON 错误码：

资源需求与性能特性

最低资源要求

SeekDB 针对边缘和轻量级场景进行了深度优化，具备极低的资源占用。资料来源：README.md

平台支持

生态系统集成

第三方框架集成

SeekDB 与主流 AI 生态系统深度集成，提供开箱即用的支持。资料来源：README.md

graph LR
    A[SeekDB] <--> B[LangChain]
    A <--> C[LangGraph]
    A <--> D[HuggingFace]
    A <--> E[SQLAlchemy]

版本演进

v1.3.0 最新特性

SeekDB V1.3.0 是面向多平台覆盖和高性能的重大版本更新，引入了基于 Change Stream 增量框架的异步索引功能，实现了写入与索引构建的解耦，提供极致的数据摄入吞吐量和稳定的查询性能。资料来源：community_context

相关文档

• 快速开始指南 - SeekDB 入门教程
• Python SDK 文档 - Python API 详细参考
• SQL 参考手册 - SQL 语法和函数说明
• 向量搜索指南 - 向量索引和混合查询
• 部署与运维 - 生产环境部署最佳实践

See Also

• LangChain 集成示例
• OceanBase 官方文档
• seekdb GitHub 仓库
• 社区讨论 #104: C ABI 多语言 SDK - 社区对 Rust/Go/Java SDK 的需求
• 社区讨论 #40: TypeScript/JavaScript SDK - 社区对 JS/TS SDK 的需求

概述

Change Stream 异步索引是 SeekDB V1.3.0 引入的核心特性，旨在构建一种新型的增量数据流框架。该框架的核心设计理念是将数据写入操作与索引构建操作解耦，从而实现极高的数据摄取吞吐量和稳定的查询性能。在传统的数据库系统中，数据写入往往需要同步完成索引更新，这在高并发写入场景下会成为性能瓶颈。Change Stream 异步索引通过引入增量变更数据流机制，使得写入操作可以立即返回成功，而索引构建则在后台异步执行，极大地提升了系统的整体吞吐量。

从架构角度来看，Change Stream 异步索引框架涵盖了从数据变更捕获、增量日志获取、索引构建任务调度到最终索引完成的完整生命周期。该框架不仅服务于向量索引的异步构建，还支持全文索引（Full-Text Search Index）的异步更新机制，形成了一个统一的、多类型的索引异步构建体系。SeekDB 通过这一框架，能够在保持数据一致性的同时，为 AI 应用场景提供高效的数据处理能力。

核心概念与术语定义

在深入了解 Change Stream 异步索引之前，需要明确几个核心概念的定义。这些概念构成了整个异步索引体系的基础，理解它们对于正确使用该功能至关重要。

变更数据捕获（Change Data Capture，CDC） 是一种用于识别和捕获数据库中数据变更的技术。SeekDB 通过 Change Stream 机制记录所有数据变更操作，包括插入、更新和删除操作，并将这些变更以流的形式输出供下游消费者使用。这种设计使得索引构建可以独立于主数据写入流程进行。

异步索引构建 指的是索引的创建和更新操作在后台任务中执行，而非在数据写入的同步路径上完成。这种方式确保了写入延迟的稳定性，因为主写入路径不会被耗时的索引操作阻塞。同时，异步构建允许系统对索引构建任务进行批处理和优化调度，进一步提升效率。

增量日志获取（Log Fetching） 是 Change Stream 框架的关键组件，负责从存储层获取变更日志记录。在 SeekDB 的架构中，日志服务（LogService）模块承担这一职责，其 logfetcher 组件负责高效、可靠地拉取增量日志数据。

架构设计

整体架构图

graph TD
    A[数据写入请求] --> B[主存储引擎]
    B --> C[变更日志生成]
    C --> D[Change Stream 模块]
    D --> E[增量日志队列]
    E --> F[异步索引构建器]
    F --> G[向量索引]
    F --> H[全文索引]
    G --> I[索引查询服务]
    H --> I
    I --> J[查询结果合并]
    J --> K[客户端响应]
    
    L[日志服务 LogFetcher] -.->|增量日志拉取| D

如上图所示，Change Stream 异步索引框架的核心流程包含以下关键阶段：当客户端发起数据写入请求时，主存储引擎在处理数据的同时生成变更日志。这些变更日志通过 Change Stream 模块进行组织和分发，进入增量日志队列。异步索引构建器从队列中消费日志数据，根据数据类型构建相应的索引。无论是向量索引还是全文索引，最终都服务于查询服务，经过结果合并后返回给客户端。

值得注意的是，日志服务中的 LogFetcher 组件持续运行，从集群节点获取增量日志数据，确保异步索引构建器始终能够获取到最新的变更信息。这种设计保证了索引与源数据的一致性，尽管在时间上存在一定的延迟。

模块层次结构

graph TD
    A[SeekDB 核心引擎] --> B[存储层]
    A --> C[计算层]
    A --> D[日志服务层]
    
    B --> B1[行存储]
    B --> B2[列存储]
    B --> B3[索引存储]
    
    C --> C1[SQL 解析器]
    C --> C2[查询优化器]
    C --> C3[执行器]
    
    D --> D1[Change Stream]
    D --> D2[LogFetcher]
    D --> D3[日志复制]
    
    C3 --> C4[异步任务调度器]
    C4 --> E[索引构建任务]
    E --> B3
    
    style D1 fill:#e1f5fe
    style D2 fill:#e1f5fe
    style E fill:#fff3e0

全文索引异步构建

索引构建工具组件

SeekDB 的全文索引（Full-Text Index）异步构建依赖于 ObFtsIndexBuilderUtil 工具类。该组件负责管理全文索引的构建流程，包括解析器加载、字典加载以及索引属性配置等关键环节。

在全文索引构建过程中，系统首先需要验证分词器（Parser）的有效性。不同的语言和文本类型可能需要不同的分词策略，例如中文通常需要支持 ik 分词器，而英文则可能使用标准分词器。ObFtsIndexBuilderUtil::check_need_to_load_dic 函数负责判断是否需要加载词典数据，这取决于分词器的类型和配置。

资料来源：src/share/ob_fts_index_builder_util.cpp:45-60

int ObFtsIndexBuilderUtil::check_need_to_load_dic(
    const uint64_t tenant_id,
    const ObString &parser_name,
    bool &need_to_load_dic)
{
  ObString real_parser_name = parser_name;
  need_to_load_dic = false;
  // 验证租户ID有效性
  if (!is_valid_tenant_id(tenant_id) || parser_name.empty()) {
    ret = OB_INVALID_ARGUMENT;
  }
}

解析器属性配置

全文索引的查询质量很大程度上取决于分词器的配置。ObFTParserJsonProps 类负责管理和解析分词器的属性配置，包括字符集设置、停用词列表、同义词词典等。这些配置通过 JSON 格式的字符串传入，并在索引构建时生效。

graph LR
    A[索引定义] --> B[Parser Properties JSON]
    B --> C[ObFTParserJsonProps 解析]
    C --> D{字符集验证}
    D -->|UTF8MB4| E[词典加载]
    D -->|其他| F[错误处理]
    E --> G[索引构建配置]

资料来源：src/share/ob_fts_index_builder_util.cpp:20-44

JSON 搜索与异步处理

JSON 表达式求值流程

SeekDB 支持丰富的 JSON 数据操作能力，这些能力通过 ObExprJsonSearch 等表达式类实现。JSON 搜索功能在异步索引框架中扮演重要角色，因为 JSON 类型的字段常常需要建立全文索引或向量索引以支持复杂的查询场景。

ObExprJsonSearch::eval_json_search 函数是 JSON 搜索表达式的核心求值方法。该方法首先验证输入参数的类型有效性，然后调用 JSON 表达式帮助类 ObJsonExprHelper 进行类型检查。对于 JSON 类型的参数，系统要求使用 UTF8MB4 字符集编码，确保文本处理的正确性。

资料来源：src/sql/engine/expr/ob_expr_json_search.cpp:30-60

int ObExprJsonSearch::eval_json_search(const ObExpr &expr, ObEvalCtx &ctx, ObDatum &res)
{
  // JSON 文档验证
  if (OB_FAIL(ObJsonExprHelper::is_valid_for_json(types_stack, 0, "json_search"))) {
    LOG_WARN("wrong type for json doc.", K(ret));
  }
  // 参数类型处理
  for (int64_t i = 1; i < param_num; i++) {
    if (ob_is_string_type(types_stack[i].get_type())) {
      types_stack[i].set_calc_collation_type(CS_TYPE_UTF8MB4_BIN);
    }
  }
}

JSON 函数下推优化

ObExprJsonFuncHelper 模块负责判断 JSON 函数是否可以在存储层下推执行。并非所有 JSON 操作都需要在计算层完成，当 JSON 列引用、路径表达式和返回类型满足特定条件时，系统可以将 JSON 函数下推到存储层执行，从而减少数据传输量，提升查询性能。

资料来源：src/sql/engine/expr/ob_expr_json_func_helper.cpp:25-50

下推条件包括：文档表达式必须是 JSON 类型的列引用，路径表达式必须属于支持下推的类型，常量表达式用于返回类型、截断标志和 ASCII 标志的判断。任何不满足这些条件的表达式都将保留在计算层执行。

数据类型支持

SQL 类型系统

SeekDB 继承并扩展了 OceanBase 的类型系统，定义了完整的 SQL 数据类型枚举。在异步索引场景中，某些数据类型可能需要特殊的索引处理方式，例如向量类型 T_VECTOR 用于存储高维向量数据，而 JSON 类型 T_JSON 则需要支持全文索引。

资料来源：src/objit/include/objit/common/ob_item_type.h:1-50

类型转换与索引

在异步索引构建过程中，数据类型转换是一个重要考量。不同类型的数据可能需要转换为兼容的中间类型以支持索引构建。ObObjType 相关的类型转换表定义了各种数据类型之间的转换规则和兼容性。

某些类型之间可以直接转换而无需特殊处理（如 INT 到 BIGINT），而某些类型则不支持相互转换（如 VARCHAR 到 JSON）。这种严格的类型检查确保了索引构建的正确性，避免了因类型不兼容导致的索引损坏。

资料来源：deps/oblib/src/common/object/ob_obj_type.h:80-120

AI 函数与重排序

AI 重排序机制

SeekDB 在 V1.3.0 中引入了更完善的 AI 函数支持，其中 AI 重排序（AI Rerank）功能是异步索引框架的重要组成部分。重排序通常发生在初始检索之后，用于对候选结果进行更精确的二次排序。

ObExprAiRerank 类负责实现重排序表达式的求值。该类接受查询文本、文档列表和可选的文档键参数。文档参数支持 JSON 格式，允许传入复杂的文档结构。系统会对每个文档进行相关性评分，并返回按分数降序排列的结果。

资料来源：src/sql/engine/expr/ob_expr_ai/ob_expr_ai_rerank.cpp:40-80

int ObExprAiRerank::cg_static(
    ObExprCGCtx &op_cg_ctx,
    const ObRawExpr &raw_expr,
    ObExpr &rt_expr) const
{
  // 验证文档参数类型
  if (OB_FAIL(ObJsonExprHelper::is_valid_for_json(types_stack, DOCUMENTS_IDX, N_AI_RERANK))) {
    LOG_WARN("wrong type for json config.");
  }
  // 字符集处理
  if (types_stack[DOCUMENTS_IDX].get_charset_type() != CHARSET_UTF8MB4) {
    types_stack[DOCUMENTS_IDX].set_calc_collation_type(CS_TYPE_UTF8MB4_BIN);
  }
}

重排序参数说明

错误处理机制

错误码定义

SeekDB 定义了完整的错误码体系，用于标识异步索引构建过程中可能出现的各种异常情况。错误码遵循 MySQL 兼容性规范，同时扩展了数据库特有的错误类型。

资料来源：src/share/mysql_errno.h:1-30

常见错误场景

JSON 路径下推失败：当 JSON 表达式的路径不符合下推条件时，系统会记录警告日志并回退到计算层执行。这种降级处理确保了查询的正确性，但可能影响查询性能。

分词器加载失败：如果指定的分词器不存在或不支持当前字符集，全文索引构建将失败。错误消息会明确指出不兼容的字符集类型和分词器名称。

向量索引构建超时：在处理大规模向量数据时，如果索引构建任务超过预设的超时时间，系统会返回超时错误。这通常需要通过调整批处理大小或增加构建资源来解决。

配置与调优

索引构建参数

异步索引的构建行为可以通过多个配置参数进行调整，以适应不同的工作负载和性能需求。

性能优化建议

批量大小调整：较大的批量大小可以提高索引构建的吞吐率，但会增加内存占用和延迟。对于内存受限的环境，建议使用较小的批量值；对于追求高吞吐的场景，可以适当增加批量大小。

线程池配置：索引构建线程数应根据 CPU 核心数和查询负载进行调整。过少的线程可能无法充分利用系统资源，而过多的线程可能导致上下文切换开销。

增量日志保留：合理配置增量日志的保留时间，确保异步索引构建器有足够的时间消费积压的日志，同时避免长时间占用存储空间。

使用示例

创建带向量索引的表

以下示例展示如何在 SeekDB 中创建支持异步索引的表：

CREATE TABLE articles (
    id INT PRIMARY KEY,
    title TEXT,
    content TEXT,
    embedding VECTOR(384),
    FULLTEXT INDEX idx_fts(content) WITH PARSER ik,
    VECTOR INDEX idx_vec (embedding) WITH(
        DISTANCE=l2, 
        TYPE=hnsw, 
        LIB=vsag
    )
) ORGANIZATION = HEAP;

在这个示例中，content 列上创建了全文索引，支持中文分词；embedding 列上创建了向量索引，使用 L2 距离度量和 HNSW 算法。这两种索引都受益于异步构建机制，可以独立于数据写入进行更新。

混合搜索查询

SELECT
    title,
    content,
    l2_distance(embedding, '[query_embedding]') AS vector_distance,
    MATCH(content) AGAINST('关键词' IN NATURAL LANGUAGE MODE) AS text_score
FROM articles
WHERE MATCH(content) AGAINST('关键词' IN NATURAL LANGUAGE MODE)
ORDER BY vector_distance APPROXIMATE
LIMIT 10;

此查询结合了全文搜索和向量搜索，首先通过全文索引快速过滤候选文档，然后使用向量距离进行精确排序。异步索引确保了在大数据量场景下查询性能的稳定性。

相关文档

概述

SeekDB 是 OceanBase 团队开发的 AI Native 数据库产品，基于 OceanBase 数据库核心引擎构建，专为 AI 应用场景设计。向量搜索与混合检索是 SeekDB 的核心能力之一，它将传统的关系型数据管理、向量相似度搜索、全文检索和 AI 函数深度融合，为开发者提供统一的、多模态的数据查询能力。

向量搜索使得系统能够通过计算向量之间的距离（欧氏距离、余弦相似度等）来找到语义上相似的数据，而混合检索则允许同时结合向量搜索、全文搜索和标量过滤，实现更精确、更灵活的查询结果。资料来源：README.md:1-15

核心数据类型

SeekDB 支持多种数据类型来满足向量搜索和混合检索的需求。向量列用于存储高维 embedding 数据，文本列用于全文检索，JSON 列用于处理半结构化数据。

资料来源：src/objit/include/objit/common/ob_item_type.h:22-37

向量索引架构

SeekDB 的向量索引基于 HNSW（Hierarchical Navigable Small World）算法实现，这是一种高效的近似最近邻搜索算法，能够在大规模向量数据中快速找到相似结果。

graph TD
    A[查询向量] --> B[向量索引层]
    B --> C{距离计算}
    C --> D[L2 距离]
    C --> E[余弦相似度]
    C --> F[内积]
    D --> G[结果排序]
    E --> G
    F --> G
    G --> H[Top-K 结果返回]
    
    I[向量数据写入] --> J[索引构建]
    J --> K[HNSW 图结构]
    K --> B

索引创建语法

创建带有向量索引的表需要指定向量维度、距离度量方式和索引参数：

CREATE TABLE articles (
    id INT PRIMARY KEY,
    title TEXT,
    content TEXT,
    embedding VECTOR(384),
    FULLTEXT INDEX idx_fts(content) WITH PARSER ik,
    VECTOR INDEX idx_vec (embedding) WITH(DISTANCE=l2, TYPE=hnsw, LIB=vsag)
) ORGANIZATION = HEAP;

关键参数说明：

资料来源：README.md:89-103

全文索引与搜索

SeekDB 支持全文索引功能，允许对文本列建立全文搜索能力。通过内置的分词器（如 ik 分词器），系统能够对中文等语言进行智能分词。

全文搜索表达式

JSON 搜索表达式用于处理 JSON 文档中的文本搜索需求，支持路径表达式和通配符匹配：

// JSON搜索表达式参数检查
if (OB_FAIL(ObJsonExprHelper::is_valid_for_json(types_stack, 0, "json_search"))) {
    LOG_WARN("wrong type for json doc.", K(ret), K(types_stack[0].get_type()));
}

// 路径字符串参数处理
for (int64_t i = 1; OB_SUCC(ret) && i < param_num; i++) {
    if (types_stack[i].get_type() == ObNullType) {
    } else if (ob_is_string_type(types_stack[i].get_type())) {
        types_stack[i].set_calc_collation_type(CS_TYPE_UTF8MB4_BIN);
    }
}

资料来源：src/sql/engine/expr/ob_expr_json_search.cpp:1-25

混合搜索实现

混合搜索是 SeekDB 的核心优势之一，它能够同时利用向量搜索、全文搜索和标量条件过滤，通过智能排序返回最优结果。

graph LR
    A[查询请求] --> B[查询解析器]
    B --> C[向量查询分支]
    B --> D[全文查询分支]
    B --> E[标量过滤分支]
    
    C --> F[向量索引检索]
    D --> G[全文索引检索]
    E --> H[行级过滤]
    
    F --> I[结果集合并]
    G --> I
    H --> I
    
    I --> J[重排序模块]
    J --> K[混合评分]
    K --> L[Top-N 结果]

混合搜索查询示例

-- 混合搜索查询示例
SELECT
    title,
    content,
    l2_distance(embedding, '[query_embedding]') AS vector_distance,
    MATCH(content) AGAINST('your keywords' IN NATURAL LANGUAGE MODE) AS text_score
FROM articles
WHERE MATCH(content) AGAINST('your keywords' IN NATURAL LANGUAGE MODE)
ORDER BY vector_distance APPROXIMATE
LIMIT 10;

此查询同时执行向量相似度搜索和全文关键词搜索，最终返回两种得分综合最优的结果。

资料来源：README.md:100-115

AI 函数支持

SeekDB 内置了多种 AI 函数，支持 embedding 生成、重排序和推理等操作，无需外部 AI 服务即可完成端到端的智能搜索流程。

AI 函数列表

资料来源：deps/oblib/src/lib/ob_name_def.h:68-73

重排序函数实现

重排序函数允许对初步检索结果进行深度语义排序，提升搜索结果的相关性：

// AI重排序函数参数处理
ObObjType doc_key_type = types_stack[DOC_KEY_IDX].get_type();
if (doc_key_type == ObNullType) {
} else if (doc_key_type == ObJsonType) {
} else if (ob_is_string_type(doc_key_type)) {
    types_stack[DOC_KEY_IDX].set_calc_collation_type(CS_TYPE_UTF8MB4_BIN);
} else {
    ret = OB_INVALID_ARGUMENT;
    LOG_WARN("invalid param type", K(ret), K(types_stack[DOC_KEY_IDX]));
}

资料来源：src/sql/engine/expr/ob_expr_ai/ob_expr_ai_rerank.cpp:1-30

Python SDK 使用指南

SeekDB 提供 Python SDK (pyseekdb)，支持便捷的向量数据管理和查询操作。

安装与连接

pip install -U pyseekdb

import pyseekdb
from pyseekdb import DefaultEmbeddingFunction

# 嵌入式模式（本地 SeekDB）
client = pyseekdb.Client(
    path="./seekdb.db",
    database="test"
)

# 服务模式（连接远程 SeekDB 服务器）
# client = pyseekdb.Client(
#     host="127.0.0.1",
#     port=2881,
#     database="test",
#     user="root",
#     password=""
# )

资料来源：README.md:130-150

向量数据操作

from pyseekdb import DefaultEmbeddingFunction

# 创建带 embedding 函数的集合
embedding_fn = DefaultEmbeddingFunction()
collection = client.create_collection(
    name="articles",
    dimension=384,
    embedding_function=embedding_fn
)

# 添加文档（自动生成向量）
documents = [
    "AI is transforming technology",
    "Vector databases enable semantic search",
    "Machine learning models require good data"
]

collection.add(
    ids=["id1", "id2", "id3"],
    documents=documents,
    metadatas=[
        {"category": "AI", "index": 0},
        {"category": "Database", "index": 1},
        {"category": "ML", "index": 2}
    ]
)

# 文本查询（自动生成查询向量）
query_text = "artificial intelligence and machine learning"
results = collection.query(
    query_texts=query_text,
    n_results=3
)

资料来源：README.md:153-190

部署模式

SeekDB 支持多种部署模式以适应不同的应用场景：

SeekDB 最小可在 1 核 CPU 和 1GB 内存环境下运行，单节点部署无需外部依赖。

资料来源：package/wheel/README.md:8-15

配置与调优

索引参数配置

创建向量索引时可以指定详细的参数来平衡搜索精度和性能：

VECTOR INDEX idx_vec (embedding) WITH(
    DISTANCE=l2,           -- 距离度量
    TYPE=hnsw,             -- 索引类型
    LIB=vsag,              -- 底层库
    M=16,                  -- HNSW M参数：每层连接数
    EF_CONSTRUCTION=200,   -- 构建时的探索范围
    EF_SEARCH=100          -- 查询时的探索范围
)

性能调优建议

• 批量写入：优先使用批量插入操作，减少索引更新开销
• 预热查询：首次查询前执行预热，避免冷启动延迟
• 索引选择：根据实际查询模式选择合适的索引类型
• 内存配置：确保有足够内存容纳热点数据

常见问题与解决方案

向量维度不匹配

问题：插入向量时维度与表定义不符。

解决方案：

-- 检查表定义
DESCRIBE articles;

-- 确保插入的向量维度与表定义一致
INSERT INTO articles (id, embedding) VALUES (1, '[0.1, 0.2, ..., 0.384]');

全文索引未生效

问题：MATCH 查询无结果返回。

解决方案：

1. 确认全文索引已正确创建
2. 检查分词器是否支持目标语言
3. 验证数据已正确写入

-- 检查全文索引状态
SHOW INDEX FROM articles;

-- 测试分词效果
SELECT MATCH(content) AGAINST('关键词' IN NATURAL LANGUAGE MODE) AS score
FROM articles;

混合搜索结果不理想

问题：混合搜索返回的结果相关性不高。

解决方案：

1. 调整向量搜索和全文搜索的权重比例
2. 使用 ai_rerank 函数对结果进行深度排序
3. 优化 embedding 模型的选型

相关错误码

SeekDB 使用 MySQL 兼容的错误码体系，以下是常见的与搜索相关的错误码：

资料来源：src/share/mysql_errno.h:1-15

版本更新 (v1.3.0)

SeekDB v1.3.0 引入了基于 Change Stream 增量框架的异步索引机制，将写入与索引构建解耦，实现了极致的摄入吞吐量和稳定的查询性能。这一改进显著提升了向量搜索在高并发写入场景下的表现。

参见

• 安装与快速开始
• Python SDK 文档
• SQL 参考手册
• AI 函数详解
• 性能优化指南

概述

FORK/MERGE 沙箱机制是 SeekDB 为支持 AI 工作流中的多版本数据管理而设计的核心功能。该机制允许用户在表级别创建数据的轻量级分支（Fork），使得 AI 开发者和数据科学家能够在隔离的沙箱环境中进行实验、调试和多变体开发，而不会影响主数据源的稳定性。

随着大语言模型（LLM）的快速发展，AI 工作流对数据管理提出了更高的灵活性要求。开发者经常需要：

• 对同一数据集进行多个变体的开发和测试
• 在隔离环境中验证模型效果而不污染原始数据
• 支持自主智能体（Autonomous Agents）的多分支推理和回溯

FORK/MERGE 机制正是为解决这些痛点而设计。

核心概念

Fork（分支）

Fork 操作创建一个表的数据副本，该副本与原始表共享未修改的数据块，仅记录变更增量，从而实现存储空间的高效利用。Fork 创建的沙箱表具备完全独立的数据操作能力。

Merge（合并）

Merge 操作将沙箱表中在分支期间产生的数据变更合并回原始主表。SeekDB 支持多种合并策略，包括：

• 全量合并：将所有变更应用到主表
• 选择性合并：仅合并指定的变更记录

架构设计

数据组织结构

graph TB
    subgraph 主表数据层
        A[主表 Main Table]
        B[共享数据块 Shared Blocks]
        C[变更日志 Change Log]
    end
    
    subgraph 沙箱环境
        D[沙箱 A Sandbox A]
        E[沙箱 B Sandbox B]
        F[分支元数据 Branch Metadata]
    end
    
    A --> B
    A --> C
    B --> D
    B --> E
    D --> F
    E --> F
    C --> F
    
    style A fill:#e1f5fe
    style D fill:#c8e6c9
    style E fill:#fff3e0

存储优化策略

SeekDB 采用写时复制（Copy-on-Write, COW）机制来实现存储空间的高效利用：

资料来源：src/storage

使用场景

1. 多变体 AI 模型训练

graph LR
    A[原始数据集] --> B[沙箱 A - 变体 1]
    A --> C[沙箱 B - 变体 2]
    A --> D[沙箱 C - 变体 3]
    B --> E[训练模型 A]
    C --> F[训练模型 B]
    D --> G[训练模型 C]
    E --> H[模型评估]
    F --> H
    G --> H
    H --> I[合并最佳变体]

2. 自主智能体实验

自主智能体（Autonomous Agents）在执行任务时需要探索多种可能的行动路径。FORK 机制允许：

• 为每个推理分支创建独立的数据视图
• 在分支中安全地执行写入操作
• 根据执行结果选择性地合并或丢弃变更

3. 数据版本回溯

开发者可以：

1. Fork 当前生产数据到新沙箱
2. 在沙箱中验证数据修复方案
3. 确认无误后将修复合并回主表

SQL 操作接口

创建分支（Fork）

-- 基于现有表创建分支
FORK TABLE original_table TO sandbox_table;

-- 带条件的分支创建
FORK TABLE original_table TO sandbox_table 
WHERE condition = 'value';

合并变更（Merge）

-- 全量合并沙箱变更到主表
MERGE TABLE sandbox_table INTO original_table;

-- 选择性合并（仅合并指定条件的数据）
MERGE TABLE sandbox_table INTO original_table
WHERE modified_at > '2024-01-01';

查看分支状态

-- 查看表的所有分支信息
SELECT * FROM information_schema.table_branches;

-- 查看未合并的变更
SELECT * FROM information_schema.pending_changes 
WHERE table_name = 'sandbox_table';

配置参数

资料来源：src/observer/table

测试用例

SeekDB 提供了完整的测试套件用于验证 FORK/MERGE 功能的正确性：

# 运行 FORK 相关测试
./mysql_test test_suite/fork_table

# 运行 MERGE 相关测试
./mysql_test test_suite/merge_table

资料来源：tools/deploy/mysql_test/test_suite/fork_table

限制与注意事项

当前限制

1. 跨数据库 Fork：暂不支持跨数据库的表 Fork 操作
2. 约束传播：Fork 创建的沙箱表初始不继承主表的触发器和存储过程
3. 并发写入：同一主表的多个沙箱间不支持并发合并操作

使用建议

• 定期清理不再需要的沙箱表以释放存储空间
• 在合并前建议进行数据校验以确保一致性
• 复杂的数据变更建议先在小规模数据上验证

相关社区讨论

根据社区反馈（Issue #50），当前实现的轻量级表级 Fork 特性主要针对以下场景优化：

• 多变体开发：支持同一数据集的多个实验变体
• 沙箱隔离：为 AI 代理提供安全的数据操作环境
• 版本控制：实现数据层面的版本管理能力

更多设计细节和使用案例可在 Issue #50 中查看。

See Also

• RAG 与知识检索 - 结合 FORK 机制实现知识库版本管理
• Python SDK 使用指南 - 使用 Python API 进行 Fork/Merge 操作
• SQL 语法参考 - 完整的 SQL 语句参考文档

概述

seekdb 的嵌入式模式（Embedded Mode）是一种轻量级部署方式，允许用户将 seekdb 数据库引擎直接嵌入到应用程序进程中运行，无需独立的数据库服务器进程。这种模式特别适合资源受限的环境（如边缘设备、移动终端）以及需要简化部署流程的 AI 应用场景。

嵌入式模式的核心特点是：

• 最小资源占用：最低可在 1 核 CPU、1GB 内存的环境下运行
• 极速启动：数秒内完成初始化，无需复杂配置
• 零外部依赖：单节点架构，部署时不依赖外部服务
• 无缝切换：支持与客户端/服务器模式进行无缝切换
• 多语言支持：当前主要通过 Python SDK 提供嵌入式访问能力

资料来源：README.md

架构设计

整体架构

seekdb 嵌入式模式采用进程内嵌入架构，数据库引擎作为动态链接库被加载到应用程序地址空间中运行。

graph TD
    A[应用程序] --> B[seekdb 嵌入式引擎]
    B --> C[存储引擎]
    B --> D[向量索引引擎]
    B --> E[全文索引引擎]
    B --> F[SQL 引擎]
    C --> G[本地文件存储]
    D --> G
    E --> G
    F --> G
    
    H[Python SDK] --> B
    I[Java SDK] --> B
    J[C API] --> B

嵌入式组件结构

嵌入式模式的核心组件位于 src/observer/embed/ 目录下：

资料来源：src/observer/embed

Python SDK 使用指南

安装

通过 pip 安装 pyseekdb 包：

pip install -U pyseekdb

资料来源：package/wheel/README.md

基本使用流程

#### 1. 创建客户端连接

嵌入式模式下，直接指定本地数据库文件路径：

import pyseekdb

# 嵌入式模式 - 使用本地 SeekDB 数据库文件
client = pyseekdb.Client(
    path="./seekdb.db",
    database="test"
)

#### 2. 数据库操作

# 连接数据库
conn = seekdb.connect()

# 创建游标执行 SQL
cursor = conn.cursor()
cursor.execute("CREATE TABLE articles (id INT PRIMARY KEY, title TEXT, embedding VECTOR(384))")

# 插入数据
cursor.execute("INSERT INTO articles VALUES (1, 'AI Article', '[0.1, 0.2, ...]')")

# 查询数据
cursor.execute("SELECT * FROM articles")
results = cursor.fetchall()

# 关闭连接
conn.close()

资料来源：package/wheel/README.md

向量搜索示例

嵌入式模式下完整使用向量搜索功能：

import pyseekdb
from pyseekdb import DefaultEmbeddingFunction

# 创建客户端
client = pyseekdb.Client(
    path="./seekdb.db",
    database="test"
)

# 使用默认嵌入函数
embedding_fn = DefaultEmbeddingFunction()

# 创建带嵌入函数的集合
collection = client.create_collection(
    name="my_collection",
    dimension=384,
    embedding_function=embedding_fn
)

# 添加文档 - 嵌入向量自动生成
documents = [
    "Artificial intelligence is transforming the world",
    "Python is a popular programming language",
    "Vector databases enable semantic search"
]

collection.add(
    ids=["id1", "id2", "id3"],
    documents=documents
)

# 使用文本查询 - 自动转换为嵌入向量
query_text = "machine learning and AI"
results = collection.query(
    query_texts=query_text,
    n_results=3
)

print(f"查询结果: {results}")

C API 接口

头文件定义

seekdb 提供稳定的 C API 接口用于嵌入式集成：

// 核心接口声明
int seekdb_open(const char* path);
int seekdb_close(void);
int seekdb_execute(const char* sql, char** result);
void seekdb_free_result(char** result);

资料来源：src/observer/embed/c/seekdb.h

接口参数说明

配置选项

嵌入式模式配置参数

环境变量配置

应用场景

边缘计算与物联网

嵌入式模式专为资源受限的边缘设备设计：

• 车载系统：在车载娱乐系统中嵌入向量数据库，支持本地语义搜索
• 工业终端：在工业控制器中实现本地 AI 推理和数据存储
• 智能家居：在网关设备中处理本地智能家居数据

seekdb 的轻量架构支持在极低资源环境下运行，单节点架构无需外部依赖。

资料来源：README.md

AI 应用与 RAG 系统

构建嵌入式 RAG（检索增强生成）应用：

# 完整的本地 RAG 流程
import pyseekdb

# 1. 启动嵌入式数据库
client = pyseekdb.Client(path="./rag_data.db", database="knowledge")

# 2. 创建知识库集合
collection = client.create_collection(
    name="documents",
    dimension=768,
    embedding_function=DefaultEmbeddingFunction()
)

# 3. 索引文档
documents = ["技术文档内容...", "用户手册...", "FAQ..."]
collection.add(ids=["doc1", "doc2", "doc3"], documents=documents)

# 4. 本地语义检索
query = "如何配置系统参数？"
results = collection.query(query_texts=query, n_results=3)

# 5. 送入 LLM 生成答案
# ...

移动端应用

seekdb 支持 Android 平台通过 JNI 集成：

// Android JNI 接口示例
#include "seekdb_jni.h"

JNIEXPORT jint JNICALL
Java_com_seekdb_EmbeddedDB_nativeOpen(JNIEnv *env, jobject obj, jstring path) {
    const char* db_path = env->GetStringUTFChars(path, 0);
    int ret = seekdb_open(db_path);
    env->ReleaseStringUTFChars(path, db_path);
    return ret;
}

资料来源：src/observer/embed/android/seekdb_jni.cpp

部署模式对比

常见问题与故障排除

1. 数据库文件锁定

问题：多个进程同时访问同一数据库文件导致锁定。

解决方案：

• 嵌入式模式仅支持单进程访问
• 多进程场景请切换至服务器模式
• 使用文件锁机制避免并发写入

2. 内存不足

问题：在资源受限环境中出现 OOM（内存不足）错误。

解决方案：

• 减小 cache_size 配置参数
• 限制单次查询返回的记录数
• 使用分页查询处理大数据集

3. 嵌入向量维度不匹配

问题：添加向量时维度与集合定义不一致。

解决方案：

# 创建集合时指定正确维度
collection = client.create_collection(
    name="my_collection",
    dimension=768,  # 必须与嵌入模型输出维度一致
    embedding_function=embedding_fn
)

社区相关讨论

seekdb 社区正在积极扩展嵌入式模式的多语言支持：

• #104：[Feature]: Stable C ABI for embedded seekdb (multi‑language SDKs) - 社区正在讨论为嵌入式模式提供稳定的 C ABI，以便支持 Rust、Go、Java 等语言的 SDK 开发
• #76：[Feature]: support rust sdk - 社区呼吁支持 Rust 语言的嵌入式 SDK
• #40：[Feature]: Support TypeScript/JavaScript SDK - 社区请求为 AI 应用开发场景提供 TypeScript/JavaScript 支持

这些 Issue 反映了开发者对嵌入式模式跨语言集成的强烈需求，未来版本可能提供更多语言的原生 SDK 支持。

性能优化建议

资源调优

# 推荐的生产环境配置
client = pyseekdb.Client(
    path="./seekdb.db",
    database="production",
    cache_size="512MB",      # 根据可用内存调整
    max_connections=32,       # 根据并发需求调整
    worker_threads=2          # 根据 CPU 核心数调整
)

索引优化

对于向量搜索场景，创建合适的索引可显著提升性能：

CREATE TABLE vectors (
    id INT PRIMARY KEY,
    data TEXT,
    embedding VECTOR(384),
    VECTOR INDEX idx_vec (embedding) WITH(DISTANCE=l2, TYPE=hnsw, LIB=vsag)
);

版本说明

当前最新版本 V1.3.0 带来了以下嵌入式模式相关改进：

• 异步索引支持，通过 Change Stream 增量框架解耦写入与索引构建
• 提供极致的写入吞吐量和稳定的查询性能
• 多平台覆盖增强（Linux x86_64, Linux aarch64）

资料来源：README.md

相关文档

• 安装指南 - 完整的 seekdb 安装步骤
• Python SDK 文档 - Python 开发接口详细说明
• SQL 参考手册 - 支持的 SQL 语法和数据类型
• 向量搜索 - 向量索引和相似度搜索功能
• 全文搜索 - 全文索引和文本检索功能

技术支持

如在使用嵌入式模式过程中遇到问题，欢迎通过以下方式获取帮助：

• GitHub Issues：oceanbase/seekdb
• GitHub Discussions：社区讨论区
• 官方文档：seekdb 文档站

概述

SeekDB SDK 为开发者提供了便捷的编程接口，用于访问和管理 SeekDB 数据库实例。SeekDB 目前主要提供 Python SDK（又称 pyseekdb），支持客户端/服务器模式和嵌入式模式两种部署方式。

Python SDK 通过简洁的 API 封装了底层的数据库连接、SQL 执行、向量操作等核心功能，开发者无需关心复杂的数据库协议细节，即可快速构建 AI 应用。

社区关注：当前社区正在讨论对 TypeScript/JavaScript SDK、Rust SDK 以及 C ABI 的支持需求，详见 Issue #40、#76 和 #104。

安装与配置

系统要求

资料来源：package/wheel/lib/setup.py:31-47

安装方式

SeekDB SDK 可通过 pip 快速安装：

pip install seekdb

资料来源：package/wheel/README.md:26

依赖项

Python SDK 的 wheel 包中包含了编译好的 native library 文件：

资料来源：package/wheel/lib/setup.py:54-58

SDK 架构

部署模式

SeekDB Python SDK 支持两种部署模式，开发者可根据应用场景灵活选择：

graph TD
    A[SeekDB Python SDK] --> B[嵌入式模式]
    A --> C[服务器模式]
    
    B --> B1[直接连接本地数据库文件]
    B1 --> B2[无需独立服务进程]
    B2 --> B3[适合边缘设备/嵌入式场景]
    
    C --> C1[连接远程 SeekDB Server]
    C1 --> C2[支持 OceanBase Server]
    C2 --> C3[适合分布式/云端场景]
    
    style B fill:#e1f5fe
    style C fill:#fff3e0

资料来源：README.md 及 package/wheel/README.md

核心组件

资料来源：package/wheel/README.md:32-50

快速入门

基础连接示例

以下示例展示了如何使用 Python SDK 连接数据库并执行查询：

import seekdb

# 打开数据库
seekdb.open()

# 创建连接
conn = seekdb.connect()

# 使用游标执行查询
cursor = conn.cursor()
cursor.execute("SELECT * FROM oceanbase.DBA_OB_USERS")
results = cursor.fetchall()

# 打印结果
for row in results:
    print(row)

# 关闭连接
conn.close()

资料来源：package/wheel/README.md:28-50

嵌入式模式连接

适用于本地文件系统中的 SeekDB 数据库实例：

import seekdb

# 指定本地数据库文件路径
conn = seekdb.connect(path="./seekdb.db", database="test")
cursor = conn.cursor()
cursor.execute("CREATE TABLE test (id INT PRIMARY KEY, data TEXT)")
conn.close()

服务器模式连接

适用于连接远程 SeekDB Server 或 OceanBase Server：

import seekdb

# 连接远程 SeekDB Server
conn = seekdb.connect(
    host="127.0.0.1",
    port=2881,
    database="test",
    user="root",
    password=""
)

# 连接 OceanBase Server
conn = seekdb.connect(
    host="127.0.0.1",
    port=2881,
    tenant="test",
    user="root",
    password=""
)

cursor = conn.cursor()
cursor.execute("SELECT * FROM users")
results = cursor.fetchall()
conn.close()

资料来源：images/demo.py

高级功能

向量搜索支持

SeekDB 支持向量索引和混合搜索功能，SDK 允许开发者通过 SQL 语句创建和管理向量列：

-- 创建带有向量列的表
CREATE TABLE articles (
    id INT PRIMARY KEY,
    title TEXT,
    content TEXT,
    embedding VECTOR(384),
    FULLTEXT INDEX idx_fts(content) WITH PARSER ik,
    VECTOR INDEX idx_vec (embedding) WITH(DISTANCE=l2, TYPE=hnsw, LIB=vsag)
) ORGANIZATION = HEAP;

资料来源：README.md

混合搜索查询

结合向量搜索和全文搜索的混合查询示例：

SELECT
    title,
    content,
    l2_distance(embedding, '[query_embedding]') AS vector_distance,
    MATCH(content) AGAINST('keywords' IN NATURAL LANGUAGE MODE) AS text_score
FROM articles
WHERE MATCH(content) AGAINST('keywords' IN NATURAL LANGUAGE MODE)
ORDER BY vector_distance APPROXIMATE
LIMIT 10;

资料来源：README.md

使用 SQLAlchemy（推荐）

对于 Python 开发者，推荐使用 SQLAlchemy 访问数据：

from sqlalchemy import create_engine, text

# 创建引擎
engine = create_engine("seekdb://./seekdb.db")

# 执行查询
with engine.connect() as conn:
    result = conn.execute(text("SELECT * FROM users WHERE id > :id"), {"id": 10})
    for row in result:
        print(row)

资料来源：README.md

API 参考

核心函数

资料来源：package/wheel/README.md 及 images/demo.py

连接参数

资料来源：images/demo.py

测试与验证

SeekDB SDK 提供了完整的测试用例，位于 seekdb_test.py 文件中。开发者可以参考该文件编写自己的测试用例：

import pytest
import seekdb

def test_basic_connection():
    """测试基本连接功能"""
    seekdb.open()
    conn = seekdb.connect(database="test")
    cursor = conn.cursor()
    cursor.execute("SELECT 1")
    result = cursor.fetchone()
    assert result == (1,)
    conn.close()

def test_create_table():
    """测试创建表"""
    conn = seekdb.connect(database="test")
    cursor = conn.cursor()
    cursor.execute("DROP TABLE IF EXISTS test_table")
    cursor.execute("CREATE TABLE test_table (id INT PRIMARY KEY, name TEXT)")
    cursor.execute("INSERT INTO test_table VALUES (1, 'test')")
    cursor.execute("SELECT * FROM test_table")
    result = cursor.fetchone()
    assert result == (1, 'test')
    conn.close()

资料来源：package/wheel/seekdb_test.py

常见问题

1. 嵌入式模式与服务器模式如何选择？

2. Python 版本兼容性问题

SeekDB Python SDK 支持 Python 3.8 至 3.14 所有版本。如遇到兼容性问题，请确保使用最新版本的 SDK：

pip install --upgrade seekdb

资料来源：package/wheel/lib/setup.py:36-40

3. 如何获取详细错误信息？

import seekdb

try:
    conn = seekdb.connect(database="nonexistent")
    cursor = conn.cursor()
    cursor.execute("INVALID SQL")
except Exception as e:
    print(f"错误类型: {type(e).__name__}")
    print(f"错误信息: {e}")

SDK 开发路线图

根据社区反馈，以下 SDK 功能正在规划或开发中：

资料来源：社区 Issue #40、#76、#104

参见

• 项目主页 - SeekDB 完整功能介绍
• 安装指南 - 详细的安装配置步骤
• SQL 参考 - 支持的 SQL 语法和函数
• 向量搜索 - 向量索引和相似度搜索
• 全文搜索 - 全文索引配置和使用
• 贡献指南 - 如何参与 SDK 开发

1. 编译环境要求

1.1 系统要求

SeekDB 支持多种操作系统平台编译。以下是各平台的具体要求：

1.2 编译工具链

SeekDB 采用 CMake 作为跨平台构建系统，需要以下编译工具：

1.3 第三方依赖

SeekDB 的编译依赖于多个第三方库，这些依赖通过 CMake 自动下载或系统包管理器安装：

• Boost: C++ 标准库扩展
• lz4: 高效压缩库
• snappy: 快速压缩库
• zlib: 压缩库
• openssl: OpenSSL 加密库

注意：部分依赖在编译过程中会自动下载，无需手动安装。建议在编译前确保网络连接正常。

2. 构建系统架构

2.1 CMake 构建流程

SeekDB 的构建系统采用分层架构，CMakeLists.txt 负责管理整体构建配置。以下是编译流程的架构图：

graph TD
    A[用户执行 build.sh] --> B[CMake 配置阶段]
    B --> C{检测平台}
    C -->|Linux| D[生成 Makefile]
    C -->|Windows| E[生成 Visual Studio 项目]
    C -->|Android| F[生成 NDK 构建文件]
    D --> G[make 构建阶段]
    E --> H[MSBuild 构建阶段]
    F --> I[NDK 交叉编译]
    G --> J[生成可执行文件/库]
    H --> J
    I --> J
    J --> K[安装到目标目录]
    
    style A fill:#e1f5fe
    style J fill:#c8e6c9
    style K fill:#fff3e0

2.2 项目结构

SeekDB 源码目录结构如下：

2.3 CMake 配置选项

CMake 提供多种配置选项以适应不同的构建需求：

提示：使用 -D 选项传递配置参数，例如：cmake -DBUILD_TESTING=ON ..

3. Linux 平台编译

3.1 环境准备

在 Linux 平台上编译 SeekDB 前，需要安装必要的系统依赖。以下是各发行版的安装命令：

Ubuntu / Debian:

sudo apt-get update
sudo apt-get install -y build-essential cmake git gcc g++ libboost-all-dev \
    liblz4-dev libsnappy-dev zlib1g-dev libssl-dev python3-dev

CentOS / RHEL:

sudo yum groupinstall -y "Development Tools"
sudo yum install -y cmake git gcc-c++ boost-devel lz4-devel snappy \
    zlib-devel openssl-devel python3-devel

3.2 编译步骤

Linux 平台提供自动化构建脚本 build.sh，支持一键编译：

# 克隆源码仓库
git clone https://github.com/oceanbase/seekdb.git
cd seekdb

# 执行构建脚本
./build.sh

build.sh 脚本的执行流程如下：

flowchart LR
    A[执行 build.sh] --> B[创建 build 目录]
    B --> C[运行 CMake 配置]
    C --> D{检查工具链}
    D -->|通过| E[执行 make 构建]
    D -->|失败| F[输出错误信息]
    E --> G[安装库文件]
    G --> H[编译完成]
    
    style A fill:#e1f5fe
    style H fill:#c8e6c9
    style F fill:#ffcdd2

3.3 构建产物

编译完成后，产物位于 build/ 目录下：

4. Windows 平台编译

4.1 环境准备

Windows 平台需要以下开发环境：

4.2 使用 PowerShell 构建

SeekDB 提供 build.ps1 PowerShell 脚本用于 Windows 平台构建：

# 克隆源码
git clone https://github.com/oceanbase/seekdb.git
cd seekdb

# 执行 PowerShell 构建脚本
.\build.ps1

4.3 CMake GUI 构建

除脚本外，也可使用 CMake GUI 进行可视化构建：

1. 打开 CMake GUI，选择源码目录和构建目录
2. 点击 "Configure" 选择 Visual Studio 编译器
3. 配置所需的构建选项
4. 点击 "Generate" 生成项目文件
5. 使用 Visual Studio 打开生成的解决方案文件进行编译

5. Android 平台编译

SeekDB 支持在 Android 设备上运行，提供轻量级部署模式。详细的 Android 编译指南请参考官方文档。

5.1 NDK 环境要求

5.2 交叉编译配置

Android 平台采用 NDK 进行交叉编译，需要配置以下环境变量：

export ANDROID_NDK_HOME=/path/to/android-ndk
export ANDROID_SDK_ROOT=/path/to/android-sdk

6. Python SDK 打包

SeekDB 提供 Python SDK（pyseekdb），可通过 setuptools 打包为 wheel 分发。

6.1 打包配置

Python SDK 的打包配置位于 package/wheel/lib/setup.py：

def get_package_data():
    """获取包数据文件"""
    return {
        __package_name__: [
            f"{__library_name()}.so.0.gz"
        ]
    }

打包配置说明：

6.2 打包步骤

cd package/wheel/lib
python3 setup.py bdist_wheel

生成的 wheel 包位于 dist/ 目录下，可使用 pip 安装：

pip install dist/pyseekdb-*.whl

7. 常见问题与解决方案

7.1 编译错误排查

7.2 性能优化建议

• 启用 ccache：CMake 默认启用 ccache，可显著加速增量编译
• 合理设置并行数：根据 CPU 核心数设置，避免内存不足
• 使用 Release 模式：生产环境建议使用 Release 构建以获得最佳性能

7.3 调试构建

如需调试版本，可使用以下配置：

cmake -DCMAKE_BUILD_TYPE=Debug ..
make -j$(nproc)

Debug 构建会包含调试符号，便于使用 GDB 或 LLDB 进行调试。

8. 相关文档

9. 参考资料

• OceanBase SeekDB 官方仓库：https://github.com/oceanbase/seekdb
• CMake 官方文档：https://cmake.org/documentation/
• OceanBase 社区：https://open.oceanbase.com/

概述

SeekDB 是 OceanBase 团队开发的全新 AI 原生数据库产品，基于 OceanBase 数据库核心引擎构建，进一步满足 AI 应用场景的需求。项目采用 Apache 2.0 开源许可证，欢迎社区贡献者参与代码、文档、测试、观测性、工具和生态系统集成等各个方面的工作。资料来源：docs/developer-guide/zh/contributing.md:1-15

贡献类型

SeekDB 项目接受多种类型的贡献，包括但不限于：

资料来源：README.md:1-10

开发环境搭建

系统要求

SeekDB 支持 Linux x86_64 和 Linux aarch64 平台，开发者需要准备以下环境：

资料来源：package/wheel/lib/setup.py:30-40

开发依赖安装

# 安装 Python 开发依赖
pip install -U pyseekdb

# 安装构建工具
yum install -y gcc gcc-c++ make cmake

# 安装 Git
yum install -y git

资料来源：package/wheel/README.md:1-20

代码规范

SeekDB 项目遵循严格的代码规范，确保代码质量和一致性。所有贡献的代码必须通过规范检查。

编码规范要点

graph TD
    A[代码提交] --> B{代码规范检查}
    B -->|通过| C[编译构建]
    B -->|失败| D[返回修改]
    C --> E{单元测试}
    E -->|通过| F[代码审查]
    E -->|失败| G[修复测试]
    D --> A
    G --> A
    F --> H[合并到主分支]

C++ 代码规范

SeekDB 的 C++ 代码遵循 OceanBase 内核的编码标准，关键规范包括：

资料来源：src/sql/engine/expr/ob_expr_json_search.cpp:1-30

Python 代码规范

Python SDK (pyseekdb) 遵循 PEP 8 编码规范，并使用以下额外规则：

# 示例：正确的导入顺序
import os
import sys
from pathlib import Path

import pyseekdb
from pyseekdb import DefaultEmbeddingFunction

# 常量命名：全大写加下划线
MAX_BATCH_SIZE = 1000
DEFAULT_TIMEOUT = 30

# 类名：驼峰命名
class DataCollection:
    pass

资料来源：docs/developer-guide/en/coding-convention.md:1-50

SQL 语法规范

SeekDB 兼容 MySQL 语法，支持以下数据类型和关键字：

资料来源：src/objit/include/objit/common/ob_item_type.h:1-20

开发流程

分支管理策略

graph LR
    A[main] --> B[release/v1.x]
    A --> C[feature/xxx]
    C --> D[开发分支]
    D --> E[Pull Request]
    E --> A
    B --> A

SeekDB 采用 GitFlow 分支模型：

资料来源：docs/developer-guide/en/contributing.md:1-30

提交规范

每次提交应遵循以下格式：

<类型>(<范围>): <简短描述>

[可选的详细描述]

[可选的脚注]

提交类型：

资料来源：CONTRIBUTING.md:1-40

Pull Request 流程

sequenceDiagram
    participant 开发者
    participant GitHub
    participant 审查者
    participant CI/CD
    
    开发者->>GitHub: 创建分支并提交代码
    开发者->>GitHub: 打开 Pull Request
    GitHub->>CI/CD: 触发自动化检查
    CI/CD-->>GitHub: 返回检查结果
    审查者->>GitHub: 代码审查
    审查者->>开发者: 请求修改
    开发者->>GitHub: 提交修改
    审查者->>GitHub: 批准 PR
    GitHub->>GitHub: 合并到主分支

PR 审查要点：

1. 代码质量：是否符合代码规范
2. 测试覆盖：是否包含充分的测试用例
3. 文档更新：是否更新相关文档
4. 向后兼容：是否影响现有功能
5. 性能影响：是否引入性能退化

资料来源：docs/developer-guide/zh/contributing.md:1-35

测试要求

测试框架

SeekDB 使用多种测试框架确保代码质量：

资料来源：CONTRIBUTING.md:30-60

测试覆盖率要求

运行测试

# 运行 C++ 单元测试
make test

# 运行 Python SDK 测试
python -m pytest tests/

# 运行集成测试
./run_integration_tests.sh

# 生成测试覆盖率报告
make coverage

社区参与

联系方式

行为准则

所有社区参与者必须遵守以下行为准则：

• 尊重他人：保持友善和专业的交流态度
• 包容多元：欢迎不同背景和技能水平的贡献者
• 建设性反馈：提供具体、有建设性的反馈意见
• 保护隐私：尊重他人的隐私和信息安全

资料来源：#123: Developer Activities: Call for Participation

贡献者识别

活跃贡献者将获得以下认可：

常见问题

环境配置问题

Q: 编译失败，提示找不到头文件？

# 确保安装了所有依赖
yum install -y gcc gcc-c++ make cmake git

# 检查环境变量
echo $CPLUS_INCLUDE_PATH
echo $LIBRARY_PATH

Q: Python SDK 安装失败？

# 使用正确的安装命令
pip install -U pyseekdb

# 或从源码安装
cd package/wheel
pip install -e .

资料来源：package/wheel/README.md:20-30

代码贡献问题

Q: 如何选择合适的分支？

功能开发 → feature/功能名
Bug 修复 → fix/问题描述
文档更新 → docs/文档类型

Q: PR 被拒绝的主要原因？

性能相关问题

Q: 如何验证性能改进？

# 运行性能基准测试
./benchmark.sh --test=vector_search

# 对比基准结果
./benchmark.sh --compare=baseline.json

许可证

SeekDB 项目采用 Apache License 2.0 开源许可证。所有贡献的代码必须遵循此许可证。

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

资料来源：package/wheel/lib/setup.py:50-55

相关资源

参见

• 安装指南 - 详细的 SeekDB 安装步骤
• 快速开始 - 5 分钟构建语义搜索系统
• API 参考 - Python SDK 和 SQL API 文档
• 架构设计 - SeekDB 系统架构详解

Pitfall Log / 踩坑日志

项目：oceanbase/seekdb

摘要：发现 23 个潜在踩坑项，其中 12 个为 high/blocking；最高优先级：安装坑 - 来源证据：Docker seekdb container fails to start。

1. 安装坑 · 来源证据：Docker seekdb container fails to start

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Docker seekdb container fails to start
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_4efd5fa8734843b1a38c24dd0bf33ce1 | https://github.com/oceanbase/seekdb/issues/736 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

2. 安装坑 · 来源证据：Error executing `CALL dbms_index_manager.refresh` after upgrade to version 1.3.0

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Error executing CALL dbms_index_manager.refresh after upgrade to version 1.3.0
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_87d2b7281ded463c97a2b6b8f75838df | https://github.com/oceanbase/seekdb/issues/744 | 来源类型 github_issue 暴露的待验证使用条件。

3. 安装坑 · 来源证据：Release compilation fails on GitHub master branch due to missing devdeps-gtest-1.8.0 package

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release compilation fails on GitHub master branch due to missing devdeps-gtest-1.8.0 package
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_0952aa164d554b6eb30a33957902e7f2 | https://github.com/oceanbase/seekdb/issues/609 | 来源类型 github_issue 暴露的待验证使用条件。

4. 安装坑 · 来源证据：Replace source code dependency for compression libraries with header/static library dependency

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Replace source code dependency for compression libraries with header/static library dependency
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_dd8878c1767f48019a7a6de8ee316b6e | https://github.com/oceanbase/seekdb/issues/431 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

5. 安装坑 · 来源证据：Standby fails to switch to primary with error -4109 (can not change_access_mode) during DDL stress test

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Standby fails to switch to primary with error -4109 (can not change_access_mode) during DDL stress test
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_dd2b26a572f543dca7126dbc35c1f32c | https://github.com/oceanbase/seekdb/issues/272 | 来源类型 github_issue 暴露的待验证使用条件。

6. 配置坑 · 来源证据：Fix incorrect results for composite (vector, json->'$.page') NOT IN queries in mysqltest

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Fix incorrect results for composite (vector, json->'$.page') NOT IN queries in mysqltest
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_6ea131c334584a719bcceceb0beddbfb | https://github.com/oceanbase/seekdb/issues/518 | 来源讨论提到 linux 相关条件，需在安装/试用前复核。

7. 配置坑 · 来源证据：Fix observer crash when dbms_stats.gather_table_stats references non-existent column in method_opt

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Fix observer crash when dbms_stats.gather_table_stats references non-existent column in method_opt
• 对用户的影响：可能阻塞安装或首次运行。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_b64c8c43b45e4398adf06f1827e5cdd7 | https://github.com/oceanbase/seekdb/issues/460 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。

8. 配置坑 · 来源证据：Standby reports 'single replay task cost too much time' (errcode=-4389) after switchover

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Standby reports 'single replay task cost too much time' (errcode=-4389) after switchover
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_19eb5d217a314053acda472366849c4b | https://github.com/oceanbase/seekdb/issues/274 | 来源类型 github_issue 暴露的待验证使用条件。

9. 配置坑 · 来源证据：[Bug]: Spatial Reference System has no WGS 84（SRID=4326）support

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Bug]: Spatial Reference System has no WGS 84（SRID=4326）support
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_f018b0c63bea4d74b5000c63626fb31a | https://github.com/oceanbase/seekdb/issues/742 | 来源类型 github_issue 暴露的待验证使用条件。

10. 配置坑 · 来源证据：mysqltest on Windows fails with error 1210 when renaming table column in mysql_column_priv_sqlqa.mysql_column_priv

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：mysqltest on Windows fails with error 1210 when renaming table column in mysql_column_priv_sqlqa.mysql_column_priv
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_e93f346926154d7d8f0163da3e15da88 | https://github.com/oceanbase/seekdb/issues/470 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。

11. 维护坑 · 来源证据：Establish Performance Regression Test for Lite Edition

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Establish Performance Regression Test for Lite Edition
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_6b7dd4f41b69434d9bb4e93ec3778b4f | https://github.com/oceanbase/seekdb/issues/430 | 来源类型 github_issue 暴露的待验证使用条件。

12. 维护坑 · 来源证据：Miscellaneous optimization points for schema service and location refresh

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Miscellaneous optimization points for schema service and location refresh
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_f1c53e38c174404cbbdce3d467e8db24 | https://github.com/oceanbase/seekdb/issues/435 | 来源类型 github_issue 暴露的待验证使用条件。

13. 安装坑 · 来源证据：QPS drops to ~0.2 under read-write mixed workload when async index data volume reaches 100%

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：QPS drops to ~0.2 under read-write mixed workload when async index data volume reaches 100%
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_4517f3a695c0497e923f0ed3e1a50f6b | https://github.com/oceanbase/seekdb/issues/694 | 来源类型 github_issue 暴露的待验证使用条件。

14. 配置坑 · 来源证据：Data becomes unsearchable after process restart during asynchronous index refresh

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Data becomes unsearchable after process restart during asynchronous index refresh
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_4b4435e31bfe45cf8d66b4da4cc4ef64 | https://github.com/oceanbase/seekdb/issues/489 | 来源类型 github_issue 暴露的待验证使用条件。

15. 配置坑 · 来源证据：Fix Lost connection (2013) when using session debug with extreme parameters for CONCAT/SUBSTRING_INDEX

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Fix Lost connection (2013) when using session debug with extreme parameters for CONCAT/SUBSTRING_INDEX
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_3b877706f3d74849b08d9c4266a350e4 | https://github.com/oceanbase/seekdb/issues/766 | 来源类型 github_issue 暴露的待验证使用条件。

16. 配置坑 · 来源证据：Fix error 1526 (no partition found) for self-referencing INSERT...SELECT with count(1)+id on KEY partitioned table unde…

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Fix error 1526 (no partition found) for self-referencing INSERT...SELECT with count(1)+id on KEY partitioned table under parallel DML and trx.branch_savepoint
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_776c25de210245d6ad4460191e5d2e73 | https://github.com/oceanbase/seekdb/issues/636 | 来源类型 github_issue 暴露的待验证使用条件。

17. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 建议检查：将假设转成下游验证清单。
• 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
• 证据：capability.assumptions | github_repo:1080442728 | https://github.com/oceanbase/seekdb | README/documentation is current enough for a first validation pass.

18. 运行坑 · 运行可能依赖外部服务

• 严重度：medium
• 证据强度：source_linked
• 发现：项目说明出现 external service/cloud/webhook/database 等运行依赖关键词。
• 对用户的影响：本地安装成功不等于能力可用，外部服务不可用会阻断体验。
• 建议检查：确认是否有离线 demo、mock 数据或可替代服务。
• 防护动作：外部服务依赖未明确时，不把本地安装成功等同于能力可用。
• 证据：packet_text.keyword_scan | github_repo:1080442728 | https://github.com/oceanbase/seekdb | matched external service / cloud / webhook / database keyword

19. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
• 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
• 证据：evidence.maintainer_signals | github_repo:1080442728 | https://github.com/oceanbase/seekdb | last_activity_observed missing

20. 安全/权限坑 · 下游验证发现风险项

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：下游已经要求复核，不能在页面中弱化。
• 建议检查：进入安全/权限治理复核队列。
• 防护动作：下游风险存在时必须保持 review/recommendation 降级。
• 证据：downstream_validation.risk_items | github_repo:1080442728 | https://github.com/oceanbase/seekdb | no_demo; severity=medium

21. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 建议检查：把风险写入边界卡，并确认是否需要人工复核。
• 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
• 证据：risks.scoring_risks | github_repo:1080442728 | https://github.com/oceanbase/seekdb | no_demo; severity=medium

22. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
• 防护动作：issue/PR 响应未知时，必须提示维护风险。
• 证据：evidence.maintainer_signals | github_repo:1080442728 | https://github.com/oceanbase/seekdb | issue_or_pr_quality=unknown

23. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
• 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
• 证据：evidence.maintainer_signals | github_repo:1080442728 | https://github.com/oceanbase/seekdb | release_recency=unknown