はじめてのJQL 第2回: 関数、変更履歴、並び替えを活用

Atlassian Community Eventでの盛り上がりをきっかけに、日本語でのJQLについての解説を増やすべく始まったブログ連載ですが、第1回ではJQLに必要なパーツの紹介とシンプルなJQLクエリを解説しました。第2回となるこの記事では、よりダイナミックな検索のための関数や、変更履歴を元に検索する方法、並び替えの方法など、JQLがさらに便利になるポイントをご紹介します。

関数

JQLでの関数は、「approved()」や「endOfDay()」のように決められた単語の後に丸括弧が続く形をとり、フィールドおよび演算子と組み合わせてJQLクエリを構成します。

関数がある時のJQLクエリの構造

まずは、チームで役立ちそうな関数「membersOf()」をご紹介します。この関数を使うとグループのメンバーにアサインされている課題を、すべて一度に確認できます。ちなみにここでの「グループ」は、Jira内で定義します。この関数を使った具体例を見てみましょう:

project = Pipeline AND assignee in membersof('test-engineering')

このクエリは、プロジェクト「Pipeline」で「test-entineering(テストエンジニア)」グループのメンバーが担当者となる、すべての課題を検索して表示します。関数を使用すると変更を動的に取り込めるので、グループのメンバーが追加されると、自動的に検索結果にその追加が反映されます。

次に、前回のリリースで解決された課題を検索する方法を考えてみます。シンプルに考えるために、「前回」ではなく、仮に「スプリントA」としてみましょう:

project = Pipeline AND status in (resolved, closed) and fixversion = "スプリントA"

これでプロジェクト「Pipeline」の「スプリントA」でリリースされた、すべての課題を確認できます。このクエリをベースに、常に「前回」のリリースで解決された課題を見られるようにするには、「latestReleasedVersion()」関数を使い、次のようになります:

status in (resolved, closed) and fixVersion = latestReleasedVersion(Pipeline)

ゆくゆくチームはスプリントBやC、そしてDをリリースします。先のクエリでは「スプリントA」で解決された課題しか確認できませんが、上のクエリではプロジェクト「Pipeline」プロジェクトで、常に直近にリリースされたバージョンで解決された課題がリストできます。

変更の履歴を活用した検索

JQLで演算子「CHANGED」使うと、変更履歴を元にした検索を行うことができます。例えば、プロジェクト「Pipeline」で担当者が変更された課題を検索するには、次のようになります:

project = Pipeline AND assignee CHANGED

次に、プロジェクト「Pipeline」で解決(ステータスが「In Progress」から「Resolved」に変更)された課題を検索する場合は、次のようになります:

project = Pipeline AND status CHANGED FROM "In Progress" TO "Resolved"

これにさらに、特定のチームメイト(ユーザー名: nkameyama)によって解決した課題で絞り込んでみましょう:

project = Pipeline AND status CHANGED FROM "In Progress" TO "Resolved" BY nkameyama

また、演算子「WAS」と、関数「startOfWeek()」そして「endOfWeek()」を組み合わせると、今週対応した・している課題を検索できます:

status WAS ("In Progress") DURING (startofweek(), endofweek());

さらに担当者を加え、例えば一年の終わりに、その年に自分が解決した課題の数を確認するなら:

resolution CHANGED TO "Fixed" BY currentUser() DURING (startOfYear(), endOfYear())

となります。関数「currentUser()」はログインユーザー情報、そして関数「startOfYear()」と「endOfYear()」はそれぞれ年初と年末に基づいた検索を行います。

このように演算子と関数を組み合わせることで、検索の幅が大幅に広がりますね。

絞り込みと並び替え

Jiraで課題を検索する際、想定以上に沢山の結果が表示されることがよくあります。そこで、クエリで結果を絞り込んだり、並び替えをすると、必要な情報をより簡単に見つけられるようになります。

  • 絞り込み – クエリで結果を絞ることで、ちょうど良い量の情報を引き出し、関連のある情報だけ手元に表示させます
  • 並び替え – 重要なデータが先に表示されるようデータを並び替えます

以下、例と併せてそれぞれの内容を見ていきましょう。

絞り込み

まず、プロジェクト「Pipeline」でステータスが「Open」な課題を検索してみます:

project = Pipeline AND status = open

バックログや対応中の課題も含まれるため、大抵の場合、表示される結果の件数は非常に多くなります。それでは次に、バックログになっている課題は除き、結果を絞り込みましょう:

project = Pipeline AND status = open AND fixVersion = "Current Sprint"

少し良くなりましたが、もう少し絞れそうです。例えば、一つ前のスプリントに入れることができずに現在のスプリントに移動されたものを探してみることにします:

project = Pipeline AND status = open AND fixVersion = "Current Sprint" AND fixVersion WAS "Last Sprint"

だいぶ絞り込めたのではないでしょうか。このようにフォーカスを絞ることで、各課題をより細かく確認し、この例では、一つ前のスプリントから漏れた理由を確認しやすくなります。一番始めのクエリでも、これらの課題は検索結果に表示されていましたが、一つ一つ確認し選別するのは手間がかかります。

良いクエリにするには、繰り返しのプロセスが必要です。クエリを作り、レビューし、結果が十分に絞られているか確認します。最初は難しいかもしれませんが、回を重ねるにつれ簡単な作業になるはずです。

並び替え

ここに例として、プロジェクト「Pipeline」の現在のスプリント(Current Sprint)で、ステータスがオープン(Open)になっている課題を検索するクエリがあります:

project = Pipeline AND fixVersion = "Current Sprint" AND status = open

この結果を並び替えることで、さまざまな情報を確認できます。例えば、スプリントのリスクを把握したい場合、優先度で並び替え、エンジニアごとにまとめると、優先度の高いバグを多く抱えているエンジニアを簡単に確認でき、対策を講じることができます。

JQLには、結果の並び替えに使える「ORDER BY」というキーワードがあります。これを使って上のクエリを先に挙げた例のように並び替えるには、次のようになります:

project = Pipeline AND fixVersion = "Current Sprint" AND status = open ORDER BY priority, assignee

これでJiraは結果のリストを優先度順に並べた後、同じ優先度の課題を持つ担当者ごとにまとめます。

別の例として、プロジェクト「Pipeline」に最近加わったバグを確認しましょう。2週間内に新規で問題となるバグ、あるいはブロッカーとなる課題が追加されていないかを確認し、最近のチェックインによってサービスの安定性が損なわれていないか見ることができます。

project = Pipeline AND priority in (blocker, critical) AND created > -2w ORDER BY created DESC

このクエリは優先度がブロッカー(Blocker)あるいは重要(Critical)になっている課題を探し、その作成時期を2週間内に絞ります。そして並び替えのキーワード「ORDER BY」と併せて「DESC」を使い、新しいものから古いものへ順番になるよう並べます。こうすることで、問題が起きていないかを確認しやすくなります。

クエリを並び替えて、重要なものが最初に見えるよう工夫すると、確認作業がグッと楽になります。

最後に

この第2回を終わろうとしている今、JQLを使ったクエリへの苦手意識が下がっているのではないでしょうか。今回は関数の基礎、結果の絞り込みと並び替えを取り上げました。ここで取り上げたもの以外にも、数多くの関数や演算子、キーワードが用意されており、下記リファレンスで紹介されていますので、色々お試しください。

次回は最終回。検索の保存、フィルターなどを解説します。

なお、新しいブログ記事が公開され次第、アトラシアン株式会社の公式SNSでご案内しますので、こちらもフォローいただけると嬉しいです。