🔎 #1 JQL(JIRA Query Language) 로 JIRA Issue(지라 이슈) 검색하기 - 기본 연산자

Owned by 정광섭
Last updated: 2021-Dec-08
7 min read

JQL 이란?

JQL 은 Jira Query Language 의 약자로 Jira Issue 를 검색하기 위한 구조적 언어입니다.

SQL과  비슷한 문법을 갖고 있으므로 SQL을 알고 있는 개발자 분들은 쉽게 배워서 사용할 수 있습니다.

JQL 에 익숙하고 JIRA 에 충분한 데이타가 쌓여 있다면 여러 가지 다양한 조건으로 이슈를 검색하고 분석할 수 있으며 결과는 MS Excel 이나 다른 포맷으로 export 하여 실제 데이타 기반의 양질의 보고서를 작성할 수 있습니다. 

기본 검색은 UI 기반이므로 사용이 쉬운 대신 세밀한 검색이 어렵고 UI 로 구현이 어려운 부분이 많습니다. 특히 not 이나 not in 구문은 UI 로 구현이 어렵습니다.

예로 프로젝트가 1,000개 있는데 그 중에 a, b라는 2 개의 프로젝트를 제외하고 검색해야 한다면 기본 검색에서는 998 개의 프로젝트를 클릭해서 선택해야 합니다.

 

 



하지만 JQL 에서는 간단하게 다음과 같은 구문으로 처리 가능합니다.

project not in (a, b)

 

기본 검색이든 고급 검색이든 백엔드에는 JQL 이 동작하며 기본 검색은 JQL 을 사용하기 쉬운 wrapper 에 불과하므로 Jira 파워 유저가 되려면 JQL 은 꼭 익혀야 할 내용입니다.

JQL 을 사용하려면 아래의 절차를 따르면 됩니다.

  1. 이슈→ 이슈검색 클릭

  2. 고급을 클릭해서 JQL 입력 화면으로 전환

     

  3. 상단에서 “JQL로 전환” 클릭

 

JQL 의 2가지 주요 구성 요소

JQL 은 크게 검색 구문과 정렬 구문으로 나뉘어지며 검색 구문만 있거나 정렬 구문만 있을 수도 있습니다.

이 예에서 보이는 JQL 은 검색 구문은 없고 정렬 구문만 있습니다.

검색 구문은 SQL 의 SELECT 와 유사하다고 생각하면 되는데 INSERT나 UPDATE 구문이 없고 SELECT 와 FROM 구문이 생략되어 있고 컬럼대신 필드를 넣어주면 됩니다.

검색 구문

필드이름 연산자 필드값

필드 이름은 Jira 상세 이슈에서 볼 수 있는 바로 그 필드를 적어주면 됩니다. 주의할 점은 field 이름은 번역된 이름이 아니라 영어 필드 이름을 적어줘야 하는 점입니다.

즉 담당자라 적으면 오류가 나고 assignee 라고 적어줘야 제대로 동작합니다. 실제 보는 이슈 화면에서는 번역된 용어가 보이기때문에 JQL 을 처음 배울 때 어려운 부분이 영문 필드명을 모른다는 점입니다.

이것은 Jira 의 자주쓰는 필드의 영문 이름을 외우고 또 아래에서 설명할 자동완성의 도움을 받는 수 밖에 없습니다.

필드값에는 찾을 값을 넣어주며 예로 필드이름 이 project 일 경우 검색 필드값에는 검색 대상 프로젝트 이름을 넣어주면 됩니다.

예로 다음 구문은 프로젝트 필드가 TODO_KB 인 모든 이슈들을 나열합니다.

project = TODO_KB order by created DESC

 

정렬

SQL 처럼 ORDER BY 구문을 사용해서 정렬할 수 있으며 다음 구문은 프로젝트 필드가 TODO_KB 인 모든 이슈를 생성일 기준으로 정렬합니다.

Function

field_value 가 가변적일 경우 정해진 값 대신 function 을 사용해서 유연하게 변경되게 할 수 있습니다.

예로 현재 로그인한 사용자의 미해결 이슈를 표시하는 필터를 만들고 이를 전체에 공유할 경우 "현재 사용자" 부분은 로그인한 사용자의 정보로 교체되어야 합니다.

이때문에 JQL 에서는 function 을 지원하는데 펑션은 쿼리가 실행되기 전에 Jira가 호출하는 작은 프로그램으로 function 호출 결과가 쿼리에서 대체됩니다.

위의 예에서 현재 로그인한 사용자의 정보는 currentUser() 라는 function 을 필드 값으로 사용하면 됩니다.


이렇게 function 을 사용할 때 가장 큰 장점은 가변 정보를 하드 코딩하지 않는것이며 모든 사용자가 동일한 쿼리를 사용하여 검색 결과를 볼 수 있습니다.

sprint function

현재 스프린트 표시

date 와 time 

가장 많이 사용되는 함수중에 하나는 날자와 시간 관련 함수인데 created, updated, duedate 등 날자와 관련된 필드를 대상으로 사용할 수 있습니다.

다음은 변경일이 2주전과 3일전 사이의 모든 이슈 목록을 출력합니다.

 

또는 시작 날자와 종료날자를 의미하는 startofXXX, endof 함수들이 있습니다.

XXX 에는 day 나 week, month, year 같은 키워드가 들어가며 예로 startOfmonth 는 달의 시작을 의미하므로 1이되며 endofMonth 는 해당 달이 몇 월인지에 따라 달라집니다.

시작날자, 종료날자 관련 함수는 기본적으로는 이번 주, 이번 달, 올 해를 의미하는데 예로 다음은 이번 달에 생성된 모든 이슈를 출력합니다.

 

만약 이전 일이나 이후일이 필요한 경우 옵션으로 숫자를 넣어서 표시할 수 있으며 마이너스일 경우 이전, 플러스일 경우 이후를 의미합니다. 예로 다음은 작년부터 올해까지 생성된 모든 이슈를 출력합니다.

 

다음 예제는 만기가 다음주와 다다음주인 이슈들의 목록을 표시합니다.

 

현재 시간을 나타내는 now() 도 있는데 사용예는 다음 글에서 설명해 드리겠습니다.

Operator(연산자)

필드이름과 필드값 사이에는 연산자를 적어 주는데 어떤 조건으로 필드값을 사용할지를 의미합니다.

예로 등호를 사용할 경우 필드 값이 연산자 우측과 같은 이슈들을 가져오며 부등호의 경우 해당 값이 아닌 이슈를 찾게 됩니다.

예로 다음은 담당자가 현재 로그인한 사용자가 아닌 이슈들을 표시합니다.

 

JQL 은 SQL 처럼 Equal(=), Not Equal(!=), Less than(<), is, is not  등의 다양한 연산자를 지원하는데 필드의 유형에 따라서 사용할 수 있는 연산자가 제한되어 있습니다.

less than (<)

작은 부등호는 날자에 대해서 많이 사용하는데 다음은  만료일이 지났고 미해결인 이슈를 표시합니다.

 

great than (>)

> 연산자는 필드값이 더 큰 경우를 의미하며 다음은 기한이 지나지 않은 이슈중  미해결 이슈를 표시합니다

 

CONTAINS(~)

Text 필드(summary 요약 , Description 설명, comments 댓글) 에서 특정 문자열 검색하며 다음은 웹 서버라는 단어가 있는 모든 이슈를 출력합니다.

Does not CONTAINS(!~)

!~ 는 해당 단어가 없는 이슈를 찾을 때 사용합니다. 한 가지 주의할 점은 does not 을 사용할 경우 필드명에 text 라고 쓰면 안 되고 검색할 텍스트 필드이름을 바로 써 줘야 함. 

예로 summary 에 "웹 서버" 가 없는 이슈를 찾을 경우 다음과 같이 질의합니다.

 

또는 댓글에 단어가 없는 경우는 아래와 같이 질의합니다.

 

IS

Empty 또는 null 키워드와 같이 사용하며 아래는 수정 버전 필드 값이 비어있는 모든 이슈를 검색합니다.

 

IS NOT

IS 의 반대로 아래는 수정 버전 필드값이 있는 모든 이슈를 검색합니다.

IN

여러 개의 필드 값이 있을 경우 사용하며 2 개 프로젝트의 모든 이슈를 표시합니다.

 

NOT IN

여러 개의 필드 값이 아닌 이슈를 검색할 때 사용하며 2 개 프로젝트의 모든 이슈를 표시합니다.

 

키워드


JQL 에서 키워드는 word 또는 phrase 로 여러 검색 절을 연결하는데 사용 가능한 키워드는 AND, OR, NOT, EMPTY, NULL, ORDER BY 가 있습니다.

'TEST' 프로젝트내 담당자가 Jack, John이 아닌 모든 이슈를 createDate로 정렬

AND

두 개의 검색 절의 조건을 모두 만족하는 이슈를 검색하며 다음은 TODO_KB  프로젝트에서 상태가 todo 인 이슈만 출력합니다.

 

OR

검색 절의 조건을 만족하는 이슈들을 결합하며 다음은 보고자가 백엔드개발자이거나 현재 로그인한 사용자인 모든 이슈를 출력합니다.

 

NOT

조건을 만족하지 않는 이슈를 검색하며 not 키워드는 필드이름 앞에 붙여줍니다.

다음은 보고자가 lesstif 가 아닌 이슈만 표시합니다.



다음은 ng_scrum 이 아닌 모든 프로젝트의 미해결 이슈를 검색합니다.

 

not 키워드 대신 부정을 나타내는 != 연산자를 사용해도 됩니다.

 

EMPTY

필드값이 비어 있는 경우 true 를 리턴하며 is 나 is not 키워드를 지원하는 필드에서만 사용할 수 있습니다. 

다음은 담당자가 비어 있는 이슈를 검색합니다.

 

empty 조건일 때 등호 연산자는 다음과 같이 is 를 사용할 수 있습니다. 

 

NULL

필드 값이 없는 경우를 의미하며 SQL 에서 EMPTY string 과 null string field 는 다른데 JQL 에서는 empty와 동일한 의미로 사용하면 됩니다.

예약어

SQL 처럼 JQL 도 일부 단어들은 특별한 용도로 예약되어 있습니다.

 

이런 단어들을 사용할 경우 따옴표로 둘러 싸야 제대로 처리됩니다.

"a", "an", "abort", "access", "add", "after", "alias", "all", "alter", "and", "any", "are", "as", "asc", "at", "audit", "avg", "be", "before", "begin", "between", "boolean", "break", "but", "by", "byte", "catch", "cf", "char", "character", "check", "checkpoint", "collate", "collation", "column", "commit", "connect", "continue", "count", "create", "current", "date", "decimal", "declare", "decrement", "default", "defaults", "define", "delete", "delimiter", "desc", "difference", "distinct", "divide", "do", "double", "drop", "else", "empty", "encoding", "end", "equals", "escape", "exclusive", "exec", "execute", "exists", "explain", "false", "fetch", "file", "field", "first", "float", "for", "from", "function", "go", "goto", "grant", "greater", "group", "having", "identified", "if", "immediate", "in", "increment", "index", "initial", "inner", "inout", "input", "insert", "int", "integer", "intersect", "intersection", "into", "is", "isempty", "isnull", "it", "join", "last", "left", "less", "like", "limit", "lock", "long", "max", "min", "minus", "mode", "modify", "modulo", "more", "multiply", "next", "no", "noaudit", "not", "notin", "nowait", "null", "number", "object", "of", "on", "option", "or", "order", "outer", "output", "power", "previous", "prior", "privileges", "public", "raise", "raw", "remainder", "rename", "resource", "return", "returns", "revoke", "right", "row", "rowid", "rownum", "rows", "select", "session", "set", "share", "size", "sqrt", "start", "strict", "string", "subtract", "such", "sum", "synonym", "table", "that", "the", "their", "then", "there", "these", "they", "this", "to", "trans", "transaction", "trigger", "true", "uid", "union", "unique", "update", "user", "validate", "values", "view", "was", "when", "whenever", "where", "while", "will", "with"

 

자동 완성

필드 자동 완성

JQL 을 입력할 때 사용자 편의성을 위해 자동 완성해 주는 기능이 있습니다. 예로  pr 를 치면 해당 단어로 시작하는 모든 필드를 표시합니다.

만약 project 필드를 사용할 예정이었다면 목록에서 project 를 선택하거나 아니면 pro 를 쳐서 나머지 필드를 제외하고 선택해도 됩니다.

자동 완성은 최대 15개의 필드들을 표시하므로 결과 값이 이 이상일 경우 단어를 더 쳐서 걸러내야 합니다.

그리고 목록 맨 아래에는 구문 도움말이 있으므로 JQL 이 혼동될 경우 도움말을 읽고 진행하면 됩니다.

연산자 자동 완성(Operator autocomplete)

필드 이름과 값 사이에 연산자가 넣어서 가져올 조건을 지정해야 합니다. 위 예에서는 프로젝트 이름이 ng_scrum 인 것을 찾으려고 했으므로 이때 사용할 연산자는 등호입니다.


자동 완성을 사용하여 특정 필드 이름에 사용할 수있는 연산자를 확인할 수 있습니다. 예로 프로젝트 필드 이름을 입력 한 다음 스페이스 바를 누르면 사용 가능한 연산자 목록이 표시 됩니다.

우선순위를 나타내는 priority 필드 같은 경우는 연산자가 더욱 복잡합니다. prio 를 입력한 후에 스페이스 바를 누르면 사용할 수 있는 연산자가 프로젝트 필드보다 훨씬 많은 것을 볼 수 있습니다.

이번에는 요약 필드인 summary  를 입력하고 스페이스 바를 입력해 보겠습니다. 그러면 다른 필드들과는 달리 4개의 연산자만 표시되는 것을 볼 수 있습니다.

 

여기에서 물결표시(tilde) 는 요약이나 설명 같은 text 필드에서 SQL 의 like 와 같은 역할을 수행합니다. 즉 summary ~ "웹 서버" 는 요약 필드에 "웹 서버" 라는 단어가 있는 이슈를 찾겠다는 의미입니다.

 

이렇게 JIRA 의 자동 완성 기능을 사용하면  JQL 작성이 훨씬 쉬워지고 실수를 피할 수 있습니다.

Ref