Know your data before you query it.

The execution layer is solved - DuckDB runs SQL brilliantly. The unsolved problem is that people don't understand their data: which tables exist, how they connect, which join is correct. QueryPad is an AI CLI that answers those questions first, then writes the SQL.

★ Star on GitHub

querypad - zsh

$ querypad inspect ./data
Tables:        3
Relationships: 2
  payments.user_id ↳ users.id  (100%, many-to-one)
  events.user_id   ↳ users.id  (100%, many-to-one)
Wrote artifacts to ./data/.datactx

$ querypad ask "total payment amount by user plan" ./data
-- SQL
SELECT u.plan, COUNT(*) AS payment_count, SUM(p.amount) AS total
FROM payments p JOIN users u ON p.user_id = u.id GROUP BY u.plan

plan  payment_count   total
----  -------------  ------
paid              8  285.74

Insight: All payments come from paid-plan users.

Understanding before SQL

Point it at a folder of CSV / Parquet / JSON files - or attach a live database - and it builds a machine-readable picture of your data that both its own agent and yours can trust.

inspectrelationship discovery: Profiles every file and infers foreign-key joins with confidence scores and cardinality, from value overlap and structure - not guesses. Your accept/reject verdicts are honored on every re-run.
semantic modelthe AST for data: Rolls relationships into named business entities with dimensions, measures, and synonyms. A deterministic metric compiler emits join-guarded SQL and refuses groupings that would silently double-count.
askagentic + self-verifying: An agent explores the schema with read-only tools, runs SQL, self-corrects on errors, and re-checks its own answer - projection, ranking, safety - before replying. Scored continuously against a committed trap-dataset eval.
mcpbring your own agent: The same read-only toolkit, served over MCP. Claude Code or Cursor connects with one command and analyzes your data grounded in the inferred relationships - no API keys handed over, nothing leaves your machine.
--dblive databases, read-only: Attaches Postgres, MySQL, or SQLite through DuckDB - engine-enforced READ_ONLY, tables exposed as pushdown views, credentials redacted from every log line and artifact.

Install

Pre-release - runs from source today. Node ≥ 20.

$ git clone https://github.com/kiyeonjeon21/querypad && cd querypad
$ npm install && npm run build && npm link
$ querypad inspect ./your-data

npm package and native desktop app are on the roadmap.