Connect a database
Go to Datasets and click New Dataset. Choose your database type and enter your connection credentials.
MongoDB supports replica sets, Atlas clusters, and standalone instances. Paste a connection string or fill in host, port, database name, and credentials individually.
PostgreSQL works the same way — connection string parsing is supported for both.
SSH tunnel
If your database isn't publicly accessible, toggle SSH Tunnel on and provide:
SSH host and port (default: 22)
Username
Authentication method — private key or password
Connection string parsing
Paste a full URI and QPilot fills the form fields automatically. You can also do the reverse: fill the form and copy the generated connection string out.
Schema ingestion
After connecting, QPilot reads your schema and generates a dataset summary using AI. This summary is what QPilot uses to understand your data before you ask anything.
Ingestion runs in the background and takes 10–60 seconds depending on schema size. You'll see a progress indicator on the dataset card.
Your first question
Click the dataset card to open a new conversation. Suggested questions based on your schema appear automatically — click one or type your own in the input at the bottom.
QPilot will:
1.Plan — understand your question and choose a query approach
2.Query — generate and run the database query
3.Analyze — write a plain-language explanation of the results
4.Visualize — pick the best chart type automatically
Tip: Start with a simple count — "How many records are in [your main collection]?" — to confirm the connection is working before asking anything complex.
The query input
Type your question in natural language. Press Enter to send. Use Shift+Enter for a new line within your message.
QPilot reads the question, figures out what data to pull, generates the query, and streams the result back.
Tips for better questions
Be specific about what you want to measure:
With time bounds — "Revenue last 30 days grouped by day" beats "show me revenue"
With groupings — "Top 10 customers by order count this quarter"
With filters — "Failed payments in Q1 2025 where amount > $100"
With comparisons — "MRR this month vs last month"
QPilot uses your dataset summary and schema to interpret terminology. If results look wrong, try using the exact field or collection name from the Schema Explorer.
Suggestions
New conversations show pre-generated questions tailored to your schema, ranging from simple aggregations to multi-step analyses.
Click any suggestion to pre-fill the input. Edit before sending or press Enter to run as-is.
Follow-up questions
Conversations are threads. QPilot carries context between messages — you can refine naturally:
"Now break that down by region"
"Filter to only enterprise accounts"
"Same metric but for last year"
"Show me the top 5 instead"
Editing a question
Each message block has an edit button. Click it to modify the original question and rerun — QPilot replaces the result in place without creating a new message.
Stopping a response
Click the stop button (replaces the send button while streaming) to halt the current query mid-generation.
Message blocks
Each question + answer pair is a message block. It contains:
Your original question
A data visualization (chart or table)
An AI-written analysis
Action buttons for sharing, pinning, and generating reports
Message blocks are permanent — they live in the conversation and can be revisited, shared, or turned into dashboards pins anytime.
The analysis
Below every chart, QPilot writes a plain-language explanation of what the data shows. It highlights trends, outliers, and notable patterns automatically.
The analysis is editable — click the edit icon to rewrite it, then save. Useful when you want to add context before sharing a report.
Query details
Click Query details on any message block to see:
The exact SQL or MongoDB query that ran
Which tables or collections were used
Execution time and row count
This is useful for auditing results or copying the query to run elsewhere.
Reasoning
For complex questions, QPilot shows a step-by-step reasoning trace — how it planned the approach, what it considered, and why it made certain choices.
Click Show reasoning to expand the trace. Useful for understanding why a result looks unexpected.
Pipeline steps
When QPilot uses multi-step transformations (filter → group → rank, for example), it shows a pipeline view with each step labeled. This is the query execution plan before data is fetched.
Explore
Charts & Visualizations
Chart types available, how to switch views, and what each is good for.
Available chart types
QPilot picks a chart type automatically based on your data shape. You can always switch manually.
| Type | Best for |
|---|---|
| Table | Raw data, many columns, non-visual output |
| Line | Trends over time (one or more series) |
| Bar | Comparisons across categories |
| Area | Cumulative or stacked trends |
| Pie / Donut | Part-to-whole relationships (< 8 segments) |
| Scatter | Correlation between two numeric metrics |
| Radar | Multi-dimensional comparisons across categories |
| KPI | A single key number with optional delta |
| Spark table | Multiple metrics each with a mini sparkline |
Switching views
Use the toggle in the bottom-right pill of any chart to switch between chart view and table view:
Shows a table icon when you're in chart mode → click to see raw data
Shows a chart icon when you're in table mode → click to return to the chart
The toggle only appears when a chart type is available. Pure table results show only the table.
Fullscreen
Click the expand button on any chart to open it fullscreen. Useful for dense tables with many columns, or wide charts that benefit from more horizontal space.
Hover tooltips
Hover over any data point to see the exact value. Multi-series line and bar charts show all series values at the hovered point simultaneously.
How QPilot picks a chart type
QPilot evaluates the shape of your results:
One row, one number → KPI
One column is a date/time + one numeric column → Line
Category + numeric, few categories → Bar
Two numeric columns → Scatter
Many rows, many columns → Table
You can override by describing what you want: "show this as a pie chart" or "give me a table".
Creating a dashboard
In the Dashboard view, click the + next to the dashboard list. Give it a name and assign a color. Dashboards are scoped to your team — all team members can see them.
Pinning a chart
After running any query, click the pin button on the chart. Choose which dashboard to add it to.
Pinned charts re-run the underlying query each time the dashboard loads — the data is always fresh, not a snapshot.
Reordering pins
Drag any pin tile to a new position within the dashboard grid. Position saves automatically. You can reorganize any time without affecting the underlying data.
Resizing pins
Click the resize handle on a pin tile to cycle through four sizes:
1.Small — 1 column (narrow metric or KPI)
2.Medium — 2 columns (standard chart)
3.Large — 3 columns (wide time-series)
4.Full width — spans all columns (dense table or wide comparison)
Filtering by dashboard
Use the dashboard selector at the top of the Dashboard view to filter tiles. Choose a specific dashboard, or select All to see every pin across all dashboards. Unassigned pins appear in a separate section at the bottom.
Removing a pin
Hover over a pin tile and click the remove icon. This removes the chart from the dashboard but doesn't delete the original message block or conversation — the query still exists in its conversation thread.
Tip: Think of pins as shortcuts to live query results, not copies. Removing a pin doesn't lose any data.
Opening the explorer
In the query view, click the Schema button (or the database icon) in the sidebar panel. The schema drawer opens showing all collections or tables in your connected dataset.
Browsing tables and collections
Each table or collection is listed with its field count. Click to expand and see:
Field names — exact names as they exist in your database
Data types — string, number, date, boolean, object, array, etc.
Indexes — which fields are indexed (important for query performance)
Sample values
Some fields show a sample value from a small non-sensitive preview captured during ingestion. This helps you understand the data format — whether a date is stored as an ISO string or a Unix timestamp, for example.
Why this matters
QPilot uses the dataset summary for context, but the Schema Explorer shows the exact field names. If QPilot generates a query with an incorrect field name, look it up here and rephrase your question using the exact name.
Example: You ask about "monthly recurring revenue" and get unexpected results. Expand the relevant table — the field might be called
mrr, monthly_revenue, subscription_amount, or something else entirely. Ask again with the exact name.Using schema context in questions
You can reference the schema directly in your questions:
"Group by the `status` field in `orders`"
"Sum of `amount_cents` divided by 100, filtered where `deleted_at` is null"
Explicit field names remove ambiguity and produce more reliable queries.
What is a report
A report is a self-contained interactive HTML page generated from a single message block. It includes the question, chart, AI analysis, and live data — the underlying query re-runs every time someone loads the page, so results are always current.
Reports live at a permanent URL (
/mbx/[id]) and don't require a QPilot account to view — depending on the visibility setting.Generating a report
Each message block with query results shows a Generate Report button. The button reflects the current state:
Generate Report — no report exists yet, click to start
Generating… — report is being built, polls automatically every 3 seconds
View Report — ready, opens in a new tab
Retry Report — generation failed, click to re-queue
Generation takes 15–45 seconds. The engine builds the HTML page, uploads it, and the button updates automatically.
Viewing the report
Click View Report to open it in a new tab at
/mbx/[id]. This URL is what you share.Tip: The report URL is the share link. Bookmark it or send it directly — no login required for Link or Public visibility.
Live data
Reports aren't static exports. The chart and data re-run the original query on every page load. If someone views the report tomorrow, they see today's data.
Retrying
If generation fails (network issue, query timeout, storage error), click Retry Report to re-queue. Check that your database connection is healthy if retries keep failing — the engine needs a working connection to fetch the data it embeds in the page.
Viewing datasets
Go to Datasets to see all connections for your current team. Each card shows:
Database type (MongoDB or PostgreSQL)
Custom label and color
Connection status
Last ingestion timestamp
Editing a connection
Click the edit button (pencil icon) on a dataset card to update connection details — host, port, database name, credentials, or SSH tunnel settings. Changes take effect on the next query.
Re-ingesting
If your schema changes — new tables added, columns renamed, collections removed — click Re-ingest on the dataset card. QPilot re-reads the schema and refreshes its understanding of your data structure.
Re-ingestion doesn't affect existing conversations, message blocks, or pinned charts.
Regenerating the summary
The AI-generated dataset summary is what QPilot uses to interpret your questions in context. Click Regenerate summary to rewrite it — useful if:
The schema has changed significantly since initial setup
The initial summary was inaccurate or too generic
You've added meaningful context to the dataset description
Deleting a dataset
Click Delete on the dataset card and confirm. This permanently removes:
The database connection
All conversations and message blocks in this dataset
All dashboard pins sourced from this dataset
Warning: Deletion is permanent and cannot be undone. Export any queries or reports you want to keep before deleting.
Editing your profile
Go to Settings → General to update:
First and last name
Job title
Company name
Changes save automatically.
Teams
QPilot organizes everything by team — datasets, conversations, dashboards, and members are all team-scoped.
Creating a team — open the team selector at the top of the Dashboard and click New Team. Give it a name. You become the owner.
Switching teams — use the team selector dropdown. Your entire view (datasets, dashboards, queries) switches to show that team's data.
Teams are useful for separating environments (production vs staging), departments (engineering vs growth), or client accounts.
Connected apps
Settings → Connected Apps lists every third-party application you've authorized to access your QPilot data via OAuth.
For each authorized app you'll see:
App name, logo, and description
Scopes granted (read, write, datasets, conversations)
When you authorized it
When it last accessed your account
Click Revoke access to remove an app's authorization permanently. The app will lose access immediately and need to re-authorize if it tries to connect again.
Token usage
QPilot measures AI processing in tokens. Each query consumes tokens for planning, query generation, and writing the analysis. Complex multi-step queries use more tokens than simple ones.
Go to Settings → Billing or the Usage page to see:
Total tokens used in the current billing period
Daily usage chart
Remaining balance or limit
Usage limits
Your plan sets a monthly token budget. When the limit is reached, queries are paused until the next period resets or you add more capacity.
Check the Usage page to monitor how quickly you're burning through your budget — useful before sending a dataset to a heavy user.
Payment methods
In Settings → Billing, click Add card to save a payment method. QPilot uses Stripe for card processing — your card details are never stored on QPilot servers.
You can save multiple cards:
Click the star icon to set a card as the default
Click the delete icon to remove a card
You need at least one valid card on file to run queries beyond the free tier.
Plans
Your current plan is shown at the top of the Billing tab with token limits and included features. Contact support@qpilot.io to upgrade, downgrade, or discuss an enterprise plan.
OAuth clients
QPilot supports OAuth 2.0 authorization. Build applications that query data on behalf of QPilot users — automations, integrations, internal tools, or AI assistants.
Go to Settings → Developer and click New Client.
Fill in:
Name — shown to users during the authorization screen
Description — explains what your app does
Website and Logo URL — branding shown during authorization
Redirect URIs — one or more valid callback URLs (must match exactly during the auth flow)
Scopes — what access to request from users
Scopes
| Scope | Access |
|---|---|
read | Read conversations and message blocks |
write | Create conversations and run queries |
datasets | Read dataset schema and metadata |
conversations | Full conversation management |
Request only the scopes your application actually needs.
Authorization flow
1.Redirect the user to QPilot's authorization page with your
client_id, redirect_uri, and requested scopes2.User reviews and approves — QPilot redirects back with an authorization
code3.Exchange the
code for an access_token at the token endpoint4.Use the
access_token as a Bearer token on API requestscode
GET https://app.qpilot.io/oauth/authorize
?client_id=YOUR_CLIENT_ID
&redirect_uri=https://yourapp.com/callback
&response_type=code
&scope=read datasetsClient credentials
After creating a client, copy the Client ID and Client Secret immediately from the confirmation screen. The secret is shown only once — if you lose it, rotate it.
Rotating the secret
In the client details panel, click Rotate Secret. A new secret is generated and the old one is invalidated immediately. Update your app's secret before rotating to avoid downtime.
Creating a webhook
In Settings → Developer, open an OAuth client and click Add Webhook. Provide:
Endpoint URL — the HTTPS URL QPilot will POST to
Events — which events to subscribe to
QPilot generates a webhook secret for request verification
Supported events
| Event | When it fires |
|---|---|
query.completed | A query finishes successfully |
query.failed | A query errors or times out |
authorization.revoked | A user revokes your app's access |
You can subscribe to multiple events on a single webhook, or use separate webhooks per event type.
Payload
QPilot sends an HTTP POST with a JSON body containing:
event — the event nameconversation_id and message_block_id (for query events)user_idtimestampEvent-specific metadata
Verifying signatures
Every request includes an
X-QPilot-Signature header — an HMAC-SHA256 signature computed from the raw request body and your webhook secret. Always verify this before processing.javascript
const crypto = require("crypto");
const sig = req.headers["x-qpilot-signature"];
const expected = crypto.createHmac("sha256", WEBHOOK_SECRET).update(rawBody).digest("hex");
if (sig !== expected) return res.status(401).send("Invalid signature");Delivery logs
Click a webhook to see delivery history. Each entry shows the timestamp, HTTP status your endpoint returned, and the response body (truncated to 500 chars).
Green = success (2xx), Red = failed (non-2xx or timeout).
Retrying failed deliveries
Click Resend on any failed delivery to retry it immediately. QPilot does not auto-retry — you're in control of when to redeliver.
What is MCP
Model Context Protocol is an open standard for connecting AI models to external data and tools. QPilot's MCP server lets AI assistants — Claude, Cursor, Windsurf, and others — query your databases through QPilot directly within their chat interfaces.
Authentication
MCP uses QPilot's OAuth 2.0 flow. You authorize your AI assistant once and it gains access to your connected datasets.
1.In your AI assistant's settings, find the MCP or tools section
2.Add QPilot as an MCP server
3.Complete the OAuth authorization — this grants the assistant access to your team's datasets with the scopes you approve
Available tools
Once connected, your AI assistant can invoke QPilot tools:
list_datasets — see all connected databases in your team
run_query — ask a natural language question, get structured data back
get_schema — inspect table/collection structure
get_conversation — retrieve query history from a conversation
Configuration example
json
{
"mcpServers": {
"qpilot": {
"url": "https://api.qpilot.io/mcp",
"auth": {
"type": "oauth2",
"clientId": "your-client-id",
"scopes": ["read", "datasets"]
}
}
}
}Replace
your-client-id with the Client ID from Settings → Developer.Full setup guide
QPilot has a dedicated MCP documentation page with step-by-step setup per assistant, tool schemas, auth flow diagrams, and copy-paste configuration examples.
Keyboard shortcuts
| Action | Shortcut |
|---|---|
| Send query | Enter |
| New line in input | Shift+Enter |
| Stop streaming response | Click the stop button |
Query tips
Use the Schema Explorer first. Before asking anything complex, expand the relevant tables to see exact field names. One mismatch can send QPilot down the wrong path.
Start simple, then refine. Ask "Show me orders by month" first, then follow up with "filter to status = completed" and "only Q4 2024". Thread context is preserved — you don't need to repeat yourself.
Mention aggregations explicitly. "Sum of revenue grouped by month" is more reliable than "revenue over time". The more specific, the less room for interpretation.
Describe the output format. If you want a specific chart type, say so: "show as a bar chart" or "give me a table with these columns."
Dashboard tips
Name dashboards by audience. "Engineering KPIs", "Weekly Review", "CS Metrics" — clear names make it obvious what lives where and who it's for.
Use size for hierarchy. Full-width at the top for the headline number, medium-size charts below for supporting context, small KPI tiles for secondary metrics in a row.
Pin sparingly. Dashboards with 20+ tiles become noise. Pin the 5–8 charts you actually review regularly.
Report tips
Generate reports for recurring shares. Reports have permanent URLs and live data — ideal for metrics you send to stakeholders every week via Slack or email.
Check visibility before sending. A Link-visibility report is accessible to anyone with the URL. Confirm the setting in the visibility popover before distributing widely.
Regenerate when the query changes. Editing a question and rerunning creates a new result. You'll need to click Generate Report again on the updated message block.
QPilot Docs · support@qpilot.io