Explore and query metrics
Ask for metrics by name, trend them by day, week or month, split and filter them, and save charts that follow the metric definitions.
A metric query asks for metrics by name, instead of spelling out SQL: “Revenue and Orders, by month, split by plan, for the last 90 days.” Orcabase writes the SQL for your database from the current definitions every time it runs.
Explore a metric
Open any metric and go to its Explore tab. It charts the metric, and you can change the question with a few controls:
| Control | What it does |
|---|---|
| Metrics | Add more metrics to see them side by side, like Revenue and Orders. |
| Range | Last 7 days, 30 days, 90 days, 12 months, or all time. |
| Trend by | The time grain: day, week, month, quarter or year. Or no trend, for a single total. |
| Split by | Break the numbers down by a dimension, like plan or country. |
| Where | Filters, like country is one of VN, SG. Numbers and dates also compare with >, ≥, < and ≤; text can match with contains. |
Switch between the Chart and the Table, and click SQL to see exactly what ran. If you’ve edited the metric but not saved it, Explore still shows the saved definition.
Save it as a query
When the view is right, click Save as query and name it. It becomes a saved query of the metric kind: give it a chart, pin it to a dashboard, or open it from the Queries page, where the same controls replace the SQL editor.
Because a metric query stores names, not SQL, it follows the definitions: change how Revenue is calculated, and every saved metric query asking for Revenue picks up the change on its next run. Renaming a metric or a field updates saved metric queries for you.
Convert to SQL
Need something the controls can’t express? Convert to SQL, on a metric query’s page, turns it into an ordinary SQL query, starting from the SQL Orcabase wrote. It stops following the metric definitions from then on.
What the result looks like
Result columns are named after what you asked for, so charts map onto them naturally. Revenue by month, split by plan, comes back as:
created_at__month plan revenue
2025-06-01 Monthly 31,420
2025-06-01 Sampler 8,150
2025-07-01 Monthly 33,080
…A time dimension at a grain is named dimension__grain, like created_at__month.
Rules that keep numbers right
- No double-counting. A metric can be split or filtered by its own model’s dimensions, and by models it reaches through many → one or one → one joins. Across a one → many join, Orcabase refuses and explains why. See Correct or loud.
- Clear errors. Ask for a metric or field that doesn’t exist, or a grain a dimension doesn’t allow, and the error lists the valid options.
- Safe values. Filter values are sent to the database as parameters, never pasted into the SQL.
- UTC time. Grains and ranges are counted in UTC. “Last 30 days” is worked out when the query runs, so a saved query always means the most recent 30 days.
- The usual limits. At most 5,000 rows, and 30 seconds. A fine grain over a long range with a split can hit the row limit: use a coarser grain or a shorter range.
Something unclear or missing? Troubleshooting covers the common errors, or message us.