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

项目
04/17/2024

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

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

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

重要

WIQL 语法用于执行通过 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

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

ASOF

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

注意

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

日期和时间模式

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

显示“时间和区域设置”窗格上的“日期模式”下拉列表选项的屏幕截图。显示“时间和区域设置”窗格上的“时间模式”下拉列表选项的屏幕截图。

显示“时间和区域设置”窗格以及“日期”模式和“时间模式”字段的屏幕截图。

比较中使用的引号（支持单引号或双引号）日期/时间文本。它们必须采用运行查询的本地客户端计算机的 .NET 日期/时间格式。除非指定了时区，否则日期/时间文本采用本地计算机的时区。

WHERE 
   AND [System.ChangedDate] >= '01-18-2019 GMT'
   AND ([Closed Date] < '01-09-2022 GMT'
   OR [Resolved Date] >= '01-18-2019 14:30:01')

如果日期/时间文本中省略了时间，并且 dayPrecision 参数等于 false，则假定时间为零点（午夜）。 dayPrecision 参数的默认设置为 false。

或者，可以指定无论区域设置为何都有效的 ISO 8601 格式。 ISO 8601 表示日期和时间，从年份开始，然后是月、日、小时、分钟、秒和毫秒。例如，2021-12-10 15:00:00.000 表示当地时间 2021 年 12 月 10 日下午 3 点。使用 ISO 8601 格式的示例如下所示。

WHERE 
   AND [System.ChangedDate] >= '2019-01-18T00:00:00.0000000'
   AND ([Closed Date] < '2022-01-09T00:00:00.0000000'
   OR [Resolved Date] >= '2019-01-18T00:00:00.0000000')

自定义字段

可以将自定义字段添加到查询子句。使用 WIQL 时，必须指定自定义字段的引用名称。对于使用继承的流程模型的项目，自定义字段的名称前面通常会加上“Custom.”，并移除空格。例如：

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

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

有关详细信息，请参阅工作项字段和属性。

指定筛选器子句 (`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

双精度、GUID、整数

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

标识

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

PlainText

Contains Words, Not Contains Words, Is Empty, Is Not Empty

String

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

TreePath

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

逻辑分组

可以使用术语 AND 和 OR 在典型布尔意义上计算两个子句。指定 WAS EVER 运算符时，可以使用术语 AND EVER 和 OR 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>'
        )
    )

可以使用 not 对 contains, under, 和 in 运算符求反。不能对 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	使用此变量可根据所选团队上下文自动筛选分配给所选团队的当前冲刺 (sprint) 的工作项。
@Project	使用此变量可搜索当前项目中的工作项。例如，如果将“字段”列设置为“团队项目”，将“运算符”列设置为 =，将“值”列设置为“@Project”，则可查找当前项目中的所有工作项。
@StartOfDay @StartOfWeek @StartOfMonth @StartOfYear	使用这些宏可以基于当前星期几、月、年或这些值之一的偏移量筛选“日期/时间”字段。例如，如果将“字段”列设置为“创建日期”、将“运算符”列设置为“>=”，将“值”列设置为“@StartOfMonth - 3”，则可查找过去 3 个月中创建的所有项。
@Today	使用此变量可搜索与当前日期或更早日期相关的工作项。还可以通过减去天数来修改 @Today 变量。例如，如果将“字段”列设置为“激活日期”、将“运算符”列设置为“>=”，将“值”列设置为“@Today - 7”，则可查找过去一周激活的所有项。
[Any]	使用此变量可搜索为特定字段定义的任何值的相关工作项。

@me 宏

@me 宏可替换运行查询的用户的 Windows 集成帐户名称。下面的示例演示了如何使用宏和等效的静态语句。该宏旨在与标识字段（如 Assigned To）一起使用。

WHERE  
   [System.AssignedTo] = @Me

@today 宏

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

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

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 宏

可以将 @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

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

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)

上下文参数包含宏的键值对。例如，如果上下文包含一个键值对 (project, MyProject)，则 @project 就会在 WIQL 中被替换为 MyProject。此替换是工作项查询生成器在 Visual Studio 中处理 @project 宏的方式。

指定历史查询 (`ASOF`)

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

备注

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

假设工作项在 2022 年 5 月 5 日之前被分类到迭代路径 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-2022 00: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`)