# Querio Documentation
> Welcome to the Querio documentation digest.
## Welcome to Querio
> The analytics workspace where agents help your team work with data.
Welcome to Querio! This documentation is organized around the main ways you will work with Querio: connect data, run explores, teach Querio about your business, and share the results with your team.
## What Querio does
Querio is a workspace where data agents help your team analyze, explain, and operationalize work on top of your connected data.
An explore is the main workspace for an analysis. It contains the conversation with the agent and the notebook of cells the agent creates while working.
## How to get started
1. Connect your first datasource
2. Start an explore with the analysis you want to run
3. Review the notebook cells Querio creates
4. Bookmark important results or turn them into a layout
5. Add context so Querio understands your business better over time
## For data and engineering teams
If you are setting up Querio for a workspace, start with [Connect your data](/connect-data), then review [Teach Querio about your data](/teach-querio). These sections explain how Querio connects to your warehouse and how to add the context the agent uses during analysis.
## For developers
If you want to embed Querio in your own product, start with [Embed Querio](/embed). You can embed the Explore UI in an iframe or use the Embedded API to build a custom experience.
## Analyze from Slack
> Start Querio analysis directly from Slack.
The Slack integration lets you start an explore without opening the Querio app.
When you tag Querio in Slack with an analysis request, Querio creates an explore, runs the work, and replies in the Slack thread with the result. The reply shows the steps Querio took, followed by the written answer and notebook output; Markdown cells keep their formatting, tables appear as native Slack tables, and supported bar and line charts appear as native Slack charts. Other chart types are attached to the thread.
## Install the Slack app
Add the Querio app to your Slack workspace. Once it is installed, users can tag Querio in the channels where the app is available.
In **Settings → Integrations → Slack**, choose the datasources Querio can use for Slack requests. You can select more than one datasource.
## Start analysis from Slack
Mention Querio in Slack with the work you want it to run.
Example:
```text
@Querio what were our top products by revenue last month?
```
Querio will create an explore for the request and work through the analysis.
## Follow up in the thread
Mention Querio again in the same Slack thread to send a follow-up.
Querio will keep using the same explore, so the follow-up stays connected to the previous analysis.
## Open the full explore
The Slack response includes a button to open the full explore in Querio.
Open the explore when you want to see the notebook, inspect cells, bookmark results, or turn the work into a layout.
## Cells
> The main types of cells Querio uses in the notebook.
Cells are the building blocks of a Querio notebook. You can filter the notebook to show only specific cell types (like SQL, Python, or Visualization) using the filter bar.
## SQL cells
SQL cells query your connected datasource.
Use SQL cells to pull data, calculate metrics, join tables, and produce tables that other cells can use.
You can copy or download SQL results from the cell when you need to use the output outside Querio.
## Python cells
Python cells let Querio transform data, run calculations, and prepare results that are easier to visualize or explain.
Python is useful when the analysis needs more than SQL, such as reshaping data, calculating derived metrics, or preparing chart inputs. Python cells can also render interactive UI widgets—like dropdowns, date pickers, or sliders—that dynamically filter the data in downstream cells.
## Markdown cells
Markdown cells are used for written explanations.
They help turn the notebook into something readable by adding context, summaries, caveats, and next steps.
## Visualization cells
Visualization cells show charts generated from your data.
Use them to compare categories, show trends over time, inspect distributions, or explain a result visually.
You can copy or download chart data when you need to reuse the underlying result.
## Explore modes
> Use Chat, Hybrid, or Layout mode depending on how much of the notebook you want to see.
Explore has different modes so you can choose how you want to work.
## Chat mode
Chat mode focuses on the conversation with the agent.
Use Chat mode when you want quick analysis, a written summary, and the notebook kept out of the way.
## Hybrid mode
Hybrid mode shows the chat and notebook together.
Use Hybrid mode when you want to see how Querio is producing the analysis, inspect the SQL or Python, and work directly with cells.
## Layout mode
Layout mode presents selected notebook cells on a clean canvas, hiding the chat and intermediate work.
Use Layout mode when you have a finished result you want to share, monitor, or revisit later without the clutter of the conversation.
## Which mode should I use?
Start in the mode that feels most natural:
- Use Chat mode for quick analysis and follow-ups
- Use Hybrid mode when you want to inspect, edit, bookmark, or arrange notebook results
- Use Layout mode to present a clean, dashboard-like view of your findings
You can switch modes while working in the explore.
## Explore overview
> Explore is where agents work through analysis with your data.
Explore is the main workspace for analysis in Querio.
You start with the work you want Querio to run, Querio works through it, and the result appears as both an agent conversation and a notebook.
## What happens in an explore
When you send a request, Querio can:
- Read the available catalog and knowledge files
- Write SQL
- Run Python
- Create charts and tables
- Summarize the result and the reasoning behind it
- Keep the work in a notebook so you can review and edit it
## Good requests
The best requests are clear about the metric, timeframe, and filter.
Good examples:
- "Show monthly revenue for the last 12 months."
- "What are the top 10 customers by number of orders this quarter?"
- "Compare conversion rate by acquisition channel since January."
## Follow-ups
You can keep sending follow-ups in the same explore. Querio will use the previous messages and notebook cells as context.
Use the model selector in the composer to choose which model should handle the next turn. If you switch models during an explore, Querio saves that change with the conversation so later follow-ups continue from the selected model.
## Choose a model
Querio gives your team access to leading models from Anthropic, OpenAI, and Google. Choose the one that suits the work at hand:
- **Claude Sonnet 5** for everyday analysis
- **Claude Opus 4.8** for complex data work
- **GPT 5.6 Terra** for balanced, capable analysis
- **GPT 5.6 Sol** for the most demanding data tasks
- **Gemini 2.5 Pro** for deep insight across large datasets
- **Gemini 3.5 Flash** for quick lookups
The models available to your team can depend on your workspace plan and deployment.
If a result is useful, bookmark it or add it to a layout.
## Mentions
> Use mentions to guide Querio to specific resources and actions.
Mentions are shortcuts you can use in the Explore composer to tell Querio exactly what resources or actions you want to use.
By typing `@` in the composer, you can open a menu to mention:
- **Workspace resources:** Specific datasources, catalog tables, and golden queries.
- **Skills and actions:** Specific workflows or actions you want Querio to run (these previously used slash `/` commands).
- **Notebook cells:** Specific outputs and results from the current explore.
Use mentions when you want to direct the agent more precisely than a standard request.
Examples of when mentions are useful:
- **Starting a specific kind of analysis** by using a skill or action.
- **Reusing a common workflow** or logic via a golden query.
- **Asking Querio to edit or explain a specific notebook result** by mentioning its cell.
The exact mentions available depend on your workspace and how Querio has been configured.
## Notebook overview
> Understand how Querio's notebook works.
The notebook is where Querio shows its work.
Each notebook is made up of cells. Cells can contain SQL, Python, Markdown, tables, charts, or written explanations.
## Why the notebook matters
The notebook makes the analysis inspectable. Instead of only seeing a final result, you can see the steps Querio took to get there.
This is useful when you want to:
- Check the SQL Querio wrote
- Edit part of the analysis
- Re-run or continue from an existing result
- Bookmark important cells
- Add selected cells to a layout
## Reactivity
Notebook cells can depend on earlier cells. When you change something upstream, downstream results can update from that change.
This lets you keep the analysis flexible without starting over.
## Continuing from a notebook
You can ask the agent to change a cell, explain a result, or build on top of an existing output. Tag or mention the cell when you want Querio to focus on a specific result.
## Visualizations
> Learn how to create useful charts in Querio.
Querio uses visualizations to make data easier to compare and explain.
The best visualization requests are specific about what you want to compare, what should be on each axis, and how the data should be grouped.
## Good visualization requests
| Good request | Why it works |
| ----------- | ------------ |
| "Bar chart of revenue by region, sorted descending" | Names the chart type, metric, grouping, and sort |
| "Line chart of monthly sales for the last 12 months" | Gives a metric, time grain, and timeframe |
| "Scatter plot of order value vs margin, colored by region" | Defines both axes and the color grouping |
| "Heatmap of orders by weekday and hour" | Gives a clear shape for the visualization |
## What to specify
When creating a chart, include:
- Chart type: bar, line, scatter, heatmap, donut, histogram, or area
- Metric: the value you want to measure
- Grouping: the category or dimension to compare
- Timeframe: the date range or time grain
- Sorting: if the order matters
## Chart Gallery
### 1. Bar Charts
**Best for**: Comparing values across categories, rankings, top N analysis
**Example prompts**:
- "Show me total revenue by paper type"
- "What are the top 10 products by sales?"
- "Compare order counts across regions"
- "Create a bar chart of average order value by account manager"
### 2. Grouped Bar Charts
**Best for**: Comparing multiple metrics side-by-side, year-over-year comparisons, A/B analysis
**Example prompts**:
- "Compare 2024 vs 2025 revenue by quarter"
- "Show completed vs cancelled orders by region"
- "Compare average order value and total orders by paper type side by side"
- "Create a grouped bar chart showing Q1-Q4 performance for each product category"
### 3. Line Charts
**Best for**: Trends over time, time series analysis, tracking changes
**Example prompts**:
- "Show me monthly revenue trends for the past year"
- "How has order volume changed over time?"
- "Plot daily sales for the last 30 days"
- "Create a line chart of average order value by week, broken down by shipping mode"
### 4. Scatter Plots
**Best for**: Exploring relationships between variables, identifying outliers, multi-dimensional analysis
**Example prompts**:
- "Is there a relationship between discount percentage and order size?"
- "Plot accounts by revenue vs order count, sized by business size"
- "Show me a scatter plot of days to ship vs customer rating"
- "Create a bubble chart of products by price vs quantity sold, colored by paper type"
### 5. Stacked Area Charts
**Best for**: Showing composition over time, part-to-whole trends, cumulative analysis
**Example prompts**:
- "Show how revenue composition by paper type has changed over time"
- "Create a stacked area chart of orders by status over the last 6 months"
- "Visualize regional revenue share trends"
- "How has the mix of shipping modes evolved month over month?"
### 6. Heatmaps
**Best for**: Two-dimensional categorical comparisons, finding patterns across two dimensions, density analysis
**Example prompts**:
- "Create a heatmap of average order value by region and paper type"
- "Show me order volume by day of week and hour"
- "Which account managers perform best in which regions? Show as a heatmap"
- "Visualize rating distribution by product category and shipping mode"
### 7. Layered Charts (Combo Charts)
**Best for**: Showing multiple related metrics together, adding context (targets, averages), combining different perspectives
**Example prompts**:
- "Show monthly revenue as bars with a trend line overlay"
- "Create a chart with order volume bars and average order value as a line"
- "Plot revenue by month with a horizontal line showing the target"
- "Combine a bar chart of sales with a line showing cumulative total"
### 8. Faceted Charts (Small Multiples)
**Best for**: Comparing the same pattern across categories, side-by-side trend comparison, segmented analysis
**Example prompts**:
- "Show monthly revenue trends, with a separate chart for each region"
- "Create small multiples of order volume by paper type"
- "Compare seasonal patterns across account managers using facets"
- "Show me weekly trends faceted by shipping mode"
### 9. Donut/Pie Charts
**Best for**: Part-to-whole relationships, market share, simple composition snapshots
**Example prompts**:
- "What percentage of revenue comes from each paper type?"
- "Show the breakdown of orders by status as a pie chart"
- "Create a donut chart of revenue share by region"
- "What's the distribution of shipping modes?"
### 10. Histograms
**Best for**: Understanding distributions, identifying patterns in continuous data, finding outliers
**Example prompts**:
- "What's the distribution of order values?"
- "Show me a histogram of days to ship"
- "How are customer ratings distributed?"
- "Create a histogram of discount percentages"
## Advanced Customization
If the first chart is not right, send a follow-up. Querio can change the chart type, filters, labels, or grouping from the same explore.
### Custom Tooltips
Tooltips aren't just for showing raw values - you can customize them with labels, formatting, and calculated fields!
**Example prompts**:
- "Create a scatter plot of revenue vs units sold, with detailed tooltips showing product name, rating, and discount"
- "Make a chart with emoji labels in the tooltips"
### Custom Color Scales & Semantic Colors
Use colors that mean something! Red for bad, green for good, or custom gradients that tell a story.
**Example prompts**:
- "Create a bar chart where high cancellation rates are red and low ones are green"
- "Use traffic light colors to indicate performance levels"
### Text Labels & Annotations
Add labels directly on your charts for extra clarity - no legend hunting required!
**Example prompts**:
- "Add value labels on top of each bar"
- "Show percentages inside each pie slice"
### Calculated Fields & Transforms
Create new metrics on the fly! Ratios, rankings, running totals - all computed in the visualization.
**Example prompts**:
- "Show revenue per order as a calculated metric"
- "Calculate the running total of revenue"
## Widgets
> Use widgets like dropdowns and date pickers to parameterize your notebooks and build dynamic reports.
Widgets let you add interactive inputs directly inside Python cells. These widgets allow users to filter, tweak, and parameterize downstream queries and logic without writing code.
The Querio AI agent can automatically generate and use these widgets to build dynamic, reusable reports for your team.
## Available Widgets
You can use a variety of widgets to parameterize your analysis:
- **Date Pickers:** Select single dates or date ranges to filter time-series data.
- **Multi-select Dropdowns:** Choose multiple categories or tags from a list.
- **Single-select Dropdowns:** Pick exactly one option from a predefined list.
- **Text Inputs:** Provide free-form text search or filtering criteria.
- **Number Inputs:** Specify numeric thresholds, limits, or configuration values.
- **Radio Buttons:** Select a single option from a small set of mutually exclusive choices.
- **Sliders:** Adjust numeric values interactively.
## How They Work
Widgets are rendered from Python cells. When a user interacts with a widget (e.g., selects a new date or chooses a different option from a dropdown), the updated value becomes available to the rest of the notebook.
Any downstream SQL or Python cells that depend on this value will automatically react and re-execute, updating charts, tables, and metrics in real time.
Try it out in the embedded example below:
### Using Widgets with the AI Agent
You don't have to write the code for these widgets yourself. You can simply ask the AI agent to make your report dynamic.
For example, you can say:
- *"Add a date picker so I can filter the revenue chart by month."*
- *"Create a multi-select dropdown for the `region` column."*
- *"Add a slider to let me adjust the churn probability threshold."*
The AI agent understands widgets natively and will write the necessary Python code to embed them into your notebook and link them to your downstream queries.
## Work with notebook results
> Tag, find, bookmark, and reuse cells in an explore.
Once Querio creates notebook cells, you can interact with them directly.
## Tag and mention cells
Tagging cells makes it easier to tell Querio exactly what you want to work with.
By typing `@` in the composer, you can mention specific notebook cells (along with other workspace resources like datasources and skills).
You can mention a cell in your request when you want the agent to focus on a specific result.
Example:
```text
Explain why @cell changed so much in March.
```
## Find cells
Use search or cell references when an explore has many results and you need to get back to a specific output.
## Bookmark cells
Bookmark important cells so they are easier to find later.
Bookmarks stay attached to the explore. They are useful when a notebook has several outputs but only a few are important enough to revisit.
## Add cells to a layout
If a cell should be part of a cleaner shared view, add it to a layout.
Layouts let you arrange selected notebook cells on a grid without losing the full explore behind them.
## Datasource settings
> Manage datasource credentials and defaults.
Datasource settings control how Querio connects to your databases and warehouses.
## Edit a datasource
Use datasource settings when you need to update:
- Credentials
- Host or port
- Database or schema details
- Connection options
## Favorite datasources
You can set one or more favorite datasources for a member. This is useful when a workspace has multiple datasources and you want new explores to automatically start with the right context selected.
## Rotating credentials
When rotating credentials, update Querio before removing the old credential from your database. This keeps existing work from breaking during the rotation.
## Developer access
> Give developers access to embedded and API tools.
Developer access is used for team members who need to work with embedded Querio features.
When a member has developer access, they can access developer-focused parts of the app such as embedded configuration and API token management.
Use developer access for people building or maintaining:
- Embedded iframe experiences
- Embedded API integrations
- Slack or other external workflows
- Internal developer tooling around Querio
## Admin settings
> Manage workspace settings, members, datasources, and developer access.
Workspace admins manage the parts of Querio that affect the whole team.
This includes members, roles, workspace settings, datasources, and developer access.
## Admin responsibilities
Admins usually handle:
- Inviting and removing members
- Setting member roles
- Managing datasources
- Updating workspace settings
- Giving developers access to embedded tools
- Coordinating self-hosted deployments when needed
## Members and roles
> Add members and manage their workspace roles.
Use members and roles to control who can access a Querio workspace and what they can manage.
## Add a member
1. Open workspace settings
2. Go to members
3. Click **Add new member**
4. Enter the team member's email
5. Choose their role
6. Send the invite
Querio sends a signup link to the email address.
## Roles
**Admin** users can manage datasources, members, context, and workspace settings.
**Member** users can use Querio for analysis but do not manage the workspace.
## Change a role
You can change a member's role after they join. Open the member list, choose the role selector, and pick the new role.
## Self-hosting
> Run Querio infrastructure in your own environment.
Self-hosting is for teams that need to run Querio infrastructure inside their own environment.
Self-hosted deployments are usually coordinated with the Querio team because they depend on your infrastructure, security, and networking requirements.
## When to consider self-hosting
Self-hosting may be relevant if your team has strict requirements around:
- Data residency
- Network isolation
- Infrastructure ownership
- Internal security controls
If you are evaluating self-hosting, contact Querio so we can plan the right setup with your team.
## Workspace settings
> Configure workspace-level settings and access support.
Workspace settings control the behavior of the Querio workspace.
Use this area for settings that affect the whole team rather than one explore or one datasource.
Examples include:
- Workspace name and logo
- Member management
- Workspace-level defaults
- Statuses and tags for organizing explores and boards
- Developer access settings
- **Support**: Chat directly with the Querio team, schedule a call, or request a private Slack Connect channel.
Except for the Support tab (which is available to all members), only admins should change workspace settings.
## Statuses and tags
Use the **Statuses & Tags** tab to define the labels your team uses to organize work across the workspace.
Statuses are single-select labels for an explore or board, such as **Trusted** or **Needs review**. Tags are multi-select labels that can group work by team, topic, workflow, or customer.
Read [Statuses and tags](/find-manage/statuses-and-tags) for how users should think about the difference.
Admins can create, edit, and delete statuses and tags from workspace settings. Each status or tag has a name, description, and color. Statuses can also have an icon.
After statuses and tags are created, users can apply them from an explore and use them in History to find related work.
## Allowlist Querio IPs
> Allow Querio to reach databases that are behind a firewall.
If your database blocks external connections, you may need to allowlist Querio's outbound IP address before the connection can work.
## What to allow
Allow inbound traffic from Querio to the database port used by your datasource.
Common ports include:
| Datasource | Common port |
| ---------- | ----------- |
| PostgreSQL | 5432 |
| Redshift | 5439 |
| MySQL / MariaDB | 3306 |
| SQL Server | 1433 |
| ClickHouse | 9440 |
The exact IP address will be provided by the Querio team.
## How to verify
After allowlisting the IP, return to Querio and test the datasource connection. If the test still fails, check:
- The hostname and port are correct
- The database accepts SSL if required
- The user has permission to connect
- The firewall rule targets the correct network or security group
## Connect your data
> Connect databases and warehouses so Querio can query your data.
Connecting your data is the first setup step in Querio.
A datasource gives Querio read access to a database or warehouse. Querio uses that connection to run SQL, generate answers, and build the catalog that helps the agent understand your data.
## What Querio needs
Most datasources need three things:
- A read-only user, service account, or token
- Connection details like host, port, database, schema, warehouse, or project
- Network access from Querio to your database
## Keep access read-only
Querio should use a dedicated read-only account whenever possible. This keeps permissions clear and makes it easier to audit what Querio can access.
## After connecting
After the datasource is connected, Querio can generate context from it. This includes schemas, tables, columns, joins, and descriptions in the catalog.
Go to [Supported integrations](/connect-data/integrations) for setup steps for each database.
## Manage datasources
> Add, edit, and manage datasources in your Querio workspace.
Workspace admins can manage datasources from workspace settings.
## Add a datasource
1. Open workspace settings
2. Go to datasources
3. Click **Add Datasource**
4. Choose the datasource type
5. Add the connection details
6. Test and save the connection
If you do not have the credentials for the database, you can use the **Invite a colleague** option at the bottom of the connection screen to email someone who does. They will receive a link to securely enter the credentials for you.
## Edit a datasource
Use the datasource menu to update credentials, connection details, or other settings.
If you rotate credentials in your warehouse, update Querio with the new credentials before removing the old ones.
## Manage access
By default, everyone in your workspace can use a connected datasource.
To restrict access, select **Manage access** from the datasource menu and add specific people. Once the first person is added, the datasource becomes restricted, and only the people explicitly added will be able to use it.
## Remove a datasource
Only remove a datasource when you are sure the team no longer needs it. Removing access can affect explores, context, and embedded experiences that depend on that datasource.
## Upload files
> Bring CSV, Parquet, JSON, and XLSX files into Querio for analysis.
You can upload files directly into Querio without connecting an external database.
Uploaded files are converted to Parquet and stored in the `Files/files/` folder. Querio also represents them in a managed datasource called `uploads`, where you can manage metadata and agent access.
## Supported formats
- CSV
- TSV
- Parquet
- JSON
- XLSX
## How to upload
1. Open the **Context** tab for your workspace
2. Click **Datasources**
3. Click the upload button in the top-right corner
4. Drag and drop files into the dialog, or click to browse
5. Querio ingests each file and creates a Parquet file named after the original file
Each file appears in the `uploads` datasource as a catalog table so you and the agent can see its structure and metadata. It is not stored as a table in DuckDB.
## Limits
- 100MB per file
- 100MB total per batch
- 10 million rows per file
- 1,024 columns per file
## After uploading
Once ingestion is complete, the file appears in the `Files/files/` folder and is represented in your Catalog under the `uploads` datasource. You can query it in an Explore session with the local DuckDB engine using the Parquet file path:
```sql
SELECT * FROM "files/your_csv.parquet"
```
If Querio detects that the data structure or column descriptions have drifted from what the catalog says, it will flag this and suggest an update.
## Notes
- Only one file can be written to the `uploads` datasource at a time per workspace. If multiple files are uploaded at once, they are ingested sequentially.
- File uploads are available for workspace v2 (fs-mode) workspaces.
## Embedded iframe
> Embed the Querio Explore page in your own product.
You can embed the Querio Explore page in your own product using an iframe.
Access is controlled by a workspace iframe token.
## How it works
1. Create a workspace iframe token in Querio
2. Copy the embed URL
3. Add the URL to an iframe in your product
The token authenticates the embedded session and controls workspace and datasource access.
## Session Persistence
Conversations created through the iframe embed are automatically saved to your Querio workspace. They are bound to the workspace via the iframe token used to create them. This allows you to track, view, and analyze the explores generated by your embedded users directly within Querio.
## URL parameters
| Parameter | Required | Description |
| --------- | -------- | ----------- |
| `token` | Yes | Workspace iframe token |
| `mode` | No | Set to `hybrid` to show chat alongside the notebook canvas. Omit it for the focused chat experience. |
| `query` | No | Initial user message. If present, the session auto-runs with this query |
## Security
Treat iframe tokens as secrets. Share them only through secure channels and avoid exposing them where they should not be reused.
## Embed Querio
> Embed Querio in your own product.
You can embed Querio in two main ways.
## Embedded iframe
Use the embedded iframe when you want users to see the Querio Explore UI inside your own product.
This is the fastest way to embed the full experience.
## Embedded API
Use the Embedded API when you want to build your own interface on top of Querio's agentic data analysis.
The API supports conversations, follow-up turns, and assets for tables and charts.
## Boards
> Find and open explores that have a layout.
Boards is a dedicated tab in the sidebar that shows explores with a layout attached.
An explore becomes a board once you add cells to its layout. It moves out of Explores and into Boards so the two types of work stay separate.
## Finding boards
Open the Boards tab in the sidebar. It defaults to showing boards from all workspace members, so you can find work shared by your team without changing any filters.
## Opening a board
Click a board to open the explore. The layout is the default view, but the full notebook and conversation are still there.
## Working with a board
From inside a board you can:
- View the layout
- Edit or rearrange the layout cells
- Continue the conversation to update the analysis
- Share a link to the board
## Bookmarks
> Mark important notebook cells so they are easier to find later.
Bookmarks help you keep track of useful notebook cells.
Use bookmarks when a result is important but you do not need to turn it into a layout yet.
## Bookmark a cell
Open the cell toolbar and click the bookmark action.
The bookmark is saved on the explore.
## Find bookmarked work
Use History to filter for explores with bookmarks.
When you reopen the explore, the bookmarked cells are still part of the notebook.
## History
> Find previous explores and boards and continue from where you left off.
The sidebar has two tabs for finding previous work: **Explores** and **Boards**.
Every explore keeps the conversation, notebook, bookmarks, and layout state attached to it. That means you can come back to earlier work without starting again.
## Explores
Explores shows your previous analysis work — explores that do not have a layout.
Use it when you want to:
- Reopen a previous analysis
- Search for previous analysis work
- Find explores with bookmarks
- Continue an old conversation
The Explores tab defaults to showing your own work.
## Boards
Boards shows explores that have a layout attached.
Use it when you want to:
- Find a report or dashboard someone built
- Review shared layouts across the workspace
The Boards tab defaults to showing work from all creators.
## Reopen an explore
> Continue a previous explore from History.
You can reopen any explore from History.
When you reopen an explore, Querio loads the same conversation and notebook. You can inspect past cells, send follow-ups, bookmark results, or update the layout.
## Continue from previous work
Send a follow-up in the chat to continue the analysis.
Examples:
- "Update this for the current quarter."
- "Break this down by region."
- "Explain the spike in March."
- "Add this chart to the layout."
The follow-up stays in the same explore, so the context remains connected.
## Search and filter explores
> Use History filters to find the explore you need.
As your workspace creates more explores, search and filters help you find the right one.
## Search
Use search when you remember the title, topic, or output of an explore.
## Filter by status or tag
Use status and tag filters when your team organizes work with workspace labels.
Statuses are single-select labels for the current state of an explore or board, such as **Trusted** or **Needs review**. Tags are multi-select labels for grouping related work by topic, workflow, team, or customer.
Read [Statuses and tags](/find-manage/statuses-and-tags) for the difference between the two label types.
You can see status and tag columns in History, then filter the list to find matching explores or boards.
## Filter by creator
Use the creator filter when you want to see explores created by a specific person.
Admins may use this to inspect workspace activity, while members usually use it to find their own work.
## Filter by bookmarks
Use the bookmarks filter to find explores that contain bookmarked cells.
This is useful when you remember saving an important result but do not remember the exact explore title.
## Statuses and tags
> Understand how statuses and tags organize explores and boards.
Statuses and tags help your team organize explores and boards after the work has been created.
They are workspace-level labels, so everyone uses the same set of statuses and tags when reviewing work, finding trusted outputs, or grouping related analysis.
## Statuses
A status describes the current state of an explore or board.
Use statuses for labels where only one value should apply at a time, such as:
- **Trusted**
- **Needs review**
- **Draft**
Each explore or board can have one status. This makes statuses useful for workflow, quality, or readiness signals because there is a single answer to the question: what state is this work in right now?
## Tags
Tags describe what an explore or board is related to.
Use tags for labels where more than one value can apply at the same time, such as:
- A team
- A customer
- A project
- A metric area
- A recurring workflow
An explore or board can have multiple tags. This makes tags useful for grouping work across different contexts, such as finding everything related to a customer and a project.
## How they work together
Statuses and tags are meant to answer different questions:
- Status: what state is this work in?
- Tags: what is this work about?
For example, a board might have the **Trusted** status and the tags **Revenue**, **Leadership**, and **QBR**.
Admins manage the available statuses and tags in workspace settings. Once they are created, you can apply them from an explore or board and use them as filters in History.
## Connect your data
> A brief introduction to connecting your first datasource.
Querio needs a datasource before an agent can analyze your data. A datasource is usually a database or warehouse such as Snowflake, BigQuery, PostgreSQL, or Redshift.
## Before you start
You will usually need:
- A read-only user or service account
- The host, database, warehouse, schema, or project details for your datasource
- Permission to allow Querio's outbound IP if your network blocks external connections
## Connect a datasource
1. Open your workspace settings
2. Go to the datasources area
3. Add a new datasource
4. Choose the integration type
5. Add the required connection details
6. Test the connection
Once Querio can connect, it can generate a catalog from your datasource. The catalog helps the agent understand schemas, tables, columns, joins, and descriptions.
For detailed setup steps, see [Supported integrations](/connect-data/integrations).
## Create a layout
> Turn useful notebook results into a layout.
Layouts help you turn an explore into something easier to read and share.
You can add cells from the notebook to a layout, then arrange and resize them on a grid.
## When to use a layout
Use a layout when you want to:
- Share a cleaner view of several results
- Keep a live view of the most important cells from an explore
- Turn a conversation into something closer to a report
## Create a layout
1. Open an explore
2. Choose the cells you want to include
3. Add them to a layout
4. Arrange the cells on the grid
5. Share the explore or layout link with your team
The layout stays connected to the explore, so you can continue editing the notebook and update the layout as the work changes.
## Getting started
> A brief overview of what Querio is and how to get started.
Querio is an analytics workspace where agents work with your data, help your team analyze results, and turn useful work into reusable context, notebooks, and layouts.
The main workflow is simple:
1. Connect a datasource
2. Start an explore
3. Review the notebook Querio creates
4. Add context so future analysis gets better
5. Share the work through links, layouts, Slack, or embedded experiences
## The main concepts
**Explore** is the workspace for an analysis. Each explore has a conversation with the agent and a notebook where the work is captured.
**Notebook cells** are the individual outputs Querio creates. A cell can contain SQL, Python, Markdown, a table, or a visualization.
**Context** is the knowledge Querio uses to understand your data and business. This includes your catalog, knowledge base, skills, and memory.
**Layouts** turn notebook results into a cleaner view you can share with others.
## Where to go next
If you are setting up Querio, go to [Connect your data](/getting-started/connect-your-data).
If your data is already connected, go to [Run your first explore](/getting-started/run-your-first-explore).
## Run your first explore
> A brief introduction to exploring data with Querio.
An explore starts with the analysis you want Querio to run.
Describe the work you want Querio to do and send it. Querio will read the available context, choose the data it needs, and create notebook cells that show its work.
## Write a good first request
Good requests are specific. Include the metric, timeframe, and any filters you care about.
Examples:
- "Show monthly revenue for the last 12 months."
- "What were the top 10 customers by order volume last quarter?"
- "Compare conversion rate by acquisition channel this year."
## Review the work
After Querio responds, review both parts of the explore:
- The chat explains what the agent did and lets you continue the analysis
- The notebook shows the SQL, Python, charts, tables, and text created during the analysis
If something is wrong or missing, send a follow-up. Querio will continue from the same explore.
## Keep useful results
When a result is important, bookmark it or add it to a layout. You can always come back to the explore later from History.
## Share your results
> A brief introduction to links, bookmarks, and layouts.
Querio gives you a few ways to share work depending on what you want someone else to see.
## Share a link
Use a link when you want someone to open the explore and see the full context: chat, notebook, and layout.
Explores are private by default. You can share access with specific teammates or groups from the **Share** menu, which will send them an email notification.
You can also generate a **public link** from the Share menu to share your results with anyone outside of your workspace.
## Use bookmarks
Use bookmarks when you want to mark important notebook cells so they are easy to find again later.
## Use layouts
Use layouts when you want a cleaner view of selected cells. Layouts are useful when an explore has become a report or recurring analysis.
## Use Slack
If your workspace has the Slack integration installed, you can start analysis from Slack. Querio will create an explore, reply in the thread, and include a button to open the full notebook.
## Automations
> Run an explore or a prompt on a schedule and deliver the results by email or Slack.
Automations run work for you on a recurring schedule — either refreshing an existing explore or running a new prompt — and can deliver the results by email or Slack.
Use them when a piece of analysis should run regularly instead of being triggered manually every time.
## Creating an automation
Open **Automations** from the sidebar, then click **New Automation**.
You can also create one directly from an explore: use **Schedule sync** to refresh that explore on a schedule. A new automation is created automatically and linked to it.
## The automation builder
Each automation has three parts: a **Trigger**, a **Workflow**, and an optional **Action**.
### Trigger — when it runs
The trigger is a schedule. Choose how often it runs — hourly, daily, weekly, or monthly — and pick a time of day (and the days, for weekly or monthly). Schedules run in the timezone you set.
If you need something more specific, switch to a cron expression and enter it directly.
### Workflow — what it does
Choose one of two workflows:
- **Explore sync** — re-runs an existing explore's notebook to refresh its results. Use this to keep a report or dashboard up to date. Pick the explore you want to sync.
- **Run a prompt** — starts a new explore from a prompt each time it runs. Provide the prompt, choose a model, and select the datasource(s) Querio should use. Use this for a recurring question where you want fresh analysis on every run.
### Action — where the results go
The action delivers the results after each run. It's optional — without one, the automation just refreshes the explore in place.
- **Send email** — enter one or more recipient email addresses.
- **Slack message** — choose a channel. You'll need to connect your Slack integration first.
## Managing automations
All automations appear in the **Automations** list. From there you can open, edit, run, or delete any automation.
Each automation is either **Live** (running on schedule) or **Draft** (paused). Only live automations run on their schedule — use **Publish** and **Unpublish** to switch between the two. Use **Test run** to run an automation once immediately and check the result before publishing.
You can also find automations in the Catalog, under the Automations folder.
## Scheduled syncs
Scheduled syncs are a type of automation. If you previously set up a sync from an explore, it will now appear in Automations. The old Notebook Sync tab in Settings has been removed.
## Share and operationalize
> Share explores and turn useful work into repeatable views.
Once an explore has useful results, you can share it or turn it into something more repeatable.
The main tools are links, layouts, bookmarks, and automations.
## Links
Use links when someone should open the full explore.
## Layouts
Use layouts when you want to present selected notebook cells in a cleaner grid.
## Automations
Use automations when an explore or a prompt should run on a schedule, with the results delivered by email or Slack.
## Layouts
> Create and edit layouts from notebook cells.
Layouts turn selected notebook cells into a cleaner view.
Use a layout when the explore has become something you want to share, monitor, or revisit often.
## Create a layout
1. Open an explore
2. Choose a cell you want to show
3. Add it to the layout
4. Repeat for any other cells you want to include
## Edit a layout
You can change which cells appear in the layout while keeping the full notebook behind it.
This is useful when some notebook cells are supporting work and others are the final outputs.
## Arrange cells
New cells added to a layout are automatically placed at the bottom, so they don't overlap existing content. You can then move and resize them on the grid to make the result easier to read.
The layout stays connected to the explore, so you can keep working in the same notebook.
## Links
> Share an explore with your team or publicly.
Sharing a link is the simplest way to share Querio work.
Use a link when the other person should see the full context: the conversation, the notebook, bookmarks, and any layout.
## Share internally
Explores are private to you by default.
To share an explore with someone in your workspace, open the explore, click the **Share** button, and grant access to specific teammates or groups (e.g. Viewer or Editor). They will receive an email notification. You can also copy the link from your browser and send it to them.
## Request access
If a teammate sends you a link to a private explore that you don't have access to, you will see a restricted access screen. Click **Request access** to send an email notification to the owner so they can grant you access.
## Share publicly
You can create a public link to share an explore with people outside of your Querio workspace.
Open the explore, click the **Share** button, and generate a public link. Anyone with this link can view the explore without needing a Querio account. You can revoke access to a public link at any time from the share menu.
## When to use links
Use links for:
- Asking a teammate to review an analysis
- Sending someone the full notebook
- Sharing work that is still changing
- Sending a one-off report to a client or stakeholder (public links)
## Context files and folders
> Understand the file-backed context model.
The Context area is organized like a file system.
Instead of editing disconnected rows of metadata, you can work with files and folders that represent what Querio knows.
## Why files
Files make context easier to manage because they are:
- Easier to browse
- Easier to edit
- Easier to review
- Easier to reason about as a complete workspace
## Common folders
You may see folders for datasources, skills, memory, extensions, and general files depending on your workspace.
The most important datasource-level folders are:
- Catalog
- Knowledge Base
Together, these teach Querio what exists in your data and how to use it correctly.
## Datasources
> Manage catalog and knowledge base for each datasource.
Each datasource can have its own context.
This lets Querio understand one datasource differently from another, even when the same business term appears in both places.
## Catalog
The catalog is a JSON-backed map of your datasource.
Querio turns it into UI tabs so it is easier to navigate, but conceptually it is one structured catalog file.
The catalog includes:
- Schemas
- Tables
- Columns
- Joins
- Descriptions
- Agent access controls
### Refreshing the catalog
When your underlying database schema changes, you can use the **Refresh** button in the Catalog view to sync those changes. Querio will only refresh tables you have already added to your catalog, rather than pulling the entire database again.
### Schemas
Schemas group tables inside a datasource.
Use schema descriptions to explain the broad purpose of a schema and when Querio should use it.
### Tables
Tables are the core objects Querio queries.
Use table descriptions to explain what the table represents, what grain it has, and when it should or should not be used.
### Columns
Columns describe the fields inside a table.
Use column descriptions to explain business meaning, expected values, and any caveats.
### Joins
Joins explain how tables relate to each other.
Good join context helps Querio avoid incorrect joins and makes multi-table analysis more reliable.
## Knowledge Base
The Knowledge Base contains context Querio reads to understand your business and data, as well as reusable building blocks.
When you create or edit a file in the Knowledge Base, you fill in three fields:
- **Title** — a short name for the file
- **Description** — what this file covers and when it is useful
- **Context type** — either **Always** or **Reference**
**Always** means Querio loads this file into every conversation automatically.
**Reference** means Querio only uses it when it decides the content is relevant.
Use Always for core definitions and rules your team applies constantly. Use Reference for things that apply to specific topics or edge cases.
Examples of what to put in the Knowledge Base:
- Metric definitions
- Business rules
- Data caveats
- SQL examples
- Python examples
- Team-specific analysis notes
### Frontmatter
Each Knowledge Base file starts with frontmatter that controls how Querio uses it. The format depends on the file type:
- `.md` files use a `---` block
- `.sql` files use `-- field: value` lines
- `.py` files use `# field: value` lines
Three fields are supported:
- `name` — a short title for the file
- `description` — one-line summary of what the file covers
- `context` — either `always` or `reference`
**`context: always`** means the full file body is included in Querio's prompt on every turn. Use this for rules, metric definitions, naming conventions, and hard constraints that must apply universally.
**`context: reference`** means only the file's name and description appear in the prompt index. Querio fetches the full content when a question matches. Use this for query templates, SQL examples, and situational context that only applies sometimes.
New files in the Knowledge Base default to `context: reference` to keep the prompt lean. Promote to `context: always` only when the content needs to apply on every single turn.
### How Querio saves context for you
When you share a fact, correction, or hard-won query during an analysis, Querio will offer to save it to the Knowledge Base at the end of its response. It names the destination file and waits for your approval before writing anything.
You can decline. If you do, it won't offer again in that session.
## Teach Querio about your data
> Add context so Querio understands your data and business.
Querio gets better when you teach it how your data and business work.
The Context area is where this knowledge lives. It uses a file-backed workspace where context is easy to inspect, edit, and organize.
## What context is for
Context helps Querio understand:
- What tables and columns mean
- How tables join together
- Which metrics matter
- How your team defines business terms
- What reusable logic or skills the agent should follow
## Main types of context
The Context tab is organized into five main sections:
- **Datasources**: Contains context tied to specific databases. For each database, you'll find:
- **Catalog**: Your tables and schema structure.
- **Knowledge Base**: Executable files (like `.py` scripts or logic blocks) that define metrics, rules, and business logic tied to this data.
- **Memory**: Stores durable workspace-level notes (like `MEMORY.md`) that Querio can reference across all conversations.
- **Extensions**: Custom plugins and integrations that expand Querio's capabilities.
- **Skills**: Reusable instructions (e.g., `compare-periods`, `data-dictionary`) that teach Querio exactly how to perform specific, repeatable tasks.
- **Files**: Arbitrary workspace files outside of standard categories. You can view and edit any other files or folders in your workspace here.
The goal is to make Querio less dependent on one-off request detail and more aware of the way your team actually works.
## Memory
> Store durable workspace-level context for Querio.
Memory is for context Querio should remember across future work.
Use memory for stable facts that are not specific to one explore.
Examples:
- Company-specific terminology
- Important business rules
- Team preferences
- Known data caveats
Keep memory concise. If the context belongs to a specific datasource, it is usually better as catalog metadata or a file in the Knowledge Base.
## Skills
> Teach Querio repeatable ways to perform tasks.
Skills are instructions for how Querio should do a specific kind of work.
Use skills when you want the agent to follow a repeatable process.
Examples:
- Apply your team's date rules
- Compare two periods consistently
- Validate analysis before presenting it
- Refine an ambiguous request before querying data
Skills are useful when the instruction is not tied to one table or one datasource, but to how Querio should behave.
## Install a skill package
You can add a prepared skill to your workspace from the **Skills** folder in
Context.
1. Open **Context**, then select **Skills**.
2. Drag one or more `.skill` files into the page, or select the upload button
beside the Skills heading.
3. Choose the `.skill` package files to install.
Each package contains a `SKILL.md` file and can also include supporting
scripts, references, or assets. Once installed, the skill appears in the Skills
folder and is available to Querio in that workspace.
## Authentication
> Bearer token authentication for the Embedded API.
All v2 Embedded API endpoints require a Bearer token in the Authorization header.
```http
Authorization: Bearer
```
## Create a token
Create API tokens in Querio under Embedded API token management.
Store tokens securely and rotate them if you believe one has been exposed.
## Example request
```bash
curl -X POST https://app.querio.ai/api/v2/embed/{customer_slug}/conversations \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"prompt": "How many shipments happened in the last 30 days",
"datasourceId": "your_dataset_id",
"environment": "production"
}'
```
## Continue a conversation
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## Control Center
> Manage, test, and monitor your Embedded API integration.
The Control Center helps you test and monitor Embedded API usage.
## Testing
Use the testing area to create test runs before going to production.
When you create a test run, Querio shows the request that will be sent and the response shape you should expect.
## Metadata
Embedded datasets need context just like normal Querio datasources.
Use metadata management to explain tables, columns, joins, and business rules so the embedded agent can produce accurate analysis.
## Production requests
Production requests show the work customers are sending to Querio through your integration.
Use this to inspect usage, debug unexpected results, and understand how users work with your embedded experience.
## Get a conversation
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## Get an asset
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## API introduction
> Integrate Querio's agentic data analysis directly into your apps with the Embedded API.
import { PostmanButton } from "@/components/PostmanButton";
The Embedded API lets you integrate Querio's agentic data analysis directly into your own product.
The current API version is **v2**. It is built around conversations, multi-turn follow-ups, and asset-backed charts and tables.
v2 supports both testing and production environments, so you can validate your integration before sending production traffic through it.
## Quick start
1. Create an API token in Querio under Embedded API token management
2. Make your first request:
```bash
curl -X POST https://app.querio.ai/api/v2/embed/{customer_slug}/conversations \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"prompt": "How many shipments happened in the last 30 days",
"datasourceId": "your_dataset_id",
"model": "claude-sonnet-5",
"scope": {
"customer_id": "your_customer_id"
},
"environment": "production",
"tags": {
"user_id": "your_user_id"
}
}'
```
## API v2: conversations
v2 introduces **conversations** as the top-level entity.
A conversation stores the full message history. Each user-assistant pair is a **turn**. This enables multi-turn follow-ups, tagging for filtering and organization, and structured assets for tables and charts returned in assistant message parts.
- [**POST** `/v2/embed/{customer_slug}/conversations`](/embed/api/start-a-conversation) - Start a new conversation
- [**POST** `/v2/embed/{customer_slug}/conversations/{conversationId}/turns`](/embed/api/continue-a-conversation) - Add a follow-up turn
- [**GET** `/v2/embed/{customer_slug}/conversations`](/embed/api/list-conversations) - List conversations with filtering and pagination
- [**GET** `/v2/embed/{customer_slug}/conversations/{conversationId}`](/embed/api/get-a-conversation) - Get a conversation and its full message history
- [**GET** `/v2/embed/{customer_slug}/conversations/{conversationId}/assets/{cellId}`](/embed/api/get-an-asset) - Fetch table data or Vega-Lite chart assets referenced by message parts
## Message parts and assets
Assistant messages can include structured parts in addition to plain text:
- `text` - plain text content to render directly
- `data-table` - a reference to a paginated table asset
- `data-chart` - a reference to a Vega-Lite chart asset
For `data-table` and `data-chart` parts, use the returned `url` to fetch the full asset payload.
Each endpoint page includes interactive examples and detailed request and response schemas.
**Customer-specific endpoints**: All endpoints include `{customer_slug}` as a path parameter. Use the slug assigned to your organization.
## Authentication
All v2 endpoints require a Bearer token in the Authorization header:
```http
Authorization: Bearer
```
Create API tokens in Querio under Embedded API token management. No client ID or client secret is involved in the auth header.
## Additional resources
### Run in Postman
Import the collection directly into your Postman workspace with one click:
### OpenAPI spec
Use the OpenAPI file with other API clients like Insomnia:
- [openapi-v2.yml](/embedded/openapi-v2.yml)
## List conversations
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## Start a conversation
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## BigQuery
> Connect BigQuery to Querio.
## 1. Create a service account
**What**: Create a service account so Querio can securely access BigQuery.
**How**:
1. Go to Google Cloud Console > IAM & Admin > Service Accounts
2. Click **Create service account**
3. Name it something clear, like `querio-data-access`
4. Add a description if helpful
5. Click **Create and continue**
## 2. Assign required roles
**What**: Give the service account permission to run jobs and read the datasets Querio should query.
**How**:
1. Add the **BigQuery Job User** role
2. Add **BigQuery Data Viewer** at the project level or only on the specific datasets Querio should access
3. Add **BigQuery Read Session User** role
If you do not want Querio to access every dataset in the project, only grant **BigQuery Data Viewer** on the specific datasets. The **BigQuery Job User** and **BigQuery Read Session User** roles are still needed at the project level.
## 3. Create a JSON key
**What**: Generate the key file Querio uses to authenticate.
**How**:
1. Open the service account
2. Go to **Keys**
3. Click **Add key** > **Create new key**
4. Choose **JSON**
5. Download the file and store it securely
## 4. Share the key securely
Share the JSON key with Querio using a secure transfer method.
## 5. Optional: grant dataset-specific access
If you are scoping access by dataset:
1. Open BigQuery in Google Cloud Console
2. Open the dataset Querio should access
3. Go to **Sharing** > **Permissions**
4. Add the service account email
5. Grant **BigQuery Data Viewer**
Make sure to grant access on the **dataset**, not on individual tables. Table-level permissions won't expose `INFORMATION_SCHEMA` and Querio won't be able to discover your schema.
## ClickHouse
> Connect ClickHouse to Querio.
## 1. Create a dedicated user
**What**: Create a non-human ClickHouse user for Querio.
```sql
CREATE USER querio_user IDENTIFIED BY 'STRONG_PASSWORD';
```
Use a long random password and store it securely.
## 2. Grant read-only access
**What**: Give Querio read access to the database it should query.
```sql
GRANT SELECT ON my_database.* TO querio_user;
```
Repeat grants for each database Querio should access. For tighter access, grant permissions on specific tables.
## 3. Share connection details
Provide:
- Host
- Username
- Password
- Secure (use TLS — defaults to enabled)
- Verify SSL certificate (defaults to enabled)
## Databricks
> Connect Databricks to Querio.
## Before you start
You need a Databricks workspace with a SQL Warehouse or cluster, plus a token or service principal with access to the catalog and schema Querio should query.
## 1. Create an access token
**What**: Create a token Querio can use to authenticate.
**How**:
1. In Databricks, open your user settings
2. Go to **Developer** > **Access tokens**
3. Click **Generate new token**
4. Give it a clear description
5. Copy the token and store it securely
For production, use a service principal when possible.
## 2. Find connection details
**What**: Get the server hostname and HTTP path.
**How**:
1. Go to **SQL Warehouses**
2. Open the warehouse Querio should use
3. Open **Connection details**
4. Copy the **Server hostname** and **HTTP path**
## 3. Grant catalog and schema permissions
**What**: Give the token identity read access to the target catalog and schema.
```sql
GRANT USE CATALOG ON CATALOG my_catalog TO `querio-service-principal@domain.com`;
GRANT USE SCHEMA ON SCHEMA my_catalog.my_schema TO `querio-service-principal@domain.com`;
GRANT SELECT ON SCHEMA my_catalog.my_schema TO `querio-service-principal@domain.com`;
```
## 4. Share the connection details
Provide the token, server hostname, HTTP path, catalog, and schema to Querio.
## Supported integrations
> Datasources Querio can connect to.
Querio connects to the databases and warehouses your team already uses.
If your database is behind a firewall, see [Allowlist Querio IPs](/connect-data/allowlist-querio-ips).
## MariaDB
> Connect MariaDB to Querio.
## 1. Create a dedicated user
**What**: Create a non-human MariaDB user for Querio.
```sql
CREATE USER 'querio_user'@'%' IDENTIFIED BY 'STRONG_PASSWORD';
```
You can replace `%` with Querio's IP address for tighter network access.
## 2. Grant read-only access
**What**: Give Querio access to the database it should query.
```sql
GRANT SELECT ON my_database.* TO 'querio_user'@'%';
FLUSH PRIVILEGES;
```
For tighter access, grant permissions on specific tables instead of the whole database.
## 3. Share connection details
Provide:
- Username
- Password
- Host
- Port, usually `3306`
- Database
Connection string format:
```text
mysql://:@:/
```
## MongoDB Atlas
> Connect MongoDB Atlas to Querio using Atlas SQL.
Querio connects to MongoDB Atlas using its native Atlas SQL interface. This lets you query your Atlas collections using standard SQL, without moving data to another warehouse.
## 1. Get connection details
To connect, you need an Atlas SQL connection string.
You can find this in the Atlas UI by clicking **Connect** on your cluster, selecting **Atlas SQL**, and choosing the ODBC driver option to view the connection details.
Provide Querio with:
- **Server:** Your Atlas cluster connection string
- **Database:** The database name you want to query
- **Username:** Your Atlas database user
- **Password:** The password for the user
## Note on permissions
The database user you provide to Querio must have read access to the database you want to query.
## MotherDuck
> Connect MotherDuck or DuckDB to Querio.
## 1. Create a MotherDuck service token
**What**: Create a token Querio can use to connect.
**How**:
1. Log in to MotherDuck
2. Go to **Settings** > **Service Tokens**
3. Click **Create Service Token**
4. Give it a descriptive name
5. Copy the token and store it securely
## 2. Grant read-only access
**What**: Limit Querio to the databases and schemas it should query.
```sql
GRANT SELECT ON ALL TABLES IN DATABASE my_database TO querio_service_token;
GRANT SELECT ON ALL TABLES IN SCHEMA my_database.my_schema TO querio_service_token;
```
Adjust the database and schema names for your setup.
## 3. Share connection details
For MotherDuck, provide the service token and database name.
Connection string format:
```text
md:?motherduck_token=
```
## SQL Server
> Connect Microsoft SQL Server to Querio.
## 1. Create a dedicated login
**What**: Create a SQL Server login for Querio.
```sql
CREATE LOGIN querio_user WITH PASSWORD = 'STRONG_PASSWORD';
```
## 2. Create a database user
**What**: Map the login to the database Querio should query.
```sql
USE my_database;
CREATE USER querio_user FOR LOGIN querio_user;
```
## 3. Grant read-only access
**What**: Give Querio read-only access to the database.
```sql
ALTER ROLE db_datareader ADD MEMBER querio_user;
```
## 4. Share connection details
Provide:
- Server host
- Port, usually `1433`
- Database
- Username
- Password
Connection string format:
```text
mssql+pyodbc://:@:1433/?driver=FreeTDS&TDS_Version=8.0
```
URL-encode any special characters in the username or password (e.g. `@` becomes `%40`). Querio's sandbox uses the FreeTDS ODBC driver — the `driver=FreeTDS` query parameter is required.
## MySQL
> Connect MySQL to Querio.
## 1. Create a dedicated user
**What**: Create a non-human MySQL user for Querio.
```sql
CREATE USER 'querio_user'@'%' IDENTIFIED BY 'STRONG_PASSWORD';
```
You can replace `%` with Querio's IP address for tighter network access.
## 2. Grant read-only access
**What**: Give Querio access to the database it should query.
```sql
GRANT SELECT ON my_database.* TO 'querio_user'@'%';
FLUSH PRIVILEGES;
```
For tighter access, grant permissions on specific tables instead of the whole database.
## 3. Share connection details
Provide:
- Username
- Password
- Host
- Port, usually `3306`
- Database
Connection string format:
```text
mysql://:@:/
```
## PostgreSQL
> Connect PostgreSQL to Querio.
## 1. Create a dedicated user
**What**: Create a non-human PostgreSQL user for Querio.
```sql
CREATE USER querio_user WITH PASSWORD 'STRONG_PASSWORD';
```
## 2. Grant read-only access
**What**: Give Querio access to the database and schemas it should query.
```sql
GRANT CONNECT ON DATABASE my_database TO querio_user;
GRANT USAGE ON SCHEMA public TO querio_user;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO querio_user;
ALTER DEFAULT PRIVILEGES IN SCHEMA public
GRANT SELECT ON TABLES TO querio_user;
```
Repeat the schema grants for each schema Querio should access.
## 3. Share connection details
Provide:
- Username
- Password
- Host
- Port, usually `5432`
- Database
- Schema (optional, defaults to public)
Connection string format:
```text
postgresql://:@:/
```
## Redshift
> Connect Redshift to Querio.
## 1. Create a read-only user
**What**: Create the database user Querio will use.
```sql
CREATE USER querio_reader WITH PASSWORD '';
```
You must run this as a superuser or an admin role with permission to create users.
## 2. Grant schema access
**What**: Give Querio read access to the schemas it should query.
```sql
GRANT USAGE ON SCHEMA your_schema TO querio_reader;
GRANT SELECT ON ALL TABLES IN SCHEMA your_schema TO querio_reader;
ALTER DEFAULT PRIVILEGES IN SCHEMA your_schema
GRANT SELECT ON TABLES TO querio_reader;
```
Repeat this for each schema Querio should access.
## 3. Grant metadata access
**What**: Let Querio inspect the metadata it needs to understand tables and columns.
```sql
GRANT USAGE ON SCHEMA information_schema TO querio_reader;
GRANT SELECT ON ALL TABLES IN SCHEMA information_schema TO querio_reader;
```
## 4. Allowlist Querio's IP
Allow Querio's outbound IP to reach your Redshift cluster on port `5439`.
## 5. Share connection details
Provide the host, port, database, username, password, and SSL requirements to Querio.
## SAP HANA
> Connect SAP HANA to Querio.
## 1. Create a dedicated user
**What**: Create a non-human user in SAP HANA for Querio.
```sql
CREATE USER QUERIO_USER PASSWORD "STRONG_PASSWORD" NO FORCE_FIRST_PASSWORD_CHANGE;
```
## 2. Grant read-only access
**What**: Give Querio SELECT access to the specific schemas it should query.
```sql
GRANT SELECT ON SCHEMA "MY_SCHEMA" TO QUERIO_USER;
```
Repeat the grant for each schema Querio should access.
## 3. Share connection details
Provide:
- Username
- Password
- Host
- Port, usually `443` or `39015` (depends on your HANA Cloud or on-premise setup)
- Schema (optional, used as default schema)
Connection string format:
```text
hana://:@:?encrypt=true&sslValidateCertificate=true
```
## Snowflake
> Connect Snowflake to Querio.
## Before you start
You need a Snowflake admin role that can create users, roles, and grants. You also need the RSA public key Querio will use for key-pair authentication.
## 1. Create a service user
**What**: Create a non-human Snowflake user for Querio.
```sql
CREATE USER QUERIO_SVC
LOGIN_NAME = QUERIO_SVC
TYPE = SERVICE
DEFAULT_ROLE = QUERIO_ROLE
DEFAULT_WAREHOUSE = QUERIO_WH
DEFAULT_NAMESPACE = MY_DATABASE.PUBLIC
COMMENT = 'Service user for Querio integration';
```
## 2. Create a least-privilege role
**What**: Give Querio only the permissions it needs.
```sql
CREATE ROLE IF NOT EXISTS QUERIO_ROLE;
GRANT USAGE ON WAREHOUSE QUERIO_WH TO ROLE QUERIO_ROLE;
GRANT USAGE ON DATABASE MY_DATABASE TO ROLE QUERIO_ROLE;
GRANT USAGE ON SCHEMA MY_DATABASE.PUBLIC TO ROLE QUERIO_ROLE;
GRANT SELECT ON ALL TABLES IN SCHEMA MY_DATABASE.PUBLIC TO ROLE QUERIO_ROLE;
GRANT SELECT ON ALL VIEWS IN SCHEMA MY_DATABASE.PUBLIC TO ROLE QUERIO_ROLE;
GRANT SELECT ON FUTURE TABLES IN SCHEMA MY_DATABASE.PUBLIC TO ROLE QUERIO_ROLE;
GRANT SELECT ON FUTURE VIEWS IN SCHEMA MY_DATABASE.PUBLIC TO ROLE QUERIO_ROLE;
GRANT ROLE QUERIO_ROLE TO USER QUERIO_SVC;
```
Scope these grants to the databases and schemas Querio should read.
## 3. Add the RSA public key
**What**: Register the public key on the service user. Querio displays the RSA public key in the datasource setup screen — copy it from there and paste it into the ALTER USER statement below.
```sql
ALTER USER QUERIO_SVC SET RSA_PUBLIC_KEY='MIIBIjANBgkqh...';
DESC USER QUERIO_SVC;
```
Snowflake expects the base64 content of the public key without the `BEGIN PUBLIC KEY` and `END PUBLIC KEY` lines. The value Querio shows in the UI is already in this correct base64-only form (no headers).
## 4. Share the connection metadata
Provide the account, user, warehouse, database, and schema to Querio.
```json
{
"account": "orgname-account_name",
"user": "QUERIO_SVC",
"warehouse": "QUERIO_WH",
"database": "MY_DATABASE",
"schema": "PUBLIC"
}
```
## SSH Tunnel
> Connect through an SSH bastion or jump host.
Use an SSH tunnel when your database is in a private network reachable only via a bastion host.
## Prerequisites
* A Linux or macOS bastion host that has network access to the target database.
* The database must be one of the supported types (PostgreSQL or MySQL). No other database types are supported through the SSH tunnel right now.
## 1. Create a dedicated SSH user
**What**: Create a dedicated SSH user on the bastion for Querio.
```bash
sudo adduser --disabled-password --gecos "" querio
sudo mkdir -p /home/querio/.ssh
sudo chmod 700 /home/querio/.ssh
```
## 2. Generate an SSH keypair
**What**: Generate an SSH keypair for Querio to use.
```bash
ssh-keygen -t ed25519 -C "querio-tunnel" -f querio_tunnel
```
This command produces two files: `querio_tunnel` (the private key, which you will give to Querio) and `querio_tunnel.pub` (the public key, which you will install on the bastion).
## 3. Authorize the public key
**What**: Add the public key to the bastion's authorized keys list.
```bash
sudo tee -a /home/querio/.ssh/authorized_keys < querio_tunnel.pub
sudo chown -R querio:querio /home/querio/.ssh
sudo chmod 600 /home/querio/.ssh/authorized_keys
```
**Optional hardening**: In `/etc/ssh/sshd_config.d/querio.conf`, you can restrict the user:
```text
Match User querio
AllowTcpForwarding yes
PermitOpen :
ForceCommand /usr/sbin/nologin
X11Forwarding no
```
## 4. Allowlist Querio
**What**: Allow Querio's outbound IP on the bastion's firewall for SSH (typically port 22).
## 5. Create the database user
**What**: Create a dedicated database user and grant read-only access.
Depending on your database, follow the steps on the [PostgreSQL](/connect-data/integrations/postgresql) or [MySQL](/connect-data/integrations/mysql) integration page. The SQL grants are identical, just executed against the database that lives behind the bastion.
## 6. Share connection details
Querio will ask for two groups of fields in the connection form:
**SSH Tunnel:**
* **SSH Host**: The address of the bastion host (e.g. `bastion.example.com`).
* **SSH Port**: The port the bastion is listening on (defaults to 22).
* **SSH Username**: The dedicated SSH user (e.g. `querio`).
* **Private Key**: The full PEM contents of the `querio_tunnel` file, including the `-----BEGIN ... PRIVATE KEY-----` and `-----END ... PRIVATE KEY-----` markers.
* **Destination Host**: The database hostname as seen from the bastion (often `localhost` or a private IP).
* **Destination Port**: The database port (e.g. 5432 for Postgres, 3306 for MySQL).
**Database (behind tunnel):**
* **Database Client**: `postgres` or `mysql`.
* **Database Name**: The target database name.
* **Database Username**: The read-only database user.
* **Database Password**: The password for the database user.
* **Database Schema**: The schema to query (PostgreSQL only; defaults to `public`).
## Troubleshooting
* **"permission denied (publickey)"**: Check the ownership and permissions of the `/home/querio/.ssh/authorized_keys` file.
* **"channel ... open failed: administratively prohibited"**: `AllowTcpForwarding` might be disabled, or `PermitOpen` in the sshd configuration excludes the target database host/port.
* **"connection refused" on the destination**: The database isn't listening on the specified `Destination Host`:`Destination Port` from the bastion's perspective.
