duckdb-docs

DuckDB または DuckLake の関連ドキュメントをユーザーが見つけられるよう支援します。

クエリ：$@

以下の手順を順番に実行してください。

手順 1 — DuckDB がインストールされていることを確認する

command -v duckdb

見つからない場合は、/duckdb-skills:install-duckdb に委任してから続行してください。

手順 2 — 必要な拡張機能がインストールされていることを確認する

duckdb :memory: -c "INSTALL httpfs; INSTALL fts;"

これに失敗した場合は、エラーを報告して停止してください。

手順 3 — データソースを選択し、検索語を抽出する

クエリは次のとおりです：$@

データソースの選択

使用できる検索インデックスは 2 つあります。

インデックス	リモート URL	ローカルキャッシュファイル名	バージョン	使用する場合
DuckDB のドキュメントとブログ	https://duckdb.org/data/docs-search.duckdb	duckdb-docs.duckdb	lts、current、blog	デフォルト — DuckDB に関するすべての質問
DuckLake のドキュメント	https://ducklake.select/data/docs-search.duckdb	ducklake-docs.duckdb	stable、preview	クエリに DuckLake、カタログ、または DuckLake 固有の機能が含まれる場合

両方のインデックスで同じスキーマを使用します。

列	型	説明
chunk_id	VARCHAR (PK)	例：stable/sql/functions/numeric#absx
page_title	VARCHAR	フロントマターにあるページタイトル
section	VARCHAR	セクションの見出し（ページの導入部では null）
breadcrumb	VARCHAR	例：SQL > Functions > Numeric
url	VARCHAR	アンカーを含む URL パス
version	VARCHAR	上の表を参照
text	TEXT	チャンクの Markdown 全文

デフォルトでは、DuckDB のドキュメントを検索し、version = 'lts' で絞り込みます。次の場合は別のバージョンを使用してください。

• ユーザーが current／nightly の機能について明示的に尋ねている場合 → version = 'current'
• ユーザーがブログ記事について尋ねている、または背景や動機を知りたがっている場合 → version = 'blog'
• ユーザーが DuckLake について尋ねている場合 → DuckLake インデックスを version = 'stable' で検索
• 判断に迷う場合は、すべてのバージョンを検索するため、バージョンフィルターを省略してください。

検索語

入力が自然言語の質問（例：「最も頻度の高い値を見つけるにはどうすればよいですか」）の場合は、重要な技術用語（名詞、関数名、SQL キーワード）を抽出して、簡潔な BM25 クエリ文字列を作成してください。「how」、「do」、「I」、「the」などのストップワードは除外します。

入力がすでに関数名または技術用語（例：arg_max、GROUP BY ALL）の場合は、そのまま使用してください。

抽出した語句を、次の手順の SEARCH_QUERY として使用してください。

手順 4 — ローカルキャッシュが最新であることを確認する

キャッシュは $HOME/.duckdb/docs/CACHE_FILENAME にあります（CACHE_FILENAME は手順 3 に応じて duckdb-docs.duckdb または ducklake-docs.duckdb です）。

まず、ディレクトリが存在することを確認してください。

mkdir -p "$HOME/.duckdb/docs"

次に、キャッシュファイルが存在し、最新（2 日以内）かどうかを確認してください。

CACHE_FILE="$HOME/.duckdb/docs/CACHE_FILENAME"
if [ -f "$CACHE_FILE" ]; then
    MTIME=$(stat -f %m "$CACHE_FILE" 2>/dev/null || stat -c %Y "$CACHE_FILE")
    CACHE_AGE_DAYS=$(( ( $(date +%s) - MTIME ) / 86400 ))
else
    CACHE_AGE_DAYS=999
fi
echo "Cache age: $CACHE_AGE_DAYS days"

CACHE_AGE_DAYS が 2 以下の場合 → 手順 5 に進みます。

それ以外の場合（古い、またはファイルが存在しない）→ インデックスを取得します。

duckdb -c "
LOAD httpfs;
LOAD fts;
ATTACH 'REMOTE_URL' AS remote (READ_ONLY);
ATTACH '$HOME/.duckdb/docs/CACHE_FILENAME.tmp' AS tmp;
COPY FROM DATABASE remote TO tmp;
" && mv "$HOME/.duckdb/docs/CACHE_FILENAME.tmp" "$HOME/.duckdb/docs/CACHE_FILENAME"

手順 3 に従って REMOTE_URL と CACHE_FILENAME を置き換えてください。取得に失敗した場合（ネットワークエラー）は、エラーを報告して停止してください。

手順 5 — ドキュメントを検索する

duckdb "$HOME/.duckdb/docs/CACHE_FILENAME" -readonly -json -c "
LOAD fts;
SELECT
    chunk_id, page_title, section, breadcrumb, url, version, text,
    fts_main_docs_chunks.match_bm25(chunk_id, 'SEARCH_QUERY') AS score
FROM docs_chunks
WHERE score IS NOT NULL
  AND version = 'VERSION'
ORDER BY score DESC
LIMIT 8;
"

手順 3 に従って CACHE_FILENAME、SEARCH_QUERY、VERSION を置き換えてください。すべてのバージョンを検索する場合は、AND version = 'VERSION' の行を削除してください。

ユーザーの質問への回答に DuckDB のドキュメントとブログの両方が役立つ可能性がある場合は、2 つのクエリを実行する（1 つは version = 'stable'、もう 1 つは version = 'blog'）か、バージョンフィルターを省略してください。

ステップ 6 — エラーに対処する

• 拡張機能がインストールされていない（httpfs または fts が見つからない）：duckdb :memory: -c "INSTALL httpfs; INSTALL fts;" を実行して、再試行します。
• ATTACH が失敗する／ネットワークに接続できない：ドキュメントのインデックスを利用できないことをユーザーに伝え、インターネット接続を確認するよう案内します。DuckDB のインデックスは https://duckdb.org/data/docs-search.duckdb に、DuckLake のインデックスは https://ducklake.select/data/docs-search.duckdb にホストされています。
• 結果がない（すべてのスコアが NULL、または結果セットが空）：クエリを広げてみます。最も具体性の低い語を削除するか、クエリを 1 語にして再試行し、その後ステップ 5 を再実行します。それでも結果がない場合は、一致するドキュメントが見つからなかったことをユーザーに伝え、https://duckdb.org/docs または https://ducklake.select/docs に直接アクセスするよう案内します。

ステップ 7 — 結果を提示する

返された各結果チャンクを（スコアの降順で）次の形式で表示します。

### {section} — {page_title}
{url}

{text}

---

すべてのチャンクを提示した後、取得したドキュメントに基づいて、ユーザーの元の質問（$@）への簡潔な回答をまとめます。チャンクが質問に直接答えている場合は、出典を示す前に回答を提示します。