querying-from-seekdb

seekdb からデータをクエリしてエクスポートする

スカラー検索、ハイブリッド検索（全文検索＋セマンティック検索）、CSV／Excel ファイルへのエクスポートに対応し、seekdb ベクトルデータベースのデータをクエリします。

パスの規則

注：このドキュメント内のすべてのパス（例：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

2 種類の検索モード

モード 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（Reciprocal Rank Fusion）を使って順位付けされます

リクエストの例：

• 「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}}'
「ブランドが Samsung または Apple の」	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	{"$and": [{"year": 2023}, {"source": "notion"}]}
$or	論理 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 はデータを 2 つの異なる場所に保存します。

ストレージ	説明	フィルター方法	例
メタデータ	構造化されたキーと値のフィールド	--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
• フィルター演算子