히스토리

• GitLab 18.7에서 도입됨.

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

사전 요건:

• 그룹 또는 프로젝트가 해당 데이터에 대한 접근을 허용해야 합니다.

• 비공개 그룹 및 프로젝트의 경우 적절한 권한이 있는 개인 액세스 토큰을 사용해야 합니다.

GLQL 쿼리 실행#

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

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
}

예시: 프론트 매터 구성이 있는 쿼리#

사용자 정의 필드와 정렬로 검색:

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에서 도입되었습니다.

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.34.0"
}

분석 모드는 디멘션과 메트릭이 허용하는 인수를 나열하므로, 쿼리에서 기본값에 의존하는 대신 인수를 명시적으로 설정할 수 있습니다:

"parameterized_fields": [
  {
    "name": "finished",
    "parameters": [
      { "name": "granularity", "kind": "Enum", "values": ["daily", "weekly", "monthly"], "default": "weekly" }
    ]
  },
  {
    "name": "durationQuantile",
    "parameters": [{ "name": "quantile", "kind": "Number", "min": 0.01, "max": 0.99, "default": 0.95 }]
  }
]

속도 제한#

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바이트(10 KB).

• 최대 쿼리 제한: 요청당 100개 결과.

• 기본 제한: 지정하지 않은 경우 100개 결과.

• 페이지네이션: 이전 응답의 endCursor 값과 함께 after 속성을 사용하는 앞 방향 페이지네이션만 지원됩니다.

• 속도 제한: 쿼리는 쿼리 SHA-256 해시를 기반으로 속도 제한됩니다.

관련 항목#

• GLQL 쿼리 언어 문서

• REST API 인증

• OAuth 2.0 인증