Jira 中的三種搜尋方式分別為快速、基本及高級，在前面章節介紹了快速、基本搜尋，包括新增、編輯、訂閱篩選器以及如何對issue、board做篩選。今天要來介紹JQL語法的進階搜尋的撰寫。
這章節你將學會

• 什麼是JQL
• 搜尋介面介紹
• 語法介紹
• 常用的JQL搜尋語句

什麼是JQL

Jira Query Language簡稱JQL，是 Jira 中最強大的工具之一與SQL很類似，會使用JQL原因是有些無法在快速或基本搜尋中定義的條件，透過自訂義條件縮小搜尋範圍，可以幫助團隊提高工作效率，讓他們不需要花費大量的時間去找尋相關訊息。

介面

圖片來源

1. 基本或JQL切換
2. JQL 編輯器
3. 展開/折疊編輯器
4. 語法幫助
5. 搜尋按鈕
6. 當JQL查詢語法超過一行時的行號
7. 根據上下文自動完成建議

語法顯示

搜尋由字段、運算符、值、關鍵字及Functions組成，運算符是搜尋的核心，當你在輸入框搜尋文字時，會給予提示，讓搜尋更加方便。

圖片來源
接下來讓我們了解每個名詞的意思

Field (字段)

搜尋包含在Jira系統中Issue 的字段，像是project、Component、Assignee、Reporter、Status等，在一個句子中，一個字段後面有一個運算符，而運算符後面有一個或多個值或方法詳細可參閱。

Value

具體要尋找的實際值

Operator(運算符)

運算符是數學符號，像是等於 (=)、不等於 (!=)、大於 (>)、小於或等於 (<=) 等，用來描述字段與你尋找value值之間的關係。下面來介紹常用的運算符號

• 等於(=)：field值與value值完全符合
  找尋所有sunny wang建立的所有問題
  reporter = "sunny wang"

• 不等於(!=)：field值與value值不符合
  找尋除了sunny wang以外任何人建立的所有問題
  reporter != "sunny wang"

• 大於(>)：field值大於value值，需注意的是僅用於排序的字段
  找尋priority大於normal的問題
  priority > normal

• 大於等於(>=)：field值大於等於value值
  找尋過去三天內建立的所有問題
  created >= "-3d"

• 小於(<)：field值小於value值
  找尋在2022/09/03之前解決的所有問題
  resolved < "2022/09/03"

• 小於等於(<=)：field值小於等於value值
  找尋在2022/09/03或之前解決的所有問題
  resolved <= "2022/09/03"

• 包含(~)：field值與value值1匹配的問題
  text字段中包含test單字的問題
  text ~ "test"

  text字段中包含單字test文字的問題
  text ~ "test*"

• 不包含(!~)：field值與value值不匹配的問題
  text字段中不包含test單字的問題
  text !~ "test"

  text字段中不包含單字test文字的問題
  text !~ "test*"

• IN：field值為多個value值的問題

  找尋所有sunny、winne建立的所有問題
  reporter in (sunny,winne)

• NOT IN：field值不是多個value值的問題

  找尋除了sunny、winne以外任何人建立的所有問題
  reporter not in (sunny,winne)

• IS：field值有value值的問題，只能與「EMPTY」或「NULL」一起使用

  搜索沒有附件的問題
  attachments IS EMPTY

• IS NOT：field值沒有value值的問題，只能與「EMPTY」或「NULL」一起使用

  搜索有附件的問題
  attachments IS NOT EMPTY

Keyword(關鍵字)

是將不同的運算符連接在一起，可以進一步縮小搜索範圍，它包含三種類型的關鍵字，分別為

• 連接兩個表達式：AND、OR、NOT
• 表示空值的關鍵字：EMPTY、NULL
• 排序：ORDER BY

讓我們來看以下幾的範例

尋找2022/9月所建立的問題

created > "2022/09/01" and created < "2022/10/01"
這是針對在這個站的Project問題，只要符合條件的都會被搜尋出來

尋找分配給sunny Wang或winnie的問題

assignee = "sunny Wang" or assignee = "winnie"

如果想針對某專案，就加入字段Project，值為project key
project = "PRKB" AND assignee = "sunny Wang"

project等於有「TES」文字按照建立日期由大到小排序

project = "TES" ORDER BY created DESC

Function(方法)

Jira提供一些方法，讓查詢的人可以直接套入使用，找尋需要的問題，以下列出幾個比較常會用到的Function，更多詳細可參閱此網站

• 時間相關
  • startOfDay/startOfWeek/startOfMonth/startOfYear
    尋找今天所建立的新問題
    created > startOfDay()
  • endOfDay/endOfWeek/endOfMonth/endOfYear
    尋找到今天結束的問題
    due < endOfDay()
  • now()
• Issue相關
  • issueHistory()：搜尋你最近查看的問題
    尋找我最近查看分配給我的問題
    issue in issueHistory() AND assignee = currentUser()
  • myApproval()：搜尋需要批准或需要當前用戶批准的請求
    搜尋所有需要我批准的請求
    approval = myApproval()
  • myPending()：搜尋當前或以前需要當前用戶批准的請求
  • subtaskIssueTypes()：根據屬於子任務的問題執行搜尋
    查找屬於子任務的問題
    issuetype in subtaskIssueTypes()

自動填寫

開始輸入查詢，輸入框左側會告訴你查詢是否有效，綠色Ｖ表示你的搜尋有效；紅色 X則表示你搜尋無效。

Jira中常用的JQL搜尋語句

在網路上也有很多寫JQL的好資源，以下是JQL常用的搜尋語句

• 分配給我的待處理任務
  assignee = currentUser() AND resolution is EMPTY
• 我報告的並且沒處理完成的任務
  reporter = currentUser() AND resolution is EMPTY
• 某項目中已經過期的任務
  project = "XXX" AND due < now()
• 某項目中3天后要過期的任務
  project = "XXX" AND due <= endOfDay(3d)
• 某項目中待辦和處理中狀態上的任務
  project = "XXX" AND status in (待辦, 處理中)
• 某項目中48小時內沒變化過的任務
  project = "XXX" AND updated <= -48h ORDER BY updated DESC
• 某項目中最近30天解決的任務
  project = "XXX" and resolved >= startOfDay(-30d)
• 某項目上即將發布的版本中還沒解決的任務
  project = "XXX" and fixVersion = earliestUnreleasedVersion() and resolution is EMPTY
• 某項目上當前進行的Sprint中被標記的任務
  jsx project = "XXX" and Sprint in openSprints() and Flagged = Impediment
• 上週發生狀態變化的Issue
  status changed DURING (startOfWeek(-1), endOfWeek(-1))
• 3天以來關閉的Issue
  status = Closed and status was not Closed ON startOfDay(-3)

總結

這章節你學習如何使用JQL撰寫簡單的查詢、如何導出查詢結果及儲存篩選器的結果，可以幫助團隊提高工作效率，讓他們不需要花費大量的時間去找尋相關訊息。明天將會來討論Dashboard。

參考資料：
https://support.atlassian.com/jira-software-cloud/docs/advanced-search-reference-jql-operators/
https://blog.csdn.net/zhangguanglin_csdn/article/details/105202265
https://www.idalko.com/jira-jql/
https://doc.devpod.cn/jira/jql-3244098.html