9月16日にオンラインで開催されたAtlassian Community Event（通称「ACE」、アトラシアンのユーザー会）で、リーダーである高橋さんが、アトラシアンのYouTube動画「便利なJQL」を元に、Tipsなどを交えながらJQLを解説してくださいました。
この時の盛り上がりから、日本語でのJQLについての解説が少ないことがよくわかったので、ブログで複数回に分けてご案内することにしました。
そもそも「JQL」とは
「Jira Query Language」の略で、Jiraで特定の課題を検索するための、強力で柔軟な方法です。ACEリーダーの高橋さんによると「JQLを制するものがJiraを制す」と言われるほど、使いこなせると非常に便利な機能です。
技術者だけでなく非エンジニアでも使えるよう設計されてはいるものの、「クエリ」に触れたことのない人が見ると、とっつきにくい印象を受けると思います（現に私もそうでした）。そこで、今回はまず、Jiraでの検索の概要とJQLの基礎をカバーします。
Jiraで利用できる検索方法
JQLを使わなくてもJiraで課題を検索することはできます。Jiraの検索には大きく「クイック検索」と「高度な検索」があり、高度な検索の中に「基本検索」と「詳細検索」があります。クイック検索と基本検索ではJQLを使用しません。以下に、それぞれの検索方法についてご紹介します。
クイック検索
最も手軽な検索方法で、製品画面で右上に設置されている検索ボックスに任意の文字列を入力します。具体的には下記の検索を行えます。
- プロジェクト キーを入力して課題を検索（例：JiraKEY-15）
- 課題の要約・説明・コメントに含まれる単語をフリーテキストで検索（例：アトラシアン）
- スマート クエリを使った検索（例：my open bugs – この場合、自分に割り当てられた課題で、ステータスがオープンなもののリストが表示されます）
基本検索
画面上部の「フィルター」メニューから「高度な課題検索」を選択するか、ショートカット 「g」「i」で検索画面に移動します。ここでは、特定のフィールドの値を元に課題をフィルターし、検索できます。
フィルターに使用できるフィールドの種類はプロジェクトによって異なりますが、プロジェクト名や課題タイプ、ステータス、担当者といったJiraで利用されているフィールドでフィルターすることができます。
詳細検索
いよいよJQLの出番です。JQLを使用してクエリ（データベース管理システムを操作するのに使用する文字列）を作成し、より複雑な検索を行えます。フィールド、演算子、そして値という3つの基本パーツがあり、これとキーワードを組み合わせてクエリを作成します。
- フィールド：異なる種類の情報が入力される場所で、「担当者」や「報告者」、「ステータス」といったものがあります。フィールドは英語名で指定する必要がありますが、日本語で追加されたカスタムフィールドについては、日本語で参照することができます。
- 演算子：クエリの核となるもので、フィールドと値の関係を表現します。よく使われる演算子には、「=（等しい）」や「!=（等しくない）」、「<（より少ない・小さい）」などがあります。
- 値：実際のデータで、例えば「担当者」フィールドであれば、そこに入力されている担当者名が値にあたります。
- キーワード：2つ以上のJQLの句をつなげたり、句のロジックを変更する単語または語句で、この記事では「AND」と「OR」について解説します。
JQLで使用する主な演算子とキーワード
アトラシアンでは、JQLで使用できる演算子やキーワードを網羅したリファレンスを用意していますが、非常に数が多いので、ここではよく使われるものをピックアップしてご紹介します。
| 演算子 | 説明と例 |
| != | 指定したフィールドの値が合致しないものを検索するのに使用します。下の例は、ステータスが「To Do」ではない課題を検索します。 例：status != “To Do” |
| >= | 指定したフィールドの値が、この演算子に続く値と同じかそれ以上のものを検索するのに使用します。下の例は、ストーリーポイントが「5」以上の課題を検索します。 例：”Story Points” >= 5 似た比較演算子に「>（〜より大きい）」や「<（〜より小さい）」、「<=（〜以下の）」があります。 |
| IN | 指定したフィールドの値が、後に続く括弧で囲まれた複数の値のいずれかである課題を検索する場合に使用します。下の例は、ステータスが「To Do」、「In Progress」または「Closed」の課題を検索します。 例：status IN (“To Do”, “In Progress”, “Closed”) 反対の演算子は「NOT IN」です。 |
| IS | 必ず「EMPTY」または「NULL」と一緒に使います。「EMPTY」および「NULL」は指定したフィールドに値がない（空である）ことを指し、下の例は「description」フィールドが空の課題を検索します。 例：description IS EMPTY |
| キーワード | 説明と例 |
| AND | 複数の条件をすべて満たす課題を検索する場合に使用します。下の例は、「Collaboration」プロジェクト内の課題で、ステータスが「In Progress」のものを検索します。 例： project = Collaboration AND status = “In Progress” |
| OR | 複数の条件の内、いずれかを満たす課題を検索する場合に使用します。下の例は、「Collaboration」プロジェクトに含まれる課題、あるいはステータスが「In Progress」のものを検索します。 例：project = Collaboration OR status = “In Progress” |
実際にJQLを使ってみましょう！
ここまでカバーした内容を元に、検索クエリを組み立ててみます。
例えば、特定のプロジェクト「Pipeline」でチームメイト（ユーザー名: nkameyama）が起票したバグチケットを検索する場合、ANDを使用して、下記のようになります：
Reporter = nkameyama AND project = Pipelineまた、複数プロジェクト（ProjA、ProjB、ProjC）の中でブロッカー（Blocker）となっている、あるいは重要（Critical）である課題を探す場合は、次のようになります：
priority in (Blocker, Critical) AND project in (ProjA, ProjB, ProjC)別の使用例として、顧客とのSLA（サービスレベルアグリーメント）がある組織において便利なクエリをご紹介します。例えば、過去1日以内に担当者が割り振られていない、あるいは更新されていない課題を探す場合、「is EMPTY」を使用して、下記のようになります：
assignee is EMPTY and created < -1d
こんなJQLの始め方もあります
「一からクエリを組み立てるのはハードルが高い」という場合は、高橋さんも紹介されていた、クイック検索や基本検索で出た結果を元に「JQLに切り替え」て詳細検索を行う方法もあります。
なお、クエリ入力欄の左端にあるアイコンで、入力されたクエリが構文的に正しいときは緑のチェックマーク、間違っているときは赤いバツマークが付くので、こちらも参考にしてみてください。
いかがでしょうか？はじめは小難しそうに感じましたが、一つ一つ紐解くと、便利に使いこなせそうではないでしょうか。
以上、今回はJQLの基礎をご紹介しました。引き続き、数回に分けて関数やフィルターなどを解説してまいります。
- 第2回: 関数、変更履歴、並び替えを活用
- 第3回: フィルターとサブスクリプションの活用
なお、新しいブログ記事が公開され次第、アトラシアン株式会社の公式SNSでご案内しますので、こちらもフォローいただけると嬉しいです。