Natural Language Queries in DenchClaw: Ask Your CRM Anything

DenchClaw's natural language query system lets you ask your CRM questions in plain English and get instant, SQL-powered results. No filter dropdowns. No report builder. No waiting for an analyst. Type what you want to know, and DenchClaw translates it into a DuckDB query against your local database and returns the results — as a filtered view, a chart, or a plain text answer.

This is one of DenchClaw's most-used features. Here's exactly how it works and what you can do with it.

How Natural Language Queries Work#

When you type a question to DenchClaw, the AI:

1. Reads your workspace schema — it knows your objects, fields, and data types
2. Translates to SQL — generates a DuckDB query against your PIVOT views (e.g., v_people, v_companies)
3. Executes against local data — runs the query against your local DuckDB file
4. Returns structured results — as a table view, chart, or text summary depending on the query type

The AI has full context about your schema because it helps you build it. When you created your "people" object with a "Status" field containing values like "Lead," "Active," and "Churned," the AI remembered all of that. When you ask "show me active leads," it knows exactly what that means.

Anatomy of a Natural Language Query#

Here's what happens when you ask: "Show me all companies in San Francisco with more than 10 employees who haven't been contacted in 30 days."

DenchClaw generates something like:

SELECT *
FROM v_companies
WHERE "City" = 'San Francisco'
  AND "Employee Count" > 10
  AND ("Last Contacted" < CURRENT_DATE - INTERVAL '30 days'
       OR "Last Contacted" IS NULL)
ORDER BY "Last Contacted" ASC NULLS FIRST

Results appear as a filtered table view in your CRM. You can then:

• Save this as a named view ("SF Stale Accounts")
• Switch to kanban, gallery, or list view
• Click into any record to take action
• Ask DenchClaw to draft follow-up emails for the results

What You Can Ask#

Filtering and Finding#

Simple queries:

• "Show me all leads"
• "Find Sarah Chen"
• "Show me all deals over $50K"

Complex filters:

• "Show me all active clients in New York who haven't had a meeting in 60 days"
• "List all deals in the negotiation stage that have been there for more than 2 weeks"
• "Show me contacts without an email address"

Date-based:

• "Which contacts were added this week?"
• "Show me deals closing this month"
• "What tasks are overdue?"

Tag-based:

• "Show me all companies tagged as Enterprise"
• "List all people with the tag 'Warm Lead'"

Analytics and Aggregation#

Count queries:

• "How many leads do I have?"
• "How many deals are in each pipeline stage?"

Sum and average:

• "What's the total value of my open deals?"
• "What's the average deal size by stage?"

Ranking:

• "Who are my top 5 clients by deal value?"
• "Which sales rep has the most closed deals this quarter?"

Trends:

• "How many new leads came in each month this year?"
• "Show me deal close rate by month for the past 6 months"

Creating and Updating Records#

Create:

• "Add a new lead: John Smith, john@example.com, at Acme Corp"
• "Create a new deal for Apex Software, $25,000, in the proposal stage"

Update:

• "Mark the deal with Stripe as Closed Won"
• "Change Sarah Chen's status to Active Client"
• "Set the next follow-up for TechCorp to April 15"

Bulk update:

• "Move all leads in San Francisco to the 'SF Bay Area' territory tag"

Saving Query Results as Views#

Any query result can be saved as a named view. When you ask "show me all deals closing this month" and get results, say:

"Save this as a view called 'Closing This Month'"

DenchClaw writes the filter configuration to your .object.yaml file. The view now appears in your sidebar as a permanent, live-updating filter. Next time you want this view, click it — the query re-runs against current data.

This is how DenchClaw's natural language interface becomes a persistent productivity tool, not just a one-time query engine.

Chart Generation from Queries#

When your query returns aggregated data, DenchClaw can visualize it:

"Show me deal count by stage as a bar chart"

DenchClaw generates a structured chart block that renders as an interactive bar chart in the UI. Supported chart types: bar, line, area, pie, donut, funnel, scatter.

Charts are saved as .report.json files in your workspace and appear in your sidebar as live dashboards that re-execute their queries when viewed.

Natural Language with Context#

DenchClaw remembers the context of your conversation. Follow-up queries work:

• "Show me all leads"
• "Filter to only those in California" (refines the previous result)
• "Sort by date added, newest first" (adds sort)
• "Save this as a view" (saves the combined filter)

You don't have to re-state everything from scratch for every refinement.

Behind the Scenes: PIVOT Views#

DenchClaw's database uses an EAV (Entity-Attribute-Value) schema internally, but natural language queries work against automatically-generated PIVOT views that look like flat tables:

-- v_people pivot view
SELECT
  e.id,
  MAX(CASE WHEN f.name = 'Full Name' THEN ef.value END) AS "Full Name",
  MAX(CASE WHEN f.name = 'Email' THEN ef.value END) AS "Email",
  MAX(CASE WHEN f.name = 'Status' THEN ef.value END) AS "Status",
  MAX(CASE WHEN f.name = 'Company' THEN ef.value END) AS "Company"
FROM entries e
JOIN entry_fields ef ON e.id = ef.entry_id
JOIN fields f ON ef.field_id = f.id
WHERE e.object_id = (SELECT id FROM objects WHERE name = 'people')
GROUP BY e.id

The AI queries these pivot views, not the raw EAV tables. This means queries run fast and results are immediately readable.

Exploring Your Own Data#

One underused aspect of natural language queries: exploration. Ask DenchClaw questions you don't know the answer to about your own data:

• "Which of my contacts work at companies with over 100 employees?"
• "How many contacts do I have per country?"
• "What's the most common company size among my leads?"
• "Which tags do I use most frequently?"

DenchClaw becomes a data analyst working on your personal CRM, surfacing insights you'd never find by scrolling through a spreadsheet.

Frequently Asked Questions#

Does DenchClaw send my data to an AI service when I query it?#

The natural language translation (converting your question to SQL) requires an API call to the configured AI model. The AI sees your schema (field names and object names) and your query text, but not your full database contents. The actual data never leaves your machine — only the schema metadata and query text are sent to generate the SQL. You can use local models to keep everything fully private.

Can I run raw SQL queries if I need them?#

Yes. DenchClaw gives you direct access to the underlying DuckDB file. You can query it with any DuckDB client, the duckdb CLI, or even Python's duckdb library. The PIVOT views are auto-generated and available for direct SQL queries too.

How accurate are the natural language translations?#

For clear, specific queries, accuracy is very high. The AI knows your exact field names and object names, so "show me all leads" maps precisely to WHERE Status = 'Lead' in your people view. For ambiguous queries or fields with unusual naming, the AI may ask a clarifying question or generate a slightly different query than intended. Review the results and correct by refining your query.

Can I query across multiple objects in one question?#

Yes. You can ask cross-object queries: "Show me all deals along with the company name and primary contact for each." DenchClaw joins the relevant PIVOT views to return a unified result. The AI handles the join logic.

What happens if I ask for something my CRM doesn't track?#

DenchClaw will tell you that the field or data doesn't exist and suggest how to create it. If you ask "show me all clients by annual revenue" and there's no revenue field, the AI will say: "I don't see a revenue field on your clients object. Want me to add one?"

Ready to try DenchClaw? Install in one command: npx denchclaw. Full setup guide →