diff --git a/docs/boards/includes/prerequisites-queries.md b/docs/boards/includes/prerequisites-queries.md index c9e4535ff90..344f60ce286 100644 --- a/docs/boards/includes/prerequisites-queries.md +++ b/docs/boards/includes/prerequisites-queries.md @@ -3,7 +3,7 @@ ms.service: azure-devops-boards ms.author: chcomley author: chcomley ms.topic: include -ms.date: 09/07/2021 +ms.date: 09/05/2024 --- @@ -11,9 +11,10 @@ ms.date: 09/07/2021 ::: moniker range="azure-devops" -* You must have **Stakeholder** access to view and run shared queries. All project members have Stakeholder access by default. For more information, see [Change the permissions for a shared query or folder](../queries/set-query-permissions.md). -* You must have **Basic** access or higher to add and save a shared query. -* You must have your **Contribute** permission set to **Allow** for the folder that you want to add a query to. By default, the **Contributors** group *doesn't* have this permission. +* **Access levels:** + * Have **Stakeholder** access to view and run shared queries. All project members have Stakeholder access by default. For more information, see [Change the permissions for a shared query or folder](../queries/set-query-permissions.md). + * Have **Basic** access or higher to add and save a shared query. +* **Permissions:** Have your **Contribute** permission set to **Allow** for the folder that you want to add a query to. By default, the **Contributors** group *doesn't* have this permission. > [!NOTE] > Users with **Stakeholder** access for a public project have full access to query features just like users with **Basic** access. For more information, see [Stakeholder access quick reference](../../organizations/security/stakeholder-access.md). @@ -22,7 +23,7 @@ ms.date: 09/07/2021 ::: moniker range="< azure-devops" -* By default, all project members and users with **Stakeholder** access can view and run all shared queries. You can change the permissions set for a shared query folder or shared query. For more information, see [Set query permissions](../queries/set-query-permissions.md). -* To add and save a query under **Shared queries**, you must be granted **Basic** access or higher. Also, you must have your **Contribute** permission set to **Allow** for the folder you want to add the query to. By default, the **Contributors** group doesn't have this permission. +* **Access levels:** By default, all project members and users with **Stakeholder** access can view and run all shared queries. You can change the permissions set for a shared query folder or shared query. For more information, see [Set query permissions](../queries/set-query-permissions.md). +* **Permissions:** To add and save a query under **Shared queries**, you must be granted **Basic** access or higher. Also, you must have your **Contribute** permission set to **Allow** for the folder you want to add the query to. By default, the **Contributors** group doesn't have this permission. ::: moniker-end diff --git a/docs/boards/queries/linking-attachments.md b/docs/boards/queries/linking-attachments.md index 5503f954ced..06a8ebf446e 100644 --- a/docs/boards/queries/linking-attachments.md +++ b/docs/boards/queries/linking-attachments.md @@ -1,7 +1,7 @@ --- title: Query work items by link or attachment count in Azure Boards titleSuffix: Azure Boards -description: Learn how to query work items based on link type, link count, link restrictions, and attachment file count in Azure Boards. +description: Learn how to query work items based on link type, link count, link restrictions, and attached file count in Azure Boards. ms.custom: boards-queries, engagement-fy23 ms.service: azure-devops-boards ms.assetid: 219717a0-de6e-4f70-8558-54f813f82507 @@ -9,7 +9,7 @@ ms.author: chcomley author: chcomley ms.topic: example-scenario monikerRange: '<= azure-devops' -ms.date: 10/27/2023 +ms.date: 09/06/2024 --- # Query work items by link or attachment count @@ -19,11 +19,11 @@ ms.date: 10/27/2023 You can [link work items to track related work and dependencies](../backlogs/add-link.md) and attach files to share information with your team. You can then list work items based on one or more of the following fields: ::: moniker range="azure-devops" -Attachment File Count | (Discussion) Comment Count | External Link count| Hyperlink Count| Link Comment| Related Link Count|Remote Link Count +Attached File Count | (Discussion) Comment Count | External Link count| Hyperlink Count| Link Comment| Related Link Count|Remote Link Count ::: moniker-end ::: moniker range="< azure-devops" -- Attachment File Count +- Attached File Count - (Discussion) Comment Count - External Link count - Hyperlink Count @@ -129,7 +129,7 @@ The following query finds work items in all projects that are linked to work ite #### [Visual Studio 2015](#tab/visual-studio/) -Use this type of query to list all dependent work items that link to active Product Backlog Items or Bugs that haven't been removed, closed, or completed. Only those dependent work items that are under a product area other than the **Phone Save\Phone Customers** are returned. +Use this type of query to list all dependent work items that link to active Product Backlog Items or Bugs that aren't removed, closed, or completed. Only those dependent work items that are under a product area other than the **Phone Save\Phone Customers** are returned. ![Work Items and Dependent Links Query](media/example-work-item-queries/IC588290.png) @@ -167,7 +167,7 @@ The following table describes fields associated with links and attachments. Most :::row::: :::column span="1"::: - **Attachment File Count** + **Attached File Count** :::column-end::: :::column span="3"::: The number of files attached to the work item and stored in the work item tracking database. @@ -193,7 +193,7 @@ The following table describes fields associated with links and attachments. Most :::column-end::: :::column span="3"::: - The number of links from the work item to artifacts that aren't work items. such as pull requests, commits, changesets, or other link types. + The number of links from the work item to artifacts that aren't work items, such as pull requests, commits, changesets, or other link types. Reference Name=System.ExternalLinkCount, Data type=Integer :::column-end::: :::row-end::: diff --git a/docs/boards/queries/query-operators-variables.md b/docs/boards/queries/query-operators-variables.md index e5665245945..28de54ef10b 100644 --- a/docs/boards/queries/query-operators-variables.md +++ b/docs/boards/queries/query-operators-variables.md @@ -9,7 +9,7 @@ ms.author: chcomley author: chcomley ms.topic: conceptual monikerRange: '<= azure-devops' -ms.date: 06/29/2022 +ms.date: 09/06/2024 --- @@ -17,9 +17,9 @@ ms.date: 06/29/2022 [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] -Here you'll find detailed descriptions of each field data type, query operators, and query macros. Some data types, operators, and macros are only valid for the indicated Azure DevOps version. +This article provides descriptions of each field data type, query operator, and query macro. Some data types, operators, and macros are only valid for the indicated Azure DevOps version. -For a quick reference of query tasks and operators and macros supported for each data type, see [Query quick reference](query-index-quick-ref.md). See also [Create a query/Best practices](using-queries.md#best-practices). +For more information, see [Query quick reference](query-index-quick-ref.md) and [Manage and organize queries](organize-queries.md). @@ -51,7 +51,7 @@ The value you specify for a field must conform to the data type for that field. **DateTime** or **Date/Time** :::column-end::: :::column span="3"::: - A date field in which you can specify a variable, such as **** or ****, or a value, such as 1/1/2023. Enter dates in the Date Pattern you set for your personal profile. (See [Set personal preferences](../../organizations/settings/set-your-preferences.md) for details.) For query examples, see [Query by date or @CurrentIteration](query-by-date-or-current-iteration.md). + A date field in which you can specify a variable, such as **** or ****, or a value, such as `01/01/2025`. Enter dates in the Date Pattern you set for your personal profile. (See [Set personal preferences](../../organizations/settings/set-your-preferences.md) for details.) For query examples, see [Query by date or @CurrentIteration](query-by-date-or-current-iteration.md). For WIQL queries, you can also specify the date in the Coordinated Universal Time (UTC) pattern. For more information, see [Syntax for the Work Item Query Language (WIQL)](wiql-syntax.md). :::column-end::: @@ -77,7 +77,7 @@ The value you specify for a field must conform to the data type for that field. **History** :::column-end::: :::column span="3"::: - Custom formatted field used to track historical information. This data type is only used to support the **History** field. This field is automatically indexed for full-text search when full-text search is available. See [Full-Text and partial word searches](#full-text) described later in this article. For query examples, see [History and auditing](history-and-auditing.md). + Custom formatted field used to track historical information. This data type is only used to support the **History** field. This field is automatically indexed for full-text search when full-text search is available. See [Full-Text and partial word searches](#full-text) described later in this article. For query examples, see [History and auditing](history-and-auditing.md). :::column-end::: :::row-end::: :::row::: @@ -114,7 +114,7 @@ The value you specify for a field must conform to the data type for that field. :::row-end::: :::row::: :::column span="1"::: - **picklistDouble**1 + **picklistDouble** :::column-end::: :::column span="3"::: Custom field defined to contain a pick list of Decimal values. @@ -122,7 +122,7 @@ The value you specify for a field must conform to the data type for that field. :::row-end::: :::row::: :::column span="1"::: - **picklistInteger**1 + **picklistInteger** :::column-end::: :::column span="3"::: Custom field defined to contain a pick list of Integer values. @@ -130,7 +130,7 @@ The value you specify for a field must conform to the data type for that field. :::row-end::: :::row::: :::column span="1"::: - **picklistString**1 + **picklistString** :::column-end::: :::column span="3"::: Custom field defined to contain a pick list of short text string (255 characters or less) values. @@ -149,7 +149,7 @@ The value you specify for a field must conform to the data type for that field. **TreePath** :::column-end::: :::column span="3"::: - A branching tree structure, such as an Area Path or Iteration path. Choose an item from a list of valid values. Find work items that equal, not equal, under or not under a tree structure, or use the In or Not In operators to specify several values. You define the tree structure for a project—[area paths](../../organizations/settings/set-area-paths.md) and [iteration paths](../../organizations/settings/set-iteration-paths-sprints.md)—and then select the ones you want to associate with a team. + A branching tree structure, such as an Area Path or Iteration path. Choose an item from a list of valid values. Find work items that are equal to, not equal to, under, or not under a tree structure. You can also use the `In` or `Not In` operators to specify multiple values. Define the tree structure for a project—[area paths](../../organizations/settings/set-area-paths.md) and [iteration paths](../../organizations/settings/set-iteration-paths-sprints.md)—and then select the ones you want to associate with a team. For more information on constructing queries, see [Query by area or iteration path](query-by-area-iteration-path.md) or [Query by date or current iteration](query-by-area-iteration-path.md). @@ -157,7 +157,7 @@ The value you specify for a field must conform to the data type for that field. :::row-end::: > [!NOTE] -> 1. The **picklist...** data types are only assigned to custom fields defined for an inherited process. The Inherited process model is only supported for Azure DevOps Services and Azure DevOps Server 2019. +> The **picklist...** data types are only assigned to custom fields defined for an inherited process. [!INCLUDE [date-time-pattern](../includes/date-time-pattern.md)] @@ -165,9 +165,9 @@ The value you specify for a field must conform to the data type for that field. ## Query operators -You can use query operators in the following table to specify how each value in a clause must relate to the corresponding value in a work item. For information about the data type that is assigned to work item fields, see [Work item field reference](../work-items/guidance/work-item-field.md). +Use query operators in the following table to specify how each value in a clause must relate to the corresponding value in a work item. For information about the data type that is assigned to work item fields, see [Work item field reference](../work-items/guidance/work-item-field.md). -To learn about adding clauses and use of the And/Or operators, see [Define a query](using-queries.md). +For more information, see [Define a query](using-queries.md). :::row::: :::column span="1"::: @@ -272,7 +272,8 @@ To learn about adding clauses and use of the And/Or operators, see [Define a que :::column-end::: :::column span="3"::: - Name of a field that is of the same data type as the specified field + Name of a field that is of the same data type as the specified field
+ Checks if the Boolean field is equal to another field :::column-end::: :::row-end::: @@ -286,7 +287,8 @@ To learn about adding clauses and use of the And/Or operators, see [Define a que :::column-end::: :::column span="3"::: - Name of a field that is of the same data type as the specified field + Name of a field that is of the same data type as the specified field
+ Checks if the Boolean field isn't equal to another field :::column-end::: :::row-end::: @@ -396,7 +398,7 @@ To learn about adding clauses and use of the And/Or operators, see [Define a que :::column span="3"::: Doesn't contain the exact text string or words within the field you selected for filtering. Text string is limited to 100 characters. - Use this operator in combination with a clause with the **Contains Words** operator to include and exclude specific keywords. + Use this operator in combination with a clause with the `Contains Words` operator to include and exclude specific keywords. :::column-end::: :::column span="3"::: @@ -410,7 +412,7 @@ To learn about adding clauses and use of the And/Or operators, see [Define a que :::column-end::: :::column span="3"::: - Matches any value in a delimited set. For example, you can find work items whose IDs are 100, 101, and 102 if you specify those values for the ID field. 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(,). + Matches any value in a delimited set. For example, you can find work items whose IDs are 100, 101, and 102 if you specify those values for the ID field. 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 `,`. :::column-end::: :::column span="3"::: @@ -425,7 +427,7 @@ To learn about adding clauses and use of the And/Or operators, see [Define a que :::column-end::: :::column span="3"::: - Lists work items that contain an empty HTML field. You don't specify a value with this operator. This operator is supported for Azure Boards (cloud service), Azure DevOps Server 2019, and later versions. + Lists work items that contain an empty HTML field. You don't specify a value with this operator. This operator is supported for Azure Boards and Azure DevOps Server. :::column-end::: :::column span="3"::: @@ -438,7 +440,7 @@ To learn about adding clauses and use of the And/Or operators, see [Define a que :::column-end::: :::column span="3"::: - Lists work items that contain some content in the HTML field. You don't specify a value with this operator. This operator is supported for Azure Boards (cloud service), Azure DevOps Server 2019, and later versions. + Lists work items that contain some content in the HTML field. You don't specify a value with this operator. This operator is supported for Azure Boards and Azure DevOps Server. :::column-end::: :::column span="3"::: @@ -451,10 +453,10 @@ To learn about adding clauses and use of the And/Or operators, see [Define a que :::column-end::: :::column span="3"::: - Doesn't match any value in a delimited set. You can exclude work items whose states are not Resolved, Completed, or Closed from query results if you specify those values for the State field. 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(,). + Doesn't match any value in a delimited set. You can exclude work items whose states aren't Resolved, Completed, or Closed from query results if you specify those values for the State field. 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 `,`. - > The **Not In** operator is available from Azure Boards and TFS 2018.2 and later versions. + > The **Not In** operator is supported for Azure Boards and Azure DevOps Server. :::column-end::: @@ -477,12 +479,10 @@ To learn about adding clauses and use of the And/Or operators, see [Define a que :::column span="3"::: **String** that matches the name of a team, security group, or category defined in the system. - - > [!NOTE] > You can use the **In Group** operator only with fields that use the **String** data type or the **Work Item Type** field. You can also use groups defined in Microsoft Entra ID when your Azure Boards account is backed by Microsoft Entra ID, or Active Directory when your on-premises server instance is backed by Active Directory. - For information about category groups, see [Use categories to group work item types](/previous-versions/azure/devops/reference/xml/use-categories-to-group-work-item-types). + For information, see [Use categories to group work item types](/previous-versions/azure/devops/reference/xml/use-categories-to-group-work-item-types). :::column-end::: :::row-end::: @@ -496,7 +496,7 @@ To learn about adding clauses and use of the And/Or operators, see [Define a que :::column-end::: :::column span="3"::: - **String** that matches the name of a user group in Team Foundation Server or a category group defined for a project. + **String** that matches the name of a user group in Azure DevOps Server or a category group defined for a project. > [!NOTE] > You can use the **Not In Group** operator only with fields that use the **String** data type or the **Work Item Type** field. You can also use groups defined in Microsoft Entra ID when your Azure Boards account is backed by Microsoft Entra ID, or Active Directory when your on-premises server instance is backed by Active Directory. @@ -544,7 +544,7 @@ To learn about adding clauses and use of the And/Or operators, see [Define a que **String** , **DateTime** > [!NOTE] - > **Was Ever** on date fields is not currently supported when using the Query Editor. They are only supported when doing a direct WIQL. + > **Was Ever** on date fields isn't currently supported when using the Query Editor. They're only supported when doing a direct WIQL. :::column-end::: :::row-end::: @@ -577,7 +577,7 @@ You can use the macros described in the following table to filter your queries b **[Any]** :::column-end::: :::column span="3"::: - Use with the **Work Item Type** or **State** fields to search across all work item types or across all states. For example, `Work Item Type=[Any]` won't place any filters based on the work item type. + Use with the **Work Item Type** or **State** fields to search across all work item types or across all states. For example, `Work Item Type=[Any]` doesn't place any filters based on the work item type. :::column-end::: :::row-end::: --- @@ -597,7 +597,7 @@ You can use the macros described in the following table to filter your queries b :::column-end::: :::column span="3"::: Use with the **Iteration Path** field to filter the set of work items assigned to the current sprint +/- *n* sprints based on the [current team focus or context](../../project/navigation/go-to-project-repo.md?toc=/azure/devops/boards/toc.json&bc=/azure/devops/boards/breadcrumb/toc.json). For specific examples, see [Query by date or current iteration](query-by-date-or-current-iteration.md). - The **@CurrentIteration +/- n** macro is supported for Azure Boards, Azure DevOps Server 2019 and later versions, and only when run from the web portal. + The **@CurrentIteration +/- n** macro is supported for Azure Boards, Azure DevOps Server when run from the web portal. :::column-end::: :::row-end::: --- @@ -606,7 +606,7 @@ You can use the macros described in the following table to filter your queries b **@Follows** :::column-end::: :::column span="3"::: - Use with the **ID** field and **In** operator to list all work items that you're following in the project. To learn more about the Follow feature, see [Follow a work item or pull request](../work-items/follow-work-items.md). You can view this same list from the [Work Items page, **Following** pivot view](../work-items/view-add-work-items.md). + Use with the **ID** field and **In** operator to list all work items that you're following in the project. For more information, see [Follow a work item or pull request](../work-items/follow-work-items.md). You can view this same list from the [Work Items page, **Following** pivot view](../work-items/view-add-work-items.md). The **@Follows** macro is supported only when run from the web portal. :::column-end::: :::row-end::: @@ -622,10 +622,10 @@ You can use the macros described in the following table to filter your queries b --- :::row::: :::column span="1"::: - **@MyRecentActivity** 1 + **@MyRecentActivity** :::column-end::: :::column span="3"::: - Use with the **ID** field and **In** operator to list work items that you have viewed or updated in the project within the last 30 days. You can view this same list from the [Work Items page, **My activity** pivot view](../work-items/view-add-work-items.md). + Use with the **ID** field and **In** operator to list work items you viewed or updated in the project within the last 30 days. You can view this same list from the [Work Items page, **My activity** pivot view](../work-items/view-add-work-items.md). :::column-end::: :::row-end::: --- @@ -640,25 +640,25 @@ You can use the macros described in the following table to filter your queries b --- :::row::: :::column span="1"::: - **@RecentMentions** 1 + **@RecentMentions** :::column-end::: :::column span="3"::: - Use with the **ID** field and **In** operator to list work items where you have been mentioned in the Discussion section. You can view this same list from the [Work Items page, **Mentioned** pivot view](../work-items/view-add-work-items.md). + Use with the **ID** field and **In** operator to list work items where you're mentioned in the Discussion section. You can view this same list from the [Work Items page, **Mentioned** pivot view](../work-items/view-add-work-items.md). :::column-end::: :::row-end::: --- :::row::: :::column span="1"::: - **@RecentProjectActivity** 1 + **@RecentProjectActivity** :::column-end::: :::column span="3"::: - Use with the **ID** field and **In** operator to list work items that have been recently updated. The number of work items listed depends on the work tracking activity of the project. For highly active projects, the macro lists work items that have been updated in the project within the last 30 days or so. For less active projects, however, this list could include work items older than 30 days. You can view similar lists from the [Work Items page, **Recently created**, **Recently updated** and **Recently completed** pivot views](../work-items/view-add-work-items.md). The number of work items returned is capped at 5000. + Use with the **ID** field and **In** operator to list work items recently updated. The number of work items listed depends on the work tracking activity of the project. For highly active projects, the macro lists work items updated in the project within the last 30 days or so. For less active projects, however, this list could include work items older than 30 days. You can view similar lists from the [Work Items page, **Recently created**, **Recently updated** and **Recently completed** pivot views](../work-items/view-add-work-items.md). The number of work items returned is capped at 5000. :::column-end::: :::row-end::: --- :::row::: :::column span="1"::: - **@StartOfDay** 2 + **@StartOfDay** :::column-end::: :::column span="3"::: Use with a `DateTime` field to filter for work items that relate to the current date or with a plus/minus offset. For example, you can find all items closed in the last week with the clause `Closed Date>=@StartOfDay-7`. For more examples, see [Query by date or current iteration](query-by-date-or-current-iteration.md). @@ -667,7 +667,7 @@ You can use the macros described in the following table to filter your queries b --- :::row::: :::column span="1"::: - **@StartOfMonth** 2 + **@StartOfMonth** :::column-end::: :::column span="3"::: Use with a `DateTime` field to filter for work items that relate to the current month or with a plus/minus offset. For example, you can find all items created in the last three months with the clause `Created Date>=@StartOfMonth-3`. For more examples, see [Query by date or current iteration](query-by-date-or-current-iteration.md). @@ -676,7 +676,7 @@ You can use the macros described in the following table to filter your queries b --- :::row::: :::column span="1"::: - **@StartOfWeek** 2 + **@StartOfWeek** :::column-end::: :::column span="3"::: Use with a `DateTime` field to filter for work items that relate to the current week or with a plus/minus offset. For example, you can find all items changed in the last two weeks with the clause `Changed Date>=@StartOfWeek-2`. For more examples, see [Query by date or current iteration](query-by-date-or-current-iteration.md). @@ -685,7 +685,7 @@ You can use the macros described in the following table to filter your queries b --- :::row::: :::column span="1"::: - **@StartOfYear** 2 + **@StartOfYear** :::column-end::: :::column span="3"::: Use with a `DateTime` field to filter for work items that relate to the current year or with a plus/minus offset. For example, you can find all features that have a Target Date scheduled within the current year with the clause `Target Date>=@StartOfYear`. For more examples, see [Query by date or current iteration](query-by-date-or-current-iteration.md). @@ -698,7 +698,7 @@ You can use the macros described in the following table to filter your queries b :::column-end::: :::column span="3"::: Only use with the **Area Path** field to filter for work items whose area path corresponds to one assigned to a specific team. Requires you use the **=** operator. For example, you can find all items assigned to the area paths assigned to the Web team with the clause `Area Path=@TeamAreas [Fabrikam Fiber]\Web`. For more examples, see [Query by area or iteration path](query-by-area-iteration-path.md). - The **@TeamAreas** macro is supported for Azure DevOps Server 2019 and later versions, and only when run from the web portal. + The **@TeamAreas** macro is supported for Azure DevOps Server only when run from the web portal. :::column-end::: :::row-end::: --- @@ -711,13 +711,6 @@ You can use the macros described in the following table to filter your queries b :::column-end::: :::row-end::: --- - - -> [!NOTE] -> 1. The **@MyRecentActivity**, **@RecentMentions**, and **@RecentProjectActivity** macros are supported for TFS 2018.2 and later versions. -> 2. The **@StartOfDay**, **@StartOfWeek**, **@StartOfMonth**, and **@StartOfYear** macros are supported for Azure DevOps Server 2019 Update 1 and later versions. - - @@ -727,28 +720,24 @@ Specify **Contains** or **Does Not Contain** to search against exact or partial For examples, see [Example work item queries](query-index-quick-ref.md) and [Query for work items using the History field](history-and-auditing.md). - > [!NOTE] > Not all deployments support full-text searches. For example, SQL Express and SQL Azure, which support the cloud service, do not support full-text search. In these instances, you only see the **Contains** and **Does not Contain** operators. - ::: moniker range="< azure-devops" -Azure DevOps Server and Team Foundation Server automatically index all long-text fields with a data type of **PlainText** and **HTML** and the **Title** field for full-text search. The index and operators are only available when the SQL Server that supports Team Foundation Server supports full-text search. +Azure DevOps Server automatically indexes all long-text fields with a data type of **PlainText** and **HTML** and the **Title** field for full-text search. The index and operators are only available when the SQL Server that supports Azure DevOps Server supports full-text search. -Full-text searches require a SQL collation that corresponds to a language that has a word breaker registered with SQL Server. If the collation settings for the project collection database used for your Team Foundation Server instance don't correspond to a supported language, your search results may not match your expectations. In these cases, you might try using the **Contains** or **Does Not Contain** operators. +Full-text searches require a SQL collation that corresponds to a language that has a word breaker registered with SQL Server. If the collation settings for the project collection database used for your Azure DevOps Server instance don't correspond to a supported language, your search results might not match your expectations. In these cases, you might try using the **Contains** or **Does Not Contain** operators. For more information, see [Full-Text Search Queries and Collation Settings](/azure/devops/server/install/sql-server/collation-requirements). ::: moniker-end - - ## Related articles -- [Query quick reference](query-index-quick-ref.md) -- [About managed queries](about-managed-queries.md) -- [Work item field index](../work-items/guidance/work-item-field.md) -- [Syntax for the Work Item Query Language (WIQL)](wiql-syntax.md) +- [Use the query quick reference](query-index-quick-ref.md) +- [Learn about managed queries](about-managed-queries.md) +- [Access the work item field index](../work-items/guidance/work-item-field.md) +- [Understand the syntax for the Work Item Query Language (WIQL)](wiql-syntax.md) [!INCLUDE [temp](../includes/rest-apis-queries.md)] diff --git a/docs/boards/queries/using-queries.md b/docs/boards/queries/using-queries.md index a2c45aad557..91c3147d899 100644 --- a/docs/boards/queries/using-queries.md +++ b/docs/boards/queries/using-queries.md @@ -1,7 +1,7 @@ --- title: Define a work item query in Azure Boards titleSuffix: Azure Boards -description: Learn how to use queries and perform tasks like define a flat-list, clause, or hyperlink, and use a tree, direct link, hyperlink or logical expression. Also learn how to query across or within projects and view results in a dashboard, and best practices. +description: Learn how to use queries and perform tasks like define a flat-list, clause, or hyperlink, and use a tree, direct link, hyperlink, or logical expression. Also learn how to query across or within projects and view results in a dashboard, and best practices. ms.custom: boards-queries, linked-from-support, cross-project, engagement-fy23 ms.service: azure-devops-boards ms.assetid: 364000d3-200a-495a-bfb9-83915240af67 @@ -9,7 +9,7 @@ ms.author: chcomley author: chcomley ms.topic: tutorial monikerRange: '<= azure-devops' -ms.date: 08/10/2023 +ms.date: 09/06/2024 --- # Define a work item query in Azure Boards @@ -23,8 +23,7 @@ Work item queries generate lists of work items based on the filter criteria prov You can create queries from the web portal or from a supported client, such as Visual Studio Team Explorer. To support bulk updates or additions, import or export queries using [Excel](../backlogs/office/bulk-add-modify-work-items-excel.md) or [.csv files](import-work-items-from-csv.md). ::: moniker-end - -Check out our recommended best practices, later in this article. +Check out our recommended [best practices](#best-practices), later in this article. [!INCLUDE [temp](../includes/prerequisites-queries.md)] @@ -33,10 +32,8 @@ Check out our recommended best practices, later in this article. From the Query Editor, you can select the filter to jump to an article with sample queries. Along with the query filters, you can [interactively apply filters to query results](../backlogs/filter-backlogs-boards-plans.md). -::: 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. For more information, see [Functional work item search](../../project/search/functional-work-item-search.md). -::: moniker-end --- :::row::: @@ -123,17 +120,17 @@ Modify the **Values** and [add or remove clauses](#define-a-clause), or change t #### [Visual Studio](#tab/visual-studio/) > [!IMPORTANT] -> We strongly recommend that everyone use the [default view](../work-items/view-add-work-items.md?view=azure-devops&tabs=visual-studio&preserve-view=true#open-work-items) instead of this legacy view. It is designed for you to quickly access a list of work items based on your assignment, following, mentioned, or recent updates. The legacy view is no longer being enhanced and we expect to remove it in a future release of Visual Studio. +> We strongly recommend using the [default view](../work-items/view-add-work-items.md?view=azure-devops&tabs=visual-studio&preserve-view=true#open-work-items) instead of this legacy view. This view is designed for you to quickly access a list of work items based on your assignment, following, mentioned, or recent updates. The legacy view is no longer being enhanced and we expect to remove it in a future release of Visual Studio. -Select **New Query** from the **Work Items** page. +1. Select **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."::: + :::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]**. + 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."::: + :::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](#define-a-clause). Or, change the **Type of query** to [Work items and direct links](#use-direct-links-to-view-dependencies) or to a [Tree of work items](#use-a-work-item-tree-to-view-hierarchies). +2. Modify the **Values** and [add or remove clauses](#define-a-clause). Or, change the **Type of query** to [Work items and direct links](#use-direct-links-to-view-dependencies) or to a [Tree of work items](#use-a-work-item-tree-to-view-hierarchies). --- @@ -221,12 +218,9 @@ When finished, choose :::image type="icon" source="../media/icons/run_query.png" ### Checklist for defining 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](query-operators-variables.md#field-values). - 2. In the same row, under the **Operator** column heading, select the down arrow to display the list of available operators, and then choose an item in the list. For more information, see [Operators](query-operators-variables.md#operators). - 3. In the same row, under the **Value** column heading, either enter a value, or select the down arrow, and then 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](query-operators-variables.md#variables). - -5. To add a clause, choose **Add new clause**. +4. To add a clause, choose **Add new clause**. You can add a clause to the end of the query, or perform the following tasks with the corresponding icons: - :::image type="icon" source="../media/icons/add-green-icon.png" border="false"::: **Insert new filter line** @@ -355,7 +349,16 @@ If your query results don't return expected results, do the following steps: To ungroup a clause, select the :::image type="icon" source="../media/icons/ungroup-clause.png" border="false"::: ungroup clauses icon for the grouped clause. ---- +## Set default column width in query results + +To set the default column width in query results, do the following steps: + +1. Open the query you want to modify. +2. Manually adjust the column widths to your desired size by dragging the edges of the column headers. +3. Select **Save** or **Save As** if you want to save it as a new query. +4. Close and reopen the query to ensure that the column widths are retained. + +Azure DevOps doesn't currently support setting a default column width that persists across all sessions. The column widths are saved per query, so you need to adjust and save them for each query individually. ## View query results in a dashboard @@ -481,7 +484,7 @@ The `Contains` operator runs a table scan, which is a slower operation than the The `In Group` operator filters work items based on matches within a group of values. The group of values correspond to the values contained within a team, security group, or [work tracking category](../work-items/agile-glossary.md#categories). For example, you can create a query to find all work items that are assigned to any member of a team. Or, find all work items that belong to the requirements category (`Microsoft.RequirementCategory`). -When you filter on a group that contains a large number of members, your result set tends to be larger and nonselective. Also, if a group corresponds to a large Microsoft Entra group, the query generates a fairly large cost to resolve that group from Microsoft Entra ID. +When you filter on a group that contains a large number of members, your result set tends to be larger and nonselective. Also, if a group corresponds to a large Microsoft Entra group, the query generates a fairly large cost to resolve that group from Microsoft Entra ID. ### Avoid use of negated operators diff --git a/docs/report/powerbi/create-quick-report-odataq.md b/docs/report/powerbi/create-quick-report-odataq.md index ef3d49048df..4f1af269118 100644 --- a/docs/report/powerbi/create-quick-report-odataq.md +++ b/docs/report/powerbi/create-quick-report-odataq.md @@ -7,7 +7,7 @@ ms.author: chcomley author: chcomley monikerRange: '>= azure-devops-2019' ms.topic: quickstart -ms date: 10/17/2022 +ms date: 09/06/2024 --- # Create a Power BI report with an OData Query @@ -16,14 +16,7 @@ ms date: 10/17/2022 With Power BI Desktop, you can easily start creating reports for your project in Azure DevOps. -If you don't have Power BI Desktop, you can [download](/power-bi/desktop-what-is-desktop) and install it for free. - -Follow the steps to create a report in Power BI desktop that shows a **daily trend of bugs**. - -> [!div class="checklist"] -> * Create a Power BI query -> * Create Power BI transforms -> * Create an Open Bugs trend report +If you don't have Power BI Desktop, [download](/power-bi/desktop-what-is-desktop) and install it for free. @@ -33,68 +26,71 @@ To create a Power BI report, you must meet the following criteria: ::: moniker range="azure-devops" -- You must be a member of a project. If you don't have a project yet, create one. See [Sign up for free](../../user-guide/sign-up-invite-teammates.md). -- If you haven't been added as a project member, [get added now](../../organizations/accounts/add-organization-users.md). Anyone with access to the project, except Stakeholders, can view Analytics views. -- Have the **View Analytics** permission set to **Allow**. See [Grant permissions to access Analytics](./analytics-security.md). -- **Boards** must be enabled. To re-enable it, see [Turn an Azure DevOps service on or off](../../organizations/settings/set-services.md). -- Have installed *Power BI Desktop* *October 2018 Update* or later version. You can download this client application from the official [Power BI Desktop download page](/power-bi/desktop-what-is-desktop). -- Have tracked work items for some period of time on which to generate a trend report. +- Be a project member. If you aren't, [get added now](../../organizations/accounts/add-organization-users.md). Anyone with access to the project, except Stakeholders, can view Analytics views. +- Have the **View Analytics** permission set to **Allow**. See [Grant permissions for Analytics access](./analytics-security.md). +- Enable **Boards**. To re-enable Boards, see [Turn an Azure DevOps service on or off](../../organizations/settings/set-services.md). +- Have *[Power BI Desktop](/power-bi/desktop-what-is-desktop)* *October 2018 Update* or later version. +- Track work items for some period of time on which to generate a trend report. ::: moniker-end -::: moniker range=">= azure-devops-2019 < azure-devops" +::: moniker range=" < azure-devops" -- You must be a member of a project. If you don't have a project yet, [create one](../../organizations/projects/create-project.md). -- If you haven't been added as a project member, [get added now](../../organizations/security/add-users-team-project.md). Anyone with access to the project, except Stakeholders, can view Analytics views. -- Have [enabled or installed Analytics](../dashboards/analytics-extension.md). You must be an account owner or a member of the [**Project Collection Administrators** group](../../organizations/security/change-organization-collection-level-permissions.md) to add extensions or enable the service. -- **Boards** must be enabled. To re-enable it, see [Turn an Azure DevOps service on or off](../../organizations/settings/set-services.md). -- Have the **View Analytics** permission set to **Allow**. See [Grant permissions to access Analytics](./analytics-security.md). -- Have installed *Power BI Desktop* *October 2018 Update* or later version. You can download this client application from the official [Power BI Desktop download page](/power-bi/desktop-what-is-desktop). -- Have tracked work items for some period of time on which to generate a trend report. +- Be a project member. If you aren't, [get added now](../../organizations/accounts/add-organization-users.md). Anyone with access to the project, except Stakeholders, can view Analytics views. +- [Enable or install Analytics](../dashboards/analytics-extension.md). You must be an account owner or a member of the [**Project Collection Administrators** group](../../organizations/security/change-organization-collection-level-permissions.md) to add extensions or enable the service. +- Enable **Boards**. To re-enable Boards, see [Turn an Azure DevOps service on or off](../../organizations/settings/set-services.md). +- Have the **View Analytics** permission set to **Allow**. See [Grant permissions for Analytics access](./analytics-security.md). +- Have *[Power BI Desktop](/power-bi/desktop-what-is-desktop)* *October 2018 Update* or later version. +- Track work items for some period of time on which to generate a trend report. ::: moniker-end - -## Create a Power BI Query +## Create a Power BI query -Create a Power BI Query to pull the data into Power BI as follows: +Create a Power BI query to pull the data into Power BI as follows: 1. Choose **Get Data**, and then **Blank Query**. > [!div class="mx-imgBorder"] - > ![Power BI - Blank Query](media/BlankQuery.png) + > ![Screenshot shows Power BI - Blank Query.](media/BlankQuery.png) 2. From the Power BI Query editor, choose **Advanced Editor**. > [!div class="mx-imgBorder"] - > ![Power BI - Select Advanced Editor](media/AdvancedEditor.png) + > ![Screenshot shows Power BI - Select Advanced Editor.](media/AdvancedEditor.png) 3. The Advanced Editor window opens. > [!div class="mx-imgBorder"] - > ![Power BI - Advanced Editor](media/odatapowerbi-advancededitor.png) + > ![Screenshot shows Power BI - Advanced Editor.](media/odatapowerbi-advancededitor.png) -4. Replace the contents with the following query. +4. Replace the contents with the following query: ``` let - Source = OData.Feed ("https://analytics.dev.azure.com/{organization}/{project}/_odata/v4.0-preview/WorkItemSnapshot? " - $apply=filter( - WorkItemType eq 'Bug' - AND StateCategory ne 'Completed' - AND startswith(Area/AreaPath,'{areapath}') - AND DateValue ge {startdate} )/ - groupby((DateValue,State,WorkItemType,Area/AreaPath), aggregate($count as Count)) - &$orderby=DateValue" - ,null, [Implementation="2.0",OmitValues = ODataOmitValues.Nulls,ODataVersion = 4]) - in - Source - ``` - - > [!div class="mx-imgBorder"] - > ![Screenshot of Power BI, Advanced Editor, Pasted Query.](media/odatapowerbi-advancededitor-pasted.png) - -5. Substitute your values within the sample query. + The query you provided has a syntax issue due to the placement of double quotes. Specifically, the `$apply` and `$orderby` parameters should be part of the URL string, but they are not correctly concatenated. Here is the corrected version: + +```markdown +let + Source = OData.Feed ( + "https://analytics.dev.azure.com/{organization}/{project}/_odata/v4.0-preview/WorkItemSnapshot?" + &"$apply=filter(" + &"WorkItemType eq 'Bug' " + &"AND StateCategory ne 'Completed' " + &"AND startswith(Area/AreaPath,'{areapath}') " + &"AND DateValue ge {startdate} )/" + &"groupby((DateValue,State,WorkItemType,Area/AreaPath), aggregate($count as Count))" + &"&$orderby=DateValue", + null, [Implementation="2.0", OmitValues = ODataOmitValues.Nulls, ODataVersion = 4] + ) +in + Source +``` + + > [!div class="mx-imgBorder"] + > ![Screenshot of Power BI, Advanced Editor, Pasted Query.](media/odatapowerbi-advancededitor-pasted.png) + +1. Substitute your values within the sample query. The sample query has strings that you must replace with your values: @@ -106,9 +102,9 @@ Create a Power BI Query to pull the data into Power BI as follows: > [!div class="mx-imgBorder"] > ![Screenshot of Power BI, Advanced Editor, Replaced Strings in Query.](media/odatapowerbi-advancededitor-replaced.png) -6. Choose **Done** to execute the query. +2. Choose **Done** to execute the query. - If you've never connected to your account, Power BI may require you to authenticate. For more information, see [Client authentication options](client-authentication-options.md). + Power BI might require you to authenticate. For more information, see [Client authentication options](client-authentication-options.md). ## Expand Area, Iteration, AssignedTo columns @@ -125,24 +121,24 @@ After closing the **Advanced Editor** and while remaining in the **Power Query E > [!NOTE] > The available properties to select depends on the properties requested to return in the query. If you don't specify any properties, then all properties are available. For more information about these properties, see the following metadata references: [Areas](../analytics/entity-reference-boards.md#areas), [Iterations](../analytics/entity-reference-boards.md#iterations), and [Users](../analytics/entity-reference-general.md#users). -1. The table now contains entity field(s). +1. The table now contains entity fields. > [!div class="mx-imgBorder"] > ![Screenshot of expanded Area columns.](media/transform-data/expanded-area-columns.png) -1. Repeat steps 1 through 3 for all fields representing entities that need expanding. These appear with *Record* listed in the table column when unexpanded. +1. Repeat steps 1 through 3 for all fields representing entities that need to expand. These fields appear with *Record* listed in the table column when unexpanded. ## Rename fields and query, then Close & Apply -When finished, you may choose to rename columns. +When finished, you might choose to rename columns. 1. Right-click a column header and select **Rename...** > [!div class="mx-imgBorder"] > ![Screenshot of Power BI transform data, Rename Columns.](media/transform-data/powerbi-rename-columns.png) -1. You also may want to rename the query from the default **Query1**, to something more meaningful. +1. You also might want to rename the query from the default **Query1**, to something more meaningful. > [!div class="mx-imgBorder"] > ![Screenshot of Power BI transform data, Rename Query.](media/transform-data/powerbi-rename-query.png) @@ -152,27 +148,24 @@ When finished, you may choose to rename columns. > [!div class="mx-imgBorder"] > ![Screenshot of Power BI Power Query Editor, Close & Apply.](media/transform-data/powerbi-close-apply.png) - ## Create the report Power BI shows you the fields you can report on. > [!NOTE] -> The example below assumes that no one renamed any columns. - -:::image type="content" source="media/reports-boards/bug-trends-selections.png" alt-text="Screenshot of Power BI Visualizations and Fields selections for Bug trends report. "::: +> The following example assumes that no one renamed any columns. +> :::image type="content" source="media/reports-boards/bug-trends-selections.png" alt-text="Screenshot of Power BI Visualizations and Fields selections for Bug trends report. "::: For a simple report, do the following steps: 1. Select Power BI Visualization **Line chart**. 1. Add the field "DateValue" to **Axis** - - Right-click "DateValue" and select "DateValue", rather than Date Hierarchy + - Right-click "DateValue" and select "DateValue," rather than Date Hierarchy 1. Add the field "State" to **Legend** 1. Add the field "Count" to **Values** - Right-click WorkItemId field and ensure **Sum** is selected -The example report: - +Example report: :::image type="content" source="media/odatapowerbi-bugtrend-report.png" alt-text="Screenshot of Sample Bug trends line chart report."::: @@ -181,7 +174,6 @@ The example report: > [!div class="nextstepaction"] > [Create an Open bugs report](sample-boards-openbugs.md) - ## Related articles -[!INCLUDE [temp](includes/sample-relatedarticles.md)] \ No newline at end of file +[!INCLUDE [temp](includes/sample-relatedarticles.md)] diff --git a/docs/report/powerbi/includes/sample-relatedarticles.md b/docs/report/powerbi/includes/sample-relatedarticles.md index b62a7c85715..abf55744367 100644 --- a/docs/report/powerbi/includes/sample-relatedarticles.md +++ b/docs/report/powerbi/includes/sample-relatedarticles.md @@ -6,9 +6,9 @@ ms.topic: include ms.date: 12/05/2022 --- -* [Overview of sample reports using OData queries](../sample-odata-overview.md) +* [Explore sample reports using OData queries](../sample-odata-overview.md) * [Construct OData queries for Analytics](../../analytics/analytics-query-parts.md) -* [Connect using Power BI and OData queries](../odataquery-connect.md) -* [Metadata reference for Azure Boards Analytics](../../analytics/entity-reference-boards.md) -* [Sample reports and quick reference index](../../extend-analytics/quick-ref.md) -* [Add a Team slicer to an existing report](../sample-boards-teamslicer.md) \ No newline at end of file +* [Connect to Power BI using OData queries](../odataquery-connect.md) +* [Refer to metadata for Azure Boards Analytics](../../analytics/entity-reference-boards.md) +* [Access sample reports and quick reference index](../../extend-analytics/quick-ref.md) +* [Add a Team slicer to an existing report](../sample-boards-teamslicer.md)