Introduction
Zenntraa Documentation
Zenntraa lets you query your financial database using plain English — no SQL, no code, no waiting. Just ask a question and get an exact answer very fast.
Instant on repeat queries
Zenntraa remembers answers it has given before and returns them instantly from cache — zero AI cost, zero database load.
Exact answers, not guesses
Unlike fuzzy AI search, Zenntraa runs real SQL queries against your database. The number you get is the number in your data.
Read-only & secure
Zenntraa can only read your data — never modify or delete it. All queries are validated before execution.
Plain English interface
No SQL knowledge required. Ask questions the way you'd ask a colleague — Zenntraa handles the technical translation.
Architecture
How It Works
Every time you submit a query, Zenntraa follows one of two paths depending on whether it has seen your question before.
You type a question in plain English
Zenntraa checks its memory (cache)
AI converts your question to SQL
SELECT revenue FROM financials WHERE quarter = 'Q1 2025'.SQL runs securely against your database
SELECT statements are permitted — your data is never at risk of modification.Answer is returned and stored
Setup
Connect Your Database
Before running queries, connect Zenntraa to your database. Navigate to Settings → Connect Database in your dashboard.
Open Settings
Enter your database credentials
Test the connection
Activate
If you have a CSV uploaded, you will need to remove it first before connecting a database. Only one data source can be active at a time.
Setup
Upload a CSV
Don't have a PostgreSQL database? You can upload a CSV file and start querying it straight away. No database setup needed.
Go to Settings in your dashboard and look for the Upload a CSV card.
Open Settings
Choose your file
.csv file from your computer. Maximum file size is 15 MB.Upload
Start querying
Only one CSV can be active at a time. Uploading a new file replaces the previous one.
What Zenntraa detects automatically
- Numbers including values formatted with commas like 1,200,000
- Dates in standard formats
- Text, IDs, and codes where leading zeros matter (so 07001 stays 07001, not 7001)
Setup
Data Sources
Zenntraa works with three data sources and only one is active at a time.
| Source | When it is used |
|---|---|
| PostgreSQL | When you have connected your own database under Settings |
| CSV | When you have uploaded a CSV file and no database is connected |
| Demo database | When neither is connected. Sample financial data to explore the product |
You can see your active source on the Query page. A chip in the top right shows whether you are on Demo, CSV, or your own database.
To switch: connect a PostgreSQL database to replace an active CSV, upload a new CSV to replace the current one, or remove your CSV to go back to the demo.
Getting Started
Your First Query
Once your database is connected, go to the Query page from the sidebar. Type your question in the input box and press Enter or click Ask.
Start simple to confirm everything is working:
You'll see the answer below the input box, along with two key indicators: whether the result came from Cache Hit or a fresh Cache Miss, and how fast the response came back.
Best Practices
Writing Good Queries
Zenntraa understands natural language, but the more specific your question, the more accurate and cache-friendly the answer.
Be specific with names and time periods
Use exact company names
Zenntraa queries your database directly, so company names must match what's stored. If a query returns no results, try the exact spelling as it appears in your data.
Specify time periods clearly
Use formats like Q1 2025, 2024, January 2025 rather than relative terms like "last quarter" — your database stores data at fixed dates, not relative ones.
Break complex questions into parts
Reference
Query Examples
Company information
Revenue & profitability
Comparative analysis
Financial KPIs
Dashboard Guide
Reading Your Results
Every query response shows four pieces of information alongside the answer:
| Indicator | What it means |
|---|---|
| Cache Hit | Answer was retrieved from memory — no AI cost, returned instantly. |
| Cache Miss | New question — AI was called, SQL was run, answer is now cached for future use. |
| Response time | How long the answer took. Cache hits come back near-instantly; first-time queries take a few seconds depending on complexity. |
| Query ID | Unique identifier for this specific query — useful if you need to report an issue. |
Your query history is available in the sidebar so you can revisit past answers without re-running them.
Performance
Cache & Speed
Zenntraa's cache is what makes it dramatically faster and cheaper than running AI queries every time.
Why your first query is slower
The first time you ask a question, Zenntraa calls the AI and queries your database. This typically takes a few seconds. Every subsequent time you ask the same question, it returns instantly from cache.
Why slightly different wording causes a miss
"List all companies" and "Show me all companies" are treated as different questions. For reports you run regularly, use the same wording each time to guarantee a cache hit.
Why cached answers don't last forever
Your database data changes — new companies get added, financial records get updated. Zenntraa's cache has a limited lifetime to ensure you always see fresh data rather than stale results.
Support
Troubleshooting
Query returns no results
This usually means the data doesn't exist in your database for the specified parameters. Try asking Zenntraa what data is available:
Query returns an error about a column not existing
Zenntraa occasionally generates SQL using a column name that doesn't exactly match your schema. It will automatically retry with the correct schema. If errors persist, try rephrasing your question more specifically.
Response is slow
First-time queries (Cache Miss) can take 1–7 seconds while the AI generates and runs the SQL. This is normal. The same query will be near-instant on all future runs. If every query is slow, check your database connection under Settings.
"Service unavailable" or error 503
The system may be temporarily overloaded. Wait 30 seconds and try again. If the issue persists, contact support via email with your Query ID.
Database won't connect
Double-check that your host, port, database name, username, and password are all correct. Ensure your database server allows inbound connections from Zenntraa's IP. Use the Test Connection button in Settings to diagnose.
Getting a 429 rate limit error
You've sent more than 60 queries in a minute. Wait a moment and resume. If you need higher limits, contact us to discuss your plan.
My CSV uploaded but the numbers look wrong
If your CSV had numbers formatted with commas like 1,200,000, Zenntraa removes the commas before storing so calculations work correctly. If results still look off, check that the column contains only numeric values with no mixed text.
My CSV data is gone
CSV data is kept between sessions but can be lost if the server restarts. If this happens, go to Settings and upload the file again. Your query history will not be affected.
I want to query a different CSV
Go to Settings, remove the current CSV, then upload the new one. Only one CSV can be active at a time.
The database connection form is greyed out
This happens when a CSV is already uploaded. Remove the CSV first, then you can connect a database.
The CSV upload card is greyed out
This happens when a database is already connected. Disconnect the database first, then you can upload a CSV.
FAQ
Frequently Asked Questions
Do I need to know SQL to use Zenntraa?
No. Zenntraa converts your plain English questions into SQL automatically. You never write or see any SQL unless you specifically ask for it.
Can Zenntraa modify or delete my data?
No. Zenntraa is strictly read-only. Only SELECT queries are permitted — it cannot insert, update, or delete any records in your database.
Why does the same question sometimes get a Cache Miss?
Zenntraa caches by exact question text. Minor wording differences — "List all companies" vs "Show me all companies" — are treated as separate questions. Use consistent phrasing for queries you run regularly to always hit the cache.
How long does Zenntraa keep cached answers?
Cache entries expire automatically to prevent stale data. Since financial databases update regularly, Zenntraa refreshes its cache on a short cycle to ensure you always see accurate results.
What databases does Zenntraa support?
Zenntraa supports PostgreSQL databases and CSV file uploads. If you are on the demo, it uses built-in sample financial data. You can set up either under Settings, but not both at the same time.
Can I have both a CSV and a PostgreSQL database at the same time?
No. Zenntraa uses one data source at a time. Remove the current one first and then set up the other.
Will my CSV still be there when I come back?
Usually yes. Your CSV stays between sessions. In rare cases it may be cleared if there is a server restart, and you would just need to upload the file again from Settings.
What is the CSV file size limit?
15 MB. If your file is larger, consider splitting it or using a PostgreSQL database instead.
What's a good cache hit rate?
Target 80% or higher. You can check your current cache hit rate on the Metrics page. A low hit rate typically means queries are being phrased differently each time — try standardizing your question wording.
What if Zenntraa gives a wrong answer?
Zenntraa retrieves exact values from your database — it doesn't guess or estimate. If an answer looks wrong, verify the underlying data in your database first. If the data is correct but the answer is still wrong, contact support with the Query ID shown in the response.
How do I get support on the Free plan?
Free plan users can access all documentation pages. For additional help, use the email support link in the dashboard footer. Pro and Enterprise plans include priority email and live support.