Example query charts
Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019
Query charts are excellent for visualizing status and trends. Adding multiple charts to a dashboard allows quick monitoring of essential data for your team or project. Consider discussing the following questions with your team:
- Which query charts are most useful for us to create and monitor?
- Which charts help maintain backlog hygiene?
- What time frame should we use for trend charts?
While teams might have varied goals and tracking needs, Agile teams typically perform these tasks. Select status and trend charts that support the following activities:
- Triage incoming work to ensure new work is well defined
- Plan sprints and set sprint goals as described in Scrum and best practices
- Conduct daily stand-ups
Prerequisites
- Access levels: To create a query chart or view query charts from the Queries page, have at least Basic access.
- Permissions:
- To create or edit a shared query, have your Contribute permission set to Allow for the shared query folder.
- To view a query chart added to a dashboard, have Read permissions to the underlying query. If this permission is denied, then the widget displays a Widget failed to load message.
- Tasks: To add a query chart to a dashboard, save the query under the Shared Queries folder.
Note
Users with Stakeholder access for a public project have full access to query chart features just like users with Basic access. Users with Stakeholder access for a private project can't view or create charts from the Queries page, however, they can view charts added to a team dashboard.
Guidelines for creating query charts
For detailed instructions on creating query charts, see Track progress with status and trend query-based charts. Ensure your queries adhere to the following guidelines:
- Query type: Use Flat list of work items as only flat-list queries support query charts.
- Save changes: Save your query after modifying clauses or column options before navigating to the Charts page.
- Operators: Utilize In and Not In operators to include multiple work item types, workflow states, or other groupings.
- Trend charts: Limit queries for trend charts to a maximum of 1,000 work items to avoid widget errors.
- Grouping fields: Add relevant fields to your query clauses or column options. You can group charts by:
- State: Include the State field.
- Assigned To: Include the Assigned To field.
- Iteration Path: Include the Iteration Path field.
- Node Name: Include the Node Name field for team grouping.
- Custom Fields: Include any custom fields as needed.
- Summing numeric columns: To sum a numeric column, include the corresponding field in your query clause or column options. For examples, see Query by a numeric field.
Limitations
You can't group charts by the following field data types:
- ID or Parent fields
- Date-time fields (for example, Created Date, Changed Date)
- Plain Text fields (for example, Title)
- Rich-text fields (for example, Description, Acceptance Criteria, Repro Steps)
- Tags: You can filter queries using tags, but can't use them to configure query charts.
Note
While you can't group a query-based chart by tags, you can group a Chart for Work Items widget by tags added to a dashboard as described in Configure a chart for work items widget.
Adding query charts to dashboards
- Create dashboard first: To add a query chart to a dashboard, first create the dashboard. Then add the chart from the Queries > Charts page.
- Refresh required: After you add a query, refresh your browser to register the new query on the dashboard.
- Optimize performance: For complex queries, see Best integration practices, Optimize queries.
Maintain backlog hygiene
The following queries help your team maintain a healthy backlog by ensuring that work is properly assigned. The following table provides example queries to review periodically, typically at the beginning or end of a sprint. Customize these queries to fit your team and organizational goals by replacing Fabrikam Team with your team name and adding other filters as needed.
Note
Work item types and workflow states applicable to your project might differ from those shown in the following examples depending on the process used by your project.
Query focus
Query clauses
Unassigned work: Work assigned to the current sprint but not assigned to a team member.
Active work not assigned to the current sprint
Active work assigned to a past sprint
Stale work: Work items with no changes made in the last two to three months (query by Changed Date).
Ill-defined work: For example, ones with no Description, Acceptance Criteria, Story Points, or Effort defined.
In the following image, all five query charts appear on a team dashboard. To add query charts to a dashboard, see Add charts to a dashboard
Alternatively, you can add query tiles that reference the same query and show the total count of work items as shown in the following image.
Note
The query tile widget is a 1x1 tile, whereas the smallest query chart dashboard widget is 2x2. To add query tiles to a dashboard, see Add widgets to a dashboard.
Example status charts
The following table provides some examples of status charts you can create and the queries behind them.
Query focus
Query clauses
Planned work: How much work is represented in the backlog. A query that looks at work in the New or Proposed category state provides a snapshot of work in the backlog.
Active bugs: Agile teams monitor their bug or technical debt and set goals to maintain the total number under a specific number.
From this one query, you can create a chart based on assignment or state.
Tagged work items: Monitor tagged work to ensure the team is meeting specific goals, milestones, or categories of work.
Blocked work: How much work is currently blocked? You can query blocked work using a tag or custom field.
Example trend charts
The following table provides some examples of trend charts you can create.
Query focus
Query clauses and chart
Bug trends over time by state (last 30 days)
Active work trends by state (last 30 days)
Useful work tracking widgets and charts
In addition to the query charts provided earlier in this article, the following built-in widgets provide a wealth of information for teams working to monitor progress and continuous improvement goals. Each of these charts can be added to a team dashboard.