工作项查询语言 (WIQL) 语法参考

项目
07/19/2022

Azure DevOps Services | Azure DevOps Server 2020 | Azure DevOps Server 2019 | TFS 2018

可以使用 WIQL 语法将查询定义为超链接，或使用工作项查询语言 (REST API) 时。

WIQL 语法支持通过 Web 门户提供的所有函数，查询编辑器另外几个函数。可以指定要返回的字段，并指定查询子句的逻辑分组。此外，还可以使用 ASOF 子句根据以前日期的分配进行筛选。

重要

WIQL 语法用于执行查询 By Wiql REST API。目前，无法调用 API 直接从 WIQL 查询返回详细的工作项信息。无论 SELECT 语句中包含哪些字段，API 仅返回工作项 ID。若要获取完整信息，需要执行两个步骤： (1) 从 WIQL 获取工作项的 ID， (2) 通过按 ID 获取工作项列表和特定字段获取工作项列表。

先决条件

查询仅返回具有此节点权限中 “查看工作项 ”或 “查看工作项 ”的工作项。通常，这些权限将授予每个团队项目的读者和 参与者 组的成员。有关详细信息，请参阅权限和组。

查询语言概述

工作项查询语言包含以下语法代码片段所示的五个部分，如下表所述。 WIQL 语法不区分大小写。

SELECT
    [System.Id],
    [System.AssignedTo],
    [System.State],
    [System.Title],
    [System.Tags]
FROM workitems
WHERE
    [System.TeamProject] = 'Design Agile'
    AND [System.WorkItemType] = 'User Story'
    AND [System.State] = 'Active'
ORDER BY [System.ChangedDate] DESC
ASOF '02-11-2020'

提示

通过安装 Wiql 编辑器市场扩展，可以使用查询编辑器构造查询，然后查看 WIQL 语法。然后，可以使用添加到 Boards 的 Wiql Playground 中心复制和修改 WIQL 语法并运行查询。

子句

示例

SELECT

标识要为查询返回的每个工作项返回的字段。可以指定友好名称或引用名称。如果名称包含空白或句点，请使用方括号 ([]) 。

FROM

指示是希望查询查找工作项还是工作项之间的链接。

用于 FROM WorkItems 返回工作项。
用于 FROM workItemLinks 返回工作项之间的链接。有关详细信息，请参阅本文后面的工作项之间的查询。

WHERE

指定查询的筛选条件。有关详细信息，请参阅本文后面的 “筛选条件” (WHERE) 。

ORDER BY

指定返回的工作项的排序顺序。可以为一个或多个字段指定升序 (Asc) 或降序 (Desc) 。例如：
ORDER BY [State] Asc, [Changed Date] Desc

ASOF

通过指示要应用筛选器的日期来指定历史查询。例如，此查询返回 2020 年 2 月 11 日定义为 Active 的所有用户情景。根据日期和时间模式中提供的指南指定日期。 ASOF '02-11-2020'

注意

针对Azure Boards进行的查询的 WIQL 长度不得超过 32K 个字符。系统不允许创建或运行超过该长度的查询。

日期和时间模式

为 DateTime 字段输入的日期和时间模式应与通过配置文件选择的日期和时间模式匹配。若要查看或更改所选内容，请参阅 “设置用户首选项”、“时间和区域设置”。

“时间和区域设置”页、“日期模式”选项 “时间”和“区域设置”页、“时间模式”选项

时间和区域设置页面，日期模式选项

比较中使用的 DateTime 文本) 支持引号 (单引号或双引号。它们必须采用运行查询的本地客户端计算机的 .NET DateTime 格式。除非指定时区，否则 DateTime 文本位于本地计算机的时区中。

WHERE [System.ResolvedDate] >= '01-18-2019 GMT' and [Resolved Date/Time] < '01-09-2019 GMT'
WHERE [Resolved Date] >= '01-18-2019 14:30:01'

当日期时间文本中省略时间且 dayPrecision 参数等于 false 时，假定时间为零 (午夜) 。 dayPrecision 参数的默认设置为 false。

自定义字段

可以将自定义字段添加到查询子句。使用 WIQL 时，必须为自定义字段指定引用名称。对于使用继承进程模型的项目，自定义字段通常标有 Custom。 前面加上其名称，并删除了空格。例如：

友好名称	引用名称
审批者	Custom.Approver
请求类型	Custom.RequestType
范围估计	Custom.CustomEstimate

对于使用本地 XML 进程模型的项目，引用名称由 XML 工作项类型定义定义。

若要了解详细信息，请参阅 “工作项”字段和属性。

可以将自定义字段添加到查询子句。使用 WIQL 时，必须为自定义字段指定引用名称。

若要了解详细信息，请参阅添加或修改字段以跟踪工作。

指定筛选器子句 (`WHERE`)

子 WHERE 句指定筛选条件。查询仅返回满足指定条件的工作项。例如，以下示例 WHERE 子句返回活动且分配给你的用户情景。

WHERE [Work Item Type] = 'User Story'
   AND [State] = 'Active'
   AND [Assigned to] = @Me

可以通过将逻辑运算符括在括号中以对筛选条件进行分组来控制计算顺序。例如，若要返回分配给你或关闭的工作项，请更改查询筛选器以匹配以下示例。

WHERE
    [System.TeamProject] = @project
    AND (
        [System.WorkItemType] = 'Product Backlog Item'
        AND (
            [System.AssignedTo] = @me
            OR [Microsoft.VSTS.Common.ClosedBy] = @me
        )
    )

筛选条件

每个筛选条件由三个部分组成，每个部分必须符合以下规则：

字段：可以指定引用名称或友好名称。以下示例是有效的 WIQL 语法：
- 引用名称： SELECT [System.AssignedTo] ...
- 具有空格的友好名称： SELECT [Assigned To] ...
- 不带空格的名称不需要方括号： SELECT ID, Title ...
运算符：本文后面的 “运算符” 部分中指定了有效值。
字段值：可以根据指定的字段指定以下三个值之一。
- 文本值必须与字段值的数据类型匹配。
- 指示特定值的 *变量或宏。例如， @Me 指示运行查询的人员。有关详细信息，请参阅本文后面的宏和变量。
- 另一 个字段的名称。例如，可用于 [Assigned to] = [Changed by] 查找分配给最近更改工作项的人员的工作项。

有关所有系统定义字段的说明和引用名称，请参阅 “工作项”字段索引。

运算符

查询使用逻辑表达式来限定结果集。这些逻辑表达式由一个或多个串联操作构成。

下面列出了一些简单的查询操作。

WHERE
    [System.TeamProject] = @project
    AND [System.WorkItemType] <> ''
    AND [System.AssignedTo] = 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'
    AND [Microsoft.VSTS.Common.Severity] <> '1 - Critical'

下表汇总了不同字段类型支持的所有运算符。有关每个字段类型的详细信息，请参阅 “工作项”字段和属性。

运算符 =, <>, >, <, >=, and <= 按预期工作。例如， System.ID > 100 查询 ID 大于 100 的所有工作项。 System.ChangedDate > '01-01-19 12:00:00' 查询 2019 年 1 月 1 日中午后更改的所有工作项。

除了这些基本运算符之外，还有一些特定于某些字段类型的行为和运算符。

注意

可用的操作员取决于你的平台和版本。有关详细信息，请参阅查询快速参考。

字段类型

支持的运算符

布尔

= , <> , =[Field] , <>[Field]

DateTime

= , <> , > , < , >= , <= , =[Field], <>[Field], >[Field], <[Field], >=[Field], <=[Field], In, Not In, Was Ever

Double、GUID、Integer

= , <> , > , < , >= , <= , =[Field], <>[Field], >[Field], <[Field], >=[Field], <=[Field], In, Not In, Was Ever

标识

= , <> , > , < , >= , <= , =[Field], <>[Field], >[Field], <[Field], >=[Field], <=[Field], Contains, Does Not Contain, In, Not In, In Group, Not In Group, Was Ever

PlainText

Contains Words, Does Not Contain Words, Is Empty, Is Not Empty

String

= , <> , > , < , >= , <= , =[Field], <>[Field], >[Field], <[Field], >=[Field], <=[Field], Contains, Does Not Contain, In, Not In, In Group, Not In Group, Was Ever

TreePath

=, <>, In, Not In, Under, Not Under

逻辑分组

可以使用术语 AND 和 OR 典型的布尔值来评估两个子句。可以使用术语 AND EVER 和 OR EVER 指定 WAS EVER 运算符时。可以根据需要对逻辑表达式进行分组，并进一步连接它们。下面显示了示例。

WHERE
    [System.TeamProject] = @project
    AND (
        [System.WorkItemType] <> ''
        AND [System.State] IN ('Active', 'Approved', 'Committed', 'In Progress')
        AND (
            [System.CreatedBy] = ''
            OR [System.AssignedTo] = 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'
        )
    )

可以使用来否定 contains, under, 和 in 运算符 not。不能否定 ever 运算符。下面的示例查询未在子树 Fabrikam Fiber\Account Management下分配的所有工作项。

WHERE
    [System.TeamProject] = @project
    AND [System.WorkItemType] <> ''
    AND NOT [System.AreaPath] UNDER 'Fabrikam Fiber\Account Management'

示例查询，已分配给

以下查询编辑器示例查找分配给 Jamal Hartnett 的所有工作项。

分配了查询编辑器平面列表查询的屏幕截图。

而且，下面是相应的 WIQL 语法。

SELECT
    [System.Id],
    [System.Title],
    [System.State],
    [System.IterationPath]
FROM workitems
WHERE
    [System.TeamProject] = @project
    AND [System.WorkItemType] <> ''
    AND EVER [System.AssignedTo] = 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'

宏或变量

下表列出了可在 WIQL 查询中使用的宏或变量。

宏	使用情况
@Me	使用此变量可在包含用户别名的字段中自动搜索当前用户的别名。例如，如果将字段列设置为 “已激活者”、“ 运算符 ”列和 =“ 值 ”列 @Me，则可以找到打开的工作项。
@CurrentIteration	使用此变量根据所选团队上下文自动筛选分配给所选团队当前冲刺的工作项。
@Project	使用此变量搜索当前项目中的工作项。例如，如果将“字段”列设置为“团队项目”、“操作员”列和“值”列=以@Project，则可以找到当前项目中的所有工作项。
@StartOfDay @StartOfWeek @StartOfMonth @StartOfYear	使用这些宏基于当前日期、周、月、年或偏移量之一筛选 DateTime 字段。例如，如果将“字段”列设置为“创建日期”，将“运算符”列设置为 =，将“值”列>设置为@StartOfMonth - 3，则可以找到在过去 3 个月内创建的所有项。
@Today	使用此变量可搜索与当前日期或更早日期相关的工作项。还可以通过减去天数来修改 @Today 变量。例如，如果将字段列设置为 “已激活日期”、“ 运算符 ”列设置为 >=，将值列设置为 @Today - 7，则可以找到上周激活的所有项。
[任何]	使用此变量可搜索为特定字段定义的任何值的相关工作项。

宏	使用情况
@Me	使用此变量可在包含用户别名的字段中自动搜索当前用户的别名。例如，如果将字段列设置为 “已激活者”、“ 运算符 ”列和 =“ 值 ”列 @Me，则可以找到打开的工作项。
@CurrentIteration	使用此变量根据所选团队上下文自动筛选分配给所选团队当前冲刺的工作项。
@Project	使用此变量搜索当前项目中的工作项。例如，如果将“字段”列设置为“团队项目”、“操作员”列和“值”列=以@Project，则可以找到当前项目中的所有工作项。
@Today	使用此变量可搜索与当前日期或更早日期相关的工作项。还可以通过减去天数来修改 @Today 变量。例如，如果将字段列设置为 “已激活日期”、“ 运算符 ”列设置为 >=，将值列设置为 @Today - 7，则可以找到上周激活的所有项。
[任何]	使用此变量可搜索为特定字段定义的任何值的相关工作项。

@me 宏

该 @me 宏将替换运行查询的用户的 Windows 集成帐户名称。下面的示例演示如何使用宏和等效的静态语句。该宏用于标识字段，例如 Assigned To。

WHERE  
   [System.AssignedTo] = @Me

@today 宏

可以将宏与任何 DateTime 字段一起使用@today。此宏替换运行查询的本地计算机上的当前日期的午夜。还可以分别指定@today+x或使用 x 天后@today和 y 天前@today的@today-y整数偏移量。使用宏的 @today 查询可以返回不同的结果集，具体取决于运行它的时区。

以下示例假定今天为 1/3/19。

WHERE  
   [System.CreatedDate] = @today

等效于：

WHERE  
   [System.CreatedDate] = '01-03-2019'

且

WHERE  
   [System.CreatedDate] > @today-2

等效于：

WHERE  
   [System.CreatedDate] > '01-01-2019'

@StartOfDay、、@StartOfWeek@StartOfMonth@StartOfYear宏

可以将宏与任何 DateTime 字段一起使用@StartOf...。此宏替换运行查询的本地计算机上的当前日午夜、星期开始、月开始或年初。

注意

需要Azure DevOps Server 2019 Update 1 或更高版本。

这些宏接受格式为的 (+/-)nn(y|M|w|d|h|m)修饰符字符串。与 @Today 宏类似，可以指定加减整数偏移量。如果省略时间单位限定符，则默认为函数的自然周期。例如，@StartOfWeek("+1") 和 @StartOfWeek("+1w") 相同。如果省略加/减 (+/-) 符号，则假定加号。

此语法允许嵌套修饰符并两次偏移查询。例如，子句 Closed Date >= @StartOfYear - 1筛选自去年以来已关闭的工作项。通过将其修改为 Closed Date >= @StartOfYear('+3M') - 1，它将排除去年头三个月内关闭的工作项。 WIQL 语法如以下示例所示。

WHERE 
   [Microsoft.VSTS.Common.ClosedDate] >=@StartOfYear('+3M') - 1

以下示例假定今天为 4/5/19。

WHERE  
   [Microsoft.VSTS.Common.CreatedDate] >= @StartOfMonth-3

等效于：


WHERE 
   [Microsoft.VSTS.Common.CreatedDate] >= '01-01-2019'

且

WHERE 
   [Microsoft.VSTS.Scheduling.TargetDate] > @StartOfYear

等效于：

WHERE 
   [Microsoft.VSTS.Scheduling.TargetDate]  > '01-01-2019'

自定义宏

WIQL 还支持任意自定义宏。以 @ 自定义宏为前缀的任何字符串都将被视为自定义宏，将被替换。从对象模型中查询方法的上下文参数中检索自定义宏的替换值。以下方法是用于宏的 API：

public WorkItemCollection Query(string wiql, IDictionary context)

上下文参数包含宏的键值对。例如，如果上下文包含 (项目的键值对，MyProject) ， 则 WIQL 中将替换 MyProject @project。此替换是工作项查询生成器如何处理 Visual Studio 中的 @project 宏。

指定历史查询 (`ASOF`)

可以在查询中使用 ASOF 子句来筛选满足指定筛选条件的工作项，因为它们是在特定日期和时间定义的。

注意

无法在 Visual Studio 的查询生成器中创建 ASOF 查询。如果创建包含子句的查询文件 (.wiq) ASOF ，然后在 Visual Studio 中加载该子句，则忽略该 ASOF 子句。

假设工作项在 2022 年 5 月 5 日/05 之前被分类为迭代路径Fabrikam Fiber\Release 1，并分配给“Jamal Hartnett”。但是，工作项最近被分配到“Raisa Pokrovskaya”，并移动到版本 2 的新迭代路径。以下示例查询将返回分配给 Jamal Hartnett 的工作项，因为查询基于过去日期和时间的工作项的状态。

SELECT
    [System.Id],
    [System.Title],
    [System.State],
    [System.IterationPath]
FROM workitems
WHERE
    [System.TeamProject] = @project
    AND [System.WorkItemType] <> ''
    AND ([System.IterationPath] UNDER 'Fabrikam Fiber\Release 1'
    AND [System.AssignedTo] = 'Jamal Hartnett <fabrikamfiber4@hotmail.com>') 
    ASOF  '01-05-2022T00:00:00.0000000'

注意

如果未指定时间，WIQL 将使用午夜。如果未指定时区，WIQL 将使用本地客户端计算机的时区。

设置排序顺序 (`ORDER BY`)

可以使用 ORDER BY 子句按升序或降序按一个或多个字段对查询结果进行排序。

注意

数据层上 SQL Server 的排序首选项决定了默认排序顺序。但是，可以使用 asc 或 desc 参数选择显式排序顺序。

以下示例 先按升 序对工作项进行排序， (默认) ，然后按 “创建日期 ”按降序排序 (DESC) 。

SELECT
    [System.Id],
    [System.Title],
    [System.State],
    [System.IterationPath]
FROM workitems
WHERE
    [System.TeamProject] = @project
    AND [System.WorkItemType] <> ''
    AND [System.State] =  'Active'
    AND [System.AssignedTo] = 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'
ORDER BY [Microsoft.VSTS.Common.Priority],
    [System.CreatedDate] DESC

查询工作项之间的链接

若要返回工作项之间的链接，请指定 FROM WorkItemLinks。子 WHERE 句中的筛选条件可以应用于链接或任何作为链接源或目标的工作项。例如，以下查询返回产品积压工作项与其活动子项之间的链接。

SELECT
    [System.Id],
    [System.Title],
    [System.State],
    [System.IterationPath]
FROM workitemLinks
WHERE
    (
        [Source].[System.TeamProject] = @project
        AND [Source].[System.WorkItemType] = 'Product Backlog Item'
    )
    AND (
        [System.Links.LinkType] = 'System.LinkTypes.Hierarchy-Forward'
    )
    AND (
        [Target].[System.TeamProject] = @project
        AND [Target].[System.WorkItemType] <> ''
        AND [Target].[System.State] <> 'Closed'
    )
ORDER BY [Microsoft.VSTS.Common.Priority],
    [System.CreatedDate] DESC
MODE (Recursive)

下表汇总了工作项查询与工作项之间链接的查询之间的差异。

子句

工作项

工作项之间的链接

FROM

FROM WorkItems

FROM WorkItemLinks

WHERE

[FieldName] = Value

Specify one or more of the following:
[Source].[FieldName] = Value
[Target].[FieldName] = Value
[System.Links.LinkType] = 'LinkName'

MODE

不适用

指定以下值之一：

MODE (MustContain)： (默认) 仅返回满足源、目标和链接条件的 WorkItemLinkInfo 记录。
MODE (MayContain)：返回满足源和链接条件的所有工作项的 WorkItemLinkInfo 记录，即使没有链接的工作项满足目标条件也是如此。
MODE (DoesNotContain)：仅当没有链接的工作项满足链接和目标条件时，才返回满足源的所有工作项的 WorkItemLinkInfo 记录。
MODE (Recursive)：用于树查询 ([System.Links.LinkType] = 'System.LinkTypes.Hierarchy-Forward') 。链接类型必须是树拓扑和向前方向。返回满足源、递归目标的所有工作项的 WorkItemLinkInfo 记录。 ORDER BY 并且 ASOF 与树查询不兼容。

RETURNS

WorkItemQueryResult

WorkItemLink

可以指定以下系统链接类型名称之一。

可以指定以下系统链接类型名称之一，或者使用本地 XML 进程定义的自定义链接类型。

System.LinkTypes.Hierarchy-Forward
System.LinkTypes.Related
System.LinkTypes.Dependency-Predecessor
System.LinkTypes.Dependency-Successor
Microsoft.VSTS.Common.Affects-Forward (CMMI 进程)

有关详细信息，请参阅链接类型参考。

树类型查询示例

以下查询返回当前项目中定义的所有工作项类型。如查询编辑器所示的查询如下图所示。

查询编辑器、树查询、所有工作项和状态的屏幕截图。

等效的 WIQL 语法如下所示。

SELECT
    [System.Id],
    [System.Title],
    [System.State],
    [System.IterationPath]
FROM workitemLinks
WHERE
    (
        [Source].[System.TeamProject] = @project
        AND [Source].[System.WorkItemType] <> ''
        AND [Source].[System.State] <> ''
    )
    AND (
        [System.Links.LinkType] = 'System.LinkTypes.Hierarchy-Forward'
    )
    AND (
        [Target].[System.TeamProject] = @project
        AND [Target].[System.WorkItemType] <> ''
    )
MODE (Recursive)

直接链接查询示例

以下查询返回当前项目中定义的所有工作项类型。如查询编辑器所示的查询如下图所示。

查询编辑器、直接链接查询、所有工作项和状态的屏幕截图。

等效的 WIQL 语法如下所示。

SELECT
    [System.Id],
    [System.WorkItemType],
    [System.Title],
    [System.AssignedTo],
    [System.State]
FROM workitemLinks
WHERE
    (
        [Source].[System.TeamProject] = @project
        AND [Source].[System.WorkItemType] <> ''
        AND [Source].[System.State] <> ''
    )
    AND (
        [System.Links.LinkType] = 'System.LinkTypes.Dependency-Reverse'
        OR [System.Links.LinkType] = 'System.LinkTypes.Related-Forward'
        OR [System.Links.LinkType] = 'System.LinkTypes.Dependency-Forward'
    )
    AND (
        [Target].[System.TeamProject] = @project
        AND [Target].[System.WorkItemType] <> ''
        AND [Target].[System.ChangedDate] >= @today - 60
    )
ORDER BY [System.Id]
MODE (MustContain)

工作项查询语言 (WIQL) 语法参考

先决条件

查询语言概述

日期和时间模式

自定义字段

指定筛选器子句 (`WHERE`)

筛选条件

运算符

逻辑分组

示例查询，已分配给

宏或变量

@me 宏

@today 宏

@StartOfDay、、@StartOfWeek@StartOfMonth@StartOfYear宏

自定义宏

指定历史查询 (`ASOF`)

设置排序顺序 (`ORDER BY`)

查询工作项之间的链接

树类型查询示例

直接链接查询示例

更多查询示例

日期时间模式

示例子句

字符串和纯文本

TreePath) 区域和迭代 (

修饰符和特殊运算符

工作项查询语言 (WIQL) 语法参考

先决条件

查询语言概述

日期和时间模式

自定义字段

指定筛选器子句 (WHERE)

筛选条件

运算符

逻辑分组

示例查询，已分配给

宏或变量

@me 宏

@today 宏

@StartOfDay、、@StartOfWeek@StartOfMonth@StartOfYear宏

自定义宏

指定历史查询 (ASOF)

设置排序顺序 (ORDER BY)

查询工作项之间的链接

树类型查询示例

直接链接查询示例

更多查询示例

日期时间模式

示例子句

字符串和纯文本

TreePath) 区域和迭代 (

修饰符和特殊运算符

相关文章

指定筛选器子句 (`WHERE`)

指定历史查询 (`ASOF`)

设置排序顺序 (`ORDER BY`)