querying-from-seekdb

从 seekdb 查询和导出数据

从 seekdb 向量数据库查询数据，支持标量搜索、混合搜索（全文 + 语义）以及导出为 CSV/Excel 文件。

路径约定

注意：本文档中的所有路径（例如 scripts/）均相对于当前技能目录，而非项目根目录。

前提条件

• 已安装 Python 3.10+
• 数据已导入 seekdb 集合
• 所需软件包：

pip install pyseekdb pandas openpyxl

⚠️ 关键：执行工作流

处理用户搜索请求时，必须遵循此工作流：

步骤 1：获取集合信息（如果尚未了解）

构建任何查询之前，必须先了解数据结构。不过，你应在当前对话中缓存这些信息。

缓存规则：

• ✅ 首次查询某个集合：执行 --info 以获取元数据结构
• ✅ 后续查询同一个集合：使用对话中先前缓存的信息，跳过 --info
• ✅ 查询不同的集合：对新集合执行 --info
• ✅ 用户明确要求查看集合信息：执行 --info

# Get collection info to see metadata fields (only if not already known)
python scripts/query_from_seekdb.py <collection_name> --info

此操作会显示：

• 记录总数
• 可用的元数据字段名称（例如 source、year、category）
• 示例文档

对话流程示例：

User: "找 seekdb_demo 中 2023 年的教程"
→ Claude Code: 执行 --info (第一次查询此 collection)
→ 发现 metadata 有 source, year 字段
→ 执行搜索

User: "再找一下 notion 来源的"
→ Claude Code: 不需要再执行 --info (同一 collection，结构已知)
→ 直接执行搜索

User: "查一下 another_collection 中的数据"
→ Claude Code: 执行 --info (不同 collection)
→ 了解新 collection 的结构
→ 执行搜索

步骤 2：分析用户请求

解析用户的自然语言请求，识别以下内容：

组成部分	查找内容	对应参数
元数据条件	字段-值对，例如“2023 年”“来自 notion”“价格<100”	--where 筛选条件
内容/语义搜索	关键词、概念、描述、问题	--query-text（同时用于全文和语义搜索）

重要：--query-text 会同时用于全文搜索（$contains）和语义搜索（query_texts）。两者使用相同的文本。

步骤 3：选择搜索方式

User Request Analysis
       │
       ▼
┌─────────────────────────────────────────────────────────────┐
│ Does the request involve ONLY metadata field conditions?    │
│ (e.g., "year=2023", "source=notion", no content search)     │
└─────────────────────────────────────────────────────────────┘
       │
       ├── YES ──► Scalar Search: --where only
       │
       └── NO ───► Does it involve content/semantic search?
                          │
                          ├── YES (no metadata) ──► Hybrid Search: --query-text only
                          │
                          └── YES (with metadata) ──► Scalar + Hybrid: --where + --query-text

两种搜索模式

模式 1：标量搜索（仅元数据）

适用情况：用户只想按元数据字段筛选，不需要内容/语义搜索。

# Filter by metadata fields only
python scripts/query_from_seekdb.py seekdb_demo --where '{"source": "notion", "year": 2023}'

请求示例：

• “找出所有来自 notion 的文档”
• “显示 2023 年的记录”
• “source 是 google-docs 的数据”

模式 2：混合搜索（全文 + 语义）

适用情况：用户想按内容搜索——查询文本同时用于全文匹配和语义相似度搜索。

# Hybrid search: query text used for both fulltext ($contains) and semantic (query_texts)
python scripts/query_from_seekdb.py seekdb_demo --query-text "seekdb 教程"

工作原理：

• --query-text "seekdb 教程" → 全文：where_document: {"$contains": "seekdb 教程"} + 语义：query_texts: "seekdb 教程"
• 使用 RRF（倒数排名融合）对结果进行排序

请求示例：

• “找 seekdb 教程” → --query-text "seekdb 教程"
• “搜索 python 技术文档” → --query-text "python 技术文档"

模式 3：标量 + 混合搜索

适用情况：用户想同时按元数据筛选和按内容/语义搜索。

# Metadata filter + Hybrid search
python scripts/query_from_seekdb.py seekdb_demo --query-text "seekdb 教程" --where '{"year": 2023}'

请求示例：

• “请找出 seekdb_demo 集合中 2023 年写的 seekdb 教程” → --query-text "seekdb 教程" --where '{"year": 2023}'
• “找 notion 来源的编程指南” → --query-text "编程指南" --where '{"source": "notion"}'

🎯 真实场景示例分析

用户请求：“请找出 seekdb_demo 集合中 2023 年写的 seekdb 教程”

步骤 1：运行 --info 以获取元数据结构：

python scripts/query_from_seekdb.py seekdb_demo --info
# Output shows metadata fields: source, year

步骤 2：分析请求：

部分	类型	筛选条件
“2023 年”	元数据字段 year	--where '{"year": 2023}'
“seekdb 教程”	内容/语义搜索	--query-text "seekdb 教程"

步骤 3：执行：

python scripts/query_from_seekdb.py seekdb_demo --query-text "seekdb 教程" --where '{"year": 2023}'

CLI 参考

命令

# List all collections
python scripts/query_from_seekdb.py --list-collections

# Show collection info (run this first to understand data structure!)
python scripts/query_from_seekdb.py <collection_name> --info

# Scalar search (metadata filter only)
python scripts/query_from_seekdb.py <collection_name> --where '<json_filter>'

# Hybrid search (fulltext + semantic, using same query text for both)
python scripts/query_from_seekdb.py <collection_name> --query-text "<text>" [-n <count>]

# Scalar + Hybrid search (metadata filter + fulltext + semantic)
python scripts/query_from_seekdb.py <collection_name> --query-text "<text>" --where '<json>'

# Export to CSV/Excel
python scripts/query_from_seekdb.py <collection_name> <search_options> --output results.csv
python scripts/query_from_seekdb.py <collection_name> <search_options> --output results.xlsx

选项

选项	短选项	描述
--query-text	-q	用于混合搜索（全文 + 语义）的文本
--where	-w	JSON 字符串格式的元数据筛选条件
--n-results	-n	结果数量（默认值：5）
--output	-o	导出到文件（.csv 或 .xlsx）
--json	-j	以 JSON 格式输出
--info		显示集合信息
--list-collections	-l	列出所有集合
--include		要包含的字段：documents,metadatas,embeddings
--sheet-name	-s	Excel 导出的工作表名称

过滤运算符

如何构造 --where 参数

步骤 1：运行 --info 查看可用的元数据字段：

python scripts/query_from_seekdb.py seekdb_demo --info

# Example output:
# Collection: seekdb_demo
#   Total records: 2
# Preview (first 3 records):
#   ID: doc1...
#     Document: python tutorial...
#     Metadata keys: ['source', 'year']    ← These are the metadata field names!

步骤 2：使用元数据字段名称构造 --where：

# From the output above, we know the collection has 'source' and 'year' fields
# So we can filter by these fields:

--where '{"source": "notion"}'           # source equals "notion"
--where '{"year": 2023}'                 # year equals 2023
--where '{"source": "notion", "year": 2023}'  # both conditions (implicit AND)

步骤 3：将用户请求与元数据字段匹配：

用户表述	元数据字段	--where 值
“2023 年的”	year	'{"year": 2023}'
“来自 notion 的”	source	'{"source": "notion"}'
“价格低于 100 的”	price	'{"price": {"$lt": 100}}'
“品牌是三星或苹果的”	brand	'{"brand": {"$in": ["Samsung", "Apple"]}}'

元数据过滤运算符

运算符	描述	示例
$eq	等于	{"year": {"$eq": 2023}} 或 {"year": 2023}
$ne	不等于	{"status": {"$ne": "deleted"}}
$gt	大于	{"score": {"$gt": 90}}
$gte	大于或等于	{"score": {"$gte": 90}}
$lt	小于	{"score": {"$lt": 50}}
$lte	小于或等于	{"score": {"$lte": 50}}
$in	在列表中	{"tag": {"$in": ["ml", "ai"]}}
$nin	不在列表中	{"tag": {"$nin": ["old"]}}
$and	逻辑与	{"$and": [{"year": 2023}, {"source": "notion"}]}
$or	逻辑或	{"$or": [{"year": 2023}, {"year": 2024}]}

复杂过滤示例

# Multiple conditions with implicit AND (both must be true)
--where '{"source": "notion", "year": 2023}'

# Explicit AND
--where '{"$and": [{"source": "notion"}, {"year": {"$gte": 2023}}]}'

# OR condition
--where '{"$or": [{"source": "notion"}, {"source": "google-docs"}]}'

# Range condition (year between 2022 and 2024)
--where '{"$and": [{"year": {"$gte": 2022}}, {"year": {"$lte": 2024}}]}'

# Combined AND + OR
--where '{"$and": [{"year": 2023}, {"$or": [{"source": "notion"}, {"source": "obsidian"}]}]}'

导出为 CSV/Excel

# Export scalar search results to CSV
python scripts/query_from_seekdb.py mobiles --where '{"Brand": "SAMSUNG"}' --output samsung.csv

# Export hybrid search results to Excel
python scripts/query_from_seekdb.py mobiles --query-text "good camera" --output results.xlsx

# Export with custom sheet name
python scripts/query_from_seekdb.py mobiles --query-text "phone" --output phones.xlsx --sheet-name "Search Results"

支持的导出格式

格式	扩展名	描述
CSV	.csv	逗号分隔值，采用 UTF-8 编码并带 BOM
Excel	.xlsx	Excel 工作簿格式

seekdb 中的数据结构

seekdb 在两个不同的位置存储数据：

存储位置	描述	过滤方法	示例
元数据	结构化键值字段	--where	{"source": "notion", "year": 2023}
文档	文本内容	--query-text（混合搜索）	全文搜索 + 语义搜索

连接配置

为服务器模式设置环境变量：

变量	描述	默认值
SEEKDB_HOST	服务主机（设置后使用服务器模式）	-
SEEKDB_PORT	服务端口	2881
SEEKDB_DATABASE	数据库名称	test
SEEKDB_USER	用户名	root
SEEKDB_PASSWORD	密码	-

参考资料

• pyseekdb SDK 入门指南
• hybrid_search API
• get API
• 过滤运算符