Why use data queries
Data queries solve a common problem: you have a complex query that multiple apps need, and you do not want to duplicate it everywhere. For example, your team might need a query that calculates monthly recurring revenue from your billing database. Rather than writing and maintaining that query in each app separately, you save it as a data query called “Monthly MRR” and reference it anywhere. Benefits of data queries:- Reusable — Write once, use in any app across your organization
- Consistent — Every app uses the same query logic, so results are always consistent
- Maintainable — Update the query in one place and all apps pick up the change
- Shareable — Any team member in your organization can use saved queries
Query types
Data queries support two types of data sources:| Type | Data source | Use case |
|---|---|---|
| SQL queries | Connected external databases (PostgreSQL, MySQL, Redshift) | Query your existing database tables |
| API queries | Connected integration services | Fetch data from third-party services |
Creating a data query
Open the Integrations page
Navigate to Integrations in the left sidebar and scroll to the Data Queries section.
Select the data source
Choose which connected database or integration service the query should run against. Only databases and integrations that are already connected to your organization appear here.
Write and name the query
Give your query a unique name and write the query itself. For SQL queries, write standard SQL for your database type. For API queries, configure the request parameters.Query names must be unique within your organization. Use descriptive names that make the query’s purpose clear:
monthly-mrrinstead ofquery1active-users-last-30-daysinstead ofusersopen-support-ticketsinstead oftickets
Using data queries
Once saved, data queries can be used in several ways:In the AI chat
The AI can execute your saved data queries during a conversation. Reference the query by name:Run the “monthly-mrr” data query and show me the results.
What does the “active-users-last-30-days” query return right now?The AI identifies the saved query, executes it against the configured data source, and displays the results inline.
In app code
The AI can generate code that references your saved data queries when building app features. When you describe what your app needs, the AI may use an existing data query rather than writing a new query from scratch.Across multiple apps
Because data queries are organization-scoped, any app in your workspace can use them. This is particularly useful when multiple apps need the same data — for example, a dashboard app and a reporting app that both need the same revenue metrics.Managing data queries
From the Data Queries section on the Integrations page, you can:- Edit — Update the query logic or rename it. Changes apply everywhere the query is used.
- Test — Run the query and preview the results before using it in an app.
- Delete — Remove a query you no longer need. Apps that reference a deleted query will need to be updated.
Deleting a data query does not automatically update apps that reference it. If you delete a query that apps depend on, those apps will encounter errors until you update them.
Best practices
- Use descriptive names. Query names should make their purpose obvious without needing to read the SQL.
- Start with the AI chat. Test a query in the chat first, then save it as a data query once you are happy with the results.
- Keep queries focused. A single data query should answer one question. If you find yourself writing a query that does too many things, split it into multiple queries.
- Document complex queries. For queries with non-obvious logic (joins across many tables, calculated fields), add a clear name and consider mentioning the purpose when you create it so other team members understand what it does.