クエリを定義するDefine a query

Azure Boards | Azure DevOps Server 2020 | Azure DevOps Server 2019 | TFS 2018 - TFS 2013Azure Boards | Azure DevOps Server 2020 | Azure DevOps Server 2019 | TFS 2018 - TFS 2013

作業項目クエリでは、指定したフィルター条件に基づいて作業項目のリストが生成されます。Work item queries generate lists of work items based on the filter criteria you provide. その後、これらの管理対象クエリを保存し、他のユーザーと共有することができます。You can then save and share these managed queries with others. これに対し、セマンティック検索では作業項目の一覧が表示されますが、保存または共有することはできません。In contrast, semantic searches list work items, but can't be saved or shared.

クエリは、web ポータルまたはサポートされているクライアント (Visual Studio チームエクスプローラーや Team Explorer Everywhere など) から作成できます。You can create queries from the web portal or from a supported client, such as Visual Studio Team Explorer and Team Explorer Everywhere. また、 Excel でクエリを開いて、一括追加や変更を行うこともできます。Also, you can open a query in Excel to perform bulk additions and modifications.

注意

Visual Studio 2019 でクエリを定義するには、 作業項目のエクスペリエンス を [レガシ] オプションに設定する必要があります。To define queries in Visual Studio 2019, you need to Set the Work Items experience to the legacy option.

クエリの結果を返すには時間がかかりすぎている場合は、 パフォーマンスの高いクエリを作成するためのガイダンスを確認してください。If you find that your queries take too long to return results, review the Guidance to create high-performing queries.

この記事では、次のことについて説明します。In this article you'll learn:

  • クエリを追加または作成する方法How to add or create a query
  • プロジェクト間でクエリを実行する方法How to query across projects
  • クエリ句をグループ化およびグループ解除する方法How to group and ungroup query clauses
  • 作業項目のツリーまたは直接リンククエリを作成する方法How to create a tree of work items or a direct-links query

すべてのクエリタスクにすばやくアクセスするには、フィールドのデータ型に基づいて、、、、、および (not 演算子) などのサポートされている演算子を使用し — Contains In In Group <> — ます。クエリの例については、「 クエリクイックリファレンス」を参照してください。For quick access to all query tasks, supported operators—such as, Contains, In, In Group, and <>(not operator) — based on field data type, and query examples, see Query quick reference.

クエリ フィルターQuery filters

クエリエディターから、次のフィルター関数を実行できます。From the Query Editor, you can exercise the following filter functions. フィルターを選択して、サンプルクエリを含む記事に移動します。Choose the filter to jump to an article with sample queries. クエリフィルターに加えて、 クエリ結果にフィルターを対話的に適用できます。In addition to the query filters, you can interactively apply filters to query results.

注意

マネージクエリでは近接検索はサポートされませんが、セマンティック検索ではサポートされます。Managed queries don't support proximity searches, however semantic searches do. また、セマンティック検索では、ワイルドカード文字としてとの両方がサポートされており、複数の * ? ワイルドカード文字を使用して複数の文字に一致させることができます。In addition, semantic searches supports both * and ? as wildcard characters and you can use more than one wildcard character to match more than one character. 詳細については、「 機能する作業項目の検索」を参照してください。To learn more, see Functional work item search.


フィルター機能Filter features

マクロMacros



前提条件Prerequisites

  • 既定では、すべてのプロジェクトメンバーおよび 利害関係 者アクセス権を持つユーザーは、すべての共有クエリを表示および実行できます。By default, all project members and users with Stakeholder access can view and run all shared queries. 共有クエリフォルダーまたは共有クエリに設定されているアクセス許可を変更できます。You can change the permissions set for a shared query folder or shared query. 詳細については、「 クエリのアクセス許可の設定」を参照してください。For details, see Set query permissions.
  • 共有クエリ の下にクエリを追加して保存するには、 Basic アクセス以上の権限が付与されている必要があります。To add and save a query under Shared queries, you must be granted Basic access or higher. また、クエリを追加するフォルダーに対して、[ 投稿 ] アクセス許可が [ 許可 ] に設定されている必要があります。Also, you must have your Contribute permission set to Allow for the folder you want to add the query to. 既定では、 貢献 者グループにはこのアクセス許可がありません。By default, the Contributors group doesn't have this permission.

注意

パブリックプロジェクトに対する 利害関係 者アクセス権を持つユーザーは、 基本的な アクセス権を持つユーザーと同じように、クエリ機能にフルアクセスできます。Users with Stakeholder access for a public project have full access to query features just like users with Basic access. 詳細については、「 アクセスレベルについて」を参照してください。For details, see About access levels.

  • 既定では、すべてのプロジェクトメンバーおよび 利害関係 者アクセス権を持つユーザーは、すべての共有クエリを表示および実行できます。By default, all project members and users with Stakeholder access can view and run all shared queries. 共有クエリフォルダーまたは共有クエリに設定されているアクセス許可を変更できます。You can change the permissions set for a shared query folder or shared query. 詳細については、「 クエリのアクセス許可の設定」を参照してください。For details, see Set query permissions.
  • 共有クエリ の下にクエリを追加して保存するには、 Basic アクセス以上の権限が付与されている必要があります。To add and save a query under Shared queries, you must be granted Basic access or higher. また、クエリを追加するフォルダーに対して、[ 投稿 ] アクセス許可が [ 許可 ] に設定されている必要があります。Also, you must have your Contribute permission set to Allow for the folder you want to add the query to. 既定では、 貢献 者グループにはこのアクセス許可がありません。By default, the Contributors group doesn't have this permission.

クエリを開くOpen Queries

(1) web ブラウザーから、適切なプロジェクトが選択されていることを確認します。 (2) [ ボード>のボード] を選択し、(3) [ すべて 選択] をクリックします。From your web browser, (1) check that you have selected the right project, (2) choose Boards>Queries, and then (3) choose All.

開いているボード>クエリ、垂直ナビゲーションOpen Boards>Queries, vertical nav

クエリ を初めて開くときには、[お気に入り] ページが開きます。If it is your first time opening Queries, the page opens to Favorites. このページには、お気に入りとして指定したクエリが一覧表示されます。This page lists those queries that you have indicated are a favorite. それ以外の場合は、[ すべて ] を選択して、プロジェクトに定義されているすべてのクエリと共有クエリを表示できます。Otherwise, you can choose All to view all queries you've defined and shared queries defined for the project.

ヒント

[ お気に入り ] ページにお気に入りが表示されます。Queries you or your team have chosed as favorites show up on the Favorites page. お気に入りのクエリは、他のオブジェクトと共に、 プロジェクト ページにも表示されます。Favorite queries along with other objects also appear on your Project page. 詳細については、「 個人用またはチームのお気に入りの設定」を参照してください。To learn more, see Set personal or team favorites.

Web ブラウザーから、 ボード>のクエリ を開きます。From your web browser, open Boards>Queries.

Web ブラウザーから、ボード>のクエリを開きます。

フラットリストクエリを定義するDefine a flat-list query

新しいクエリを開始するには、web ポータルの [ クエリ ] タブまたはチームエクスプローラーの [ 作業項目 ] タブを使用します。You can start a fresh, new query from the Queries tab in the web portal or the Work Items tab in Team Explorer.

新しいクエリの追加、新しいエクスペリエンスAdd new query, new experience

[クエリ] ページで、ドロップダウンメニューから [新しいクエリ] を選択します。

プロジェクト内またはプロジェクト内でのクエリQuery across or within projects

既定では、新しいクエリのスコープは現在のプロジェクトになります。By default, new queries are scoped to the current project. ただし、クエリを作成して、組織またはプロジェクトコレクション内で定義された作業項目を検索することができます。However, you can create queries to find work items defined within the organization or project collection. ただし、保存したすべてのクエリは、特定のプロジェクトに保存されます。All queries that you save, however, are saved under a specific project.

2つ以上のプロジェクトで定義されている作業項目を一覧表示するには、 プロジェクト間 のチェックマークを表示します。To list work items defined in two or more projects, checkmark Query across projects. たとえば、次のクエリでは、過去30日以内にすべてのプロジェクトで作成されたすべての機能が検索されます。For example, the following query finds all features created in all projects within the last 30 days.

Web portal, Queries page, Query Editor, Checkbox, Query across projects

注意

プロジェクト間のクエリ 機能は、TFS 2015.1 以降のバージョンでサポートされています。The Query across projects feature is supported from TFS 2015.1 and later versions.

[ プロジェクト間でクエリ を実行する] チェックボックスをオンにすると、チームプロジェクトフィールドを追加して、選択した数のプロジェクトにフィルターを適用できます。With the Query across projects checked, you can add the Team Project field to filter to a select number of projects.

Azure Boards and TFS 2015.1, Web portal, Query across select projects using the In operator

注意

複数のプロジェクト名を、クライアントコンピューターに定義されている地域設定 (コンマ (,) など) に対応するリスト区切り記号で区切ります。Separate multiple project names with the list separator that corresponds to the regional settings defined for your client computer, for example, a comma (,).

[ チームプロジェクト ] フィールドは、 プロジェクト間のクエリ を確認した後にのみ使用できるようになります。The Team Project field becomes available only after you check Query across projects. さらに、[ プロジェクト間でクエリ を実行する] をオフにすると、現在のプロジェクトで定義されているこれらの wit のフィールドのみが [フィールド] ドロップダウンメニューに表示されます。Moreover, when Query across projects is unchecked, only those fields from those WITs defined in the current project appear in the Field drop-down menu. [ プロジェクト間でクエリ を実行する] チェックボックスをオンにすると、コレクション内のすべてのプロジェクトで定義されているすべての wit のすべてのフィールドが [フィールド] ドロップダウンメニューに表示されます。When Query across projects is checked, all fields from all WITs defined in all projects in the collection appear in the Field drop-down menu.

過去30日以内にすべてのプロジェクトで作成されたすべての機能を検索するには、クエリからTeam Project = @Project 句を削除します。To find all features created in all projects within the last 30 days, remove the Team Project=@Project clause from the query.

TFS 2013-2015, Web portal, Query across select projects using the In operator

コレクション内のすべてのプロジェクトで定義されているすべての Wit のすべてのフィールドは、常に [フィールド] ドロップダウンメニューに表示されます。All fields from all WITs defined in all projects in the collection always appear in the Field drop-down menu.

チームプロジェクト = @Project を使用して、現在のプロジェクトに対して定義されている作業項目のみを検索するようにクエリのスコープを設定します。Use Team Project=@Project to scope the query to find only those work items defined for the current project.

句を定義するDefine a clause

クエリを作成するには、1つ以上の句を定義します。You create a query by defining one or more clauses. 各句は、1つのフィールドのフィルター条件を定義します。Each clause defines a filter criteria for a single field. [ 新しい句の追加 ] を選択して別の句を追加し、その句の フィールド演算子、および を選択します。Choose Add new clause to add another clause and then choose the Field, Operator, and Value for that clause.

句を定義します。Define a clause.

たとえば、 割り当て先ユーザー/グループ フィールド、equals (=) 演算子、および @Me ユーザー id を表すマクロを指定することによって、割り当てられているすべての作業項目を検索できます。For example, you can search for all work items assigned to you by specifying the Assigned To field, the equals (=) operator, and the @Me macro which represents your user identity.

サンプルのクエリ句Sample query clause

[ルールの適用条件]And/Or フィールドField 演算子Operator Value

AndAnd

割当先Assigned To

=

@@Me

フィールドのデータ型に基づいて使用できる演算子のクイックリファレンスについては、「 クエリインデックスクイックリファレンス」を参照してください。For a quick reference of the operators available based on the field data type, see Query index quick reference.

追加するすべての句は、ステートメント および ステートメントとして追加されます。All clauses you add are added as an And statement. グループ化を変更するに は、または を選択します。Choose Or to change the grouping. 句をグループ化して、句のステートメントが必要な順序で実行されるようにします。You group clauses to ensure that the clause statements are executed in the sequence required.

ヒント

クエリの WIQL 構文と、句をグループ化するためのかっこの使用方法を表示するには、 Marketplace の Wiql エディターをインストールします。To view the WIQL syntax for a query, and how parenthesis are used to group clauses, install the Marketplace Wiql Editor. この拡張機能では、REST API 呼び出しで使用するために、WIQL 構文を表示し、それを WIQL ファイルにエクスポートできます。This extension supports viewing the WIQL syntax and exporting it to a WIQL file for use in REST API calls. 詳細については、「 作業項目クエリ言語の構文 (WIQL)」を参照してください。To learn more, see Syntax for the Work Item Query Language (WIQL).

クエリ句を定義する方法のチェックリストChecklist for how to define a query clause

  1. 最初の空白行の [ フィールド] 列見出しの下にある下向き矢印をクリックして、使用可能なフィールドの一覧を表示し、一覧内の項目を選択します。In the first empty row, under the Field column heading, choose the down arrow to display the list of available fields, and choose an item in the list.

    詳細については、「 クエリフィールドと値」を参照してください。For more information, see Query Fields and Values.

  2. 同じ行の [ 演算子 ] 列見出しで下向きの矢印をクリックして使用可能な演算子の一覧を表示し、一覧で項目を選択します。In the same row, under the Operator column heading, choose the down arrow to display the list of available operators, and choose an item in the list.

    詳細については、「演算子」を参照してください。For more information, see Operators.

  3. 同じ行の [ ] 列の見出しの下で、値を入力するか、下矢印をクリックしてリスト内の項目を選択します。In the same row, under the Value column heading, either type a value, or choose the down arrow, and choose an item in the list.

    マクロまたは変数を使用して、現在のプロジェクト、ユーザー、日付、またはその他の選択項目を指定する方法の詳細については、「 変数」を参照してください。For more information about how to use a macro or variable to specify the current project, user, date, or other selection, see Variables.

  4. 句を追加するには、[ 新しい句の追加] を選択します。To add a clause, choose Add new clause.

    句をクエリの末尾に追加し、既存の句の後に句を挿入することができます (You can add a clause to the end of the query, insert a clause after an existing clause (句の挿入アイコン)、を削除します (), and remove (句の削除アイコン)、グループ (), group (group 句アイコン) とグループ解除 (), and ungroup (句のグループ解除アイコン) 句が必要です。) clauses as needed.

作業項目のツリーを使用して階層を表示するUse a tree of work items to view hierarchies

複数階層の入れ子になった作業項目の一覧を表示するには、作業項目クエリのツリー を使用します。 たとえば、すべてのバックログ項目と、それらにリンクされたタスクを表示できます。For example, you can view all backlog items and their linked tasks. ツリーのさまざまな部分にフォーカスを移動するには、[ノード] ([ノード]、[web ポータル] の順 に展開) または  [折りたたみ] ([ノードの折りたたみ]) ノードを展開し ます。Expand (Expand node (Expand node, web portal) or collapse (Collapse node, web portal) nodes to focus on different parts of the tree.

注意

Test Plans、テストスイート、およびテストケースの階層ビューを表示するクエリを作成することはできません。You can't construct a query that shows a hierarchical view of Test Plans, Test Suites, and Test Cases. これらの項目は、親子リンクの種類を使用してリンクされていません。These items aren't linked together using parent-child link types. ただし、テストに関連する作業項目を一覧表示するダイレクトリンククエリを作成することはできます。However, you can create a direct links query that lists test-related work items. また、 [テスト>Test Plans] ページで階層を表示することもできます。Also, you can, view the hierarchy through the Test>Test Plans page.

親と子の両方の作業項目に対してフィルター条件を定義します。Define the filter criteria for both parent and child work items. リンクされた子を検索するには、[ 最上位の作業項目を最初に照合] を選択します。To find linked children, select Match top-level work items first. リンク先の親を検索するには、[リンクされた 作業項目を最初に一致] を選択します。To find linked parents, select Match linked work items first.

作業項目とダイレクトリンク のクエリを使用して、タスク、バグ、懸案事項、機能など、追跡対象の他の作業に依存する作業項目を追跡します。 たとえば、実装中の他の項目や修正中のバグに依存するバックログ項目を表示できます。For example, you can view backlog items that depend on other items being implemented or a bug being fixed.

ダイレクト リンク クエリは、自分のチームが依存している他のチームの作業を追跡したり、自分のチームから他のチームに対して行ったコミットメントを管理したりする場合に使用します。Use the direct links query to track dependencies your team has that other teams work on, or manage commitments your team has made to other teams. 最上位の作業項目およびリンクされた作業項目の両方にフィルター条件を指定し、依存関係をフィルター処理するときに使用するリンクの種類を選択します。Specify the filter criteria for both top and linked work items, and select the types of links used to filter the dependencies.

ダイレクトリンクのクエリ結果

ダイレクトリンククエリ、エディターDirect Links Query, editor

ダイレクトリンククエリエディター

次のオプションのいずれかを選択して、作業項目の第 1 層リストをフィルター処理します。Filter your first-tier list of work items by choosing one of these options:

  • 一致するリンクがある項目のみを返す: 第1層の作業項目が返されますが、リンクされた作業項目のフィルター条件によって指定された作業項目へのリンクがある場合にのみ返されます。Only return items that have matching links: First-tier work items are returned, but only if they have links to work items specified by the linked work items filter criteria.

  • 最上位レベルの項目をすべて返す: リンクされた作業項目のフィルター条件に関係なく、すべての第1層の作業項目が返されます。Return all top level items: All first-tier work items are returned regardless of the linked work items filter criteria. 第 1 層にリンクされた第 2 層の作業項目は、作業項目のフィルター条件に一致する場合に返されます。Second-tier work items that are linked to the first tier are returned if they match the linked work items filter criteria.

  • 一致するリンクがない項目のみを返す: 第1層の作業項目が返されますが、リンクされた作業項目のフィルター条件で指定された作業項目へのリンクがない場合にのみ返されます。Only return items that do not have matching links: First-tier work items are returned, but only if they do not have links to work items specified by the linked work items filter criteria.

各リンクの種類の詳細については、「リンク 、追跡可能性、および依存関係の管理」を参照してください。To learn more about each link type, see Linking, traceability, and managing dependencies.

Or 論理式And/Or logical expression

クエリ句の論理式を作成するには 、And また は or を 指定します。You specify And or Or to create logical expressions of your query clauses. 現在の句と前の句の両方で条件を満たす作業項目を検索するには 、と を指定します。Specify And to find work items that meet the criteria in both the current clause and the previous clause. 現在の句または前の句の条件を満たす作業項目を検索するに は、または を指定します。Specify Or to find work items that meet the criterion in either the current clause or the previous clause.

検索条件を絞り込むために、各作業項目フィールドに対して新しい句を 1 つ追加して、目的の作業項目セットのみを返すようにできます。You can add one new clause for each work item field in order to refine your search criteria, so that it returns only the set of work items that you want. クエリから予期していた結果が得られなかった場合は、クエリ句を追加、削除、グループ化、またはグループ解除し、クエリ結果を絞り込むことができます。If you do not receive the results that you expect from your query, you can add, remove, group, or ungroup query clauses to refine your query results.

クエリ句をグループ化すると、クエリの他の部分とは別の1つの単位として動作します。これは、数式や論理ステートメントで式をかっこで囲むのと似ています。You can group query clauses to operate as a single unit separate from the rest of the query, similar to putting parentheses around an expression in a mathematical equation or logic statement. 句をグループ化すると、グループ内の最初の句の AND または or がグループ全体に適用されます。When you group clauses, the AND or OR for the first clause in the group applies to the whole group.

句のグループ化Group clauses

グループ化された句は、数式またはロジック式をかっこで囲むのと同様に、クエリの残りの部分とは別の1つの単位として動作します。Grouped clauses operate as a single unit separate from the rest of the query, similar to putting parentheses around a mathematical equation or logic expression. グループ内の最初の句に対する AND または OR が、グループ全体に適用されます。The And or Or operator for the first clause in the group applies to the whole group.

次の例に示すように、グループ化された句は対応する論理式に変換されます。As the following examples show, the grouped clauses are translated to the corresponding logical expression.

ヒント

クエリの WIQL 構文を表示するには、wiql クエリエディター拡張機能 をインストールします。これにより、任意のクエリ UI エントリの wiql バージョンを確認できます。To view the WIQL syntax for a query, install the WIQL query editor extension which will allow you to see the WIQL version of any Query UI entry. この拡張機能を使用すると、および/またはグループ化された句がどのように扱われるかを確認できます。This extension allows you to see just how AND/OR grouped clauses are treated.

クエリQuery グループ化された句Grouped clauses 論理式Logical expression
11 Group 句のクエリを示すスクリーンショット。 論理式のスクリーンショット。
22 [作業項目の種類] フィールドと [状態] フィールドまたは [担当者] フィールドのいずれかのフィルターを使用して、group 句クエリを示すスクリーンショット。 論理式のスクリーンショット。
33 Group 句のクエリを示すスクリーンショット。 論理式のスクリーンショット。

これらのクエリは、種類がバグで、次の論理式を満たす作業項目を返します。These queries return work items that are type Bug and meet the following logical expressions:

  • クエリ 1: および状態 = アクティブまたは割り当て先 @MeQuery 1: AND State=Active OR Assigned to @Me
  • クエリ 2: および (状態 = アクティブまたは割り当て済み @Me )Query 2: AND (State=Active OR Assigned to @Me)
  • クエリ 3: または (状態 = アクティブおよび割り当て済み @Me )Query 3: OR (State=Active AND Assigned to @Me)

1つ以上の句をグループ化するには、句を選択し、[ 句のグループ化] アイコンをクリックします。

Web ポータル、選択したクエリ句のグループ化Web portal, Group Selected Query Clauses

また、複数のグループ化された句をグループ化することもできます。そのためには、既にグループ化されている各句のボックスをオンにし、[ グループ句] アイコンをクリックします。

複数のクエリ句をグループ化するGroup multiple query clauses

クエリ結果が期待どおりの結果を返さない場合は、次の手順を実行します。If your query results don't return expected results, follow these steps:

  • それぞれの句が意図したとおりに定義されていることを確認します。Make sure that each clause is defined as you intended.
  • 各句の AND/OR の割り当てを確認します。Verify And/Or assignments to each clause. 予期していた数よりも多くの作業項目が結果に含まれる場合は、AND 句ではなく OR 句が使用されています。If your results contain more work items than expected, often an Or clause is present instead of an And clause.
  • クエリ句をグループ化するかどうか、またはクエリ句のグループとグループ化されたそれぞれの句の AND/OR の割り当てを変更する必要があるかどうかを判断します。Determine if you need to group or change the grouping of the query clauses and the And/Or assignments of each grouped clause.
  • クエリ句をさらに追加し、クエリのフィルター条件を絞り込みます。Add more query clauses to refine your query filter criteria.
  • フィールド、演算子、および値を指定するために使用できるオプションを確認します。Review the options available to specify fields, operators, and values.

句のグループ解除Ungroup a clause

句のグループ化を解除するには、グループ化された 句の [句のグループ解除] アイコンをクリックします。

これは、クエリの定義に関する基本です。That's the basics about defining queries. クエリ例のインデックスについては、「 クエリクイックリファレンス」を参照してください。For an index of query examples, see Query quick reference.