作業項目クエリ言語 (WIQL) 構文リファレンス

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

WIQL 構文を使用して、ハイパーリンクとして、または作業項目クエリ言語 (REST API) を使用する場合にクエリを定義できます。

WIQL では、Web ポータルのクエリエディターで使用できるすべての関数に加えて、いくつかの関数がサポートされています。返すフィールドとクエリ句の論理的なグループ化を指定できます。 ASOF句を使用して、前の日付の割り当てに基づいてフィルター処理することもできます。

Important

WIQL 構文は、 Wiql REST API によるクエリを実行するために使用されます。 API は、 SELECT ステートメントに含めるフィールドに関係なく、作業項目 ID のみを返します。完全な情報を取得するには、(1) WIQL から ID を取得し、(2) ID と特定のフィールドで作業項目の一覧を取得して作業項目を取得します。

Prerequisites

Category	Requirements
Permissions	[作業項目表示]または[このノードの作業項目を表示権限が[を許可]設定されます。通常、これらのアクセス許可は、各チームプロジェクトの閲覧者グループと共同作成者グループのメンバーに付与されます。詳細については、アクセス許可とグループに関する記事を参照してください。

クエリ言語の概要

WIQL には、次の構文スニペットに示すように 5 つの部分があり、表で説明します。 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'

Tip

Wiql エディター Marketplace 拡張機能をインストールすると、クエリエディターを使用してクエリを作成し、WIQL 構文を表示できます。 WIQL 構文をコピーして変更し、Boards に追加された Wiql Playground ハブを使用してクエリを実行できます。

条項	例/説明
`SELECT`	作業項目ごとに返すフィールドを識別します。フレンドリ名または参照名のいずれかを指定できます。名前に空白またはピリオドが含まれている場合は、角かっこ (`[]`) を使用します。
`FROM`	クエリで作業項目と作業項目間のリンクのどちらを検索するかを指定します。 - `FROM WorkItems` を使用して作業項目を返します。 - `FROM workItemLinks` を使用して作業項目間のリンクを返します。詳細については、「作業項目間のリンクのクエリ」を参照してください。
`WHERE`	クエリのフィルター条件を指定します。詳細については、「フィルター条件 (`WHERE`)」を参照してください。
`ORDER BY`	返される作業項目の並べ替え順序を指定します。 1 つ以上のフィールドに昇順 (`Asc`) または降順 (`Desc`) を指定できます。例: `ORDER BY [State] Asc, [Changed Date] Desc`
`ASOF`	フィルターを適用する日付を指定して、履歴クエリを指定します。たとえば、このクエリは、2025 年 2 月 11 日にアクティブとして定義されたすべてのユーザーストーリーを返します。日付は、「日付と時刻のパターン」で説明されているガイダンスに従って指定します。 `ASOF '02-11-2025'`

Note

Azure Boards に対して行われる WIQL クエリは、32 K 文字を超えてはなりません。システムでは、その長さを超えるクエリを作成または実行することはできません。

日付と時刻のパターン

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 の場合、時刻は 0 (午前 0 時) と見なされます。 dayPrecision パラメーターの既定の設定は false です。

または、ロケールに関係なく有効な ISO 8601 形式を指定できます。 ISO 8601 は、年から始まり、その後に月、日、時、分、秒、ミリ秒が続く日付と時刻を表します。たとえば、 2025-12-10 15:00:00.000 は 2025 年 12 月 10 日午後 3 時 (現地時刻) を表します。 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')

カスタムフィールド

クエリ句にカスタムフィールドを追加できます。 WIQL では、カスタムフィールドの参照名を指定する必要があります。継承されたプロセスモデルを使用するプロジェクトの場合、ユーザー設定フィールドには通常、名前の前に Custom. が付き、スペースが削除されます。例えば次が挙げられます。

フレンドリーな名前	参照名
`Approver`	`Custom.Approver`
`Request Type`	`Custom.RequestType`
`Scope Estimate`	`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
        )
    )

フィルター条件

各フィルター条件は、3 つの部分から構成され、それぞれが次の規則に適合している必要があります。

フィールド: 参照名またはフレンドリ名を指定できます。次に、有効なWIQL構文の例を示します。
- 参照名: SELECT [System.AssignedTo] ...
- スペースを含むフレンドリ名: SELECT [Assigned To] ...
- スペースを含まない名前には角かっこは必要ありません: SELECT ID, Title ...
演算子: 有効な値は、この記事の後半の「演算子」セクションで指定します。
フィールド値: 指定したフィールドに応じて、次の 3 つの値のいずれかを指定できます。
- リテラル値は、フィールド値のデータ型と一致する必要があります。
- 特定の値を示す変数またはマクロ。たとえば、 @Me はクエリを実行しているユーザーを示します。詳細については、「マクロと変数」を参照してください。
- 別の フィールドの名前。たとえば、[Assigned to] = [Changed by] を使用すると、作業項目を最近変更したユーザーに割り当てられている作業項目を検索できます。

すべてのシステム定義フィールドの説明と参照名については、作業項目フィールドのインデックスに関する記事を参照してください。

Operators

クエリでは、論理式を使って結果セットを修飾します。これらの論理式は、1 つ以上の結合された操作によって形成されます。

簡単なクエリ操作の一部を次に示します。

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 日の正午以降に変更されたすべての作業項目のクエリ。

これらの基本的な演算子以外にも、特定のフィールド型に固有の動作と演算子がいくつか存在します。

Note

使用できる演算子は、プラットフォームとバージョンによって異なります。詳細については、クエリクイックリファレンスを参照してください。

Field タイプ	サポートされている演算子
`Boolean`	`= , <> , =[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`
`Identity`	`= , <> , > , < , >= , <= , =[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 という用語を使って、2 つの句を評価できます。 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 クエリ内で使用できるマクロまたは変数の一覧です。

Macro	Usage
`@Me`	この変数を使用すると、ユーザーエイリアスを含むフィールドで、現在のユーザーのエイリアスを自動検索できます。たとえば、 `Field` 列を `Activated By`に設定し、 `Operator` 列を `=`、 `Value` 列を `@Me`に設定すると、開いた作業項目を見つけることができます。
`@CurrentIteration`	この変数を使うと、選んだチームの現在のスプリントに割り当てられた作業項目を、選んだチームのコンテキストに基づいて自動的にフィルター処理することができます。
`@Project`	この変数を使うと、現在のプロジェクト内の作業項目を検索できます。たとえば、 `Field` 列を `Team Project`に設定し、 `Operator` 列を `=`、 `Value` 列を `@Project`に設定すると、現在のプロジェクトのすべての作業項目を検索できます。
`@StartOfDay` `@StartOfWeek` `@StartOfMonth` `@StartOfYear`	これらのマクロを使用して、現在の日、週、月、年、またはこれらの値のいずれかに対するオフセットに基づいて、 `DateTime` フィールドをフィルター処理します。たとえば、 `Field` 列を `Created Date`に設定し、 `Operator` 列を `>=`、 `Value` 列を `@StartOfMonth - 3`に設定すると、過去 3 か月間に作成されたすべてのアイテムを検索できます。
`@Today`	この変数を使用すると、現在の日付または以前の日付に関連する作業項目を検索できます。日数を減算して、 `@Today` 変数を変更することもできます。たとえば、 `Field` 列を `Activated Date`に設定し、 `Operator` 列を `>=`、 `Value` 列を `@Today - 7`に設定すると、先の週にアクティブ化されたすべてのアイテムを見つけることができます。
`[Any]`	この変数を使用すると、特定のフィールドに定義されている値に関連した作業項目が検索されます。

`@me` マクロ

@me マクロは、クエリを実行するユーザーの Windows 統合アカウント名に置き換えられます。次の例は、マクロと同等の静的ステートメントを使用する方法を示しています。このマクロは、Assigned To などの ID フィールドでの使用を目的としています。

WHERE  
   [System.AssignedTo] = @Me

`@today` マクロ

@today マクロは、任意のDateTimeフィールドで使用できます。このマクロは、クエリを実行するローカルコンピューターの現在の日付の午前 0 時に置き換えられます。また、@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") と同じです。プラス/マイナス (+/-) 記号が省略された場合は、プラスと見なされます。

この構文では、修飾子を入れ子にしたり、クエリを 2 回オフセットしたりできます。たとえば、この句 Closed Date >= @StartOfYear - 1 、昨年以降に閉じられた作業項目をフィルター処理します。 Closed Date >= @StartOfYear('+3M') - 1に変更すると、昨年の最初の 3 か月以内に終了した作業項目は除外されます。次の 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 は任意のカスタムマクロもサポートしています。 @によってプレフィックスされた文字列は、カスタムマクロとして扱われ、置き換えられます。カスタムマクロの置換値は、オブジェクトモデル内のクエリメソッドの context パラメーターから取得されます。次のメソッドは、マクロに使われる API です。

public WorkItemCollection Query(string wiql, IDictionary context)

context パラメーターには、マクロのキーと値のペアが含まれています。たとえば、コンテキストにキーと値のペア (project、 MyProject) が含まれている場合、 @project は WIQL の MyProject に置き換えられます。この置換は、作業項目クエリビルダーが Visual Studio で @project マクロを処理する方法です。

履歴クエリを指定する (`ASOF`)

クエリで ASOF 句を使うと、特定の日付と時刻に定義された、指定したフィルター条件を満たす作業項目をフィルター処理できます。

Note

Visual Studio のクエリビルダーでは、ASOF クエリは作成できません。 .wiq句を含むクエリファイル (ASOF) を作成し、Visual Studio で読み込む場合、ASOF句は無視されます。

2025 年 5 月 5 日より前に、作業項目がIteration PathのFabrikam Fiber\Release 1に分類され、"Jamal Hartnett" に割り当てられたとします。ただし、この作業項目は最近 'Raisa Pokrovskaya' に割り当てられ、新しいイテレーションパスである Release 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'

Note

時刻が指定されていない場合、WIQL では午前 0 時が使われます。タイムゾーンが指定されていない場合、WIQL はローカルクライアントコンピューターのタイムゾーンを使います。

並べ替え順序を設定する (`ORDER BY`)

ORDER BY 句を使って、クエリの結果を 1 つ以上のフィールドで昇順または降順に並べ替えることができます。

Note

データ層の SQL サーバーの並べ替え設定によって、既定の並べ替え順序が決まります。ただし、asc または desc パラメーターを使って、明示的な並べ替え順序を選択できます。

次の使用例は、作業項目を昇順 (既定) で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)

次の表は、作業項目のクエリと、作業項目間のリンクに対するクエリの違いをまとめたものです。

条項	作業項目	作業項目間のリンク
`FROM`	`FROM WorkItems`	`FROM WorkItemLinks`
`WHERE`	`[FieldName] = Value`	次の 1 つ以上を指定します。 `[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 プロセス)

詳細については、リンクの種類のリファレンスを参照してください。

ツリー型のクエリ例

Note

ORDER BY と ASOF は、ツリークエリと互換性がありません。これらの句はツリークエリに含めないでください。

次のクエリは、現在のプロジェクトで定義されているすべての作業項目の種類を返します。クエリエディターには、次の図に示すようにクエリが表示されます。

クエリエディター、ツリークエリ、すべての作業項目と状態のスクリーンショット。

同等の 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 クエリの例では、フィールドに参照名を使っています。このクエリでは、 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]

日付と時刻のパターン

日付-時刻パターンは、次の 2 つのパターンのいずれかに従って指定します。

日付パターンと時刻パターンの形式は、ユーザー設定、時刻、およびロケールから取得されます
UTC で指定されたパターンで、このパターンに従う場合、日付-時刻に Z が付加されます。

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

句の例

次のステートメント例では、具体的な修飾句を示しています。

条項	Example
`AND`	`SELECT [System.Id], [System.Title]<br>FROM WorkItems<br>WHERE [System.TeamProject] = @project<br>AND [System.AssignedTo] = 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'`
`OR`	`SELECT [System.Id], [System.Title]<br>FROM WorkItems<br>WHERE [System.TeamProject] = @project<br>AND ([System.AssignedTo] = 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'<br>OR [System.AssignedTo] = 'Raisa Pokrovskaya <fabrikamfiber5@hotmail.com>')`
`NOT`	`SELECT [System.Id], [System.Title]<br>FROM WorkItems<br>WHERE [System.TeamProject] = @project<br>AND [System.AssignedTo] EVER 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'<br>AND [System.AssignedTo] NOT CONTAINS 'Raisa Pokrovskaya <fabrikamfiber5@hotmail.com>'`
`EVER`	`SELECT [System.Id], [System.Title]<br>FROM WorkItems<br>WHERE [System.TeamProject] = @project<br>AND [System.AssignedTo] EVER 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'`
`UNDER`	`SELECT [System.Id], [System.Title]<br>FROM WorkItems<br>WHERE [System.TeamProject] = @project<br>AND [System.AssignedTo] EVER 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'<br>AND [System.AreaPath] UNDER 'Agile1\Area 0'`
`ORDER BY`	`SELECT [System.Id], [System.Title]<br>FROM WorkItems<br>WHERE [System.TeamProject] = @project<br>AND [System.AssignedTo] = 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'<br>ORDER BY [System.Id] [asc \| desc]`
`ASOF` (時間フィルター)	`SELECT [System.Title]<br>FROM workitems<br>WHERE [System.IterationPath] = 'MyProject\Beta'<br>AND [System.AssignedTo] = 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'<br>ASOF '3/16/25 12:30'`

文字列とプレーンテキスト

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\Administration、 MyProject\Server\Administration\Feature 1、 MyProject\Server\Administration\Feature 2\SubFeature 5、またはその他のノードであった場合に true に評価されます。

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

修飾子と特殊演算子

クエリ式では、いくつかの修飾子と特殊演算子を使用できます。

フィールド値がいずれかの値セットと等しいかどうかを評価するには、IN 演算子を使います。この演算子は、 String、 Integer、 Double、および DateTime フィールドの種類でサポートされています。次の例とそのセマンティック同等の例は、これを示しています。

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、 Integer、 Double、 DateTime の各フィールド型でサポートされます。 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 やその他の副操縦士など) を使用して、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' の @Me に割り当てられ、過去 30 日間に変更されたアクティブなバグの ID とタイトルを返します。 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 クエリを自動化する

Copilot などの AI アシスタントを使用して、2 段階の WIQL REST API プロセスを自動化できます。

Wiql REST API によるクエリを使用して、WIQL に一致する作業項目 ID を取得します。
Get Work Items API を使用して、これらの ID の完全な詳細をフェッチします。

AI は次の場合に役立ちます。

プレーン言語から WIQL を生成し、コード内の 2 つの API 呼び出し (Python、PowerShell、JavaScript など) をチェーンします。
ダッシュボードまたはレポートの結果の書式設定と集計を行います。

Tip

REST API の詳細については、 Wiql によるクエリ (REST API) に関するページを参照してください。

例: Python と AI を使用して WIQL を自動化する

プロジェクト内のすべてのアクティブなバグのタイトルと状態を一覧表示するとします。

Copilot へのプロンプト:
"Azure DevOps REST API を使用して、プロジェクト内のすべてのアクティブなバグのタイトルと状態を一覧表示する Python コードを記述します。 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.")

フィードバック

このページはお役に立ちましたか?

Last updated on 2025-10-08

次の方法で共有

作業項目クエリ言語 (WIQL) 構文リファレンス

Prerequisites

クエリ言語の概要

日付と時刻のパターン

カスタム フィールド

フィルター句を指定する (WHERE)

フィルター条件

Operators

論理グループ化

クエリの例: 次の値と等しかったことがある、割り当て先

マクロまたは変数

@me マクロ

@today マクロ

@StartOfDay、@StartOfWeek、@StartOfMonth、@StartOfYear マクロ

カスタム マクロ

履歴クエリを指定する (ASOF)

並べ替え順序を設定する (ORDER BY)

作業項目間のリンクのクエリ

ツリー型のクエリ例

直接リンク クエリの例

その他のクエリ例

日付と時刻のパターン

句の例

文字列とプレーンテキスト

領域とイテレーション (TreePath)

修飾子と特殊演算子

Copilot を使用して WIQL の作成、修正、最適化を行う

REST API と AI を使用して WIQL クエリを自動化する

関連コンテンツ

フィードバック

その他のリソース

カスタムフィールド

フィルター句を指定する (`WHERE`)

`@me` マクロ

`@today` マクロ

`@StartOfDay`、`@StartOfWeek`、`@StartOfMonth`、`@StartOfYear` マクロ

カスタムマクロ

履歴クエリを指定する (`ASOF`)

並べ替え順序を設定する (`ORDER BY`)

直接リンククエリの例

領域とイテレーション (`TreePath`)