Compartir vía

Track your work by using managed queries in Azure Boards

  • Artículo

TFS 2018

List bugs, user stories, or other work items based on field criteria you specify using queries. You can then review these lists with your team, triage work, or bulk update work items. Along with managed queries, the semantic search tool provides some overlapping and different functionality worth exploring.

Use managed queries to support these operations:

  • Bulk update of work items using the web portal
  • Triage and update work items
  • Review a hierarchy of work items
  • Share a list of work items with a team member

You can create queries and query folders from the web portal or from Visual Studio Team Explorer. Changes you make in one client are reflected in other clients as all changes are stored in the work tracking data store.

Get started using queries

If you're just getting started, read View, run, or email a work item query. For a quick reference to query editor tasks and sample queries, see Query quick reference.

  • To find work items that are assigned to you, add the @Me macros as the value for the Assigned To field in one of the query clauses.
  • All valid users with standard access can create queries and folders under the My Queries area. To create queries and query folders under Shared Queries, you must have the Contribute permission set. For more information, see Set permissions on queries.
  • You can modify any query by adding criteria to focus on a product area, an iteration, or another field. To modify a query, open the query editor.
  • You can open any query in Excel. You can also update the fields of one or more work items and publish your changes to the database for tracking work items.
  • You can visualize status or progress by creating a pie-chart, column chart, or trend chart for flat-list queries.

Query capabilities

The following sections provide an overview of the functions supported to define and manage work item queries.

  • Query filters are defined through the Query Editor.
  • Query macros can be selected for specific fields to create a query clause.
  • Query results and query management features are capabilities available through the Query Results page.

Query filters

The following table summarizes the query filter functions supported by each Azure DevOps version.

Filter function

Query support

Supported versions

Text string searches (single text, multi-line text, rich text)

Searches are not case sensitive.

All versions

Wildcard searches

Wild card = *

All versions

Linked work item searches

Find work items based on direct links or topological/hierarchical link types.
Filter linked work items based on MODE (WIQL syntax)

All versions

Logical clause groupings

Group and nest clauses using AND and OR Boolean operators.

All versions

Historical String and DateTime field queries

Find work items based on a field match with a previous value. Supported operator: Was Ever Find work items based on a value defined on a specific date. Supported operator: ASOF (WIQL syntax)

All versions

Query using macros or variables

Use macros to create queries relative to a date, other tools, such as team area path, team iteration, and more.

All versions

Search across projects

Find work items in one or more projects in an organization or collection. Default is the current project. Use the Team Project field to query on two or more projects.

All versions

Field comparison searches

Find work items based on how two fields compare with one another.
Supported operators: =[Field], <>[Field], >[Field], <[Field], >=[Field], <=[Field]

All versions

Query on tags

Find work items based on whether they contain or don't contain a tag. Supported operators: Contains, Does Not Contain

All versions

Query on blank or empty fields

Find work items based on empty or not empty HTML/rich text fields.
Supported operators: Is Empty, Is Not Empty

Azure DevOps 2019 through Azure DevOps Server 2022, Azure DevOps Services

In and Not In Group searches

Find work whose field value matches any value in a delimited set, such as a set of work item types, workflow states, or picklist values. Separate values with the list separator that corresponds to the regional settings that are defined for your client computer. For example, you might use a comma(,).

All versions

Boolean searches

Find work items based on boolean field value.

All versions

Query History and Discussion

Find work items based on key words or phrases added through the Discussion.

All versions

Query on Kanban board fields

Find work items based on their Kanban column, swimlane, or Doing/Done status.

Azure DevOps 2019 through Azure DevOps Server 2022, Azure DevOps Services

Interactive query filters

Filter query results based on a key word or select fields.

Azure DevOps 2019 through Azure DevOps Server 2022, Azure DevOps Services

To bulk move, copy, or paste query clauses, install and use the WIQL editor.

Supported macros

The following table summarizes the query macros or variables supported by the Azure DevOps versions. You can use some of these macros to filter notifications.

Note

You can use certain macros from the web portal only. These include the @CurrentIteration, @CurrentIteration +/- n, @Follows, @MyRecentActivity, @RecentMentions, @RecentProjectActivity, and @TeamAreas macros. These macros aren't supported when exporting a query to Excel, notification filters, or exercised from Team Explorer, or REST APIs.

For more detailed descriptions and links to examples, see Query fields, operators, and macros.

Macro

Query support

Supported versions

[Any]

Find any work item type, Work Item Type=[Any], or any State, State=[Any].

All versions

@Me

Find work where Identity field=logged in user.

All versions

@Today

Find work where Date-Time field=today.

All versions

@Project

Find work defined in one or more projects.

All versions

@CurrentIteration

Find work defined in current iteration for a team.

All versions

@CurrentIteration +/-n

Find work defined in +/- n of current iteration for a team.

Azure DevOps 2019 through Azure DevOps Server 2022, Azure DevOps Services

@Follows

Find work current logged in user is following, ID In @Follows.

All versions

@MyRecentActivity, @RecentMentions, @RecentProjectActivity

Find work items recently changed, ID In @MyRecentActivity See also View and add work items, Work Items page.

All versions

@StartOfDay, @StartOfMonth, @StartOfWeek, @StartOfYear

Find work where the selected date-time field is within the current day, month, week, or year with a plus/minus offset, example: Closed Date>=@StartOfDay-7.

Azure DevOps 2019 through Azure DevOps Server 2022, Azure DevOps Services

@TeamAreas

Find work assigned to an Area Path or Iteration Path of specified team, for examples, see Query by area or iteration path.

Azure DevOps 2019 through Azure DevOps Server 2022, Azure DevOps Services

Query results and query management features

The following features provide support for working with query results, saving and sharing queries, and more.

- Add a query chart to a dashboard
- Apply interactive filters
- Choose column sort
- Choose query column options
- Copy query results - Copy Query URL
- Create query charts
- Create query folders

- Define and edit a query
- Define WIQL syntax
- Email query results
- Favorite a query
- Filter a query

- Import/export a query (csv)
- Import/export a query (.wiq)
- Open and run a query
- Publish/refresh a query (Excel)
- Run REST API queries
- Save queries
- Set query permissions

Unsupported features

Work item queries only support querying of work items and work items linked to other work items. Here are a few of the tasks that managed queries don't support:

  • Hierarchical views of Test Plans, Test Suites, and Test Cases. These items aren't linked together using parent-child link types. Instead, you can view the hierarchy through the Test>Test Plans page.
  • Views showing linked objects such as builds, releases, code, or other non-work item objects.
  • List work items linked from one project to another.
  • Export a cross-project query to Excel. Direct links queries export to Excel as a flat-list.

Azure Boards supports three query types. The icon next to each query indicates the query type. Use the following guidance to choose the query type based on what you want to accomplish with the query.

Query type icon list

Query type

Usage guidance

Flat list of work items

  • List items to do bulk updates to fields
  • Triage a list of work items
  • Create a query chart and add it to a dashboard
  • Create a chart to get a count of items or sum a field
  • Export a list of items to Excel to update fields

Work items and direct links

  • List items that are dependent on other work items
  • Find items related or dependent on other work items
  • List linked work items to do bulk updates to fields
  • Triage a list of linked work items
  • List test-related linked work items
  • Find orphaned backlog items, work items that have no parent

Note

Work items and direct links queries export to Excel as a flat list. Direct links queries are imported as a flat list as modifying multiple types of links isn't a supported feature in Excel.

Tree of work items

  • List a tree of Parent-Child related work items, or other tree-topology link type
  • Triage a hierarchical list of work items
  • Export a hierarchical list of items to Excel to update fields or modify the hierarchy

To learn more about link types, see Link type reference.

My Queries, Shared Queries, and Favorites

Only you can view and run queries that you save under My Queries with the queries directory. Also, you can favorite one of these queries to have it appear within your query selector.

Queries you and others save under Shared Queries can be viewed by everyone with access to the project. Shared queries can be organized within folders and favorited by you or for a team. Also, you can set permissions on the folders and queries to prevent others from moving or editing them.

For more information, see:

Query charts and widgets

You can quickly create pie, bar, pivot, and trend charts from a flat-list query. Queries must be flat-list and return 1000 or less work items. You can add your query charts to a dashboard, retitle, and reconfigure them.

Example pie chart. Example pivot chart. Example bar chart. Example trend chart.

Query-based widgets provide support for presenting query information on a dashboard. For example, the number of active bugs or a list of work items that you can interact with. To learn about query charts and widgets, see these articles:

Add a custom field to support queries

To add a custom field to support your query needs, see Customize your work tracking experience.

Taskboard versus query list items

You may notice and wonder why the contents of the taskboard differ from the contents listed with its created query? For more information, see taskboard items versus query list items.

Full-text search queries and collation settings

To support full-text search queries, the collation settings of the SQL Server database should correspond to a language that has a word breaker registered with SQL Server. If you use an unsupported language, you could receive unexpected results when you run a work item query that specifies the Contains or Contains Words operators with text strings.

For more information, see the following articles:

REST API

To programmatically interact with queries, see one of these REST API resources: