Clarity's Query tool lets you define ad-hoc metrics by asking questions in plain English. THEO translates those questions into SQL against your synchronized PSA data, runs the query, and returns a chart or table. Queries you use regularly can be saved and reused without retyping.
This is how you go beyond the built-in metrics to answer specific questions about your business.
Asking a Custom Question
- Go to Query in Clarity.
- Type your question in plain English. Examples:
- "What was MRR last month compared to the prior month?"
- "Which technician logged the most billable hours this quarter?"
- "Show me clients with more than 10 open tickets older than 30 days."
- Click Run. Results stream in as THEO processes the query.
- Results appear as a table or chart depending on the shape of the data.
THEO uses your vertical context (MSP or Legal) to frame queries appropriately, and injects industry-estimate benchmarks when relevant.
Saving a Query
- After running a query, click Save.
- Give it a name and optional description.
- Saved queries appear under Query > Saved Queries.
- Click any saved query to run it again immediately.
- To remove a saved query, open it and click Delete.
Using Suggestions
If you are not sure what to ask, click Suggestions. Clarity shows common questions relevant to your vertical — a practical starting point for exploring your data.
Adding a Query to a Dashboard
Custom query results can be added to a dashboard as a widget. After saving a query, go to your dashboard, click Add Widget, and select the saved query from your library. The widget will re-run the query each time the dashboard loads.
Limits
Natural-language queries are rate-limited to 20 per minute per organization. This limit exists to keep AI processing costs predictable. If you hit the limit, wait a minute and retry.
FAQ
Can I edit the SQL THEO generates? The Query interface works at the natural-language level — you type questions, not SQL. THEO generates the SQL internally. If a query returns unexpected results, try rephrasing the question with more specific terms.
What data can custom queries access? Queries run against the data Clarity has synced from your PSA: tickets, time entries, contracts, invoices, and company records. The data available is limited to what has been synced and is current to within 15 minutes.
My query returned an error. What should I do? Try simplifying or rephrasing the question. Complex or ambiguous questions sometimes produce SQL that cannot execute. If THEO is not configured (no AI service URL set), all NL queries will fail — contact your platform admin.