Introduction
Zentra Documentation
Zentra lets you query your financial database using plain English — no SQL, no code, no waiting. Just ask a question and get an exact answer in milliseconds.
Sub-50ms on repeat queries
Zentra 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, Zentra runs real SQL queries against your database. The number you get is the number in your data.
Read-only & secure
Zentra 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 — Zentra handles the technical translation.
Architecture
How It Works
Every time you submit a query, Zentra follows one of two paths depending on whether it has seen your question before.
You type a question in plain English
Zentra 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 Zentra to your database. Navigate to Settings → Connect Database in your dashboard.
Open Settings
Enter your database credentials
Test the connection
Activate
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 the response latency in milliseconds.
Best Practices
Writing Good Queries
Zentra 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
Zentra 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 in under 50ms. |
| Cache Miss | New question — AI was called, SQL was run, answer is now cached for future use. |
| Latency (ms) | Total time from your question to the displayed answer. Cache hits typically show 20–50ms. First-time queries show 500–7000ms 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
Zentra'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, Zentra calls the AI and queries your database. This typically takes 1–7 seconds. Every subsequent time you ask the same question, it returns in under 50ms 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. Zentra's cache has a limited lifetime to ensure you always see fresh data rather than stale results.
Developers
API Reference
If you're integrating Zentra into your own tools or scripts, use the REST API directly.
Base URL
Authentication
All requests require a Firebase Bearer token:
POST /query
Submit a natural language question and receive an answer.
Request body:
| Field | Type | Required | Description |
|---|---|---|---|
query | string | Yes | Your natural language question |
Response:
| Field | Description |
|---|---|
answer | The formatted answer to your question |
cache_hit | true if served from cache, false if fresh AI call |
latency_ms | Total response time in milliseconds |
query_id | Unique ID for this query |
GET /health
Check if the Zentra system is online.
GET /metrics
Returns total query count, cache hit rate, and average latency.
GET /cache/status
Returns cache health, hit count, and hit rate.
Rate limits
| Limit | Value |
|---|---|
| Requests per user per minute | 60 |
| Response when exceeded | HTTP 429 |
Support
Troubleshooting
Query returns no results
This usually means the data doesn't exist in your database for the specified parameters. Try asking Zentra what data is available:
Query returns an error about a column not existing
Zentra 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 Zentra'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.
FAQ
Frequently Asked Questions
Do I need to know SQL to use Zentra?
No. Zentra converts your plain English questions into SQL automatically. You never write or see any SQL unless you specifically ask for it.
Can Zentra modify or delete my data?
No. Zentra 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?
Zentra 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 Zentra keep cached answers?
Cache entries expire automatically to prevent stale data. Since financial databases update regularly, Zentra refreshes its cache on a short cycle to ensure you always see accurate results.
What databases does Zentra support?
Zentra currently supports PostgreSQL. If you're on the demo, it uses a built-in database with sample financial data. Connect your own PostgreSQL database under Settings.
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.
Can I use Zentra programmatically via API?
Yes. Zentra exposes a REST API at POST /api/v1/query. See the API Reference section above for full details. Useful for building custom dashboards or automating report generation.
What if Zentra gives a wrong answer?
Zentra 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.