히스토리

• GitLab 18.7에서 도입되었습니다.

이 API를 사용하면 GitLab Query Language(GLQL) 쿼리를 프로그래밍 방식으로 실행할 수 있습니다. GLQL은 프로젝트와 그룹 전반에서 이슈, 머지 리퀘스트, 에픽 같은 GitLab 리소스를 검색하고 필터링하기 위한 단순한 쿼리 언어를 제공합니다.

사전 요구 사항:

• 그룹 또는 프로젝트가 자신의 데이터에 대한 액세스를 허용해야 합니다.
• 비공개 그룹과 프로젝트에서는 적절한 권한을 가진 개인 액세스 토큰을 사용해야 합니다.

GLQL 쿼리 실행#

GLQL 쿼리를 실행하여 GitLab 리소스를 검색하고 필터링합니다.

POST /glql

지원되는 속성:

쿼리 형식#

glql_yaml 파라미터는 query 키를 포함하는 YAML 형식을 허용합니다.

fields: id,title,author
group: my-group
limit: 10
sort: created desc
query: state = opened

구성 옵션#

YAML에 다음 구성 옵션을 포함할 수 있습니다.

사용 가능한 필드#

fields 구성 옵션에 사용 가능한 GLQL 필드를 쉼표로 구분한 목록으로 설정합니다.

GLQL 쿼리 구문#

쿼리 구문은 GLQL에 정의되어 있습니다.

응답 속성#

요청이 성공하면 200 OK와 다음 응답 속성을 반환합니다.

예시: 기본 쿼리#

그룹에서 열린 이슈를 검색합니다.

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header "Content-Type: application/json" \
  --data '{
    "glql_yaml": "query: group = \"my-group\" AND state = opened"
  }' \
  --url "https://gitlab.example.com/api/v4/glql"

응답 예시:

{
  "data": {
    "count": 1,
    "nodes": [
      {
        "id": "gid://gitlab/Issue/123",
        "iid": "123",
        "reference": "#123",
        "state": "OPEN",
        "title": "Add an example of GoLang HTTP server",
        "webUrl": "https://gitlab.example.com/my-group/my-project/-/issues/123",
        "widgets": null
      }
    ],
    "pageInfo": {
      "endCursor": "eyJpZCI6IjEyMyJ9",
      "hasNextPage": false,
      "hasPreviousPage": false,
      "startCursor": "eyJpZCI6IjEyMyJ9"
    }
  },
  "error": null,
  "fields": [
    {
      "field": "title",
      "key": "title",
      "label": "Title",
      "name": "title"
    }
  ],
  "success": true
}

예시: front matter 구성을 포함한 쿼리#

사용자 지정 필드와 정렬을 사용하여 검색합니다.

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header "Content-Type: application/json" \
  --data '{
    "glql_yaml": "fields: id,title,author,state\ngroup: my-group\nlimit: 5\nsort: created desc\nquery: state = opened"
  }' \
  --url "https://gitlab.example.com/api/v4/glql"

응답 예시:

{
  "data": {
    "count": 2,
    "nodes": [
      {
        "author": {
          "avatarUrl": "https://www.gravatar.com/avatar/4a17cff4a15e98966063bd203d88aceac682c623e74943a08cdbe0cce87c6d7c?s=80&d=identicon",
          "id": "gid://gitlab/User/123",
          "name": "John Doe",
          "username": "johndoe",
          "webUrl": "https://gitlab.example.com/johndoe"
        },
        "id": "gid://gitlab/Issue/123",
        "iid": "123",
        "reference": "#123",
        "state": "OPEN",
        "title": "Add an example of GoLang HTTP server",
        "webUrl": "https://gitlab.example.com/my-group/my-project/-/issues/123",
        "widgets": null
      },
      {
        "author": {
          "avatarUrl": "https://www.gravatar.com/avatar/4a17cff4a15e98966063bd203d88aceac682c623e74943a08cdbe0cce87c6d7c?s=80&d=identicon",
          "id": "gid://gitlab/User/122",
          "name": "Jane Doe",
          "username": "janedoe",
          "webUrl": "https://gitlab.example.com/janedoe"
        },
        "id": "gid://gitlab/Issue/122",
        "iid": "122",
        "reference": "#122",
        "state": "OPEN",
        "title": "HTTP server examples for all programming languages",
        "webUrl": "https://gitlab.example.com/groups/my-group/-/issues/122",
        "widgets": null
      }
    ],
    "pageInfo": {
      "endCursor": "eyJpZCI6IjEyMyJ9",
      "hasNextPage": false,
      "hasPreviousPage": false,
      "startCursor": "eyJpZCI6IjEyMyJ9"
    }
  },
  "error": null,
  "fields": [
    {
      "field": "id",
      "key": "id",
      "label": "ID",
      "name": "id"
    },
    {
      "field": "title",
      "key": "title",
      "label": "Title",
      "name": "title"
    },
    {
      "field": "author",
      "key": "author",
      "label": "Author",
      "name": "author"
    },
    {
      "field": "state",
      "key": "state",
      "label": "State",
      "name": "state"
    }
  ],
  "success": true
}

예시: 프로젝트 범위를 지정한 쿼리#

특정 프로젝트에서 검색합니다.

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header "Content-Type: application/json" \
  --data '{
    "glql_yaml": "query: project = \"my-group/my-project\" AND state = opened"
  }' \
  --url "https://gitlab.example.com/api/v4/glql"

예시: currentUser() 함수를 사용한 쿼리#

현재 사용자에게 할당된 이슈를 검색합니다.

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header "Content-Type: application/json" \
  --data '{
    "glql_yaml": "fields: id,title,assignees\nquery: group = \"my-group\" AND assignee = currentUser()"
  }' \
  --url "https://gitlab.example.com/api/v4/glql"

응답 예시:

{
  "data": {
    "count": 1,
    "nodes": [
      {
        "assignees": {
          "nodes": [
            {
              "avatarUrl": "https://www.gravatar.com/avatar/4a17cff4a15e98966063bd203d88aceac682c623e74943a08cdbe0cce87c6d7c?s=80&d=identicon",
              "id": "gid://gitlab/User/123",
              "name": "John Doe",
              "username": "johndoe",
              "webUrl": "https://gitlab.example.com/johndoe"
            }
          ]
        },
        "id": "gid://gitlab/Issue/123",
        "iid": "123",
        "reference": "#123",
        "state": "OPEN",
        "title": "Add an example of GoLang HTTP server",
        "webUrl": "https://gitlab.example.com/my-group/my-project/-/issues/123",
        "widgets": null
      }
    ],
    "pageInfo": {
      "endCursor": "eyJpZCI6IjEyMyJ9",
      "hasNextPage": false,
      "hasPreviousPage": false,
      "startCursor": "eyJpZCI6IjEyMyJ9"
    }
  },
  "error": null,
  "fields": [
    {
      "field": "id",
      "key": "id",
      "label": "ID",
      "name": "id"
    },
    {
      "field": "title",
      "key": "title",
      "label": "Title",
      "name": "title"
    },
    {
      "field": "assignees",
      "key": "assignees",
      "label": "Assignees",
      "name": "assignees"
    }
  ],
  "success": true
}

예시: 제한과 페이지네이션을 사용한 쿼리#

제한된 개수의 결과를 조회하고 페이지 단위로 이동합니다.

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header "Content-Type: application/json" \
  --data '{
    "glql_yaml": "limit: 2\nquery: group = \"my-group\" AND state = opened"
  }' \
  --url "https://gitlab.example.com/api/v4/glql"

응답 예시:

{
  "data": {
    "count": 68,
    "nodes": [
      {
        "id": "gid://gitlab/Issue/321",
        "iid": "321",
        "reference": "#321",
        "state": "OPEN",
        "title": "Corrupti consectetur impedit non blanditiis hic vitae minus.",
        "webUrl": "https://gitlab.example.com/my-group/my-project/-/issues/321",
        "widgets": null
      },
      {
        "id": "gid://gitlab/WorkItem/322",
        "iid": "322",
        "reference": "#322",
        "state": "OPEN",
        "title": "Ipsa cupiditate corrupti vel maxime quasi at assumenda repellat quod.",
        "webUrl": "https://gitlab.example.com/my-group/my-project/-/issues/322",
        "widgets": null
      }
    ],
    "pageInfo": {
      "endCursor": "eyJpZCI6IjIifQ==",
      "hasNextPage": true,
      "hasPreviousPage": false,
      "startCursor": "eyJpZCI6IjEyMyJ9"
    }
  },
  "error": null,
  "fields": [
    {
      "field": "title",
      "key": "title",
      "label": "Title",
      "name": "title"
    }
  ],
  "success": true
}

다음 페이지를 가져오려면 이전 응답의 endCursor 값을 사용합니다.

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header "Content-Type: application/json" \
  --data '{
    "glql_yaml": "limit: 2\nquery: group = \"my-group\" AND state = opened",
    "after": "eyJpZCI6IjIifQ=="
  }' \
  --url "https://gitlab.example.com/api/v4/glql"

예시: 분석 모드 쿼리#

파이프라인 지표를 차원별로 집계합니다. 분석 모드에서는 fields 배열에 각 필드의 type 속성이 포함되며, 파라미터 필드에는 parameters 속성이 포함됩니다.

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header "Content-Type: application/json" \
  --data '{
    "glql_yaml": "mode: analytics\ndimensions: ref\nmetrics: durationQuantile(0.5) as \"p50\"\nquery: type = Pipeline AND project = \"my-group/my-project\" AND finished >= -30d"
  }' \
  --url "https://gitlab.example.com/api/v4/glql"

응답 예시:

{
  "data": {
    "count": 2,
    "nodes": [
      {
        "durationQuantile_quantile_0_d5": 245.5,
        "p50": 245.5,
        "ref": "main"
      },
      {
        "durationQuantile_quantile_0_d5": 312.0,
        "p50": 312.0,
        "ref": "feature-branch"
      }
    ],
    "pageInfo": {
      "endCursor": "eyJpZCI6IjIifQ==",
      "hasNextPage": false,
      "hasPreviousPage": false,
      "startCursor": "eyJpZCI6IjEifQ=="
    }
  },
  "error": null,
  "fields": [
    {
      "field": "ref",
      "key": "ref",
      "label": "Ref",
      "name": "ref",
      "type": "dimension"
    },
    {
      "field": "durationQuantile",
      "key": "p50",
      "label": "p50",
      "name": "durationQuantile_quantile_0_d5",
      "parameters": {
        "quantile": "0.5"
      },
      "type": "metric"
    }
  ],
  "success": true
}

GLQL 스키마 조회#

히스토리

• GitLab 19.3에서 도입되었습니다.
• List 파라미터와 required 속성이 GitLab 19.5에서 도입되었습니다.
• Granularity 파라미터 종류가 GitLab 19.5에서 도입되었습니다.
• Timestamp 파라미터 종류와 optional, requires 속성이 GitLab 19.5에서 도입되었습니다.
• List 파라미터의 String 항목이 GitLab 19.5에서 도입되었습니다.

GLQL 스키마를 조회합니다. 스키마에는 사용 가능한 데이터 소스와 각 소스의 필터·표시·정렬 필드, 연산자·값 종류·참조 유형 어휘, 사용 가능한 함수, 그리고 쿼리를 렌더링할 수 있는 표시 유형이 포함됩니다.

이 문서는 쿼리 언어를 설명합니다. 사용자에게 제공되지 않는 데이터 소스를 대상으로 하는 쿼리는 POST /glql에서 실패합니다.

이 문서는 GitLab을 업그레이드할 때만 변경됩니다. ETag와 함께 제공되므로 If-None-Match를 보내 재검증하면 전체 문서 대신 304 Not Modified를 받을 수 있습니다.

GET /glql/schema

이 엔드포인트는 파라미터를 받지 않으며 모든 사용자에게 동일한 문서를 반환합니다.

요청이 성공하면 200 OK와 다음 응답 속성을 반환합니다.

display_types[]의 응답 속성:

display_types[].selections[]의 응답 속성:

sources[]의 응답 속성:

sources[].modes[]의 응답 속성:

sources[].modes[].filter_fields[].value_types[]의 응답 속성:

sources[].modes[].parameterized_fields[].parameters[]의 응답 속성:

요청 예시:

curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/glql/schema"

응답 예시(일부 생략):

{
  "sources": [
    {
      "name": "WorkItems",
      "label": "work items",
      "modes": [
        {
          "mode": "Standard",
          "allowed_scopes": ["project", "group"],
          "filter_fields": [
            {
              "name": "label",
              "aliases": ["labels"],
              "value_types": [
                { "kind": "String", "operators": ["=", "!="] },
                {
                  "kind": "List",
                  "operators": ["in", "=", "!="],
                  "items": [{ "kind": "String" }, { "kind": "Reference", "references": "LabelRef" }]
                }
              ]
            }
          ],
          "wildcard_filter_fields": [
            {
              "name": "customField",
              "syntax": "customField(\"Name\")",
              "value_types": [{ "kind": "String", "operators": ["="] }]
            }
          ],
          "display_fields": [
            { "name": "title" },
            { "name": "assignee", "aliases": ["assignees"] }
          ],
          "sort_fields": ["created", "updated", "due"]
        }
      ]
    }
  ],
  "operators": [{ "symbol": "=", "name": "Equal", "label": "equals" }],
  "value_kinds": [{ "name": "String", "description": "A quoted string, for example \"my title\"." }],
  "reference_types": [{ "name": "LabelRef", "symbol": "~", "example": "~frontend" }],
  "display_types": [
    { "name": "list", "description": "A bulleted list of items." },
    {
      "name": "barChart",
      "description": "Horizontal bars, one per dimension value.",
      "selections": [
        { "dimensions": 1, "metrics": { "min": 1 } },
        { "dimensions": 2, "metrics": { "min": 1, "max": 1 } }
      ]
    }
  ],
  "functions": [
    { "name": "today", "kind": "value", "description": "Today's date at 00:00 UTC.", "args": [], "returns": "Date" }
  ],
  "version": "0.41.0"
}

분석 모드는 차원과 지표가 허용하는 인수를 함께 제공하므로, 쿼리에서 기본값에 의존하지 않고 인수를 명시적으로 설정할 수 있습니다.

"parameterized_fields": [
  {
    "name": "finished",
    "parameters": [
      { "name": "granularity", "kind": "Granularity", "values": ["daily", "weekly", "monthly"], "min_days": 1, "max_days": 399, "default": "weekly" },
      { "name": "origin", "kind": "Timestamp", "optional": true, "requires": { "parameter": "granularity", "value": "a fixed-day granularity such as `30d`, not a calendar bucket (`daily`, `weekly`, `monthly`)" } }
    ]
  },
  {
    "name": "durationQuantile",
    "parameters": [{ "name": "quantile", "kind": "Number", "min": 0.01, "max": 0.99, "default": 0.95 }]
  },
  {
    "name": "userTier",
    "parameters": [
      { "name": "thresholds", "kind": "List", "items": [{ "kind": "Number", "min": 1, "max": 2147483647 }], "min_length": 1, "max_length": 9, "strictly_ascending": true, "required": true }
    ]
  }
]

속도 제한#

GLQL API는 쿼리의 SHA-256 해시를 기준으로 속도 제한을 적용합니다. 타임아웃이 발생한 쿼리는 추적됩니다. 타임아웃이 발생하는 특정 쿼리가 너무 자주 실행되면 일시적으로 차단됩니다.

속도 제한이 적용되면 API는 429 Too Many Requests 상태 코드와 오류 메시지를 반환합니다.

{
  "error": "Query temporarily blocked due to repeated timeouts. Please try again later or narrow your search scope."
}

오류 처리#

API는 다음 HTTP 상태 코드를 반환합니다.

오류 응답 예시#

• 필수 파라미터 누락:

  {
    "error": "glql_yaml is missing, glql_yaml is empty"
  }
  

• 잘못된 GLQL 구문:

  {
    "error": "400 Bad request - Error: Unexpected `invalid syntax @@@ ###`, expected operator (one of IN, =, !=, >, or <)"
  }
  

• 입력 크기 초과:

  {
    "error": "400 Bad request - Input exceeds maximum size"
  }
  

• 존재하지 않는 프로젝트:

  {
    "error": "400 Bad request - Error: Project does not exist or you do not have access to it"
  }
  

• 존재하지 않는 그룹:

  {
    "error": "400 Bad request - Error: Group does not exist or you do not have access to it"
  }
  

• 속도 제한 초과:

  {
    "error": "Query temporarily blocked due to repeated timeouts. Please try again later or narrow your search scope."
  }
  

• 잘못된 필드

  {
    "error": "Field 'title' doesn't exist on type 'WorkItem' (Did you mean `title`?)"
  }
  

제한과 제약 사항#

GLQL API에는 다음 제한이 있습니다.

• 최대 입력 크기: glql_yaml 파라미터에 대해 10,000바이트(10KB).
• 최대 쿼리 제한: 요청당 100건.
• 기본 제한: 지정하지 않으면 100건.
• 페이지네이션: 이전 응답의 endCursor 값을 after 속성에 사용하는 정방향 페이지네이션만 지원합니다.
• 속도 제한: 쿼리는 쿼리 SHA-256 해시를 기준으로 속도가 제한됩니다.

관련 주제#

• GLQL 쿼리 언어 문서
• REST API 인증
• OAuth 2.0 인증