Query Builder
Query Builder lets administrators and solution designers define reusable rules for retrieving Protrak data. A Query Definition describes which type of records to return, how to filter them, which attributes to expose, and which execution options (sorting, paging, counts, freshness) to apply. Once a query is ready, the same query can be reused across widgets, reference attributes, and integrations.
A Query Definition is the data-selection engine behind dashboard widgets, report widgets, relation widgets, and filtered reference attributes. Updating a shared query updates every experience that uses it, so business rules stay consistent.
What Query Builder gives you
| Capability | Customer value |
|---|---|
| Central definition | Apply one filtering rule consistently across dashboards, reports, and integrations. |
| Runtime parameters | Build flexible experiences such as "My Open Items" or "Items for the Selected Project" from one query. |
| Relationship traversal | Show child, parent, or related records, including several levels deep, without custom code. |
| Lifecycle awareness | Focus users on actionable or relevant states. |
| Governed data presentation | Control which attributes a widget can use, with predictable sorting and paging. |
| Security alignment | Results always respect the requesting user's access permissions. |
| Performance control | Paging, count-only execution, sorting, and freshness options tailor the workload. |
| Schema portability | Move queries between environments together with their dependent schema elements. |
| API access | External applications and automation reuse the same governed filters through the Query Builder API. |
Query types
| Query type | Used for | What it returns |
|---|---|---|
| Instance Query | Dashboard, Report, and Versions widgets; reference attributes | A list of instances of the associated type |
| Relation Query | Relation widgets | Instances connected to a current instance through a relation |
| Structured Query | Advanced, multi-level results (where available in your environment) | Instances together with nested related instances |
Choose an Instance Query when the result is records of one type. Choose a Relation Query when the result depends on a current or selected record. Use a Structured Query when one result must carry related records several levels deep.
Do I need a query?
| Scenario | Query required? | Guidance |
|---|---|---|
| Relation widget | Yes | Use a Relation Query. |
| Dashboard or report with filters, sorting, paging, or parameters | Yes | Use an Instance Query. |
| Dashboard or report that must expose only selected attributes | Usually | Use an Instance Query with specific attributes. |
| Show all accessible records with default columns | Not always | No query is needed when no filtering or projection is required. |
| Reference attribute that must offer filtered choices | Yes | Use an Instance Query with static or dynamic filters. |
| API, integration, or automation | Recommended | Run a saved query, or send a query in the request body. |
Where queries are used
| Consumer | Query type | Notes |
|---|---|---|
| Dashboard widget | Instance Query | Query tab of the widget; cards, lists, charts, and grids. |
| Report widget | Instance Query | The query is the report dataset. |
| Versions widget | Instance Query | Query tab of the widget. |
| Relation widget | Relation Query | The query defines the relation path and the criteria along it. |
| Reference attribute | Instance Query | Filtered choices, optionally dependent on another field. See Query Definition for Reference Attributes. |
| Query Builder API | Any | Execute a saved query or an ad hoc query. See Query Builder API. |
In this section
| Page | What it covers |
|---|---|
| Query Builder Configuration Guide | Create and maintain Query Definitions in Design Studio: parameters, filters, data options, widgets, schema promotion, best practices, and troubleshooting. |
| Query Parameters | Parameterized queries: parameter properties and rules, expressions, where parameters can be used, how values are resolved, value formats per type, and use in widgets, reference attributes, and the API. |
| Filter Values and Logic | Value format for every operator, dates and time zones, picklist, user, and boolean fields, basic attributes, and how And/Or combine. |
| Relations, Nesting, and Recursion | Relation direction, multi-step paths, nested related queries, and walking self-referential relations such as sub-tasks. |
| Query Builder API | The execute, executeQuery, and executeQueryByName endpoints: request shape, defaults, paging, data source, permissions, errors, and a worked example. |
| Query Definitions Admin API | Create, read, update, list, and delete saved Query Definitions through the API: the saved shape for each query type, parameters, validation checks, and delete rules. |
| Query Request Cookbook | A short, task-focused guide to writing requests: look up exact names, a condition cheat sheet, ready-to-use examples (including recursive sub-tasks), how to read results, and fixes for common errors and silent mistakes. |
| Query Definitions in Design Studio | Step-by-step screen reference, including how a query drives the Column Designer. |
Guidance
- Name queries after their business purpose, not after a widget or a person.
- Prefer parameters over many nearly identical queries.
- Always define a sort order when paging results.
- Test queries with representative non-administrator roles, not only administrators.
- Review dependent widgets, reference attributes, and reports before renaming or removing a query, attribute, relation type, or state it uses.