query

Tổng quan về skill query

query skill làm gì

query skill giúp bạn chạy các truy vấn DuckDB trên một cơ sở dữ liệu làm việc đã gắn sẵn hoặc trên các tệp mà bạn chỉ định trực tiếp. Skill này được thiết kế cho những ai muốn đi từ câu hỏi đến kết quả nhanh nhất có thể: SQL tùy biến, câu hỏi dữ liệu bằng ngôn ngữ tự nhiên, hoặc phân tích tệp đơn giản với DuckDB Friendly SQL.

Phù hợp nhất với ai

Hãy dùng query skill cho Data Analysis khi bạn đã có dữ liệu trong DuckDB, một file trạng thái dự án, hoặc một tệp cục bộ như CSV/Parquet và muốn có câu trả lời ngay mà không cần dựng một pipeline đầy đủ. Skill này đặc biệt hữu ích cho analyst, engineer, và AI agent cần kiểm tra dữ liệu nhanh, lặp lại nhiều vòng.

Vì sao skill này khác biệt

Điểm khác biệt cốt lõi của query là khả năng tự chọn chế độ hoạt động. Nó có thể chạy ở session mode khi đã có trạng thái DuckDB trước đó, hoặc ở ad-hoc mode khi đầu vào tham chiếu tới tệp hoặc khi không có state khả dụng. Điều này giảm đáng kể phần đoán mò và khiến query skill hữu ích cả trong workflow thường trực lẫn tác vụ một lần.

Cách dùng query skill

Cài đặt và cách gọi cơ bản

Cài query skill bằng npx skills add duckdb/duckdb-skills --skill query. Sau đó gọi nó bằng SQL hoặc một câu hỏi, ví dụ: query "show daily revenue by country" hoặc query "select count(*) from 'events.csv'". Mẫu query usage hoạt động tốt nhất khi yêu cầu đủ cụ thể để biến thành một truy vấn rõ ràng.

Skill chọn session hay ad-hoc mode như thế nào

query skill trước hết sẽ kiểm tra xem có DuckDB state file hiện có trong .duckdb-skills/state.sql hoặc ~/.duckdb-skills/<project-id>/state.sql hay không. Nếu tìm thấy và các cơ sở dữ liệu đã gắn vẫn hoạt động, nó sẽ dùng session mode. Nếu bạn truyền --file, tham chiếu đường dẫn tệp, hoặc không có state dùng được, nó sẽ chuyển sang ad-hoc mode và truy vấn trực tiếp các tệp, hoặc :memory: khi cần. Đây là phần quan trọng nhất của query guide, vì đầu vào của bạn nên khớp với đúng chế độ bạn thực sự muốn dùng.

Nên đọc gì trước trong repo

Hãy bắt đầu với SKILL.md, vì file này chứa luồng thực thi, quy tắc về mode, và hành vi fallback. Khi chỉ đánh giá để quyết định cài đặt, như vậy thường là đủ. Nếu bạn muốn điều chỉnh skill cho workflow riêng của mình, hãy xem thêm các file được nhắc tới trong cây thư mục của repo, đặc biệt là những phần định nghĩa cách xử lý state hoặc ràng buộc của prompt. Trong repo này không có thêm rules/, resources/, hay script hỗ trợ nào khác để học thêm.

Viết prompt tốt hơn để có truy vấn tốt hơn

Hãy cung cấp cho skill lượng ngữ cảnh tối thiểu nhưng đủ để dựng đúng truy vấn: tệp hoặc bảng đích, metric, grain, bộ lọc, và khoảng thời gian. Đầu vào mạnh sẽ giống như query "For orders.csv, show revenue by month for 2024 and exclude refunds"; đầu vào yếu sẽ giống như query "analyze the sales data". Câu đầu cho skill biết nên dùng truy cập theo tệp hay không, cần tổng hợp gì, và những trường hợp biên nào quan trọng.

Câu hỏi thường gặp về query skill

query skill chỉ dành cho người giỏi SQL thôi à?

Không. query skill chấp nhận cả SQL thô lẫn câu hỏi bằng ngôn ngữ tự nhiên, nên người mới vẫn có thể dùng để phân tích đơn giản. SQL vẫn rất hữu ích khi bạn cần join, lọc, hoặc quy tắc tổng hợp chính xác.

Khi nào không nên dùng query skill?

Đừng dùng nó nếu tác vụ của bạn cần logic biến đổi nhiều bước vốn nên nằm trong notebook, ETL job, hoặc code ứng dụng. Skill này được tối ưu cho việc đặt câu hỏi và nhận câu trả lời về dữ liệu, chứ không phải để xây dựng một data product hoàn chỉnh.

Nó khác gì so với một prompt chung chung?

Một prompt chung chung có thể tạo ra một truy vấn trông hợp lý, nhưng query skill bổ sung các quy tắc vận hành: kiểm tra DuckDB state, chọn session vs ad-hoc mode, xác minh DuckDB có sẵn, và fallback an toàn khi việc gắn attachment thất bại. Điều đó khiến nó đáng tin cậy hơn cho đánh giá lúc cài đặt và cho query usage lặp lại.

Có phù hợp cho tệp cục bộ và phân tích local không?

Có. Nếu bạn muốn query for Data Analysis trên CSV, Parquet, hoặc các tệp khác mà DuckDB đọc được, skill này là lựa chọn rất phù hợp vì nó được thiết kế để truy vấn trực tiếp các tệp khi session state không có sẵn hoặc không phù hợp.

Cách cải thiện query skill

Chỉ rõ cấu trúc dữ liệu thật cụ thể

Những cải thiện hiệu quả nhất đến từ việc gọi tên nguồn dữ liệu và hình dạng đầu ra. Hãy nêu tên bảng, tên file, các cột bạn quan tâm, và mức độ nhóm dữ liệu bạn muốn nhận lại. Ví dụ: query "from sessions.parquet, group by user_id and return avg session length for paid users only" sẽ cho skill đủ cấu trúc để tránh kết quả quá rộng hoặc mơ hồ.

Xóa mơ hồ trước lần chạy đầu tiên

Một lỗi rất thường gặp là yêu cầu “insights” mà không nói rõ cần đếm, so sánh, hay lọc theo cái gì. Nếu bạn biết metric, cửa sổ thời gian, hoặc quy tắc phân khúc, hãy nói ngay từ đầu. Cách này giảm qua lại và làm cho câu trả lời đầu tiên hữu ích hơn.

Kiểm tra sớm các ràng buộc theo mode

Nếu bạn kỳ vọng session mode, hãy নিশ্চিত bảo project state đã có và các database được gắn vào vẫn mở được. Nếu bạn kỳ vọng file mode, hãy nhắc trực tiếp tệp đó trong prompt hoặc truyền --file. Điều này quan trọng vì query skill hoạt động khác nhau tùy vào việc nó có thể tái sử dụng state hiện có hay phải xử lý ad hoc.

Lặp lại bằng cách thu hẹp mục tiêu truy vấn

Sau kết quả đầu tiên, hãy cải thiện prompt tiếp theo bằng cách thêm từng ràng buộc một: khoảng thời gian hẹp hơn, join key tốt hơn, mức grouping khác, hoặc một điều kiện loại trừ bắt buộc. Cách này giữ cho query skill tiến dần tới kết quả đủ để ra quyết định thay vì chỉ là một bản tóm tắt chung chung.