GitLab 쿼리 언어(GLQL)
GitLab v19.5Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
요약
GitLab Query Language(GLQL)는 GitLab 전체를 아우르는 단일 쿼리 언어입니다. Markdown 코드 블록에 쿼리를 임베드합니다. 의견은 GLQL 기반 임베드된 뷰 피드백 이슈에 남깁니다. 쿼리 구문은 주로 논리 표현식으로 구성됩니다.
히스토리
- GitLab 17.4에서
glql_integration이라는 기능 플래그와 함께 도입되었습니다. 기본적으로 비활성화되어 있습니다. - GitLab 17.4에서 일부 그룹 및 프로젝트를 대상으로 GitLab.com에 활성화되었습니다.
- GitLab 17.10에서 실험 기능에서 베타로 변경되었습니다.
- GitLab 17.10에서 GitLab.com, GitLab Self-Managed, GitLab Dedicated에 활성화되었습니다.
- GitLab 18.3에서 일반 공급되었습니다. 기능 플래그
glql_integration이 제거되었습니다.
GitLab Query Language(GLQL)는 GitLab 전체를 아우르는 단일 쿼리 언어입니다. 익숙한 구문으로 플랫폼 어디에 있는 콘텐츠든 필터링하고 임베드할 수 있습니다.
Markdown 코드 블록에 쿼리를 임베드합니다. 임베드된 뷰는 GLQL 소스 코드 블록을 렌더링한 결과입니다.
의견은 GLQL 기반 임베드된 뷰 피드백 이슈에 남깁니다.
쿼리 구문#
쿼리 구문은 주로 논리 표현식으로 구성됩니다. 이 표현식은
<field> <operator> <value> and ... 구문을 따릅니다.
데이터 소스#
GLQL은 작업 항목, 머지 리퀘스트, 파이프라인, job, 프로젝트 등 여러 데이터 소스를 쿼리할 수 있습니다.
지원되는 데이터 소스의 전체 목록은 GLQL 데이터 소스를 참고합니다.
필드#
필드를 사용해 결과를 필터링하고 표시하고 정렬합니다.
사용할 수 있는 필드는 쿼리 대상 데이터 소스에 따라 다릅니다. 각 데이터 소스에서 지원되는 필드, 연산자, 값의 전체 목록은 GLQL 필드를 참고합니다.
연산자#
히스토리
비교 연산자:
| GLQL 연산자 | 설명 | 검색에서 동등한 표현 |
|---|---|---|
= |
같음 / 목록의 모두 포함 | is (equal to) |
!= |
같지 않음 / 목록에 포함되지 않음 | is not (equal to) |
in |
목록에 포함 | or / is one of |
not in |
목록에 포함되지 않음 | is not one of |
> |
초과 | ❌ |
< |
미만 | ❌ |
>= |
이상 | ❌ |
<= |
이하 | ❌ |
논리 연산자: and만 지원됩니다.
일부 필드에서는 in 비교 연산자를 사용해 or를 간접적으로 사용할 수 있습니다.
not in 연산자는 목록의 모든 값을 제외합니다. 예: flowType not in ("chat", "agentic_chat/v1").
이 연산자는 이를 명시한 분석 데이터 소스 필드에서 사용할 수 있으며, 목록에는 값이 하나 이상 있어야 합니다.
값 하나만 제외하려면 !=를 사용합니다.
=가 범위를 선택하는 필드(예: 날짜 필드의 하루, 또는 activeDays 같은 범위 필터의 정확한 개수)에서는
같은 필드에서 =를 다른 비교와 함께 사용할 수 없습니다.
예를 들어 created = 2024-01-01 and created > 2023-01-01은 오류를 반환합니다.
동등 비교와 범위 비교 중 하나만 사용합니다. 이는 모든 데이터 소스와 모드에 적용됩니다.
값#
값에는 다음이 포함될 수 있습니다:
- 문자열
- 숫자
- 상대 날짜(
-1d,2w,-6m,1y등) - 절대 날짜(
YYYY-MM-DD형식, 예:2025-01-01) - 함수(사용자 필드의
currentUser(), 날짜의today()등) - 열거형 값(마일스톤의
upcoming또는started등) - 불리언(
true또는false) - 널 허용 값(
null,none,any등) - GitLab 참조(레이블의
~label, 마일스톤의%Backlog, 사용자의@username등) - 앞의 값 중 하나를 담은 목록(괄호
()로 감싸고 쉼표,로 구분)
임베드된 뷰#
임베드된 뷰는 Markdown 안 GLQL 소스 코드 블록의 출력입니다. 소스에는 쿼리와 함께 GLQL 쿼리 결과를 표시하는 방법을 설명하는 YAML 속성이 포함됩니다.
지원되는 영역#
히스토리
- 리포지터리 Markdown 파일의 임베드된 뷰가 GitLab 18.3에서 도입되었습니다.
임베드된 뷰는 다음 영역에 표시할 수 있습니다:
- 그룹 및 프로젝트 위키
- 다음 항목의 설명 및 댓글:
- 에픽
- 이슈
- 머지 리퀘스트
- 작업 항목(태스크, OKR 또는 에픽)
- 리포지터리 Markdown 파일
구문#
임베드된 뷰 소스의 구문은 다음으로 구성된 YAML의 상위 집합입니다:
query매개변수:and와 같은 논리 연산자로 결합된 표현식입니다.display,limit,fields,title,description처럼 표현 계층과 관련된 매개변수이며, YAML로 표현됩니다.
뷰는 Mermaid와 같은 다른 코드 블록과 마찬가지로 Markdown에서 코드 블록으로 정의합니다.
예를 들면 다음과 같습니다:
gitlab-org/gitlab에서 인증된 사용자에게 할당된 열린 이슈 5건을 표로 표시합니다.title,state,health,description,epic,milestone,weight,updated칼럼을 표시합니다.
```glql
display: table
title: GLQL table 🎉
description: This view lists my open issues
fields: title, state, health, epic, milestone, weight, updated
limit: 5
query: type = Issue AND group = "gitlab-org" AND assignee = currentUser() AND state = opened
```
이 소스는 아래와 같은 표를 렌더링합니다:
프레젠테이션 구문#
히스토리
query 매개변수 외에도 몇 가지 선택적 매개변수를 사용해 뷰의 표현 방식을
구성할 수 있습니다.
지원되는 매개변수:
| 매개변수 | 기본값 | 설명 |
|---|---|---|
collapsed |
false |
뷰를 축소할지 확장할지 여부입니다. |
description |
없음 | 제목 아래에 표시할 선택적 설명입니다. |
display |
list |
쿼리 결과를 표시하는 방법입니다. 사용 가능한 유형은 표시 유형을 참고합니다. |
displayConfig |
없음 | 칼럼 차트의 stacked처럼 표시 유형별 옵션입니다. 표시 유형을 참고합니다. |
fields |
title |
뷰에 포함할 필드의 쉼표 구분 목록입니다. |
limit |
100 |
첫 페이지에 표시할 항목 수입니다. 최대값은 100 입니다. |
sort |
updated desc |
데이터를 정렬할 필드와 정렬 순서(asc 또는 desc)입니다. |
title |
Embedded table view 또는 Embedded list view |
임베드된 뷰 상단에 표시되는 제목입니다. |
페이지네이션#
히스토리
- GitLab 18.2에서 도입되었습니다.
임베드된 뷰는 기본적으로 결과의 첫 페이지를 표시합니다.
limit 매개변수로 표시할 항목 수를 제어합니다.
다음 페이지를 불러오려면 마지막 행에서 Load more를 선택합니다.
필드 함수#
동적으로 생성되는 칼럼을 만들려면 뷰의 fields 매개변수에 함수를 사용합니다.
전체 목록은 임베드된 뷰의 함수를 참고합니다.
커스텀 필드 별칭#
히스토리
- GitLab 18.0에서 도입되었습니다.
표 뷰의 칼럼 이름을 원하는 값으로 바꾸려면 AS 구문 키워드로 필드에 별칭을 지정합니다.
```glql
display: list
fields: title, labels("workflow::*") AS "Workflow", labels("priority::*") AS "Priority"
limit: 5
query: type = Issue AND project = "gitlab-org/gitlab" AND assignee = currentUser() AND state = opened
```
이 소스는 Title, Workflow, Priority 칼럼을 가진 뷰를 표시합니다.
표시 유형#
display 매개변수는 임베드된 뷰가 쿼리 결과를 목록, 표, 칼럼 차트 등 어떤 형태로
렌더링할지 제어합니다. 기본적으로 결과는 목록으로 표시됩니다.
표시 유형의 전체 목록과 구성 방법은 GLQL 표시 유형을 참고합니다.
뷰 액션#
뷰가 페이지에 표시되면 View actions (⋮) 드롭다운 목록에서 해당 뷰에 대한 액션을 실행합니다.
지원되는 액션:
| 액션 | 설명 |
|---|---|
| View source | 뷰의 소스를 봅니다. |
| Copy source | 뷰의 소스를 클립보드에 복사합니다. |
| Copy contents | 표 또는 목록 내용을 클립보드에 복사합니다. |
| Reload | 이 뷰를 다시 로드합니다. |
분석 모드#
히스토리
- GitLab 19.1에서 도입되었습니다.
GLQL은 집계 메트릭을 제공하는 데이터 소스에 대해 분석 모드를
지원합니다. 분석 모드 쿼리는 데이터를 그룹화하고 집계하기 위해 fields 대신
dimensions와 metrics를 사용합니다.
일부 데이터 소스는 표준 모드와 분석 모드를 모두 지원합니다. 지원되는 모드는 각 데이터 소스 페이지를 참고합니다.
구문#
분석 모드 쿼리는 다음 구조를 사용합니다:
```glql
mode: analytics
query: type = and <filters>
dimensions: <dimension fields>
metrics: <metric fields>
sort: <field> <direction>
limit: <number>
```
| 매개변수 | 필수 여부 | 설명 |
|---|---|---|
mode: analytics |
Yes | 분석 모드를 사용하려면 필수입니다. |
metrics |
Yes | 계산할 집계 값입니다. 최소 하나의 metric 이 필요합니다. |
dimensions |
No | 결과를 그룹화할 필드입니다. 임의의 조합을 선택하거나, 단일 집계 행을 반환하려면 완전히 생략합니다. |
sort |
No | 정렬 필드는 선택한 dimensions 또는 metrics에도 있어야 합니다. |
limit |
No | 페이지당 행 수이며 최대 100입니다. limit를 생략하면 차트와 stat 같은 분석 모드 표시 유형이 최대 1,000행까지 모든 페이지를 자동으로 가져옵니다. 페이지네이션 지원을 참고합니다. |
필드 매개변수#
히스토리
일부 dimension과 metric은 필드 이름 뒤 괄호 안에 매개변수를 받습니다.
매개변수를 생략하면 필드는 기본값을 사용합니다.
매개변수는 위치로(finished(weekly)) 또는 이름으로(finished(granularity=weekly)) 전달할 수 있습니다.
위치 인수 하나는 필드의 첫 번째 매개변수에 바인딩됩니다. 예: created(30d).
매개변수를 둘 이상 전달할 때는 이름 지정 구문을 사용합니다. 예:
created(granularity=30d, origin=2026-07-16). 위치 인수 두 개는 오류를 반환합니다.
매개변수를 받는 필드와 그 기본값은 데이터 소스 페이지를 참고합니다. 같은 필드를 서로 다른 매개변수로 두 번 이상 포함하려면 커스텀 별칭을 참고합니다.
예를 들어 다음 쿼리는 주 단위 버킷으로 파이프라인 소요 시간의 중앙값을 반환합니다:
```glql
mode: analytics
query: type = Pipeline and project = "gitlab-org/gitlab" and finished >= -90d
dimensions: finished(weekly)
metrics: durationQuantile(0.5)
sort: finished desc
```
목록 값#
일부 매개변수는 목록을 받습니다. 대괄호로 작성하며, 예를 들어 name(key=[v1, v2]) 또는
name([v1, v2])입니다. []는 빈 목록입니다. 숫자는 음수일 수 있습니다. 목록 매개변수에 전달한 단일 값은
항목이 하나인 목록으로 해석되므로, userTier(8)은 userTier(thresholds=[8])와 같고
totalCount(event="request_duo_chat_response")는 totalCount(event=["request_duo_chat_response"])와 같습니다.
대괄호는 필드 매개변수에만 사용합니다. query의 필터 목록에는 계속 소괄호를 사용합니다.
예: status in (paused, failed).
Granularity#
모든 날짜 dimension은 granularity 매개변수를 받습니다. 허용되는 값은 daily, weekly,
monthly, 또는 1d부터 399d까지의 고정 일수(예: created(30d))입니다. 일수는 따옴표 없이
(created(30d)), 따옴표로 묶어(created("30d")), 또는 이름으로(created(granularity=30d))
작성할 수 있습니다.
고정 일수 버킷은 origin으로 기준을 지정하지 않으면 Unix epoch(1970년 1월 1일)부터 계산되므로,
그대로는 날짜 필터와 거의 맞지 않습니다.
dimension별 기본 granularity는 각 데이터 소스 페이지에 나와 있습니다.
Origin#
origin은 모든 날짜 dimension의 선택적 두 번째 매개변수입니다. 고정 일수 버킷을 계산하기 시작하는
시점을 지정합니다.
값은 ISO 8601 날짜 또는 날짜-시간입니다. 날짜는 필터 날짜처럼 따옴표 없이 작성합니다
(origin=2026-07-16). 날짜-시간은 따옴표로 묶어야 합니다(origin="2026-07-16T00:00:00Z").
시간대 오프셋은 UTC로 변환됩니다. 소수 초는 허용되지 않습니다.
버킷 레이블은 달력 날짜를 사용하며 시각 경계를 표시하지 않으므로, 시각이 포함된 origin을 사용하면
각 버킷은 시작하는 UTC 날짜로 레이블이 지정됩니다.
origin은 고정 일수 granularity에서만 유효합니다. created(granularity=weekly, origin=...)와
달력 기본값을 사용하는 created(origin=...) 단독 사용 모두 오류를 반환합니다.
-60d나 today() 같은 상대 값은 허용되지 않습니다. 지원은
이슈 230에서 제안되었습니다.
예를 들어 다음 쿼리는 연속된 두 개의 30일 기간 동안 머지된 머지 리퀘스트를 비교합니다.
```glql
title: "Merge requests merged per 30-day period"
display: table
mode: analytics
query: type = MergeRequest and group = "gitlab-org" and merged >= 2026-07-16 and merged < 2026-09-14
dimensions: merged(granularity=30d, origin=2026-07-16) as "Period"
metrics: totalCount as "Merge requests"
sort: merged asc
```
origin이 30일 버킷을 선택한 기간의 시작에 맞추므로, 쿼리는 기간당 한 행을 반환합니다.
비어 있는 버킷은 생략됩니다.
커스텀 별칭#
히스토리
- 고유 별칭으로 매개변수화된 필드를 중복 지정하는 기능이 GitLab 19.3에서 도입되었습니다.
as 키워드로 dimension 또는 metric 칼럼의 이름을 바꿉니다:
dimensions: language as "Language", ideName as "IDE"
metrics: totalCount as "Total", acceptanceRate as "Acceptance Rate"
같은 매개변수화된 필드를 서로 다른 매개변수로 두 번 이상 포함할 수 있습니다:
metrics: durationQuantile(0.5) as "Median", durationQuantile(0.95) as "p95"
필드를 중복 지정할 때는 다음 조건이 적용됩니다:
- 중복 지정된 모든 필드에는 고유한 별칭이 있어야 합니다.
- 별칭은 모든 dimension과 metric에서 고유해야 합니다.
- 매개변수를 받지 않는 필드는 중복 지정할 수 없습니다.
- 중복 지정된 필드는 별칭으로 정렬해야 합니다. 예를 들면
sort: Median desc입니다. sort에 사용하는 별칭은 한 단어여야 합니다.
정렬#
선택한 dimension 또는 metric에 포함된 필드라면 어느 것으로든 정렬할 수 있습니다. 선택한 dimension 또는 metric에 없는 필드로는 정렬할 수 없습니다. 커스텀 별칭이 있는 필드는 별칭과 원래 필드 이름 중 어느 쪽으로도 정렬할 수 있습니다. 같은 필드가 서로 다른 매개변수로 중복 지정된 경우에는 별칭으로 정렬해야 합니다.
sort: acceptanceRate desc
여러 정렬 필드를 지원합니다:
sort: totalCount desc, acceptanceRate asc
예시#
다음 쿼리는 최근 30일 동안의 언어별 Code Suggestions 수락률을 수락률 기준으로 정렬해 반환합니다:
```glql
display: table
mode: analytics
query: type = CodeSuggestion and timestamp >= -30d
dimensions: language as "Language"
metrics: totalCount as "Total", acceptanceRate as "Acceptance Rate"
sort: acceptanceRate desc
```
자세한 내용은 특정 데이터 소스의 예시를 참고합니다.
고급 검색 통합#
히스토리
이 기능의 사용 가능 여부는 기능 플래그로 제어됩니다. 자세한 내용은 히스토리를 참고합니다.
GLQL은 쿼리 속도를 높이기 위해 사용 가능한 경우 고급 검색을 사용합니다. 고급 검색은 대규모 데이터셋을 대상으로 하는 복잡한 쿼리에 더 빠른 응답 시간을 제공합니다.
고급 검색의 제공 조건은 다음과 같습니다:
- GitLab.com 및 GitLab Dedicated 유료 구독에서는 기본적으로 활성화되어 있습니다.
- GitLab Self-Managed에서는 관리자가 고급 검색을 활성화하면 사용할 수 있습니다.
고급 검색을 사용할 수 없으면 GLQL은 대신 PostgreSQL을 사용합니다.