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

Azure DevOps Services |Azure DevOps Server |Azure DevOps Server 2022 |Azure DevOps Server 2020

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

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

Prerequisites

查询语言概述

WIQL 有五个部分，如以下语法代码片段所示，并在表中进行了说明。 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-2025'

日期和时间模式

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

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

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

如果文本中 DateTime 省略时间，参数 dayPrecision 等于 false，则假定时间为零（午夜）。 参数的 dayPrecision 默认设置为 false。

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

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

自定义字段

指定筛选器子句 (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] 查找分配给最近更改过工作项的人员的工作项。

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

Operators

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

一些简单的查询作如下所示：

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

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

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

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

逻辑分组

可以使用术语 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和underin运算符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 宏可替换运行查询的用户的 Windows 集成帐户名称。 以下示例演示如何使用宏和等效的静态语句。 该宏旨在与标识字段（如 Assigned To）一起使用。

WHERE  
   [System.AssignedTo] = @Me 

@today 宏

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

以下示例假定今天为 2025 年 1 月 3 日。

WHERE  
   [System.CreatedDate] = @today

等效于：

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

And

WHERE  
   [System.CreatedDate] > @today-2

等效于：

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

@StartOfDay、@StartOfWeek、@StartOfMonth、@StartOfYear 宏

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

这些宏接受格式为 (+/-)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

以下示例假定今天为 2025 年 4 月 5 日。

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

等效于：

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

And

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

等效于：

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

自定义宏

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

public WorkItemCollection Query(string wiql, IDictionary context)

上下文参数包含宏的键值对。 例如，如果上下文包含一个键值对（project， MyProject），则会 @project 在 MyProject WIQL 中被替换。 此替换项查询生成器 @project 如何处理 Visual Studio 中的宏。

指定历史查询 (ASOF)

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

假设工作项在 2025 年 5 月 5 日之前被归类Iteration PathFabrikam 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-2025 00:00:00.0000000'

设置排序顺序 (ORDER BY)

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

以下示例首先按 Priority 升序（默认值） Created Date 和降序（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 筛选条件可能应用于链接或指向作为链接源或目标的任何工作项。 以下示例返回其活动子项之间的 Product Backlog Items 链接。

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'
    )
MODE (Recursive)

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

• 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 查询示例为字段使用引用名称。 查询使用 a Priority=1. 选择工作项（未指定工作项类型）。 查询以 ID 列的形式返回返回和 Title 返回集。 结果按升序排序 ID 。

SELECT
    [System.Id],
    [System.Title],
    [System.State],
    [System.IterationPath]
FROM workitems
WHERE
    [System.TeamProject] = @project
    AND [Microsoft.VSTS.Common.Priority] <> ''
ORDER BY [System.Id]

日期时间模式

根据以下两种模式之一指定日期/时间模式：

• 日期模式和时间模式格式来自 用户首选项、时间和区域设置
• UTC 指定的模式，遵循此模式（Z 追加在日期/时间的后面）。

AND [System.ChangedDate] >= '1/1/2025 00:00:00Z'

示例子句

以下示例语句显示了特定的限定子句。

字符串和纯文本

与或字段进行比较 String 时，引号字符串文本（支持单引号或 PlainText 双引号）。 字符串文本支持所有 Unicode 字符。

WHERE [Custom.Blocking] = 'Not Blocking'
WHERE [Custom.Blocking] <> 'Blocked'

可以使用 contains 运算符搜索字段值中的任何位置的子字符串。

WHERE [System.Description] contains 'WIQL'

区域和迭代 （TreePath）

可以将 UNDER 运算符用于 Area Path 字段 Iteration Path 。 UNDER 运算符评估值是否位于特定分类节点的子树内。 例如，如果子树中存在Area Path、MyProject\Server\AdministrationMyProject\Server\Administration\Feature 1或任何其他节点，则以下表达式的计算结果为 trueMyProject\Server\Administration\Feature 2\SubFeature 5。

WHERE [System.AreaPath] UNDER `MyProject\Server\Administration`

修饰符和特殊运算符

可以在查询表达式中使用一些修饰符和特殊运算符。

使用 IN 运算符来评估字段值是否等于一组值中的任何一个。 支持此运算符StringIntegerDoubleDateTime和字段类型。 以下示例及其语义等效项演示了这一点。

WHERE
    [System.TeamProject] = @project
    AND [System.CreatedBy] IN ('Jamal Hartnett <fabrikamfiber4@hotmail.com>', 'Raisa Pokrovskaya <fabrikamfiber5@hotmail.com>', 'Christie Church <fabrikamfiber1@hotmail.com>')

or

WHERE
    [System.TeamProject] = @project
    AND (
        [System.CreatedBy] = 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'
        OR [System.CreatedBy] = 'Raisa Pokrovskaya <fabrikamfiber5@hotmail.com>'
        OR [System.CreatedBy] = 'Christie Church <fabrikamfiber1@hotmail.com>'
    )

运算符 EVER 用于评估字段值是否等于或曾经等于特定值，整个工作项的所有修订。 String和IntegerDoubleDateTime字段类型支持此运算符。 EVER 运算符有备用语法。 例如，以下代码片段查询是否已将所有工作项分配给 Jamal、Raisa 或 Christie。

WHERE
    [System.TeamProject] = @project
    AND (
        EVER [System.AssignedTo] = 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'
        OR EVER [System.AssignedTo] = 'Raisa Pokrovskaya <fabrikamfiber5@hotmail.com>'
        OR EVER [System.AssignedTo] = 'Christie Church <fabrikamfiber1@hotmail.com>'
    )

使用 Copilot 编写、修复和优化 WIQL

可以使用 AI 助手（例如 GitHub Copilot 或其他 copilot）帮助创建、更正或优化 WIQL 查询。 将 Copilot 视为生产力帮助（而不是权威源），并在针对生产数据运行之前始终检查和测试生成的任何查询。

指南和最佳做法：

• 功能：Copilot 可以将纯语言要求翻译为 WIQL，修复语法错误（不匹配的括号、缺少逗号、错误的关键字）、在友好名称和引用名称之间转换 SELECT 列表、生成 ASOF 子句或日期文本，并建议子句重写以缩小或扩大结果集。
• 验证：始终在查询编辑器或安全测试项目中验证生成的 WIQL。 使用前检查宏（例如 @Me） @Today和依赖区域设置的日期格式。
• 安全性：从不将机密、访问令牌或任何专用连接字符串粘贴到提示中。 删除或编辑提供给 Copilot 的示例中的任何敏感值。
• 性能：要求 Copilot 尽量减少结果有效负载（仅返回所需的字段）、添加适当的 WHERE 筛选器，并避免过度使用 IN 或未绑定的 LIKE 搜索。 请记住 WIQL 查询的 32-K 字符限制。
• 查看边缘案例：确认历史（ASOF）查询、树/链接查询（FROM workItemLinks）的行为以及 WAS EVER/EVER 扫描修订的运算符，这可能更为复杂，可能需要手动优化。

示例 - 从纯英语生成 WIQL：

提示：“返回分配给项目”Fabrikam“中的活动 Bug 的 @Me ID 和标题，并在最近 30 天内修改。 按 ChangedDate desc 排序。”

Copilot 生成：

SELECT [System.Id], [System.Title]
FROM workitems
WHERE
  [System.TeamProject] = 'Fabrikam'
  AND [System.WorkItemType] = 'Bug'
  AND [System.State] = 'Active'
  AND [System.AssignedTo] = @Me
  AND [System.ChangedDate] >= @Today - 30
ORDER BY [System.ChangedDate] DESC

使用 REST API 和 AI 自动执行 WIQL 查询

可以使用 AI 助手（如 Copilot）自动执行双重 WIQL REST API 过程：

1. 使用 Query By Wiql REST API 检索与 WIQL 匹配的工作项 ID。
2. 使用 “获取工作项 API” 获取这些 ID 的完整详细信息。

AI 可帮助你：

• 使用纯语言生成 WIQL，然后在代码中链接两个 API 调用（例如 Python、PowerShell 或 JavaScript）。
• 设置仪表板或报表的格式和汇总结果。

示例：使用 Python 和 AI 自动执行 WIQL

假设你想要列出项目中所有活动 bug 的标题和状态。

提示 Copilot：
“编写 Python 代码，该代码使用 Azure DevOps REST API 列出项目中所有活动 bug 的标题和状态。 使用 WIQL 获取 ID，然后获取这些 ID 的详细信息。

可以使用 Copilot 生成如下所示的代码：

import requests

# Azure DevOps organization and project info
org = "your-org"
project = "your-project"
pat = "your-personal-access-token"
headers = {"Authorization": f"Basic {pat}"}

# Step 1: Run WIQL query to get work item IDs
wiql = {
    "query": """
        SELECT [System.Id]
        FROM workitems
        WHERE [System.TeamProject] = '{project}'
          AND [System.WorkItemType] = 'Bug'
          AND [System.State] = 'Active'
    """.format(project=project)
}
wiql_url = f"https://dev.azure.com/{org}/{project}/_apis/wit/wiql?api-version=6.1-preview.2"
resp = requests.post(wiql_url, json=wiql, headers=headers)
ids = [item["id"] for item in resp.json()["workItems"]]

# Step 2: Get work item details
if ids:
    ids_str = ",".join(map(str, ids))
    details_url = f"https://dev.azure.com/{org}/{project}/_apis/wit/workitemsbatch?api-version=6.1-preview.1"
    body = {"ids": ids, "fields": ["System.Title", "System.State"]}
    details_resp = requests.post(details_url, json=body, headers=headers)
    for item in details_resp.json()["value"]:
        print(f"{item['fields']['System.Title']} - {item['fields']['System.State']}")
else:
    print("No active bugs found.")

相关内容

• 按 Wiql 查询 （REST API）
• 获取工作项 （REST API）
• 查询快速参考
• 工作项字段和属性
• 链接类型引用
• 权限和组
• 设置首选项