Understanding how to write queries in Azure DevOps isn’t just a technical skill; it’s the secret to maintaining project velocity. In this comprehensive tutorial, I will walk you through everything from basic flat lists to advanced Work Item Query Language (WIQL) syntax.
Table of Contents
- How To Write Queries In Azure DevOps
- Best Practices
- Video Tutorial
- Final Thoughts
How To Write Queries In Azure DevOps
Getting Started: The Query Editor Interface
To begin, navigate to your project in Azure DevOps. On the left-hand sidebar, click on Boards and then select Queries as shown in the screenshot below.
I always recommend starting with the All tab to see what your teammates have already built. To create your own, click on + New query.
Understanding the Anatomy of a Clause
A query is essentially a collection of “clauses.” Each clause consists of four main parts:
- And/Or: The logical connector.
- Field: The data point you’re looking for (e.g., State, Assigned To, Work Item Type).
- Operator: How you want to compare the field to a value (e.g., =, <>, Contains, Under).
- Value: The specific criteria (e.g., “Active”, “@Me”, “Bug”).
Level 1: Writing Flat List Queries
A Flat List is the most common query type. It returns a simple list of work items that meet your criteria.
Common Operators and Their Uses
I always emphasize these essential operators:
| Operator | Use Case | Example |
= | Exact match | State = Active |
<> | Not equal to | Work Item Type <> Task |
Contains | Partial text match | Title Contains "Cloud" |
In | Match any value in a list | State In (New, Approved, Committed) |
Was Ever | Historical search | Assigned To Was Ever "Michael Scott" |
Using Macros for Dynamic Results
Don’t hardcode your name or today’s date. Use Macros to make your queries “smart.”
- @Me: Automatically filters for the person running the query.
- @Today: Filters based on the current date (useful for “Modified Date > @Today – 7”).
- @CurrentIteration: Dynamically stays updated as your team moves from Sprint 1 to Sprint 2.
Level 2: Advanced Query Types (Trees and Direct Links)
You likely need to see relationships.
1. Tree of Work Items
This is used to view hierarchies. If you want to see all Features and the User Stories nested beneath them, use a Tree Query.
- Type of Tree: Set to “Parent/Child” to see the standard breakdown.
- Filter Options: You can choose to match the top-level items first or the child items first.
2. Work Items and Direct Links
Use this when you need to find dependencies. For example, “Show me all Tasks that are blocked by another Work Item.”
- Filter for linked items: This allows you to specify the link type (e.g., Predecessor, Successor, or Related).
Level 3: Mastering WIQL (Work Item Query Language)
For those who want to show true authority, there is WIQL. Think of this as the SQL of Azure DevOps. While the visual editor covers 90% of needs, WIQL is essential for complex API integrations or Power BI reporting.
A typical WIQL query looks like this:
$$SELECT [System.Id], [System.Title], [System.State] FROM WorkItems WHERE [System.TeamProject] = @Project AND [Work Item Type] = 'Bug' AND [System.State] = 'Active' ORDER BY [System.CreatedDate] DESC$$Why use WIQL?
- Portability: You can copy-paste the syntax into other tools.
- Complexity: You can write “ASOF” queries to see what the backlog looked like on a specific date in the past.
- Precision: It allows for specific field reference names that the GUI might hide.
Best Practices
When you save your queries, naming conventions matter—not just for you, but for your team’s ability to find them.
1. Descriptive Naming
Instead of naming a query “My Bugs,” try “Critical_Bugs_Q1_Roadmap.” This tells the user exactly what is inside.
2. Folder Organization
Use the Shared Queries folder to collaborate. I recommend a structure like this:
- Shared Queries
- Current Sprint (Daily Standup queries)
- Release Management (Tracking deployments)
- Triage (Unassigned or new items)
3. Column Options
Don’t forget to click on Column options at the top. Adding “Changed Date” or “Story Points” to your view can save you from having to click into every individual item. Common Pitfalls to Avoid
Even seasoned veterans in our Atlanta headquarters make these mistakes:
- The “Or” Trap: Be careful when mixing
AndandOrclauses. Always use Grouping (the bracket icon in the editor) to ensure the logic evaluates correctly. - Permission Issues: If a colleague can’t see your query, ensure you saved it in Shared Queries and that the folder permissions allow “Read.”
- Over-Filtering: If your query returns zero results, start by removing the most specific clause first.
Summary of Key Query Features
| Feature | Best For… | Beginner/Advanced |
| Flat List | Simple tracking and bulk updates | Beginner |
| Tree Query | Viewing Parent/Child hierarchies | Intermediate |
| Direct Links | Finding dependencies and blockers | Intermediate |
| WIQL | API usage and complex historical data | Advanced |
| Macros (@Me) | Creating reusable, personalized views | Beginner |
Video Tutorial
Final Thoughts
Writing queries in Azure DevOps is the bridge between “having data” and “having insights.” By mastering the editor, using macros, and understanding when to shift to a tree or link view, you ensure your team stays focused.
You may also like the following articles:
- Shared Queries Azure DevOps
- How to get the Project ID in Azure DevOps
- How to add team members in Azure DevOps
- How To Recover Deleted Branch In Azure DevOps
- How To Delete a Pull Request In Azure DevOps
I am Rajkishore, and I am a Microsoft Certified IT Consultant. I have over 14 years of experience in Microsoft Azure and AWS, with good experience in Azure Functions, Storage, Virtual Machines, Logic Apps, PowerShell Commands, CLI Commands, Machine Learning, AI, Azure Cognitive Services, DevOps, etc. Not only that, I do have good real-time experience in designing and developing cloud-native data integrations on Azure or AWS, etc. I hope you will learn from these practical Azure tutorials. Read more.
