Advanced Usage and Limitations
This page explains runtime overrides, preview behavior, performance considerations, and current Query Builder limitations.
Runtime Overrides
Saved filters and aggregations can be replaced when calling the API. This is useful when one saved query should serve several reporting periods, departments, or dashboard views.
Filter Overrides
Use filters[...] parameters to replace saved filters:
GET /api/query/{name}?filters[department][operation]=equals&filters[department][value]=IT
If any URL filter is provided, all saved filters are ignored for that request.
Aggregate Overrides
Use aggregates[...] parameters to replace saved aggregations:
GET /api/query/{name}?aggregates[amount]=sum&aggregates[rating]=avg
If any URL aggregate is provided, all saved aggregates are ignored for that request.
How Filters and Aggregates Fall Back
Filters and aggregates fall back independently:
| Request Parameters | Result |
|---|---|
| No URL filters or aggregates | Uses saved filters and saved aggregates |
| URL filters only | Uses URL filters and saved aggregates |
| URL aggregates only | Uses saved filters and URL aggregates |
| URL filters and URL aggregates | Uses URL filters and URL aggregates |
Combining Criteria
You can select multiple fields and configure criteria for more than one field.
Example:
department equals IT
submittedOn from_to 2025-01-01 through 2025-03-31
amount sum
Use a separate field for filtering and aggregation when possible. A single field should not have both a filter and an aggregation.
Preview Behavior
The Show Query Preview button appears when editing an existing query. Preview runs the saved query and displays JSON output.
Preview is useful for checking field keys and response shape, but it should not be used to validate final totals.
| Preview Behavior | Details |
|---|---|
| Saved Data Only | Preview uses saved filters and aggregates, not unsaved form changes |
| 2-Row Limit | Preview limits results to 2 rows before calculating totals |
| Aggregate Limitation | Preview aggregate values are calculated from the limited preview result |
To verify final total_matches and aggregate values, call the full API endpoint.
Performance Considerations
Query Builder loads matching submissions for the selected workflow into memory and then applies filters in PHP.
For workflows with high submission volume:
- Add a date range filter whenever possible.
- Avoid unfiltered queries on workflows with thousands of submissions.
- Select only the fields needed by the report or integration.
- Batch external API calls by date range if a large history must be processed.
- Run high-volume integrations during off-peak hours.
There is no built-in pagination. A successful request returns the full filtered result set in a single response.
Query Management Notes
| Action | Behavior |
|---|---|
| Edit Query | Field selection, filters, aggregates, and description can be updated |
| Rename Query | Not available after saving because the name is part of the API URL |
| Delete Query | Permanently removes the query and immediately disables the API endpoint |
Current Limitations
The current Query Builder does not support the following features:
| Feature | Current Behavior |
|---|---|
| CSV, Excel, or JSON file export | Process the API JSON response outside OSPROV |
| Group-by operations | Not implemented |
| Pagination | Full filtered results are returned in one response |
| Sorting parameters | Not documented or supported by the current endpoint |
| Field selection through URL parameters | Not documented or supported by the current endpoint |
| Joining multiple workflows | Query one workflow at a time |
| Real-time or streaming results | Results are calculated when the API is called |
| Scheduled query execution | Schedule API calls from an external system if needed |
| Webhook delivery | Not implemented in Query Builder |
| Query version history or rollback | Not implemented |
Known Field-Type Limitations
| Field Type or Option | Current Behavior |
|---|---|
| Is Null / Is Not Null in UI | Options appear in the dropdown but are not reliably saved because saving requires a non-empty value |
| Checkbox Fields | Is True and Is False appear in the UI but are not reliably saved |
| Time Fields | Filtering uses date-level start and end boundaries, not true time-only boundaries |