Query API
Query your structured data using natural language. Your data never leaves your device.
How It Works
Query API uses a two-phase approach to enable natural language filtering without exposing your data.
Upload Structured Data Client
Import your CSV, spreadsheet, or structured data. The system extracts only the column headings - your actual data rows stay in your browser.
Generate Query Template API
Column names are sent to the API which analyzes the schema and returns a query template - identifying which columns can be filtered, sorted, and searched.
Ask in Natural Language Client
Type your question naturally: "Show me high-value orders from last month" or "Sort customers by revenue, highest first".
Parse Query Intent API
The AI interprets your natural language question and converts it into structured filter/sort operations using the template context.
Execute Locally Client
The returned operations are applied to your data entirely in the browser. Results appear instantly - no data ever transmitted.
Architecture
┌─────────────────────────────────────────────────────────────────────────────┐
│ CLIENT (Browser) │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ YOUR DATA (Never Leaves Browser) │ │
│ │ │ │
│ │ ┌──────────┬───────────┬──────────┬─────────┬─────────────────┐ │ │
│ │ │ Name │ Region │ Revenue │ Date │ Status │ │ │
│ │ ├──────────┼───────────┼──────────┼─────────┼─────────────────┤ │ │
│ │ │ Acme │ West │ $50,000 │ Jan 15 │ Active │ │ │
│ │ │ Beta │ East │ $32,000 │ Jan 22 │ Pending │ │ │
│ │ │ Gamma │ West │ $78,000 │ Feb 3 │ Active │ │ │
│ │ │ ... │ ... │ ... │ ... │ ... │ │ │
│ │ └──────────┴───────────┴──────────┴─────────┴─────────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │
│ │ ▲ │
│ │ Extract headers only │ Apply operations │
│ ▼ │ locally │
│ ┌─────────────┐ ┌─────────────┐ │
│ │ ["Name", │ │ filter: │ │
│ │ "Region", │ │ Region=West│ │
│ │ "Revenue", │ │ sort: │ │
│ │ "Date", │ │ Revenue ▼ │ │
│ │ "Status"] │ └─────────────┘ │
│ └─────────────┘ ▲ │
│ │ │ │
└─────────┼──────────────────────────────────────────────┼─────────────────────┘
│ │
│ Only metadata │ Query operations
▼ │
┌─────────────────────────────────────────────────────────────────────────────┐
│ API │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────┐ ┌────────────────────────────────┐ │
│ │ 1. Receive column names │ │ 2. User asks: │ │
│ │ │ │ "West region, by revenue" │ │
│ │ Analyze schema, identify: │ │ │ │
│ │ • Filterable columns │───▶│ Parse intent, return: │ │
│ │ • Sortable columns │ │ { filter: [...], │ │
│ │ • Data types │ │ sort: {...} } │ │
│ └─────────────────────────────────┘ └────────────────────────────────┘ │
│ │
│ No access to actual data values - only column structure │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
Key Benefits
Complete Privacy
Your data never leaves your device. Process sensitive data safely.
Instant Results
Local execution means zero network latency for filtering.
Natural Language
No SQL or filter syntax to learn. Just ask naturally.
Comparison
Traditional Approach
- All data sent to server for processing
- Privacy concerns with sensitive data
- Network latency on every query
- Server storage and processing costs
- Data breach risk
Query API
- Only column names sent to API
- Data stays on your device
- Instant local filtering
- No server storage needed
- Zero data exposure risk
Cost & Speed vs OpenAI File Interpreter
OpenAI's File Interpreter uploads and processes your entire file on their servers. Query API keeps your data local and only sends the schema structure.
Cost per Session
No file upload fees, no session costs, minimal tokens
Response Speed
Feature Comparison
| Feature | File Interpreter | Query API |
|---|---|---|
| Data Privacy | Uploaded to OpenAI | Stays on device |
| Session Cost | $0.03 per session | $0.00 |
| File Size Limit | 512 MB | Unlimited (local) |
| Response Time | 5-30 seconds | <100ms |
| Offline Support | No | Yes (after template) |
Example Queries
Ask questions in plain English. The AI understands context and intent.
API Reference
Generate a query template from column headings. Call this once when data is loaded.
// Request
{
"columns": ["Name", "Email", "Amount", "Date", "Status"]
}
// Response
{
"template_id": "tpl_abc123",
"schema": {
"filterable": ["Name", "Email", "Status"],
"sortable": ["Amount", "Date", "Name"],
"searchable": ["Name", "Email"]
}
}Parse a natural language query into filter/sort operations.
// Request
{
"template_id": "tpl_abc123",
"query": "Show completed orders over $500 sorted by date"
}
// Response
{
"operations": {
"filter": [
{ "column": "Status", "operator": "equals", "value": "Completed" },
{ "column": "Amount", "operator": "gt", "value": 500 }
],
"sort": {
"column": "Date",
"direction": "desc"
}
}
}Supported Operations
Filter Operators
| Operator | Description | Example Query |
|---|---|---|
equals |
Exact match | "Status is Active" |
contains |
Partial text match | "Name contains John" |
gt / lt |
Greater/less than | "Amount over 1000" |
between |
Range match | "Date between Jan and Mar" |
in |
Multiple values | "Region is East or West" |
Sort Directions
| Direction | Description | Example Query |
|---|---|---|
asc |
Ascending (A-Z, 0-9, oldest first) | "Sort by name alphabetically" |
desc |
Descending (Z-A, 9-0, newest first) | "Highest revenue first" |