Skip to content

Latest commit

 

History

History
568 lines (367 loc) · 29.3 KB

using-queries.md

File metadata and controls

568 lines (367 loc) · 29.3 KB
title titleSuffix description ms.custom ms.technology ms.assetid ms.author author ms.topic monikerRange ms.date
Define a work item query with the Query Editor in Azure Boards
Azure Boards
Learn how to create a flat-list, tree, or direct links queries to list, triage, update, and chart work items.
boards-queries, contperf-fy21q3, linked-from-support, cross-project
devops-agile
364000d3-200a-495a-bfb9-83915240af67
kaelli
KathrynEE
tutorial
<= azure-devops
10/26/2021

Define a work item query in Azure Boards

[!INCLUDE version-lt-eq-azure-devops] [!INCLUDE version-vs-gt-2013.md]

Work item queries generate lists of work items based on the filter criteria you provide. You can then save and share these managed queries with others. In contrast, semantic searches list work items, but can't be saved or shared. ::: moniker range=">= azure-devops-2020" Create queries from the web portal or from a supported client, such as Visual Studio Team Explorer and Team Explorer Everywhere. You can also define and import a work item query using WIQL syntax and a .wiq file. To support bulk updates or additions, import or export queries using Excel or .csv files.
::: moniker-end ::: moniker range="< azure-devops-2019" Create queries from the web portal or from a supported client, such as Visual Studio Team Explorer and Team Explorer Everywhere. You can also define and import a work item query using WIQL syntax and a .wiq file. To support bulk updates or additions, import or export queries using Excel.
::: moniker-end

Browser

[!div class="mx-imgBorder"]
Query Editor, web browser.

Visual Studio

[!div class="mx-imgBorder"]
Query Editor, Visual Studio.

Note

To define queries in Visual Studio 2019, you need to Set the Work Items experience to the legacy option.

If you find that your queries take too long to return results, review the Guidance to create high-performing queries.

In this article you'll learn:

[!div class="checklist"]

  • How to add or create a query
  • How to query across projects
  • How to group and ungroup query clauses
  • How to create a tree of work items or a direct-links query

For quick access to all query tasks, supported operators—such as, Contains, In, In Group, and <>(not operator) — based on field data type, and query examples, see Query quick reference.

Choose a query filter

From the Query Editor, exercise the following filter functions. Choose the filter to jump to an article with sample queries. Along with the query filters, you can interactively apply filters to query results.

::: moniker range=">= azure-devops-2019"

Note

Managed queries don't support proximity searches, however semantic searches do. In addition, semantic searches supports both * and ? as wildcard characters and you can use more than one wildcard character to match more than one character. To learn more, see Functional work item search. ::: moniker-end

:::row::: :::column span="2"::: Filter features :::column-end::: :::column span="2"::: Macros :::column-end::: :::row-end:::

:::row::: :::column span="1"::: ::: moniker range=">= azure-devops-2019" - Compare fields - Key words
- Linked work items
- Logical groupings
- Query macros
- Tags
- Was Ever
- Was Ever (Board Column)
- Wildcard
::: moniker-end ::: moniker range="tfs-2018" - Compare fields - Key words
- Linked work items
- Logical groupings
- Query macros
- Tags
- Was Ever
- Wildcard
::: moniker-end ::: moniker range="tfs-2017" - Compare fields - Key words
- Linked work items
- Logical groupings
- Query macros
- Tags
- Was Ever
- Wildcard
::: moniker-end ::: moniker range="tfs-2015" - Compare fields - Key words
- Linked work items
- Logical groupings
- Query macros or variables ::: moniker-end ::: moniker range="tfs-2013" - Compare fields - Key words
- Linked work items
- Logical groupings
- Query macros or variables ::: moniker-end :::column-end::: :::column span="1"::: ::: moniker range=">= azure-devops-2019" - Blank or empty fields - Boolean searches - History and Discussion - Kanban board fields - In and Not In Group searches - Search across projects ::: moniker-end ::: moniker range="tfs-2018" - Boolean searches - History and Discussion - In and Not In Group searches - Search across projects - In and Not In Group searches ::: moniker-end ::: moniker range="tfs-2017" - Boolean searches - History and Discussion - Search across projects ::: moniker-end ::: moniker range="tfs-2015" - Search across projects - Tags - Was Ever - Wildcard ::: moniker-end ::: moniker range="tfs-2013" - Tags - Was Ever - Wildcard ::: moniker-end :::column-end::: :::column span="2"::: ::: moniker range=">= azure-devops-2019" - [Any] - @Me - @Today - @CurrentIteration, @CurrentIteration +/-n
- @Follows - @MyRecentActivity, @RecentMentions, @RecentProjectActivity - @StartOfDay, @StartOfMonth, @StartOfWeek, @StartOfYear
- @TeamAreas ::: moniker-end ::: moniker range="tfs-2018" - [Any] - @Me - @Today - @CurrentIteration
- @Follows - @MyRecentActivity, @RecentMentions, @RecentProjectActivity ::: moniker-end ::: moniker range="tfs-2017" - [Any] - @Me - @Today - @CurrentIteration
- @Follows ::: moniker-end ::: moniker range="tfs-2013 || tfs-2015" - [Any] - @Me - @Today - @CurrentIteration
::: moniker-end :::column-end::: :::row-end:::

Along with the filters you use from the Query Editor, you can interactively filter a query result using the :::image type="icon" source="../../media/icons/filter-icon.png" border="false"::: Filter function. To learn how, see Interactively filter backlogs, boards, queries, and plans.

[!INCLUDE temp]

Open Queries

[!INCLUDE temp]

Define a flat-list query

You can start a fresh, new query from the Queries tab in the web portal or the Work Items tab in Team Explorer.

Browser

::: moniker range=">= azure-devops-2019"

[!div class="mx-imgBorder"]
Add new query, new experience

The Query Editor displays with the following default settings: Flat list of work items, Work Item Type=[Any], and State=[Any].

:::image type="content" source="media/using-queries/new-query-web-portal.png" alt-text="Screenshot of Query Editor with flat list of work items selected.":::

You can modify the Values and add or remove clauses. Or, change the Type of query to Work items and direct links or to a Tree of work items. ::: moniker-end

::: moniker range=">= tfs-2015 <= tfs-2018"

Queries page, Choose New query from the drop down menu

The Query Editor displays with the following default settings: Flat list of work items, Team Project=@Project (the current project), Work Item Type=[Any], and State=[Any].

:::image type="content" source="media/using-queries/new-query-flat-list-tfs.png" alt-text="Screenshot of Query Editor with flat list of work items selected, TFS 2018 and earlier versions.":::

You can modify the Values and add or remove clauses. Or, change the Type of query to Work items and direct links or to a Tree of work items.

::: moniker-end

Visual Studio

Choose New Query from the Work Items page.

:::image type="content" source="media/using-queries/new-query-visual-studio-2019.png" alt-text="Screenshot of Work Items, choose New Query."::: The Query Editor displays with the following default settings: Flat list (Default), Team Project=current project, Work Item Type=[Any], and State=[Any].

:::image type="content" source="media/using-queries/visual-studio-new-query-editor.png" alt-text="Screenshot of Visual Studio Query Editor, flat-list query.":::

You can modify the Values and add or remove clauses. Or, change the Type of query to Work items and direct links or to a Tree of work items.

Query across or within projects

New queries scope to the current project by default. However, you can create queries to find work items defined within the organization or project collection. All queries that you save, however, are saved under a specific project.

Browser

::: moniker range=">= tfs-2015"

To list work items defined in two or more projects, checkmark Query across projects. For example, the following query finds all features created in all projects within the last 30 days.

Web portal, Queries page, Query Editor, Checkbox, Query across projects

::: moniker-end

::: moniker range="tfs-2015"

Note

The Query across projects feature is supported from TFS 2015.1 and later versions.

::: moniker-end

::: moniker range=">= tfs-2015"

With the Query across projects checked, you can add the Team Project field to filter to a select number of projects.

Azure Boards and TFS 2015.1, Web portal, Query across select projects using the In operator

Note

Separate multiple project names with the list separator that corresponds to the regional settings defined for your client computer, for example, a comma (,).

The Team Project field is available only after you check Query across projects. Further, when Query across projects is unchecked, only those fields from those work item types, as defined in the current project, appear in the Field drop-down menu. When Query across projects is checked, all fields from all work item types defined in all projects in the collection appear in the Field drop-down menu.

::: moniker-end

::: moniker range="tfs-2013"

To find all features created in all projects within the last 30 days, remove the Team Project=@Project clause from the query.

TFS 2013-2015, Web portal, Query across select projects using the In operator

All fields from all work item types defined in all projects in the collection always appear in the Field drop-down menu.

Use Team Project=@Project to scope the query to find only those work items defined for the current project.

::: moniker-end

Visual Studio

To list work items defined in two or more projects, change the clause for the Team Project using the In operator, and enter the names of the projects to search in. For example, the following query finds work items defined in the Fabrikam Fiber and Design Agile projects.

:::image type="content" source="media/using-queries/visual-studio-query-multiple-projects.png" alt-text="Screenshot of Visual Studio Query Editor, flat-list query, specify two projects clause":::

To query across all projects, delete the clause with the Team Project field.

Define a clause

You create a query by defining one or more clauses. Each clause defines a filter criteria for a single field.

Sample query clause

And/Or Field Operator Value
And Assigned To = @Me

For a list of available operators based on the field data type, see Query index quick reference.

All clauses you add are added as an And statement. Choose Or to change the grouping. You group clauses to ensure that the clause statements are run in the sequence required.

Browser

Choose Add new clause to add another clause at the end of the query, and then choose the Field, Operator, and Value for that clause.

[!div class="mx-imgBorder"]
Define a clause.

For example, search for all work items assigned to you by specifying the Assigned To field, the equals (=) operator, and the @Me macro, which represents your user identity.

Visual Studio

Choose Click here to add a clause to add another clause at the end of the query, and then choose the Field, Operator, and Value for that clause.

:::image type="content" source="media/using-queries/visual-studio-add-new-clause.png" alt-text="Screenshot of Visual Studio Query Editor, add new clause.":::

To insert a clause within the existing set of query clauses, place your cursor on the clause below where you want to insert the clause, and then choose Insert Clause. Then, choose the Field, Operator, and Value for that clause.

:::image type="content" source="media/using-queries/visual-studio-add-new-clause.png" alt-text="Screenshot of Visual Studio Query Editor, insert clause.":::

Or, open the context menu for the clause and choose Insert Clauses.

:::image type="content" source="media/using-queries/visual-studio-insert-delete-clauses.png" alt-text="Screenshot of Visual Studio Query Editor, context-menu for insert clauses and delete clause.":::

To delete a clause, choose the clause you want to delete, and choose :::image type="icon" source="../media/icons/icon-delete-clause-visual-studio.png" border="false"::: Delete Clause.

When finished, choose :::image type="icon" source="../media/icons/run_query.png" border="false"::: Run or :::image type="icon" source="../media/icons/icon-save-visual-studio.png" border="false"::: Save Query.

[!INCLUDE temp]

Checklist for how to define a query clause

  1. In the first empty row, under the Field column heading, choose the down arrow to display the list of available fields, and choose an item in the list.

    For more information, see Query Fields and Values.

  2. In the same row, under the Operator column heading, choose the down arrow to display the list of available operators, and choose an item in the list.

    For more information, see Operators.

  3. In the same row, under the Value column heading, either type a value, or choose the down arrow, and choose an item in the list.

    For more information about how to use a macro or variable to specify the current project, user, date, or other selection, see Variables.

  4. To add a clause, choose Add new clause.

    You can add a clause to the end of the query, insert a clause after an existing clause (insert clause icon), and remove (remove clause icon), group (group clause icon), and ungroup (ungroup clause icon) clauses as needed.

Use a work item tree to view hierarchies

Use the :::image type="icon" source="media/11.png" border="false"::: Tree of Work Items query to view a multi-tiered, nested list of work items. For example, you can view all backlog items and their linked tasks. Expand (Expand node (Expand node, web portal) or collapse (Collapse node, web portal) nodes to focus on different parts of the tree.

Note

You can't construct a query that shows a hierarchical view of Test Plans, Test Suites, and Test Cases. These items aren't linked together using parent-child link types. However, you can create a direct links query that lists test-related work items. Also, you can, view the hierarchy through the Test>Test Plans page.

Define the filter criteria for both parent and child work items. To find linked children, select Match top-level work items first. To find linked parents, select Match linked work items first.

Browser

::: moniker range=">= azure-devops-2019"

[!div class="mx-imgBorder"]
Results List Showing a Tree Query, new experience

::: moniker-end

::: moniker range=">= tfs-2017 <= tfs-2018"

[!div class="mx-imgBorder"]
Results List Showing a Tree Query

::: moniker-end

::: moniker range="<= tfs-2015"

Results List Showing a Tree Query

::: moniker-end

::: moniker range=">= tfs-2017"

[!div class="mx-imgBorder"]
Tree Query, editor

::: moniker-end

::: moniker range="<= tfs-2015"

Tree Query, editor

::: moniker-end

Visual Studio

:::image type="content" source="media/using-queries/tree-backlog-te.png" alt-text="Screenshot, Query Editor, Tree Query, Team Explorer. ":::

Use direct links to view dependencies

Use the :::image type="icon" source="media/16.png" border="false"::: Work items and Direct links query to track work items that depend on other tracked work, such as tasks, bugs, issues, or features. For example, you can view backlog items that depend on other items being implemented or a bug being fixed.

Use the direct links query to track dependencies across teams. The query also helps you manage commitments your team makes. Choose the filter criteria for the top and linked work items. And, select the types of links to filter the dependencies.

Browser

Direct Links Query Results

::: moniker range=">= tfs-2017"

[!div class="mx-imgBorder"]
Direct Links Query, editor

::: moniker-end

::: moniker range="<= tfs-2015"

Direct Links Query Editor

::: moniker-end

Filter your first-tier list of work items by choosing one of these options:

  • Only return items that have matching links: First-tier work items return, but only if they have links to work items specified by the linked work items filter criteria.

  • Return all top level items: All first-tier work items return despite the linked work items filter criteria. Second-tier work items that are linked to the first tier return if they match the linked work items filter criteria.

  • Only return items that do not have matching links: First-tier work items are returned, but only if they don't have links to work items specified by the linked work items filter criteria.

Visual Studio

:::image type="content" source="media/using-queries/direct-links-te.png" alt-text="Screenshot, Query Editor, Direct Links Query, Team Explorer.":::

Filter your first-tier list of work items by choosing one of these options:

  • Return all top level work items: All first-tier work items return despite the linked work items filter criteria. Second-tier work items that are linked to the first tier return if they match the linked work items filter criteria.

  • Only return items that have the specified links: First-tier work items return, but only if they have links to work items specified by the linked work items filter criteria.

  • Only return items that do not have the specified links: First-tier work items return, but only if they don't have links to work items specified by the linked work items filter criteria.

To learn more about each link type, see Linking, traceability, and managing dependencies.

And/Or logical expression

You specify And or Or to create logical expressions of your query clauses. Specify And to find work items that meet the criteria in both the current clause and the previous clause. Specify Or to find work items that meet the criterion in either the current clause or the previous clause.

Add one new clause for each work item field to refine your search criteria. Add clauses to return only the set of work items you want. If you don't receive the results you expect from your query, refine it. You can add, remove, group, or ungroup query clauses to improve your query results.

Group query clauses to operate as a single unit separate from the rest of the query. Grouping clauses is similar to putting parentheses around an expression in a mathematical equation or logic statement. When you group clauses, the AND or OR for the first clause in the group applies to the whole group.

Group clauses

Grouped clauses operate as a single unit separate from the rest of the query. Grouping clauses is similar to putting parentheses around a mathematical equation or logic expression. The And or Or operator for the first clause in the group applies to the whole group.

As the following examples show, the grouped clauses are translated to the corresponding logical expression.

Tip

To view the WIQL syntax for a query, install the WIQL query editor extension which will allow you to see the WIQL version of any Query UI entry. This extension allows you to see just how AND/OR grouped clauses are treated.

[!div class="mx-tdCol2BreakAll"]

Query Grouped clauses Logical expression
1 Screenshot showing a group clause query. Filters are set up for the Work item type field and either the State field or the Assigned to field. Screenshot of a logical expression. An AND operator groups the Work item type, State, and Assigned to fields. An OR operator groups the State and Assigned to fields.
2 Screenshot showing a group clause query, with filters for both the Work item type field and one of either the State field or the Assigned to field. Screenshot of a logical expression. An AND operator groups the Work item type with the State or Assigned to fields, which are grouped by an OR operator.
3 Screenshot showing a group clause query. Filters are set up for either the Work item type field or both the State field and the Assigned to field. Screenshot of a logical expression. An OR operator links the Work item type to both the State and the Assigned to fields, which are linked by an AND operator.

These queries return work items that are type Bug and meet the following logical expressions:

  • Query 1: AND State=Active OR Assigned to @Me
  • Query 2: AND (State=Active OR Assigned to @Me)
  • Query 3: OR (State=Active AND Assigned to @Me)

To group one or more clauses, select them and then choose the :::image type="icon" source="../media/icons/group-clauses-icon.png" border="false"::: group clauses icon.

[!div class="mx-imgBorder"]
Web portal, Group Selected Query Clauses

You can also group several grouped clauses. Check the boxes of each clause that's already been grouped. Then, choose the :::image type="icon" source="../media/icons/group-clauses-icon.png" border="false"::: group clauses icon.

[!div class="mx-imgBorder"]
Group multiple query clauses

If your query results don't return expected results, follow these steps:

  • Make sure that each clause is defined as you intended.
  • Verify And/Or assignments to each clause. If your results contain more work items than expected, often an Or clause is present instead of an And clause.
  • Determine if you need to group or change the grouping of the query clauses and the And/Or assignments of each grouped clause.
  • Add more query clauses to refine your query filter criteria.
  • Review the options available to specify fields, operators, and values.

Ungroup a clause

Browser

To ungroup a clause, choose the :::image type="icon" source="../media/icons/ungroup-clause.png" border="false"::: ungroup clauses icon for the grouped clause.

Visual Studio

To ungroup a clause, choose the :::image type="icon" source="../media/icons/ungroup-clause-visual-studio.png" border="false"::: ungroup clauses icon for the grouped clause, Visual Studio.

Related articles

That's the basics about defining queries. For an index of query examples, see Query quick reference.