query

query 技能概覽

query 技能能做什麼

query 技能可以讓你對已掛載的工作資料庫，或你直接指定的檔案執行 DuckDB 查詢。它特別適合想要最快從問題走到結果的人：臨時 SQL、用自然語言提資料問題，或用 DuckDB Friendly SQL 做簡單的檔案分析。

最適合哪些人使用

如果你已經有 DuckDB 裡的資料、專案狀態檔，或像 CSV/Parquet 這類本機檔案，而且想在不搭完整資料流程的情況下立刻得到答案，那 query 技能很適合 Data Analysis。它特別適合分析師、工程師，以及需要快速、反覆檢視資料的 AI agents。

這個技能有什麼不同

query 的關鍵差異在於它的模式選擇。當先前有 DuckDB 狀態時，它可以用 session mode；當輸入引用檔案，或沒有可用狀態時，它也能切換成 ad-hoc mode。這樣可以減少猜測，讓 query skill 同時適用於長期保存的工作流程與一次性的工作流程。

如何使用 query 技能

安裝與基本呼叫方式

用 npx skills add duckdb/duckdb-skills --skill query 安裝 query 技能。接著你可以用 SQL 或問題來呼叫它，例如：query "show daily revenue by country" 或 query "select count(*) from 'events.csv'"。query usage 這種用法最適合明確、能收斂成單一查詢的需求。

技能如何選擇 session 或 ad-hoc 模式

query 技能會先檢查 .duckdb-skills/state.sql 或 ~/.duckdb-skills/<project-id>/state.sql 是否已有現成的 DuckDB 狀態檔。如果找得到，而且已掛載的資料庫仍可正常使用，就會採用 session mode。如果你傳入 --file、在提示中引用檔案路徑，或根本沒有可用狀態，它就會切換成 ad-hoc mode，直接查詢檔案，必要時則使用 :memory:。這是 query guide 裡最重要的一環，因為你的輸入應該要跟你真正想要的模式一致。

先讀倉庫裡的哪些內容

先從 SKILL.md 看起，因為裡面包含執行流程、模式規則與 fallback 行為。若你是要做安裝決策，通常看到這裡就已經夠了。若你要把這個技能調整成自己的工作流程，也可以再看倉庫樹狀結構中有提到的其他檔案，特別是任何定義狀態處理或 prompt 限制的內容。這個 repo 裡沒有額外的 rules/、resources/ 或 helper scripts 需要額外學習。

寫出更好的提示，才能得到更好的查詢

給技能最少但足夠的上下文，讓它能建立正確的查詢：目標檔案或資料表、指標、粒度、篩選條件與時間範圍。好的輸入像 query "For orders.csv, show revenue by month for 2024 and exclude refunds"；不好的輸入像 query "analyze the sales data"。前者會清楚告訴技能要不要用檔案存取、要彙總什麼，以及哪些邊界情況很重要。

query 技能 FAQ

query 技能只有 SQL 專家才能用嗎？

不是。query 技能可以接受原始 SQL，也可以接受自然語言問題，所以初學者也能拿來做簡單分析。不過，當你需要精準的 join、filter 或 aggregation 規則時，SQL 還是很有幫助。

什麼情況下不該用 query 技能？

如果你的工作需要多步驟轉換邏輯，應該放在 notebook、ETL job 或應用程式碼裡，那就不適合用它。它的強項是提問與回答資料問題，不是打造完整的資料產品。

它和一般提示詞相比有什麼不同？

一般提示詞也許可以產生看起來合理的查詢，但 query 技能加入了操作層規則：它會檢查 DuckDB 狀態、選擇 session mode 或 ad-hoc mode、確認 DuckDB 可用，並在掛載失敗時安全地 fallback。這讓它在安裝時評估，以及重複使用 query usage 時，都更可靠。

它適合檔案與本機分析嗎？

適合。如果你想用 query for Data Analysis 來分析本機 CSV、Parquet，或其他 DuckDB 可讀取的檔案，這個技能會是很好的選擇，因為它在沒有 session state，或 session state 不適合使用時，就是為了直接查詢檔案而設計的。

如何改進 query 技能

提供精確的資料形狀

最有效的改進方式，是直接說明來源與輸出形狀。把資料表名稱、檔案名稱、你在意的欄位，以及你希望回傳的粒度都寫清楚。例如：query "from sessions.parquet, group by user_id and return avg session length for paid users only"，就能提供足夠結構，避免結果太廣或太模糊。

在第一次執行前先消除歧義

常見失敗模式是只說要「insights」，卻沒講清楚要計算、比較或篩選什麼。如果你知道指標、日期區間或分群規則，就先寫進去。這樣可以減少來回修正，讓第一次結果更有用。

及早檢查模式相關限制

如果你預期會用 session mode，先確認專案狀態檔存在，而且掛載的資料庫仍然能開啟。如果你預期要用檔案模式，就在提示中直接引用檔案，或傳入 --file。這很重要，因為 query 技能在能否重用既有狀態、或必須臨時處理時，行為是不同的。

透過收斂查詢目標逐步迭代

拿到第一版結果後，下一輪提示可以一次只加上一個限制：更窄的時間範圍、更好的 join key、不同的分組層級，或必須排除的項目。這樣可以讓 query skill 持續往可直接做決策的結果前進，而不是停留在模糊摘要。