Skip to main content

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​

CapabilityCustomer value
Central definitionApply one filtering rule consistently across dashboards, reports, and integrations.
Runtime parametersBuild flexible experiences such as "My Open Items" or "Items for the Selected Project" from one query.
Relationship traversalShow child, parent, or related records, including several levels deep, without custom code.
Lifecycle awarenessFocus users on actionable or relevant states.
Governed data presentationControl which attributes a widget can use, with predictable sorting and paging.
Security alignmentResults always respect the requesting user's access permissions.
Performance controlPaging, count-only execution, sorting, and freshness options tailor the workload.
Schema portabilityMove queries between environments together with their dependent schema elements.
API accessExternal applications and automation reuse the same governed filters through the Query Builder API.

Query types​

Query typeUsed forWhat it returns
Instance QueryDashboard, Report, and Versions widgets; reference attributesA list of instances of the associated type
Relation QueryRelation widgetsInstances connected to a current instance through a relation
Structured QueryAdvanced, 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?​

ScenarioQuery required?Guidance
Relation widgetYesUse a Relation Query.
Dashboard or report with filters, sorting, paging, or parametersYesUse an Instance Query.
Dashboard or report that must expose only selected attributesUsuallyUse an Instance Query with specific attributes.
Show all accessible records with default columnsNot alwaysNo query is needed when no filtering or projection is required.
Reference attribute that must offer filtered choicesYesUse an Instance Query with static or dynamic filters.
API, integration, or automationRecommendedRun a saved query, or send a query in the request body.

Where queries are used​

ConsumerQuery typeNotes
Dashboard widgetInstance QueryQuery tab of the widget; cards, lists, charts, and grids.
Report widgetInstance QueryThe query is the report dataset.
Versions widgetInstance QueryQuery tab of the widget.
Relation widgetRelation QueryThe query defines the relation path and the criteria along it.
Reference attributeInstance QueryFiltered choices, optionally dependent on another field. See Query Definition for Reference Attributes.
Query Builder APIAnyExecute a saved query or an ad hoc query. See Query Builder API.

In this section​

PageWhat it covers
Query Builder Configuration GuideCreate and maintain Query Definitions in Design Studio: parameters, filters, data options, widgets, schema promotion, best practices, and troubleshooting.
Query ParametersParameterized 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 LogicValue format for every operator, dates and time zones, picklist, user, and boolean fields, basic attributes, and how And/Or combine.
Relations, Nesting, and RecursionRelation direction, multi-step paths, nested related queries, and walking self-referential relations such as sub-tasks.
Query Builder APIThe execute, executeQuery, and executeQueryByName endpoints: request shape, defaults, paging, data source, permissions, errors, and a worked example.
Query Definitions Admin APICreate, 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 CookbookA 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 StudioStep-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.