grep

Product

JQL 활용하기

김현규Crimson(크림슨) / 기술기획팀여기어때

2023년 8월 11일

원문에서 보기 ↗

안녕하세요. 여기어때 기술기획팀 크림슨 입니다.

Jira 를 활용하는 부서들이 많아지다 보니, Admin.으로 회사의 Jira 를 관리하면서 간단한 문제를 문의하는경우가 있습니다.

특히 필드의 구성이나 Filter 같은 것들을 활용해서 대시보드의 생산성을 높이는 고민들은 누구나 하고 있을 겁니다.

그래서 간단하고 쉽게 Filter 를 사용할 수 있도록 JQL 을 활용하는 방법을 소개 하려고 합니다.

“JQL is a text-based language that defines how Jira narrows down a search.”

JQL 은 Jira Query Language 의 약자로 Jira Issue 를 검색하기 위한 구조적인 언어라고 보면 편합니다. SQL과 비슷한 문법을 갖고 있으므로 개발자 분들은 쉽게 배워서 사용할 수 있습니다.

1 .Issue 검색 (Search)

Jira 에서 Issue 검색은 크게 세 단계로 나눠볼 수 있습니다.

a. Quick search

i. Main navigation bar → “Search”

b. Basic search

i. Filters → View all issues → “Switch to basic”

c. Advanced search with JQL

i. Filters → View all issues → “Switch to JQL”

Basic search vs. JQL

JQL 을 사용하지 않아도 Jira 에서 손쉽게 Filter 를 생성할 수 있습니다.

이걸 Basic 이라고 볼 수 있습니다.

다만, 필터나 대시 보드 설정에서 JQL을 꼭 사용해야 할 경우가 있습니다.

이 경우에는 이슈 검색을 Basic 으로 설정한 후 필터 조건들을 설정하여 1차 검색을 완료합니다. 그리고 Switch to JQL 로 변경하면 기본 검색으로 설정한 결과를 자동으로 JQL 로 변경할 수 있습니다.

여기서는 Advanced 검색을 활용하기 위한 개념을 설명 드리겠습니다.

2. Elements of JQL syntax

JQL 은 Field 필드, Operator 연산자, Function 함수, Keyword 키워드로 구성되어 있습니다. 이 구조를 여러 번 사용하여 강력한 검색 조건을 만들 수 있는 구조 입니다.

a. Field 필드

i. System fields : Jira Software의 기본 시스템 필드

ii. Custom fields : 사용자 지정 필드로 사용자가 생성한 필드

b. Operator 연산자

Query에서 연산자 값은 무척 중요한데 필드에서 하나 이상의 값과 비교하여 검색되도록 만듭니다. 아래 이외에도 다른 Operator 들이 많이 있습니다만 가장 많이 사용하는 Operator 를 예시와 함께 설명 드리겠습니다.

  1. equal: status = “In Progress”
  1. not equal: status != Done
  1. greater: created > startOfWeek()
  1. greater or equal: updated >= startOfweek()
  1. less: updated < startOfWeek()
  1. less or equal: created <= startOfWeek()
  1. in : project in ()
  1. not in : project in ()

※ 주의

공백이 있는 Value 값의 경우 “ “ 을 사용해야 값의 구분이 가능합니다.

예를 들어, To Do, In Progress를 사용할 때, Value 의 값에 공백(Spacebar)를 포함하기 위해서는 “를 사용하여 “To Do”, “In Progress” 와 같이 하나의 Value값으로 묶어 주는 것이 필요합니다. 코테이션을 사용하지 않을 경우, To와 Do를 별개의 Value로 인식하게 되니 이점을 주의해야 합니다.

c. Function 함수

함수는 Query를 통해 나타나는 실제 데이터를 의미ㅑ합니다. 위에 예시로 든 startOfWeek 라는 필드의 값의 () 괄호안에 3이라고 넣으면 startOfWeek(3) 은 이슈가 시작하고 3주차라는 뜻이 됩니다.

d. Keyword 키워드

키워드는 특별한 의미를 가진 단어로 둘 이상의 쿼리문을 결합하여 복잡한 쿼리문을 생성하거나 하나 이상의 쿼리문의 로직을 변경할 수도 있으며, 특정 함수를 실행할 수 있습니다.

  1. AND : 여러 쿼리문을 연결하여 조건이 모두 일치하는 이슈를 검색

  2. OR : 여러 쿼리문의 조건 중 하나라도 일치하는 이슈를 검색

  3. NOT : 쿼리문의 조건에 해당하지 않는 이슈를 검색

  4. EMPTY : 지정된 필드 값이 없는 이슈를 검색

  5. NULL : 지정된 필드 값이 없는 이슈를 검색

  6. ORDER BY : 검색 결과를 지정된 필드로 정렬

  7. not equal: status != Done

  1. greater: created > startOfWeek()
  1. greater or equal: updated >= startOfweek()
  1. less: updated < startOfWeek()
  1. less or equal: created <= startOfWeek()
  1. in : project in ()
  1. not in : project in ()

c. Function 함수

함수는 Query를 통해 나타나는 실제 데이터를 의미합니다. 위에 예시로 든 startOfWeek 라는 필드의 값의 () 괄호안에 3이라고 넣으면 startOfWeek(3) 은 이슈가 시작하고 3주차라는 뜻이 됩니다.

d. Keyword 키워드

키워드는 특별한 의미를 가진 단어로 둘 이상의 쿼리문을 결합하여 복잡한 쿼리문을 생성하거나 하나 이상의 쿼리문의 로직을 변경할 수도 있으며, 특정 함수를 실행할 수 있습니다.

  1. AND : 여러 쿼리문을 연결하여 조건이 모두 일치하는 이슈를 검색

  2. OR : 여러 쿼리문의 조건 중 하나라도 일치하는 이슈를 검색

  3. NOT : 쿼리문의 조건에 해당하지 않는 이슈를 검색

  4. EMPTY : 지정된 필드 값이 없는 이슈를 검색

  5. NULL : 지정된 필드 값이 없는 이슈를 검색

  6. ORDER BY : 검색 결과를 지정된 필드로 정렬

All JQL queries do two things :

모든 JQL 은 두 가지 작업을 수행합니다.

i. Select a subset of issues 첫째로는 이슈들의 하위 집합을 선택하는 것과,

ii. Order the result 둘째로 주문한 결과를 보여주는 것인데요.

위의 4가지 Jira Syntax 를 조합하여 아래와 같은 JQL을 만들어 볼 수 있습니다.

BH2023은 현재 진행되고 있는 프로젝트인데요, 위 쿼리문을 해석하자면

“프로젝트 BH2023의 이슈이고, status 값이 In progress (진행중) 인 이슈를 내림차순(Descending) 검색해라”라고 볼 수 있습니다.

JQL 기본 예제

이 외에도 가장 많이 사용하는 기본 구문을 소개해 보겠습니다.

  1. “BH2023” 프로젝트에서 Status 값이 In progress 인 이슈 검색

→ project = BH2023 AND status = “In Progress”

  1. 첨부파일이 있는 이슈 검색

→ attachments IS NOT EMPTY

  1. 이슈 댓글에 “처리 되었습니다.”가 포함된 이슈 검색

→ comment ~ “\”처리 되었습니다.”\”

  1. 이슈 생성 날짜가 2023–9–11 이전에 생성된 이슈 검색

→ created < “2023–9–11”

  1. 컴포넌트가 ‘컴포넌트1’이거나 ‘컴포넌트2’인 이슈 검색

→ component in (컴포넌트1, 컴포넌트2)

※ 참조로 괄호 안의 , 는 And 가 아닌 Or 입니다. 이점은 주의해야 합니다.

  1. assignee가 변경된 이슈 검색

→ assignee CHANGED

  1. assingee가 ‘김철수’ 였던 이슈 검색

→ assignee WAS 김철수

  1. duedate가 설정되지 않은 이슈를 검색하여 생성일, 우선순위 순으로 정렬

→ duedate = empty order by created, priority asc

  1. 이번주 이슈 중 상태가 ‘In Progress’ 였던 이슈 검색

→ status was (“In Progress”) DURING (startofweek(), endofweek());

  1. Resolution이 ‘Fixed’ 로 변경된 이슈 검색

→ resolution changed to “Fixed”

  1. ‘BH2023’ 프로젝트에서 크림슨이이 상태를 ‘In Progress’에서 ‘Resolved’로 변경한 이슈 검색

→ project = BH2023 AND status CHANGED FROM “In Progress” TO “Resolved”

BY 크림슨

많이 사용되는 예제 위주로 설명 드렸습니다. 이외에도 다양한 문구를 활용할 수 있습니다.

검색 우선순위 지정

복잡한 JQL 문은 괄호를 사용하여 연산자의 우선순위를 적용할 수 있습니다.

숫자를 계산할 때, 괄호 안의 계산식을 먼저 계산하는 것과 같은 이치입니다.

괄호를 사용하지 않는다면 쿼리문은 왼쪽에서 오른쪽으로 순차적으로 실행됩니다.

이 외에도 Description에 특정 단어가 포함된 Issue 를 검색할 수도 있는데, 이런 기능들은 Basic search 에서는 제공하고 있지 않기 때문에 활용성이 매우 높습니다. 기본 검색이나 예시의 경우는 찾아보면 활용할 수 있는 글들이 매우 많습니다.

아래는 JQL사용시 주의 사항 입니다.

JQL 주의 사항

  1. 문법 관련 주의사항
  1. 성능 관련 주의사항
  1. 논리 연산자 주의사항

이외에도 주의해야 할 것들이 있지만, JQL의 경우 검색해도 권한이 없는 이슈는 보이지 않습니다. 그리고 assignee WAS currentUser() 같은 히스토리 검색은 권한에 따라 결과가 다를 수 있어 주의해야 합니다. (Admin 권한과 일반 권한 사용자 권한에서 검색 결과가 다를 수 있음)

이런 점들을 유의하면 JQL을 작성하면 더 효율적이고 정확한 검색이 가능합니다.

“Don’t trust Jira documents 100%”

마지막으로 Jira 에서 제공되는 것들은 지속적으로 업데이트 되고 있습니다. 그래서 Jira 에서 제공되는 문서를 100% 믿지 말라는 말이 있습니다.

Jira 의 Help / Request 게시판에 가보면 전 세계 유저들의 요청이 많기 때문에 변경사항이 자주 발생합니다. (심지어 변경되어도 공지되지 않는 경우도 있음)

새로운 요청으로 생겨나는 것들도 있고 Legacy가 되어 없어지는 것들도 많습니다. 이전에 잘 사용하고 있던 기능들도 개선이라는 이름으로 변경되는 경우도 있습니다.

Jira 에서 제공되는 것을 활용하는 것 뿐만 아니라, JQL 을 활용해서 자신만의 강력한 검색 조건을 통해 업무가 더 효율적으로 관리될 수 있기를 바랍니다.

※ 참조 문서.

참조 문서는 Atlassian 의 help 문서들인데, Atlassian의 경우는 호주에서 시작된 회사라서 영문으로 기능 검색을 하면 편합니다.

How to search using statusCategory() & statusCategoryChangeDate() function with JQL | Jira | Atlassian Documentation

JQL Operators

https://support.atlassian.com/jira-software-cloud/docs/jql-operators/

JQL Keywords

https://support.atlassian.com/jira-software-cloud/docs/jql-keywords/

JQL Functions

https://support.atlassian.com/jira-software-cloud/docs/jql-functions/

Learn JQL Advanced Search in Jira Software

https://www.youtube.com/playlist?list=PLaD4FvsFdarTEL2dyTr2wfo7bUWLVOb-c