工作項目查詢語言 (WIQL) 語法參考

發行項
04/06/2024

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

您可以使用 WIQL 語法將查詢定義為超連結，或使用工作專案查詢語言（REST API）時。

WIQL 語法支援所有可透過入口網站取得的函式，查詢編輯器再加上一些功能。您可以指定要傳回的欄位，並指定查詢子句的邏輯群組。此外，您可以使用 ASOF 子句，根據上一個日期根據指派進行篩選。

重要

WIQL 語法是用來執行查詢 By Wiql REST API。目前，無法呼叫 API，直接從 WIQL 查詢傳回詳細的工作項目資訊。無論您在 SELECT 語句中包含哪些欄位，API 只會傳回工作專案識別碼。若要取得完整資訊，您需要執行兩個步驟：（1）從WIQL取得工作專案的標識碼，而（2）透過依標識元取得工作專案清單和特定欄位來取得工作專案。

必要條件

查詢只會傳回您擁有此節點許可權中 檢視工作專案 或 檢視工作專案的工作 專案。一般而言，這些許可權會授與每個小組專案的讀者和參與者群組成員。如需詳細資訊，請參閱許可權和群組。

查詢語言概觀

工作專案查詢語言有下列語法代碼段中所示的五個部分，如下表所述。 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編輯器 Marketplace 延伸模組，您可以使用查詢編輯器建構查詢，然後檢視WIQL語法。然後，您可以使用新增至 Boards 的 Wiql 遊樂場中樞來複製和修改 WIQL 語法並執行查詢。

第

範例

SELECT

識別要針對查詢所傳回之每個工作項目傳回的欄位。您可以指定易記名稱或參考名稱。如果名稱包含空白或句號，請使用方括弧（[]）。

FROM

指出您想要查詢尋找工作專案或工作專案之間的連結。

使用 FROM WorkItems 傳回工作專案。
使用 FROM workItemLinks 傳回工作項目之間的連結。如需詳細資訊，請參閱本文稍後的工作專案之間連結的查詢。

WHERE

指定查詢的篩選準則。如需詳細資訊，請參閱本文稍後的篩選條件（WHERE）。

ORDER BY

指定傳回之工作專案的排序順序。您可以為一或多個字段指定遞增（Asc）或遞減（Desc）。例如：
ORDER BY [State] Asc, [Changed Date] Desc

ASOF

指定要套用篩選的日期，以指定歷程記錄查詢。例如，此查詢會傳回在 2020 年 2 月 11 日定義為作用中的所有用戶劇本。根據日期和時間模式中提供的指引來指定日期。 ASOF '02-11-2020'

注意

針對 Azure Boards 進行的查詢 WIQL 長度不得超過 32K 個字元。系統不會允許您建立或執行超過該長度的查詢。

日期和時間模式

您針對 DateTime 字段輸入的日期和時間模式應該符合您透過設定檔選取的日期與時間模式。若要檢視或變更您的選取範圍，請參閱設定時間與地區設定的用戶喜好設定。

顯示 [時間和地區設定] 窗格上 [日期模式] 下拉式清單選項的螢幕快照。顯示 [時間與地區設定] 窗格上 [時間模式] 下拉式清單選項的螢幕快照。

顯示 [時間] 和 [地區設定] 窗格的螢幕快照，其中包含 [日期模式] 和 [時間模式] 字段。

比較中使用的引號（支援單引號或雙引號） DateTime 常值。它們必須是執行查詢之本機用戶端電腦的 .NET DateTime 格式。除非指定時區，否則 DateTime 常值會位於本機計算機的時區。

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

當 DateTime 常值中省略 time 且 dayPrecision 參數等於 false 時，時間會假設為零（午夜）。 dayPrecision 參數的預設設定為 false。

或者，您可以指定不論地區設定為何，都是有效的 ISO 8601 格式。 ISO 8601 代表日期和時間，從年份開始，後面接著月份、日、小時、分鐘、秒和毫秒。例如，2021-12-10 15：00：00.000，代表當地時間下午 3 點的 2021 年 12 月 10 日。使用 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查詢標識碼大於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, 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運算子時使用字詞OR EVERAND 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查詢中使用的宏或變數。

Macro	使用方式
@Me	使用此變數，在包含用戶別名的欄位中自動搜尋目前使用者的別名。例如，如果您將 Field 資料行設定為 Activated By、將 [運算符=] 資料行設定為，並將 [值] 資料行設定為 @Me，您可以找到開啟的工作專案。
@CurrentIteration	使用此變數，根據選取的小組內容，自動篩選指派給所選小組目前短期衝刺的工作專案。
@Project	使用此變數來搜尋目前專案中的工作專案。例如，如果您將 [欄位] 資料行設定為 [小組專案]、將 [運算子=] 資料行設定為，並將 [值] 資料行設定為 @Project，則可以在目前專案中找到所有工作專案。
@StartOfDay @StartOfWeek @StartOfMonth @StartOfYear	使用這些宏，根據目前日期、周、月、年或位移的其中一個值來篩選 DateTime 字段。例如，如果您將 [欄位] 資料行設定為 [建立日期]、將 [運算符>] 資料行設定為 =，並將 [值] 數據行設定為 [@StartOfMonth - 3，則可以尋找在過去 3 個月內建立的所有專案。
@Today	使用此變數來搜尋與目前日期或更早日期相關的工作專案。您也可以藉由減去天數來修改@Today 變數。例如，如果您將 Field 數據行設定為 Activated Date、將 [運算符>] 資料行設定為 =，並將 [值] 資料行設定為 [@Today - 7，您可以在上周找到啟動的所有專案。
[任何]	使用此變數來搜尋與特定欄位所定義之任何值相關的工作專案。

@me 巨集

宏 @me 會取代執行查詢之使用者的 Windows 整合帳戶名稱。下列範例示範如何使用宏和對等的靜態語句。宏適用於與身分識別欄位搭配使用，例如 Assigned To。

WHERE  
   [System.AssignedTo] = @Me

@today 巨集

您可以使用 @today 宏搭配任何 DateTime 欄位。此宏會取代執行查詢之本機計算機上的目前日期午夜。您也可以分別指定@today+x或使用 @today-y x @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

您可以使用 @StartOf... 宏搭配任何 DateTime 欄位。此宏會取代執行查詢之本機計算機上的目前日午夜、周開始、月開始或年初。

注意

需要 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)

內容參數包含宏的索引鍵/值組。例如，如果內容包含索引鍵/值組（project， MyProject），則 @project 會由 MyProject WIQL取代。此取代是工作專案查詢產生器如何處理 Visual Studio中的@project 宏。

指定歷程記錄查詢（`ASOF`）

您可以在查詢中使用 ASOF 子句來篩選符合指定篩選條件的工作專案，因為它們是在特定日期和時間定義。

注意

您無法在 Visual Studio 的查詢產生器中建立 ASOF 查詢。如果您建立包含子句的 ASOF 查詢檔案（.wiq），然後在Visual Studio中載入，則會 ASOF 忽略子句。

假設工作專案已分類為的Fabrikam Fiber\Release 1反覆項目路徑，並在 2022 年 5 月 5 日之前指派給『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`）

查詢工作項目之間的連結

樹狀結構類型查詢範例

直接鏈接查詢範例

更多查詢範例

日期時間模式

范例子句

String 和 PlainText

區域和反覆專案（TreePath）

修飾詞和特殊運算符

意見反應

意見反應

其他資源

工作項目查詢語言 (WIQL) 語法參考

必要條件

查詢語言概觀

日期和時間模式

自訂欄位

指定篩選子句 （WHERE）

篩選條件

操作員

邏輯群組

範例查詢已指派給

宏或變數

@me 巨集

@today 巨集

@StartOfDay、、@StartOfWeek@StartOfMonth宏@StartOfYear

自訂巨集

指定歷程記錄查詢 （ASOF）

設定排序順序 （ORDER BY）

查詢工作項目之間的連結

樹狀結構類型查詢範例

直接鏈接查詢範例

更多查詢範例

日期時間模式

范例子句

String 和 PlainText

區域和反覆專案 （TreePath）

修飾詞和特殊運算符

相關文章

意見反應

意見反應

其他資源

指定篩選子句（`WHERE`）

指定歷程記錄查詢（`ASOF`）

設定排序順序（`ORDER BY`）

區域和反覆專案（TreePath）