Shared Queries Azure DevOps

In this tutorial, I will walk you through everything you need to know to create, manage, and optimize shared queries in Azure DevOps. This isn’t just about technical clicks; it’s about building a “single source of query” for your entire organization.

Shared Queries Azure DevOps

Why Shared Queries

Shared queries allow you to:

• Align Stakeholders: Ensure that everyone—from your Scrum Master to your VP of Engineering—is tracking the same KPIs.
• Standardize Reporting: Create a uniform way to view “Technical Debt” or “Sprint Progress.”
• Power Dashboards: Shared queries are the engine behind Azure DevOps Dashboards and Widgets.
• Enhance Communication: Instead of explaining what’s on your plate during a stand-up, you can simply point to a shared view.

Understanding the Query Hierarchy

Azure DevOps organizes queries into two primary folders. Understanding the distinction is the first step toward authority in the tool.

Step 1: Navigating to the Queries Hub

To begin our tutorial, let’s get into the environment.

1. Open your Azure DevOps organization (e.g., dev.azure.com/YourEnterprise).
2. Select your project from the sidebar.
3. Navigate to Boards and click on Queries as shown in the screenshot below.

You will see the two-pane view I mentioned earlier. If you are part of a large team, the Shared Queries folder might already contain subfolders such as “Sprints,” “Bugs,” or “Management Reports.”

Step 2: Creating Your First Shared Query

Let’s say our goal is to track all “High Priority Bugs” across a specific release.

Drafting the Logic

Click on New Query. You’ll be presented with the Query Editor. This is where the magic happens. I tend to follow a standard logic flow:

• Work Item Type: = Bug
• State: <> Closed (This ensures we only see active work)
• Priority: = 1 or 2
• Area Path: Under your specific product area.

Saving to Shared Queries

This is the most critical part of the tutorial. When you click Save Query, a dialog box appears. By default, it might point to “My Queries.” You must expand the Shared Queries folder to save it there. Check out the screenshot below for your reference.

Pro Tip: Use a naming convention that makes sense for your US-based team. Avoid names like “Query1.” Instead, use [Team Name] - High Priority Bugs - Active.

Step 3: Organizing with Folders and Subfolders

As your project grows from a small startup in Boulder to a massive enterprise, your list of shared queries will become unmanageable if you don’t organize.

I highly recommend creating a folder structure that mirrors your organizational hierarchy or your SDLC phases.

Recommended Folder Structure

1. Management Reports: High-level views for Directors and VPs.
2. Sprint Planning: Queries used during the bi-weekly planning sessions.
3. Triage: Specifically for incoming bugs and feature requests.
4. Quality Assurance: Test case execution status and defect density.
5. Archive: For queries used in previous fiscal years or retired products.

To create a folder, right-click on the Shared Queries root and select New Folder. You can then drag and drop existing queries into these folders.

Step 4: Advanced Query Logic (WIQL and Clauses)

To truly show authority in Azure DevOps, you need to move beyond simple “Equals” statements. I often use Macros to make queries dynamic.

Essential Macros for Shared Queries

• @Me: This is powerful in a shared query because it resolves to whoever is looking at the query. A shared query for “My Active Tasks” will show Mark in Denver his tasks, and Sarah in Miami hers.
• @CurrentIteration: Automatically filters for work items assigned to the current sprint. This saves you from updating the query every two weeks.
• @Today: Useful for finding items created or modified in the last 24 hours (e.g., Created Date > @Today - 1).
• @Project: Ensures the query only looks at the current project context.

Using “Or” Groups

Sometimes you need to find items that are either “Bugs” OR “User Stories” that are “In Progress.”

1. Add your clauses.
2. Select the rows you want to group.
3. Click the Group Clauses icon.This creates the logic: (Type = Bug OR Type = User Story) AND State = In Progress.

Step 5: Managing Permissions and Security

Setting Permissions

1. Click the … (More actions) next to the Shared Queries folder or a specific subfolder.
2. Select Security.
3. Here, you can manage access for groups like [Project]\Contributors or [Project]\Project Administrators.

Key Permissions to Understand:

• Read: Ability to view the query results.
• Edit: Ability to change the query logic.
• Delete: Self-explanatory (be very careful with this!).
• Manage Permissions: The ability to change who can do what.

I usually recommend giving the “Contributors” group Read access, but restricting Edit/Delete to Team Leads and Scrum Masters.

Step 6: Visualizing Data with Charts

A query is just a list of rows, but a chart tells a story. Once you have saved a shared query, click on the Charts tab at the top of the screen.

I find that the following charts provide the most value to US leadership teams:

• Pie Chart: Grouped by “Assigned To” to see workload distribution.
• Stacked Bar Chart: Grouped by “State” and “Priority” to see where bottlenecks are occurring.
• Trend Chart: To track “Work Item Count” over the last 30 days.

Once created, these charts can be added to your team’s Dashboard, making the shared query the engine for real-time visibility.

Best Practices for Maintaining Shared Queries

• Avoid Redundancy: Before creating a new shared query, search for an existing one.
• Use Descriptive Columns: Customize the “Column Options” in your query. If you’re tracking bugs, ensure “Priority” and “Severity” are visible. If you’re tracking tasks, “Original Estimate” and “Remaining Work” are essential.
• Regular Audits: Once a quarter, have your DevOps Lead or Scrum Master review the shared folders and delete anything that hasn’t been used in the past 90 days.
• Documentation: Use the “Description” field in the query properties to explain what the query is for and who the primary audience is.

Troubleshooting Common Issues

Here are a few things I’ve encountered:

1. “I can’t see the Shared Queries folder”: This is usually a permission issue. Ensure you are added to the “Contributors” group at the project level.
2. “The query returns too many results”: Use the Area Path (Under) and Iteration Path (Under) operators to narrow the scope.
3. “The chart isn’t updating”: Remember that charts are based on the saved version of the query. If you change the logic, you must hit Save for the chart to reflect the new data.

Conclusion:

Shared queries in Azure DevOps are more than just a technical feature; they are a fundamental component of an agile culture. By moving your team toward shared views, you reduce “status update” meetings, eliminate confusion, and empower everyone from your developers to your stakeholders to make data-driven decisions.

You may also like the following articles:

• How To Write Queries In Azure Devops
• How to get Project ID in Azure DevOps
• How to add team members in Azure DevOps
• How to Abandon PR in Azure DevOps

Rajkishore

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.