Azure DevOps queries are powerful tools that help you manage your work items efficiently. By mastering these queries, you can save time and increase productivity.
To create a query, you need to specify a title and a filter clause. The filter clause is where you define the conditions for your query, such as assigning a specific work item to a particular team or project.
A query can be as simple as finding all work items assigned to a specific team or as complex as finding all work items that meet multiple conditions. For instance, you can find all work items that are assigned to a specific team and have a specific status.
Query Basics
A query in Azure DevOps is simply a question you ask about your work items, like "Which bugs are assigned to me?" or "What's the status of my current sprint?" Queries help you quickly find the information you need.
To create a query, you can use the Query Editor, which is a visual interface that lets you build your query step by step. You can also use the Query Language, which is a more flexible way to write your query.
Azure DevOps provides several types of queries, including saved queries, which you can save and reuse later, and ad-hoc queries, which you can create on the fly. Saved queries are especially useful if you have a query you use frequently.
The Query Editor is where the magic happens, and it's here that you can build your query using a simple and intuitive interface. You can add filters, fields, and other criteria to narrow down your results.
Azure DevOps also supports the use of tags and categories in your queries, which can help you quickly identify and group similar work items. For example, you can use a tag to mark all bugs as high priority.
Querying Work Items
You can use a Tree of Work Items query to view a multi-tiered, nested list of work items, such as all backlog items and their linked tasks.
To construct a query that shows a hierarchical view of Test Plans, Test Suites, and Test Cases, you can't use parent-child link types, but you can create a direct links query that lists test-related work items.
You can't construct a query that shows a hierarchical view of Test Plans, Test Suites, and Test Cases, but you can view the hierarchy through the Test Plans page.
To view query results in a dashboard, you can use the Query results widget, which displays the results of a flat, tree, or direct-links query.
The Query results widget can be configured to display specific fields, resize column fields, and expand and collapse tree and direct-links queries.
You can view the results of a query with the Parent title displayed by creating a query, adding the Parent field as a column, saving the query as a Shared query or Team favorite, and adding the Query results widget to your dashboard.
Here are the steps to view query results in a dashboard with Parent titles:
- Create the query that filters the work items of interest.
- Add the Parent field as a column.
- Save the query as a Shared query or Team favorite.
- Add the Query results widget to your dashboard and configure the query.
Query Editor
The Query Editor is a powerful tool in Azure DevOps that allows you to create and customize queries to find specific work items.
To use the Query Editor effectively, enter the complete word or phrase specified in the History field of the work items you want to find, as this field is indexed for full-text search. You can also search for the string with a wild card, such as repro*. Common words or stop words are ignored by the query editor, as defined in Configure and Manage Stopwords and Stoplists for Full-Text Search.
If you're not getting the results you expect, try adjusting the word or phrase you entered and running the query again. You can also use the query editor toolbar to test your query and confirm that it returns the expected results.
To define a flat-list query, select New Query from the Work Items page and modify the Values and add or remove clauses as needed. You can also change the Type of query to Work items and direct links or to a Tree of work items.
Here are some default settings for the Query Editor:
- Flat list of work items
- Work Item Type=[Any]
- State=[Any]
Remember, the column widths in query results are saved per query, so you'll need to adjust and save them for each query individually.
Using the Editor
You can enter the complete word or phrase specified in the History field of work items you want to find in the query editor. This will ensure that you get accurate results.
To refine your search, enter the full text for the word you want to search in the query editor. The History field is indexed for full-text search, so entering only a partial word will not return work items that contain the full word.
Common words or stop words, as defined in Configure and Manage Stopwords and Stoplists for Full-Text Search, are ignored by the query editor. This means that words like "the" and "and" will not affect your search results.
If you're not getting the results you expect, try adjusting the word or phrase you entered and running the query again.
Here are some best practices for using the query editor:
- Enter the complete word or phrase specified in the History field
- Enter the full text for the word you want to search
- Use a wild card, such as *, to search for a string
- Ignore common words or stop words
- Test your query to ensure it returns expected results
View Hierarchies with a Work Item Tree
You can use the Tree of Work Items query to view a multi-tiered, nested list of work items. This is especially useful for viewing all backlog items and their linked tasks.
To focus on different parts of the tree, you can choose between Expand all or Collapse all. This feature allows you to zoom in and out of the hierarchy as needed.
You can't construct a query that shows a hierarchical view of Test Plans, Test Suites, and Test Cases because they aren't linked together using parent-child link types.
However, you can create a direct links query that lists test-related work items. This is a good alternative for viewing related work items in a hierarchical manner.
To view the hierarchy through the Test Plans page, you can simply navigate to that page and explore the related work items.
To find linked children, select Match top-level work items first. To find linked parents, select Match linked work items first. This will help you narrow down your search and find the relevant work items.
Here are some steps to keep in mind when working with the Tree of Work Items query:
- Use the query to view a multi-tiered, nested list of work items.
- Choose between Expand all or Collapse all to focus on different parts of the tree.
- Use the direct links query to list test-related work items.
- Select Match top-level work items first to find linked children.
- Select Match linked work items first to find linked parents.
Parameters
To use the Query Editor, you'll need to specify the required parameters. The ID of an existing query is required unless you specify the path or WIQL.
You can specify the ID of an existing query using the --id option. This is the most straightforward way to access a query.
Alternatively, you can specify the query in Work Item Query Language (WIQL) format using the --wiql option. If you do this, the ID and path options will be ignored.
The path of an existing query can also be specified using the --path option. Like the ID option, this will override the WIQL option.
To specify the organization where your query is located, you'll need to use the --org option. This is required if you haven't configured a default organization using az devops configure or picked one up from your git config.
Here are the parameters in a list format for easy reference:
- id: The ID of an existing query. Required unless --path or --wiql is specified.
- wiql: The query in Work Item Query Language (WIQL) format. Ignored if --id or --path is specified.
- path: The path of an existing query. Ignored if --id is specified.
- org: Azure DevOps organization URL. You can configure the default organization using az devops configure -d organization=ORG_URL. Required if not configured as default or picked up using git config.
- project: Name or ID of the project. You can configure the default project using az devops configure -d project=NAME_OR_ID. Required if not configured as default or picked up using git config.
Filters
Filters are a crucial part of Azure DevOps queries, allowing you to narrow down your results and find exactly what you're looking for.
You can interactively filter a query using the Filter function, which makes it easy to quickly access a list of work items based on your assignment, following, mentioned, or recent updates.
There are many types of filters available, including Compare fields, Key words, and Linked work items. You can also use filters to find work items based on blank or empty fields, boolean searches, and identity searches.
Some filters are specific to certain field types, such as the Was Ever operator, which allows you to find work items based on a field match with a previous value. The ASOF operator is also useful for finding work items based on a value defined on a specific date.
Macros can be used to create queries relative to a date, team area path, team iteration, and more. This can be especially helpful when working with large datasets.
Here are some examples of filter types:
- Compare fields: Find work items based on how two fields compare with one another.
- Key words: Find work items based on key words or phrases added through the Discussion.
- Linked work items: Find work items based on direct links or topological/hierarchical link types.
- Logical groupings: Group and nest clauses using AND and OR Boolean operators.
- Query macros: Find work items based on a relative date or other criteria.
- Tags: Find work items based on whether they contain or don't contain a tag.
- Was Ever: Find work items based on a field match with a previous value.
- Wildcard: Find work items based on a wildcard search.
Interactive query filters can also be used to filter query results based on a key word or select fields. This can be a great way to quickly narrow down your results and find what you're looking for.
Query Results
You can view query results in a dashboard, which is a great way to see your work items at a glance. The dashboard displays two types of widgets: Work assigned to me and Query results widget.
The Query results widget is super flexible and can display the results of a flat, tree, or direct-links query. You can even configure the fields displayed through the widget, resize the column fields, and expand and collapse tree and direct-links queries.
To view query results with Parent titles, you'll need to create a query that filters the work items of interest, add the Parent field as a column, and save the query as a Shared query or Team favorite. Then, add the Query results widget to your dashboard and configure the query to display the Parent field.
View Results in Dashboard
You can display query results in a dashboard using various widgets. One of the widgets, the Query results widget, allows you to configure the fields displayed, resize column fields, and expand and collapse tree and direct-links queries.
You can open work items directly from these widgets, making it easy to access the information you need. The Work assigned to me widget lists all proposed or active work items assigned to the signed-in user, showing the ID, State, and Title fields.
To view query results in a dashboard, you can add the Query results widget and configure it to display the results of a flat, tree, or direct-links query. You can also resize the column fields and expand and collapse tree and direct-links queries.
Here are some key features of the Query results widget:
- Lists the ID, State, and Title fields
- Allows you to configure the fields displayed
- Enables you to resize column fields
- Supports tree and direct-links queries
By using these widgets, you can easily view query results in a dashboard and access the information you need.
View Results with Parent Titles
You can view the results of a query with the Parent title displayed. To do so, create a query that filters the work items of interest, which can be a flat-list, tree, or direct-links query.
Add the Parent field as a column to the query. This will allow you to see the Parent title in the results.
To save the query for future use, save it as a Shared query or Team favorite.
To display the Parent field in the Query results widget, add the widget to your dashboard and configure the query to show the Parent field.
The following options are available to filter your first-tier list of work items in a direct links query:
- Only return items that have matching links
- Return all top level items
- Only return items that do not have matching links
You can also view the results of a query with the Parent title displayed by using a work item tree to view hierarchies. This can be done by using the Tree of Work Items query to view a multi-tiered, nested list of work items.
Query Navigation
Query navigation in Azure DevOps is straightforward. You can access the Queries page by selecting the Favorites or All tab.
Each tab contains a directory-focused view that you can filter to find specific queries of interest. You can navigate to a folder, subfolder, or query page as you make selections.
The breadcrumbs are shown at the top of the page, allowing you to easily navigate between folders and queries. You can also select a favorite query or return to the All queries page from the drop-down menu of an open query.
Here are the main navigation options:
- Favorites and All tabs
- Breadcrumbs at the top of the page
- Drop-down menu of an open query
View Dependencies with Direct Links
Viewing dependencies with direct links is a powerful tool in query navigation. You can use the Work items and Direct links query to track work items that depend on other tracked work.
To view dependencies, you can filter your first-tier list of work items by choosing one of the following options. For example, you can return only items that have matching links.
Here are the options to filter your first-tier list of work items:
- 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.
- 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.
You can also filter your first-tier list of work items by choosing one of the following options. For example, you can return all top level work items.
Here are the options to filter your first-tier list of work items:
- Return all top level work items: All first-tier work items return despite 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.
The direct links query also helps you manage commitments your team makes, and you can track dependencies across teams.
Navigation Elements
Navigation Elements are a key part of the Queries page.
The Queries page contains a Favorites and an All tab, with a directory-focused view that you can filter to find specific queries of interest.
As you navigate through the Queries pages, you can go to a folder, subfolder, or a query page. Breadcrumbs are shown at the top of the page to help you keep track of your path.
You can select a favorite query or return to the All queries page from the drop-down menu of an open query.
The breadcrumbs allow you to navigate to a folder, subfolder, or query page with ease.
Run in Boards
You can run queries in Azure Boards, and it's surprisingly easy. To view query results in a dashboard, you can use widgets like "Work assigned to me" or "Query results widget" which display the results of a query and allow you to configure the fields displayed.
To run a query in Azure Boards, you can use the Azure DevOps command line interface. First, you need to choose a query to run, and you can do this by opening the page where you can view all queries defined or shared within your project.
You can also run a query by choosing My Queries or Shared Queries, and then selecting a query to open. Once you've opened the query, you can view the results by right-clicking on the query and choosing View Results, or by double-clicking the query to open it.
Here are the steps to run a query in the CLI:
- Use the az boards query command to run a query.
- See the Get started with Azure DevOps CLI documentation for more information on how to get started with the CLI.
Frequently Asked Questions
Can you query across projects in Azure DevOps?
Yes, you can query across projects in Azure DevOps by creating work item queries that span all projects or filter for specific ones within your organization
How to query pull requests in Azure DevOps?
To query pull requests in Azure DevOps, use the web portal, Visual Studio, or the Azure DevOps command line to list PRs in a specific repository. Start by navigating to the project in the web portal and selecting Repos > Pull requests.
How to run a query in Azure?
To run a query in Azure, expand a folder and select the query title, or use the Azure DevOps command line interface. This will display the query results and allow you to view your previous query settings.
How do I add a query to my ADO dashboard?
To add a query to your ADO dashboard, open the query's More actions menu and select the dashboard from the dropdown list. This will add the query to the chosen dashboard.
Sources
- https://learn.microsoft.com/en-us/azure/devops/boards/queries/history-and-auditing
- https://learn.microsoft.com/en-us/azure/devops/boards/queries/query-operators-variables
- https://learn.microsoft.com/en-us/azure/devops/boards/queries/using-queries
- https://learn.microsoft.com/en-us/azure/devops/boards/queries/about-managed-queries
- https://learn.microsoft.com/en-us/azure/devops/boards/queries/view-run-query
Featured Images: pexels.com