tweeeetyのぶろぐ的めも

アウトプットが少なかったダメな自分をアウトプット<br>\(^o^)/

【JIRA】jql(JIRA Query Language)の使い方 - 検索やfilterの基本

はじめに

普段jiraを使っていますが、何かとfilterでのjqlはよく使います。
ただ、そのたびにこんな検索がしたいんだけどどうやるんだろう...と小一時間悩むことがあるので、そんな時のjqlメモです。  

補足

基本編とあんちょこ編に分けて書いてみました

あんちょこ編はtopicがあれば随時更新します(たぶん...

アジェンダ

  1. jiraの検索
  2. jql(JIRA Query Language)とは
  3. jqlとfilter
  4. jqlの基本

1. jiraの検索

jqlを使う前に、jiraの検索について軽く触れておきます。
jiraの検索は大きくわけて3つあります。

検索方法 説明
Quick search
(クイック検索)
ヘッダーにある検索ボックスに検索条件を入力して素早く検索する方法です。しかし複雑な検索はできません
Basic search
(簡易検索)
ヘッダーで、課題 > 課題を検索に移動して、検索条件を入力します。クイック検索よりも詳細な検索ができますが、高度な検索よりは柔軟に検索はできません
Advanced search
(高度な検索)
ヘッダーで、課題 > 課題を検索に移動して、検索条件を入力します。jqlというクエリで検索する事でより柔軟な検索が可能です

詳細は公式を見てみると良いです。
* [公式英語] Searching for issues * [公式日本語] 課題を検索する

公式からの引用ですが、
以下にそれぞれの簡単なイメージと説明とリンクを載せておきます。

Quick search(クイック検索)

時には、関心がある特定の課題だけ取得できればと考える場合があります。また、どの課題か覚えていないけれども、自分に割り当てられていた未処理の課題だったことだけ記憶している場合があります。このような場合はクイック検索が便利です。

f:id:tweeeety:20171110222019p:plain

Basic search(簡易検索)

ベーシック検索は、使いやすいインターフェイスを使用して、JQL の使用方法を知らなくても複雑なクエリを定義できます。

f:id:tweeeety:20171110222029p:plain

Advanced search(高度な検索)

高度な検索では JIRA クエリ言語 (JQL: JIRA Query Language) という構造的なクエリによって課題を検索することが出来ます。クイック検索やベーシック検索では定義できない検索条件を指定することができます。(例えば ORDER BY 節など) 。

f:id:tweeeety:20171110222038p:plain

2. jql(JIRA Query Language)とは

前述の通り、jqlはAdvanced search(高度な検索)を選んだ時に使えるqueryです。

特徴としては、sqlのようにselect句から書くというよりは
where句のみを書いて行くイメージです。

たとえば、jira projectが"Hoge"でチケットのstatusがopenなものは以下のように書きます

project = Hoge AND Status = Open

sqlに慣れた人であればすぐに意味がわかると思います。

3. jqlとfilter

jqlは、いろいろな検索ができますが調べたくなったら都度書いて...
なんてやりたくないですよね。

そんな時にfilterを使います。
簡単に言ってしまえば、filterはjqlに名前をつけて保存しておく機能です。

試しにfilterを作ってみるとこんな感じです。

  • jqlで検索して結果が確認できたらSave asを押します
    f:id:tweeeety:20171110222059p:plain

  • モーダルが開くのでFilter名を入れてSubmitするだけです。 f:id:tweeeety:20171110222110p:plain

これでfilterを選択すればいつでもjqlとその結果を呼び出せます。

4. jqlの基本

jqlの基本構文は以下のようになっています。

フィールド名 演算子

また、フィールド名 演算子 値 のセットを複数繋ぎたい場合はANDORを使います

フィールド名 演算子 値 AND フィールド名 演算子

以降で、フィールド名演算子キーワードについて説明します。
公式だとこのあたりです。
* 高度な検索

フィールド

jiraのフィールド名はものすっごく多いので割愛しますが、
以下のようなものがあります。

フィールド 説明
Affected version 対象バージョン affectedVersion = "3.14"
Assignee 担当者 assignee = "John Smith"
Comment コメント comment ~ "My PC is quite old"
Component コンポーネント component in (Comp1, Comp2)
Created 作成日 Created < "2010/12/12"
Created > "-1d"
Creator 作成者 Creator = "jjones"
Description 説明 description ~ "Please see screenshot"
Due 期日 due >= "2011/01/01" and due <= "2011/01/31"
Epic link エピックリンク "epic link" = Jupiter
Filter フィルター filter = 12000 and assignee = jsmith
Issue key 課題キー issueKey = ABC-123
Labels ラベル labels not in ("x") or labels is EMPTY
Parent parent = TEST-1234
Project プロジェクト project = ABC
Status ステータス status = Open
Type 課題タイプ type = Bug
issueType in (Bug,Improvement)
Updated 更新日 2週間より前
updated < "-2w"

公式にも詳しくのっています
* 高度な検索 - フィールドのリファレンス

演算子

jqlの演算子は、だいたいがsqlと同じです。
以下のようなものがあります。

演算子 説明
= 完全一致 reporter = jsmith
!= 一致しない assignee != jsmith
> 指定したフィールドの値が指定した値より大きい duedate > now()
>= 指定したフィールドの値が指定した値以上 duedate >= "2008/12/31"
< 指定したフィールドの値が指定した値より小さい votes < 4
<= 指定したフィールドの値が指定した値以下 updated <= "-4w 2d"
IN 指定したフィールドの値が指定した複数の値のいずれか reporter in (jsmith,jbrown,jjones)
NOT IN 指定したフィールドの値が指定した複数の値以外 assignee not in (Jack,Jill,John)
~ 指定したフィールドの値が、指定した値と一致する(あいまい検索) summary ~ win
!~ 指定したフィールドの値が指定した値のあいまい一致でない課題 summary !~ run
IS EMPTY または NULL とのみ一緒に使用できる fixVersion is empty
IS NOT EMPTY または NULL とのみ一緒に使用できる votes is not empty
WAS 指定したフィールドの指定した値が現在存在するか、過去に存在した課題 status WAS "In Progress"
WAS IN 指定したフィールドの指定した複数の値のいずれかが現在存在するか、過去に存在した課題 status WAS IN ("Resolved","In Progress")
WAS NOT IN 指定したフィールドの値が指定した複数の値のいずれにもなったことがない課題 status WAS NOT IN ("Resolved","In Progress")
WAS NOT 指定したフィールドが指定した値になったことがない課題 status WAS NOT "In Progress"
CHANGED 指定したフィールドの値が変更された課題 assignee CHANGED

公式にも詳しくのっています
* 高度な検索 - 演算子について

キーワード

jqlのキーワードはsqlにかなり似てるのでわかりやすいです。

キーワード 説明
AND 複数の条件の組み合わせて、検索を絞り込めます project = "New office" and status = "open"
OR 複数の条件を組み合わせて、検索範囲を広げることができます reporter = jsmith or reporter = jbrown
NOT 条件に対しての否定です not assignee = jsmith
EMPTY 指定されたフィールドに値が入力されていない課題を検索します duedate = empty
NULL 指定されたフィールドに値が入力されていない課題を検索します duedate = null
ORDER BY 検索結果の値を並べ替えるフィールドを指定します duedate = empty order by created

おわり

jiraのjqlとfilter便利ですね \(^o^)/