querying-from-seekdb

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Query and Export Data from seekdb

从seekdb查询并导出数据

Query data from seekdb vector database with support for scalar search, hybrid search (fulltext + semantic), and export to CSV/Excel files.

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

Path Convention

路径约定

Note: All paths in this document (e.g.,
scripts/
) are relative to THIS skill directory, not the project root.

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

Prerequisites

前置条件

Python 3.10+ installed
Data imported into seekdb collection
Required packages:

bash

pip install pyseekdb pandas openpyxl

已安装Python 3.10+
数据已导入seekdb集合
所需依赖包：

bash

pip install pyseekdb pandas openpyxl

⚠️ CRITICAL: Execution Workflow

⚠️ 重要：执行流程

MUST FOLLOW this workflow when handling user search requests:

处理用户搜索请求时必须遵循以下流程：

Step 1: Get Collection Information (If Not Already Known)

步骤1：获取集合信息（若未知）

Before constructing any query, you MUST understand the data structure. However, you should cache this information within the conversation.

Caching Rules:

✅ First query for a collection: Execute
```
--info
```
to get metadata structure
✅ Subsequent queries for the SAME collection: Use cached info from earlier in conversation, skip
```
--info
```
✅ Query for a DIFFERENT collection: Execute
```
--info
```
for the new collection
✅ User explicitly asks for collection info: Execute
```
--info
```

bash

undefined

在构建任何查询之前，必须了解数据结构。但应在对话中缓存此信息。

缓存规则：

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

bash

undefined

Get collection info to see metadata fields (only if not already known)

获取集合信息以查看元数据字段（仅当未知时执行）

python scripts/query_from_seekdb.py <collection_name> --info


This shows:
- Total record count
- Available metadata field names (e.g., `source`, `year`, `category`)
- Sample documents

**Example conversation flow:**

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 的结构 → 执行搜索

undefined

python scripts/query_from_seekdb.py <collection_name> --info


这将显示：
- 总记录数
- 可用元数据字段名称（如 `source`、`year`、`category`）
- 示例文档

**对话流程示例：**

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

用户："再找一下 notion 来源的" → Claude Code: 不需要再执行 --info（同一 collection，结构已知） → 直接执行搜索

用户："查一下 another_collection 中的数据" → Claude Code: 执行 --info（不同 collection） → 了解新 collection 的结构 → 执行搜索

undefined

Step 2: Analyze User Request

步骤2：分析用户请求

Parse the user's natural language request to identify:

Component	Look For	Maps To
Metadata conditions	Field-value pairs like "2023年", "来自notion", "价格<100"	`--where` filter
Content/Semantic search	Keywords, concepts, descriptions, questions	`--query-text` (used for BOTH fulltext and semantic)

Important:

--query-text

is used for BOTH fulltext search (

$contains

) and semantic search (

query_texts

) simultaneously. The same text is used for both.

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

组成部分	识别要点	对应参数
元数据条件	字段-值对，如"2023年"、"来自notion"、"价格<100"	`--where` 过滤器
内容/语义搜索	关键词、概念、描述、问题	`--query-text` （同时用于全文检索和语义搜索）

重要提示：

--query-text

同时用于全文检索（

$contains

）和语义搜索（

query_texts

）。同一文本将用于两种搜索方式。

Step 3: Choose Search Method

步骤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

用户请求分析
       │
       ▼
┌─────────────────────────────────────────────────────────────┐
│ 请求是否仅涉及元数据字段条件？                              │
│ （例如："year=2023"、"source=notion"，无内容搜索）           │
└─────────────────────────────────────────────────────────────┘
       │
       ├── 是 ──► 标量搜索：仅使用 --where
       │
       └── 否 ───► 是否涉及内容/语义搜索？
                          │
                          ├── 是（无元数据） ──► 混合搜索：仅使用 --query-text
                          │
                          └── 是（含元数据） ──► 标量+混合：--where + --query-text

Two Search Modes

两种搜索模式

Mode 1: Scalar Search (Metadata Only)

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

When to use: User wants to filter by metadata fields ONLY, no content/semantic search needed.

bash

undefined

适用场景：用户仅需按元数据字段过滤，无需内容/语义搜索。

bash

undefined

Filter by metadata fields only

仅按元数据字段过滤

python scripts/query_from_seekdb.py seekdb_demo --where '{"source": "notion", "year": 2023}'


**Example requests**:
- "找出所有来自 notion 的文档"
- "显示 2023 年的记录"
- "source 是 google-docs 的数据"

python scripts/query_from_seekdb.py seekdb_demo --where '{"source": "notion", "year": 2023}'


**请求示例**：
- "找出所有来自 notion 的文档"
- "显示 2023 年的记录"
- "source 是 google-docs 的数据"

Mode 2: Hybrid Search (Fulltext + Semantic)

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

When to use: User wants to search by content - the query text is used for BOTH fulltext matching AND semantic similarity.

bash

undefined

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

bash

undefined

Hybrid search: query text used for both fulltext ($contains) and semantic (query_texts)

混合搜索：查询文本同时用于全文检索（$contains）和语义搜索（query_texts）

python scripts/query_from_seekdb.py seekdb_demo --query-text "seekdb 教程"


**How it works**:
- `--query-text "seekdb 教程"` → Fulltext: `where_document: {"$contains": "seekdb 教程"}` + Semantic: `query_texts: "seekdb 教程"`
- Results are ranked using RRF (Reciprocal Rank Fusion)

**Example requests**:
- "找 seekdb 教程" → `--query-text "seekdb 教程"`
- "搜索 python 技术文档" → `--query-text "python 技术文档"`

python scripts/query_from_seekdb.py seekdb_demo --query-text "seekdb 教程"


**工作原理**：
- `--query-text "seekdb 教程"` → 全文检索：`where_document: {"$contains": "seekdb 教程"}` + 语义搜索：`query_texts: "seekdb 教程"`
- 结果使用RRF（Reciprocal Rank Fusion， reciprocal rank融合算法）排序

**请求示例**：
- "找 seekdb 教程" → `--query-text "seekdb 教程"`
- "搜索 python 技术文档" → `--query-text "python 技术文档"`

Mode 3: Scalar + Hybrid Search

模式3：标量+混合搜索

When to use: User wants metadata filtering + content/semantic search.

bash

undefined

适用场景：用户需元数据过滤+内容/语义搜索。

bash

undefined

Metadata filter + Hybrid search

元数据过滤 + 混合搜索

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


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

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"}'`

🎯 Real-World Example Analysis

🎯 实际案例分析

User request: "请找出 seekdb_demo 集合中 2023 年写的 seekdb 教程"

Step 1: Run

--info

to get metadata structure:

bash

python scripts/query_from_seekdb.py seekdb_demo --info

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

步骤1：执行

--info

获取元数据结构：

bash

python scripts/query_from_seekdb.py seekdb_demo --info

Output shows metadata fields: source, year

输出显示元数据字段：source, year


**Step 2**: Analyze request:
| Part | Type | Filter |
|------|------|--------|
| "2023 年" | Metadata field `year` | `--where '{"year": 2023}'` |
| "seekdb 教程" | Content/Semantic search | `--query-text "seekdb 教程"` |

**Step 3**: Execute:
```bash
python scripts/query_from_seekdb.py seekdb_demo --query-text "seekdb 教程" --where '{"year": 2023}'


**步骤2**：分析请求：
| 部分 | 类型 | 过滤器 |
|------|------|--------|
| "2023 年" | 元数据字段 `year` | `--where '{"year": 2023}'` |
| "seekdb 教程" | 内容/语义搜索 | `--query-text "seekdb 教程"` |

**步骤3**：执行查询：
```bash
python scripts/query_from_seekdb.py seekdb_demo --query-text "seekdb 教程" --where '{"year": 2023}'

CLI Reference

CLI 参考

Commands

命令

bash

undefined

bash

undefined

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

导出为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

undefined

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

undefined

Options

选项

Option	Short	Description
`--query-text`	`-q`	Text for hybrid search (fulltext + semantic)
`--where`	`-w`	Metadata filter as JSON string
`--n-results`	`-n`	Number of results (default: 5)
`--output`	`-o`	Export to file (.csv or .xlsx)
`--json`	`-j`	Output as JSON
`--info`		Show collection info
`--list-collections`	`-l`	List all collections
`--include`		Fields to include: documents,metadatas,embeddings
`--sheet-name`	`-s`	Sheet name for Excel export

选项	缩写	描述
`--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导出的工作表名称

Filter Operators

过滤运算符

How to Construct --where Parameter

如何构造 --where 参数

Step 1: Run

--info

to see available metadata fields:

bash

python scripts/query_from_seekdb.py seekdb_demo --info

步骤1：执行

--info

查看可用元数据字段：

bash

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!

Metadata keys: ['source', 'year'] ← 这些是元数据字段名称！


**Step 2**: Use the metadata field names to construct `--where`:
```bash


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

From the output above, we know the collection has 'source' and 'year' fields

根据上述输出，我们知道该集合包含'source'和'year'字段

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)


**Step 3**: Match user request to metadata fields:
| User says | Metadata field | --where value |
|-----------|----------------|---------------|
| "2023 年的" | `year` | `'{"year": 2023}'` |
| "来自 notion 的" | `source` | `'{"source": "notion"}'` |
| "价格低于 100 的" | `price` | `'{"price": {"$lt": 100}}'` |
| "品牌是三星或苹果的" | `brand` | `'{"brand": {"$in": ["Samsung", "Apple"]}}'` |

--where '{"source": "notion"}' # source等于"notion" --where '{"year": 2023}' # year等于2023 --where '{"source": "notion", "year": 2023}' # 同时满足两个条件（隐式AND）


**步骤3**：将用户请求映射到元数据字段：
| 用户表述 | 元数据字段 | --where 值 |
|-----------|----------------|---------------|
| "2023 年的" | `year` | `'{"year": 2023}'` |
| "来自 notion 的" | `source` | `'{"source": "notion"}'` |
| "价格低于 100 的" | `price` | `'{"price": {"$lt": 100}}'` |
| "品牌是三星或苹果的" | `brand` | `'{"brand": {"$in": ["Samsung", "Apple"]}}'` |

Metadata Filter Operators

元数据过滤运算符

Operator	Description	Example
`$eq`	Equal to	`{"year": {"$eq": 2023}}` or `{"year": 2023}`
`$ne`	Not equal to	`{"status": {"$ne": "deleted"}}`
`$gt`	Greater than	`{"score": {"$gt": 90}}`
`$gte`	Greater than or equal	`{"score": {"$gte": 90}}`
`$lt`	Less than	`{"score": {"$lt": 50}}`
`$lte`	Less than or equal	`{"score": {"$lte": 50}}`
`$in`	In list	`{"tag": {"$in": ["ml", "ai"]}}`
`$nin`	Not in list	`{"tag": {"$nin": ["old"]}}`
`$and`	Logical AND	`{"$and": [{"year": 2023}, {"source": "notion"}]}`
`$or`	Logical OR	`{"$or": [{"year": 2023}, {"year": 2024}]}`

运算符	描述	示例
`$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}]}`

Complex Filter Examples

复杂过滤示例

bash

undefined

bash

undefined

Multiple conditions with implicit AND (both must be true)

多个条件，隐式AND（需同时满足）

--where '{"source": "notion", "year": 2023}'

Explicit AND

显式AND

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

OR condition

OR条件

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

Range condition (year between 2022 and 2024)

范围条件（年份在2022到2024之间）

--where '{"$and": [{"year": {"$gte": 2022}}, {"year": {"$lte": 2024}}]}'

Combined AND + OR

组合AND + OR

--where '{"$and": [{"year": 2023}, {"$or": [{"source": "notion"}, {"source": "obsidian"}]}]}'

undefined

--where '{"$and": [{"year": 2023}, {"$or": [{"source": "notion"}, {"source": "obsidian"}]}]}'

undefined

Export to CSV/Excel

导出为CSV/Excel

bash

undefined

bash

undefined

Export scalar search results to CSV

将标量搜索结果导出为CSV

python scripts/query_from_seekdb.py mobiles --where '{"Brand": "SAMSUNG"}' --output samsung.csv

Export hybrid search results to Excel

将混合搜索结果导出为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"

undefined

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

undefined

Supported Export Formats

支持的导出格式

Format	Extension	Description
CSV	`.csv`	Comma-separated values, UTF-8 encoded with BOM
Excel	`.xlsx`	Excel workbook format

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

Data Structure in seekdb

seekdb中的数据结构

seekdb stores data in two distinct locations:

Storage	Description	Filter Method	Example
Metadata	Structured key-value fields	`--where`	`{"source": "notion", "year": 2023}`
Document	Text content	`--query-text` (hybrid search)	Fulltext + Semantic search

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

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

Connection Configuration

连接配置

Set environment variables for server mode:

Variable	Description	Default
`SEEKDB_HOST`	Server host (if set, uses server mode)	-
`SEEKDB_PORT`	Server port	2881
`SEEKDB_DATABASE`	Database name	test
`SEEKDB_USER`	Username	root
`SEEKDB_PASSWORD`	Password	-

设置环境变量以使用服务器模式：

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