Querying results
What you'll learn
- What are queries?
- How to write queries (without auto-completion)
Apilicious uses a proprietary DSL (Domain Specific Language) to query then visualise test results. If you are familiar with SQL (Structured Query Language), you will be familiar with it.
All visualisations are compatible with the DSL, which is ultimately used to build highly customised dashboards.
To get you started, all test suites have several pre-built dashboards which demonstrate the capabilities of querying. Additionally, visualisations on the "Results" page can be saved as dashboards.
When writing your own queries, the console will help you with auto-completion.
How queries work
Each query is built of several parts, each of which are chained together and applied one at a time.
Grouped and flattened results can
WHERE report:latest ORDER BY time DESC TOP 100 GROUP BY path GROUP BY method ORDER BY time.max DESC SELECT time.max |
|
Queries can be quickly built in real-time with the assistance of auto-completion
Query syntax
The follow syntax is available for queries,
| TOP (number) | Take (number) results from the top of the stack |
| BOTTOM (number) | Take (number) results from the bottom of the stack |
| BETWEEN (from) AND (to) | Filter results between (from) and (to) |
| WHERE (filter) (filter) (filter)... | Only includes results that match (filter) |
| IGNORE (filter) (filter) (filter)... | Ignore all results that match (filter) |
| GROUP BY (field) | Aggregate results. Can only be applied once per query. |
| GROUP BY INTERVAL:(interval) | Groups data based an an interval |
| ORDER BY (field) (ASC/DESC) | Sort results by (field) |
| SELECT (field) | Controls the metric, defaults to num_results for aggregated data, or time for results |
| FLATTEN | Flatten an aggregated results back into a regular result set |
Query examples
Use the following queries as a template to see how these rules can work together.
| BOTTOM 1000 | Take the latest 1000 results |
| WHERE status:fail GROUP BY path BOTTOM 10 | List latest failures of each path |
| WHERE response:500 | List all 500 failures |
| WHERE path:/suites path:/reports ORDER BY timestamp LIMIT 10 | List the slowest responses of /suites and /reports |
| ORDER BY timestamp ASC GROUP BY report BOTTOM 20 | Group by report (latest reports to the right) |
| WHERE status:fail GROUP BY operation | |
| BETWEEN 2020-01-01 00:00:00 AND NOW | List all results since 2020-01-01 00:00:00 |
| WHERE report:latest | List results belonging to the latest report |
The default dashboards contain a range of queries which can serve to inspire your dashboards.
Query values
Variables accept the following forms, which mostly match to the shape of a SimpleResult
| WHERE/IGNORE (filter) | report:rep_123 method:GET path:/suites scenario:Baseline template:{?id}{&suite_id} server:"http://example.com" message:"404 is not a successful response code" |
| BETWEEN (from) AND (to) | See time range filtering |
| ORDER BY (field) | time timestamp server path operation status method size |
| SELECT (aggregated) | num_results test_status.(success/fail/rate) time.(min/max/avg/sum) size.(min/max/avg/sum) |
| ORDER BY (aggregated) | label num_results time.(min/avg/max/sum) test_status.(success/fail/rate) response_status.(2xx/3xx/4xx/5xx) size.(min/max/avg/sum) |
| GROUP BY (field) | report server method path operation query status response scenario signature message |
Time range filtering
The BETWEEN query accepts two times, which accept various formats.
Common time formats
Time formats that can be parsed with javascript's new Date({time}) are supported. This supports the most common date formats, based on the browser's locale.
Examples of supported times,
| The year 2022 | BETWEEN 2022 AND 2023 | |
| January 2022 | BETWEEN 2022-01-01 AND 2020-02-01 | |
| January 2022 | BETWEEN 2022/01/01 AND 2022/02/01 | |
| 1st January 2022, 3-5pm | BETWEEN 2022/01/01 15:00:00 AND 2022/01/02 17:00:00 |
Relative time ranges
Times can be chained with modifiers that can be used to refine the date range as intended.
The following time units are accepted: s (seconds), m (minutes), h (hours) d (days), w (weeks), M (months), Q (quarters) and y (years). Multiple units can be denoted like 5d to denote 5 days. now is used as an explicit way to denote now.
The following operators are accepted: + will add units, - will subtract units, and / will go to the start of the unit's period.
Examples of relative times,
| Last 5 minutes | BETWEEN -5m AND now | |
| The day so far | BETWEEN now/d AND now | |
| This week | BETWEEN now/w AND +1w/w | |
| This week so far | BETWEEN now/w AND now | |
| Last week | BETWEEN now-1w/w AND now/w | |
| This month | BETWEEN now/m AND +1m/m | |
| Previous Month | BETWEEN now-1m/m AND now/m | |
| This year so far | BETWEEN now/y AND now | |
| This year | BETWEEN now/y AND now+y/y | |
| This Wednesday | BETWEEN now/w+1d/d AND now/w+2d/d | |
| Last Tuesday | BETWEEN now-1w/w+1d/d AND now-1w/w+2d/d |
