JQL（Jira Query Language）実務ガイド：課題検索・フィルタ・ダッシュボード集計を高速化するクエリ設計

ボードの奥で動いている検索エンジンを、自分で操作する

「Jiraのボード運用実務ガイド」では、バックログに表示される作業項目の条件を「ボードのフィルターに合致していること」と説明した。この「フィルター」の実体はJQL（Jira Query Language）で書かれた検索式であり、ボード・保存済みフィルタ・ダッシュボードのガジェットは、すべて同じ検索エンジンの上に成り立っている。また「Jiraのワークフロー・課題タイプ設計」で整理したステータスと課題タイプは、JQLで課題を絞り込むときの主要な検索対象そのものになる。

基本検索の虫眼鏡アイコンやフィルターパネルだけでは、複数条件の組み合わせや、担当者・期間をまたいだ集計はすぐに限界に来る。この記事は、Atlassian公式ドキュメントの仕様から、JQLの句の構造・演算子・キーワード・関数と、検索結果をフィルタとして保存し、ボードのフィルターやダッシュボードの集計に載せるまでの手順を整理する。ツールそのものの選定は「プロジェクト管理ツール比較」を参照してほしい。

この記事の編集基準

本記事にアフィリエイトリンク・紹介料・掲載料は一切ない。仕様はAtlassian公式サポートドキュメントを出典としている。

JQLとは何か：句の構造

Atlassian公式ドキュメント「What is advanced search in Jira Cloud?」は、高度な検索についてJQLを使って構造化クエリを組み立て、作業アイテムを検索できる機能だと説明している。複雑な検索条件がなければ基本検索（quick search）で足りるが、ORDER BYを使った並び替えなど、基本検索では定義できない条件を指定したい場面でJQLが必要になる。

JQLの基本的な句は、フィールド・演算子・1つ以上の値または関数という3つの要素で構成される。最も単純な例は「project = "TEST"」で、projectフィールドをEQUALS演算子（=）で値"TEST"と比較している。複数の条件を組み合わせるとキーワード（AND）や関数（currentuser()）が加わり、「project = "TEST" AND assignee = currentuser()」のような句になる。

基本検索で作った条件はJQLに変換できることが多いが、OR演算子やNOT演算子を含む複雑なクエリは、逆に基本検索へ戻せない場合がある。複数条件を組み合わせ始めた時点で、片道切符のつもりでJQLに乗ると考えておくとよい。

演算子（比較の記号）を覚える

JQLの句を作る演算子は、フィールドの型によって使えるものが異なる。まず比較の基本形を押さえる。

キーワードで条件をつなぐ・並べる

演算子が個々の条件を作るのに対し、キーワードは条件同士のつなぎ方と並び順を決める。Atlassian公式ドキュメント「JQL keywords」は、ANDを複数の句を組み合わせて検索を絞り込むためのもの、ORを複数の句を組み合わせて検索を広げるためのものと説明している。NOTは個々の句、または括弧でまとめた複雑なクエリ全体を否定するために使う。

EMPTY（同義語としてNULLも使える）は、指定したフィールドが値を持たない課題を検索するためのキーワードで、「fixVersion is empty」のようにIS／IS NOT演算子と組み合わせて使う。ORDER BYは検索結果の並び替えに使うフィールドを指定するキーワードで、「ORDER BY Rank ASC」のように昇順（ASC）・降順（DESC）を続けて書く。ORDER BYはクエリの末尾に置く決まりになっている。

関数で「今」と「未リリース」を動的に指定する

JQLの関数は、括弧の中に値やフィールドを取り、計算結果を検索条件として返す。Atlassian公式「Example JQL queries for board filters」が示す実例から、実務で使う頻度の高い関数を見る。

currentUser()は、検索を実行している本人を指す関数である。公式の実例では「(assignee = currentUser() or reporter = currentUser())」という形で、自分が担当者または報告者になっている課題をまとめて拾うために使われている。

unreleasedVersions()は、まだリリースされていないバージョンをすべて返す関数で、「fixVersion in unreleasedVersions() OR fixVersion is empty」という形で、修正バージョンが未設定か未リリースの課題を検索するために使われている。

earliestUnreleasedVersion(プロジェクトキー)は、指定したプロジェクトの中で最も早くリリース予定の未リリースバージョンを返す関数で、「fixVersion = earliestUnreleasedVersion(プロジェクトキー)」という形で、次のリリースに紐づく課題だけを絞り込むために使われている。

実務クエリ集：公式サンプルをそのまま使う

公式ドキュメントが示す実例は、ボードのフィルターとして使う想定のクエリだが、保存済みフィルタやダッシュボードのガジェットにもそのまま流用できる。

ボードのフィルターも、JQLとして編集できる

「Jiraのボード運用実務ガイド」で扱ったボードの表示条件は、実体としてJQLクエリで書かれた1本のフィルターである。Atlassian公式ドキュメント「What are board filters?」は、表示したい作業項目だけに絞ったボードを作りたい場合、JQLクエリに基づいたフィルターを使ってボードを作成できると説明している。複数プロジェクトの作業項目、単一プロジェクトの作業項目、プロジェクトの特定コンポーネントの作業項目のいずれでも、ボードに含める範囲をこのフィルターで決められる。ボードのフィルター設定には、プロジェクト管理者またはボード管理者の権限が要る。

会社管理ボードでこのフィルターを編集する経路は2つある。1つはボード名横の「その他の操作」（•••）から「ボード設定」を開き、「General」ページの「Board filter」セクションで「フィルタークエリを編集」を選ぶ経路。もう1つはスクラムボードのバックログ画面右上の「その他の操作」から「ボードを構成」を選び、同じく「Board filter」セクションから編集する経路である。どちらも、開いた画面でJQLクエリを直接書き換えるか、「基本に切り替え」で条件作成ツールに戻すかを選べる。編集後は保存の選択肢が表示され、自分がフィルターの作成者でない場合は上書きができず、「名前を付けて保存」で新しいフィルターとして残すことになる。

ここまでの演算子・キーワード・関数は、検索窓に打ち込むときだけでなく、このボードフィルターの編集画面でもそのまま使える。ボードの列設計をやり直す前に、まずフィルタークエリ側で対象範囲がずれていないかを確認する価値がある。

検索結果をフィルタとして保存し、共有・管理する

JQLで組み立てた検索は、実行するたびに書き直すのではなく、フィルタとして保存して繰り返し使う。Atlassian公式ドキュメント「Save your search as a filter」は、フィルタの用途として、社内外の関係者と検索結果を共有・メールで送る、よく使うフィルタをお気に入りに登録する、あらかじめ決めたスケジュールで結果をメール配信する、RSSやExcelなど各種形式でエクスポートする、という機能を挙げている。

保存したフィルタの管理は「Filters」（フィルター）画面から行う。Atlassian公式ドキュメント「Manage filters」によると、この画面では名前・所有者・スペース・グループでフィルタを検索でき、フィルタの名前や説明の変更、検索条件そのものの更新（変更後は「名前を付けて保存」で別フィルタとしても残せる）ができる。共有設定はユーザーグループ・スペース・スペースロール単位で「ビューワー」「エディター」の権限を指定でき、組織内の全ユーザーに公開する設定も選べる。購読機能では配信頻度やcron式での詳細スケジュールを指定したメール配信、RSS購読を設定できる。削除はフィルタの所有者のみが行え、複製は任意のフィルタから新規フィルタを作成でき、星アイコンでナビゲーションメニューにお気に入り登録できる。所有権の移管はJira管理者の権限で行う。

検索結果をダッシュボードのガジェットにする

保存したフィルタの結果は、検索結果一覧を毎回開かなくても、ダッシュボード上のガジェットとして常時表示できる。Atlassian公式ドキュメント「Manage search results」は、その手順を、検索結果画面右上の「Export」を選ぶ、「Create dashboard gadget」を選ぶ、表示させたいガジェットの種類を選ぶ、「Save to Dashboard」を選ぶという4段階で示している。

ガジェットの種類はAtlassian公式ドキュメント「Dashboard gadgets」で定義されている。Filter Resultsガジェットは、フィルタリングした作業項目の結果一覧をそのまま表示するガジェットである。Two Dimensional Filter Statisticsガジェットは、フィルタの結果を表形式の集計データとして表示するガジェットである。Work item Statisticsガジェットは、フィルタから返された作業項目の集合を、指定したフィールド単位で分類して表示するガジェットである。一覧をそのまま置きたいのか、件数の集計を置きたいのかで、選ぶガジェットが変わる。

まとめ：ボード・フィルタ・ダッシュボードは同じ検索エンジンの上にある

JQLは検索窓だけの機能ではなく、「Jiraのボード運用実務ガイド」で扱ったボードの表示条件、保存済みフィルタ、ダッシュボードのガジェット集計まで、すべてを支える検索エンジンの共通言語である。ボードの見え方がずれていると感じたときは、列設計をやり直す前に、まずボードフィルターのJQLを開いて対象範囲を確認するとよい。

検索対象となる課題タイプ・ステータスの設計は「Jiraのワークフロー・課題タイプ設計」で扱っている。演算子・キーワード・関数の組み合わせに慣れてきたら、日々の検索を保存フィルタに変え、ダッシュボードのガジェットとして定点観測する運用に移していく段階になる。