はじめに
普段jiraを使っていますが、何かとfilterでのjqlはよく使います。
ただ、そのたびにこんな検索がしたいんだけどどうやるんだろう...と小一時間悩むことがあるので、そんな時のjqlメモです。
補足
基本編とあんちょこ編に分けて書いてみました
あんちょこ編はtopicがあれば随時更新します（たぶん...
アジェンダ
- jiraの検索
- jql(JIRA Query Language)とは
- jqlとfilter
- jqlの基本
1. jiraの検索
jqlを使う前に、jiraの検索について軽く触れておきます。
jiraの検索は大きくわけて3つあります。
| 検索方法 | 説明 |
|---|---|
| Quick search (クイック検索) |
ヘッダーにある検索ボックスに検索条件を入力して素早く検索する方法です。しかし複雑な検索はできません |
| Basic search (簡易検索) |
ヘッダーで、課題 > 課題を検索に移動して、検索条件を入力します。クイック検索よりも詳細な検索ができますが、高度な検索よりは柔軟に検索はできません |
| Advanced search (高度な検索) |
ヘッダーで、課題 > 課題を検索に移動して、検索条件を入力します。jqlというクエリで検索する事でより柔軟な検索が可能です |
詳細は公式を見てみると良いです。
* [公式英語] Searching for issues
* [公式日本語] 課題を検索する
公式からの引用ですが、
以下にそれぞれの簡単なイメージと説明とリンクを載せておきます。
Quick search(クイック検索)
時には、関心がある特定の課題だけ取得できればと考える場合があります。また、どの課題か覚えていないけれども、自分に割り当てられていた未処理の課題だったことだけ記憶している場合があります。このような場合はクイック検索が便利です。
Basic search(簡易検索)
ベーシック検索は、使いやすいインターフェイスを使用して、JQL の使用方法を知らなくても複雑なクエリを定義できます。
Advanced search(高度な検索)
高度な検索では JIRA クエリ言語 (JQL: JIRA Query Language) という構造的なクエリによって課題を検索することが出来ます。クイック検索やベーシック検索では定義できない検索条件を指定することができます。(例えば ORDER BY 節など) 。
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を押します
モーダルが開くのでFilter名を入れて
Submitするだけです。
これでfilterを選択すればいつでもjqlとその結果を呼び出せます。
4. jqlの基本
jqlの基本構文は以下のようになっています。
フィールド名 演算子 値
また、フィールド名 演算子 値 のセットを複数繋ぎたい場合はANDやORを使います
以降で、フィールド名、演算子、キーワードについて説明します。
公式だとこのあたりです。
* 高度な検索
フィールド
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＾)／
