I asked Claude "how many active customers do we have?" three times and got 390, 190 and 190. The real answer was 88.
Claude can answer plain-English questions straight from your database. The risky part is not the SQL, it's the word "active". A one-page definitions file fixed it in every run. Here's the test, the file, and the numbers.
3 of 5 answers right, then 5 of 5 with a one-page file
Level: Intermediate. About 20 minutes. Needs SQLite (already on most Macs) and a Claude Code login. The same idea works with any database.
"How many active customers do we have?" Anyone in a company can ask that, and nobody agrees on the answer. Does "active" mean they signed up? Paid at least once? Paid recently? Is a test account a customer?
Anthropic's write-up of how it runs self-service analytics with Claude makes a point I found useful: most wrong answers don't come from bad SQL. They come from mapping a business word to the wrong data. So I tested exactly that.
The setup
I built a small shop database with 400 customers and 493 orders. Two tables, no documentation:
I planted the traps real companies have. Ten customers are test accounts. Orders can be paid, refunded, cancelled or pending. And I decided what the business means by each term, then computed the true answers myself, separately, in a script.
I asked five questions, treating today as 1 November 2026:
- How many active customers do we have? 2) What was our revenue in October 2026? 3) How many new customers did we get in October 2026? 4) What was the average order value in October 2026? 5) What share of our customers are repeat customers?
Claude was allowed to run read-only SQLite queries and nothing else.
Setup B: a one-page definitions file
For half the runs I added a CLAUDE.md file to the folder. Claude Code reads that file at the start of every session. Mine is seven lines of plain English:
Notice what's in it: what counts as revenue, what "active" means with a number in it (a paid order in the last 90 days), what "new" means (first paid order, not signup date), and a rule for test accounts. Every line settles an argument somebody would otherwise have.
The results
Three runs with no file, three runs with it:
With the file, Claude got all five right, every time. Without it, it got three of five right, every time, and the two misses are the interesting ones.
- Active customers. The true answer is 88. Without the file Claude answered 390 once and 190 twice. In the first run it counted every non-test customer. In the other two, it counted anyone with a paid order ever. Different runs, different definitions, same confident table.
- New customers. The true answer is 21. Claude answered 30 all three times, because it counted signups in October, not first purchases.
What I liked: Claude explained its assumption in every run. "Active customer = at least one paid order ever" was written right there in the answer. It didn't hide anything. But the person asking would see "190" in a summary and move on, and the assumption was one sentence long.
What it got right with no help
Revenue and average order value were correct in all six runs. Claude assumed that revenue means paid orders only, which is the sensible default. Some definitions need telling, and some it gets right on its own. The point of the file is to tell it the ones that aren't obvious.
The test-account rule made almost no difference here: only one paid October order came from a test account. I'd still keep the rule in the file, since it costs nothing and real data will be messier.
Make it work for you
- Write down your definitions before anyone asks questions. Revenue, active, new, churned. Add the number (90 days, not "recently").
- Put them where Claude reads them automatically. In Claude Code, that's
CLAUDE.md. In the claude.ai apps, a project's instructions do the same job. - Make the time rule explicit. I told it today's date, because "last 90 days" means nothing without one.
- Keep the access read-only. I allowed only
sqlite3 -readonly. Anthropic's write-up goes much further, with review steps and sign-off for anything going to leadership. - Spot-check one number yourself. The 390 versus 88 gap is not subtle once you look.
What this doesn't tell you
- One small invented database, six runs, one model on one day. A real warehouse has thousands of tables, which is the harder problem Anthropic's write-up is about.
- I wrote the definitions and the answers myself, so the file matched my truth by design. A file full of contested definitions would not make agreement appear.
- I tested counts and money. I didn't test trends, joins across many tables, or questions that really are ambiguous.
- Costs were small: Claude Code reported 14 to 25 cents per run. I'm on a Pro plan, so I wasn't billed per run.
Sources
- https://claude.com/resources/articles/how-anthropic-enables-self-service-data-analytics-with-claude
Editorial note: We ran the steps in this guide ourselves and the screenshots come from those runs. Your results may differ with your plan, model or settings, so check anything important. Cover illustrations are AI-generated. Discovia is independent and not affiliated with Anthropic.
New guides and tools
Hands-on Claude guides, straight to your inbox
Step-by-step walkthroughs of what's new in Claude and Anthropic's tools, with real screenshots and honest results, including what didn't work. No hype, no jargon, no noise.
By subscribing, you agree to receive newsletter and marketing emails, and accept our Terms of Use and Privacy Policy. You can unsubscribe anytime.
Workflow Clinic
Real-world use cases for Claude, tried end to end with what worked and what did not.
More Use Cases guides →