GQL 쿼리 API 참조

RESTful HTTP API를 사용하여 Microsoft Fabric의 그래프에서 속성 그래프에 대해 GQL 쿼리를 실행합니다. 이 참조에서는 요청 및 응답 형식, 인증, JSON 결과 인코딩 및 오류 처리와 같은 HTTP 계약에 대해 설명합니다.

중요합니다

이 글은 오직 소셜 네트워크 예시 그래프 데이터셋만을 사용합니다.

개요

GQL 쿼리 API는 GQL 쿼리를 JSON 페이로드로 받아들이고 구조적이고 타입이 맞는 결과를 반환하는 REST 엔드포인트를 제공합니다. 초기 요청 중에 완료되지 않은 쿼리에 대한 연속 폴링을 지원합니다.

주요 기능

단일 엔드포인트 - 모든 작업은 하나의 URL에 HTTP POST를 사용합니다.
JSON 기반 - 요청 및 응답 페이로드는 형식화된 GQL 값의 풍부한 인코딩과 함께 JSON을 사용합니다.
연속 폴링 - 장기 실행 쿼리는 여러 HTTP 요청을 넘어 계속될 수 있습니다.
형식 안전 - 값 표현을 위해 구분된 공용 구조체를 사용하는 강력한 GQL 호환 형식입니다.

필수 조건

노드 및 에지(관계)를 비롯한 데이터가 포함된 그래프가 필요합니다. 샘플 그래프를 만들고 로드하려면 그래프 빠른 시작을 참조하세요.
실행 결과 및 결과의 구조를 포함하여 속성 그래프 및 GQL에 대한 기본적인 이해를 잘 알고 있어야 합니다.
조직에 로그인하려면 Azure CLI 도구 az 설치하고 설정해야 합니다. 이 문서의 명령줄 예제에서는 bash와 같은 POSIX 호환 명령줄 셸을 사용하는 것으로 가정합니다.

Authentication

GQL 쿼리 API에는 전달자 토큰을 통한 인증이 필요합니다.

모든 요청의 권한 부여 헤더에 액세스 토큰을 포함합니다.

Authorization: Bearer <your-access-token>

일반적으로 MSAL(Microsoft 인증 라이브러리) 또는 Microsoft Entra 호환되는 기타 인증 흐름을 사용하여 전달자 토큰을 가져올 수 있습니다.

전달자 토큰은 일반적으로 다음 두 가지 주요 경로를 통해 가져옵니다.

사용자가 위임한 액세스

Azure CLI 도구 az 통해 명령줄에서 사용자 위임 서비스 호출에 대한 전달자 토큰을 가져올 수 있습니다.

다음을 통해 명령줄에서 사용자 위임 호출에 대한 전달자 토큰을 가져옵니다.

az login을 실행합니다.
그러면 az account get-access-token --resource https://api.fabric.microsoft.com

Azure CLI 도구 az 사용합니다.

요청을 수행하는 데 사용하면 az rest 전달자 토큰이 자동으로 획득됩니다.

애플리케이션 액세스

Microsoft Entra 등록된 애플리케이션에 대한 전달자 토큰을 가져올 수 있습니다. 자세한 내용은 Fabric API 빠른 시작을 참조하세요.

API 엔드포인트

API는 모든 쿼리 작업을 허용하는 단일 엔드포인트를 사용합니다.

POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/graphModels/{graphModelId}/executeQuery?beta=true

쿼리 API는 베타 버전이며 운영 환경에는 권장되지 않습니다. 필요한 beta 쿼리 매개변수를 로 true설정하세요. 이전 preview=true 매개변수는 하위 호환성을 위해 여전히 지원되지만, 새로운 통합에 사용됩니다 beta=true .

작업 영역에 대한 항목을 가져오 {workspaceId} 려면 다음을 사용하여 az rest사용 가능한 모든 작업 영역을 나열할 수 있습니다.

az rest --method get --resource "https://api.fabric.microsoft.com" --url "https://api.fabric.microsoft.com/v1/workspaces"

이를 가져오려면 다음을 {graphModelId}사용하여 az rest작업 영역에서 사용 가능한 모든 그래프를 나열할 수 있습니다.

az rest --method get --resource "https://api.fabric.microsoft.com" --url "https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/graphModels"

Azure CLI 출력 옵션을 사용해 이 리스트 요청의 응답을 필터링하거나 포맷할 수 있습니다. 이 옵션들은 Azure CLI 클라이언트에서 실행되며, 쿼리 API 매개변수는 아닙니다:

--query "value[?displayName=='My Workspace']" 는 a displayName 가 있는 My Workspace항목만 나열한다.
--query "value[?starts_with(displayName, 'My')]"로 시작하는 My항목 displayName 만 나열합니다.
--query "{query}" 제공된 JMESPath {query}에 맞는 항목만 나열합니다. 지원되는 구문에 대해서는 Query Azure CLI 명령 결과를 참조하세요.
-o table 테이블 결과를 생성하기 위한 것입니다.

비고

명령줄 셸에서 API 엔드포인트를 통해 쿼리를 실행하는 방법은 az-rest 사용 섹션 또는 curl 사용에 대한 섹션 을 참조하세요.

쿼리 매개 변수

매개 변수	유형	필수	Description
`beta`	불리언	Yes	베타 쿼리 API를 사용하도록 설정 `true` 하세요.
`continuationToken`	문자열	No	쿼리가 실행 중일 때 토큰 `result.nextPage` 을 사용합니다. 토큰을 사용할 때도 동일한 쿼리 텍스트를 제출하세요.

요청 헤더

Header	가치	필수
`Content-Type`	`application/json`	Yes
`Accept`	`application/json`	Yes
`Authorization`	`Bearer <token>`	Yes

요청 형식

모든 요청은 JSON 페이로드와 함께 HTTP POST를 사용합니다.

기본 요청 구조

{
  "query": "MATCH (n) RETURN n LIMIT 100"
}

요청 필드

분야	유형	필수	Description
`query`	문자열	Yes	실행할 GQL 쿼리

응답 형식

성공적인 요청에 대한 모든 응답은 실행 상태 및 결과를 포함하는 JSON 페이로드와 함께 HTTP 200 상태를 사용합니다.

응답 구조

{
  "status": {
    "code": "00000",
    "description": "note: successful completion",
    "diagnostics": {
      "OPERATION": "query",
      "OPERATION_CODE": "0",
      "CURRENT_SCHEMA": "/",
      "_graphaneGqlStatus": {
        "gqlType": "STRING",
        "value": "00000"
      }
    }
  },
  "result": {
    "kind": "TABLE",
    "columns": [...],
    "data": [...]
  }
}

Status 개체

모든 응답에는 실행 정보가 포함된 상태 개체가 포함됩니다.

분야	유형	Description
`code`	문자열	5자리 공개 API 상태 코드.
`description`	문자열	사람이 읽을 수 있는 상태 설명.
`diagnostics`	객체	상세한 진단 기록, 가능할 경우 정식 쿼리 엔진 GQLSTATUS를 포함합니다.
`cause`	객체	선택 가능한 근본 원인 상태 객체.

상태 코드

주요 status.code API는 다음과 같은 공개 API 카테고리를 사용합니다:

00000 - 최소 한 행 이상 성공적으로 완료.
00001 - 결과가 생략된 성공적인 완료. 향후 DDL 및 DML 지원을 위해 예약되어 있습니다.
01000 - 경고 또는 정보 상태.
02000 - 현재 행 생성 쿼리에서 사용할 수 있는 행이 없습니다.
42000 - 구문, 접근 규칙 또는 기타 사용자가 수정 가능한 쿼리 오류.
50000 - 시스템 또는 비분류 오류.

자세한 내용은 GQL 상태 코드 참조를 참조하세요.

진단 레코드

진단 레코드에는 상태 개체를 자세히 설명하는 다른 키-값 쌍이 포함될 수 있습니다. 밑줄(_)로 시작하는 키는 그래프와 관련이 있습니다. GQL 표준은 다른 모든 키를 규정합니다.

비고

진단에는 _graphaneGqlStatus 쿼리 엔진이 보고하는 정형적인 5자 GQLSTATUS가 포함되어 있습니다. 밑줄이 붙은 모든 진단 멤버는 JSON으로 인코딩된 GQL 값 중 하나 null 또는 하나를 포함합니다. 예를 들어, 는 _graphaneGqlStatus 를 사용 STRING하고, 오류 분류 진단은 를 사용합니다 BOOL. 값 형식 및 인코딩을 참조하세요.

원인

기본 원인을 알 수 있는 경우 상태 개체에는 선택적 cause 필드가 포함됩니다.

기타 상태 개체

일부 결과는 선택적 additionalStatuses 필드에 다른 상태 객체를 리스트로 보고할 수 있습니다.

1차 상태는 기록된 상태에서 가장 심각한 상태입니다. 각 추가 상태와 중첩된 원인마다 자체 공개 API 코드와 정식 GQLSTATUS 진단이 있습니다.

결과 형식

결과는 필드와 함께 구분된 공용 구조체 패턴을 kind 사용합니다.

테이블 결과

테이블 형식 데이터를 반환하는 쿼리의 경우:

{
  "kind": "TABLE",
  "columns": [
    {
      "name": "name",
      "gqlType": "STRING",
      "jsonType": "string"
    },
    {
      "name": "age",
      "gqlType": "INT64",
      "jsonType": "number|string"
    }
  ],
  "isOrdered": false,
  "isDistinct": false,
  "data": [
    {
      "name": "Alice",
      "age": 30
    },
    {
      "name": "Bob",
      "age": 25
    }
  ]
}

장기 실행 쿼리

현재 HTTP 요청 중에 쿼리가 완료되지 않으면, API는 HTTP 200에 공개 상태 코드 02000, 빈 테이블, nextPage 그리고 토큰을 반환합니다:

{
  "status": {
    "code": "02000",
    "description": "No data available, retry with continuation token"
  },
  "result": {
    "kind": "TABLE",
    "columns": [],
    "data": [],
    "nextPage": "{continuationToken}"
  }
}

동일한 요청 본문을 보내고 URL에 토큰을 추가하여 완성을 위해 폴링합니다:

POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/graphModels/{graphModelId}/executeQuery?beta=true&continuationToken={continuationToken}

불투명한 값으로 간주하세요 nextPage . RFC 3986에 따라 쿼리 매개변수 값으로 continuationToken 사용하기 전에 정확히 한 번만 퍼센트 인코딩하세요. 토큰을 디코딩하거나 검사하거나 수정하지 마세요.

응답이 더 이상 를 포함하지 nextPage않을 때까지 계속합니다. 쿼리 실행은 초기 요청부터 최대 20분까지 계속될 수 있습니다. 전체 시간을 초과하면 API는 HTTP 408과 오류 코드 QueryTimeout를 반환합니다.

단축 결과

그래프는 내부 이진 표현이 64MB를 초과할 때 쿼리 응답을 잘라냅니다. API는 맞는 행을 반환하고 상태( additionalStatusesstatus)를 추가합니다. 추가 상태는 공공 코드를 01000 사용하며 정통 GQLSTATUS 01M11 를 _graphaneGqlStatus유지합니다.

절단은 누락된 행에 대한 토큰을 생성 nextPage 하지 않습니다. 필터, 특정 투영법, 또는 LIMIT로 쿼리를 좁힌 후 다시 실행하세요.

생략된 결과

응답 스키마는 데이터나 평가 결과와 독립적으로 행을 생성하지 않는 연산을 나타낼 수 있습니다. 이 결과는 상태 코드를 00001사용합니다:

{
  "kind": "NOTHING"
}

이 생략된 결과는 행이 없는 테이블과 다릅니다. 빈 테이블은 현재 반환할 행이 없는 행을 생성하는 쿼리를 평가한 결과입니다.

그래프는 이 결과 형태와 상태 코드를 향후 데이터 정의 언어(DDL) 및 데이터 조작 언어(DML) 문장 지원을 위해 보존합니다. 현재 쿼리 문은 항상 테이블 결과를 반환합니다.

값 형식 및 인코딩

API는 풍부한 형식 시스템을 사용하여 GQL 값을 정확한 의미 체계로 나타냅니다. GQL 값의 JSON 형식은 구분된 공용 구조체 패턴을 따릅니다.

비고

테이블 형식 결과의 JSON 형식은 구분 gqlType 하여 구분된 공용 구조체 패턴을 실현하고 value 보다 간결한 표현을 달성합니다. 테이블 serialization 최적화를 참조하세요.

값 구조

{
  "gqlType": "TYPE_NAME",
  "value": <type-specific-value>
}

기본 형식

GQL 형식	Example	Description
`BOOL`	`{"gqlType": "BOOL", "value": true}`	네이티브 JSON 부울
`STRING`	`{"gqlType": "STRING", "value": "Hello"}`	UTF-8 문자열

숫자 유형

정수 형식

GQL 형식	범위	JSON 직렬화	Example
`INT64`	-2개~ 2개-1	숫자 또는 문자열*	`{"gqlType": "INT64", "value": -9237}`
`UINT64`	0~2-1	숫자 또는 문자열*	`{"gqlType": "UINT64", "value": 18467}`

JavaScript의 안전 범위(-9,007,199,254,740,991에서 9,007,199,254,740,991)를 벗어난 큰 정수는 문자열로 직렬화됩니다.

{"gqlType": "INT64", "value": "9223372036854775807"}
{"gqlType": "UINT64", "value": "18446744073709551615"}

부동 소수점 형식

GQL 형식	범위	JSON 직렬화	Example
`FLOAT64`	IEEE 754 바이너리 64	JSON 번호 또는 문자열	`{"gqlType": "FLOAT64", "value": 3.14}`

부동 소수점 값은 IEEE 754 특수 값을 지원합니다.

{"gqlType": "FLOAT64", "value": "Inf"}
{"gqlType": "FLOAT64", "value": "-Inf"}
{"gqlType": "FLOAT64", "value": "NaN"}
{"gqlType": "FLOAT64", "value": "-0"}

임시 형식

지원되는 임시 형식은 ISO 8601 문자열 형식을 사용합니다.

GQL 형식	포맷	Example
`ZONED DATETIME`	YYYY-MM-DDTHH:MM:SS[.ffffff]±HH:MM	`{"gqlType": "ZONED DATETIME", "value": "2023-12-25T14:30:00+02:00"}`

Graph 요소 참조 형식

GQL 형식	Description	Example
`NODE`	그래프 노드 참조	`{"gqlType": "NODE", "value": "node-123"}`
`EDGE`	그래프 에지 참조	`{"gqlType": "EDGE", "value": "edge_abc#def"}`

복합 형식

복합 형식은 다른 GQL 값으로 구성됩니다.

Lists

목록에는 일관된 요소 형식의 nullable 값 배열이 포함되어 있습니다.

{
  "gqlType": "LIST<INT64>",
  "value": [1, 2, null, 4, 5]
}

특수 목록 유형:

LIST<ANY> - 혼합 형식(각 요소에 전체 형식 정보 포함)
LIST<NULL> - null 값만 허용됨
LIST<NOTHING> - 항상 빈 배열

Paths

경로는 그래프 요소 참조 값의 목록으로 인코딩됩니다.

{
    "gqlType": "PATH",
    "value": ["node1", "edge1", "node2"]
}

테이블 serialization 최적화를 참조하세요.

테이블 serialization 최적화

테이블 결과의 경우 값 serialization은 열 형식 정보에 따라 최적화됩니다.

알려진 형식 - 원시 값만 직렬화됩니다.
ANY 열 - 형식 판별자가 있는 전체 값 개체

{
  "kind": "TABLE",
  "columns": [
    {"name": "name", "gqlType": "STRING", "jsonType": "string"},
    {"name": "amount", "gqlType": "INT64", "jsonType": "number|string"},
    {"name": "mixed", "gqlType": "ANY", "jsonType": "object"}
  ],
  "data": [
    {
      "name": "Alice",
      "amount": "123",
      "mixed": {"gqlType": "INT64", "value": "1"}
    }
  ]
}

오류 처리

전송 오류

HTTP 상태와 GQL 상태는 응답의 서로 다른 계층을 설명합니다:

HTTP 상태	Meaning
200	API가 요청을 처리했습니다. 검사 `status.code` 대상은 성공, 행 없음, 진행 중인 쿼리, 또는 사용자가 수정 가능한 쿼리 오류를 나타낼 수 있습니다.
408	쿼리 실행은 총 20분 타임아웃을 초과했습니다. 오류 코드는 .입니다 `QueryTimeout`.
429	서비스 속도 제한을 초과했습니다. 헤더에 표시된 `Retry-After` 지속 시간을 기다린 후 다시 시도하세요.
499	전화한 사람이 요청을 취소했습니다. 오류 코드는 .입니다 `ClientCancelled`.
기타 4xx 또는 5xx	요청 또는 서비스가 실패한 후 GQL 실행 결과를 반환했습니다. HTTP 오류 응답을 점검하세요.

애플리케이션 오류

애플리케이션 수준의 오류는 상태 객체에 오류 정보를 담은 HTTP 200을 반환할 수 있습니다. 예를 들어, 0으로 나누기는 공개 API 코드를 42000 사용하며 진단 레코드에서 정식 GQLSTATUS 22012 를 유지합니다:

{
  "status": {
    "code": "42000",
    "description": "error: data exception - division by zero",
    "diagnostics": {
      "OPERATION": "query",
      "OPERATION_CODE": "0",
      "CURRENT_SCHEMA": "/",
      "_graphaneGqlStatus": {
        "gqlType": "STRING",
        "value": "22012"
      },
      "_graphaneIsUserError": {
        "gqlType": "BOOL",
        "value": true
      },
      "_graphaneIsTransientError": {
        "gqlType": "BOOL",
        "value": false
      }
    }
  }
}

상태 검사

광범위한 결과를 판단하려면 대중 status.code을 확인해 보세요. 애플리케이션이 특정 쿼리 엔진 조건, 예를 들어 숫자 오버플로우(22003)와 022012의 나눗셈()을 구분해야 할 때 사용 _graphaneGqlStatus 하세요.

az rest를 사용하는 전체 예제

명령을 사용하여 쿼리를 az rest 실행하여 다음과 같이 전달자 토큰을 수동으로 가져올 필요가 없도록 합니다.

az rest --method post --url "https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/graphModels/{graphModelId}/executeQuery?beta=true" \
--headers "Content-Type=application/json" "Accept=application/json" \
--resource "https://api.fabric.microsoft.com" \
--body '{ 
  "query": "MATCH (n:Person) WHERE n.birthday > 19800101 RETURN n.firstName, n.lastName, n.birthday ORDER BY n.birthday LIMIT 100" 
}'

curl을 사용하여 전체 예제

이 섹션의 예제에서는 셸에서 HTTPS 요청을 수행하기 위해 도구를 사용합니다 curl .

다음과 같이 셸 변수에 저장된 유효한 액세스 토큰이 있다고 가정합니다.

export ACCESS_TOKEN="your-access-token-here"

팁 (조언)

유효한 전달자 토큰을 가져오는 방법은 인증 섹션 을 참조하세요.

다음과 같이 쿼리를 실행합니다.

curl -X POST "https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/graphModels/{graphModelId}/executeQuery?beta=true" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
    "query": "MATCH (n:Person) WHERE n.birthday > 19800101 RETURN n.firstName, n.lastName, n.birthday ORDER BY n.birthday LIMIT 100" 
  }'

모범 사례

GQL 쿼리 API를 사용하는 경우 다음 모범 사례를 따릅니다.

오류 처리

항상 상태 코드 확인 - HTTP 200을 기반으로 성공을 가정하지 마세요.
오류 세부 정보 구문 분석 - 진단 및 원인 체인을 사용하여 디버깅합니다.

Security

HTTPS 사용 - 암호화되지 않은 연결을 통해 인증 토큰을 보내지 않습니다.
토큰 회전 - 적절한 토큰 새로 고침 및 만료 처리를 구현합니다.
입력 검증 - 애플리케이션이 쿼리 텍스트에 삽입하는 사용자 제공 값을 검증하고 올바르게 이스케이프합니다.

값 표현

큰 정수 값 처리 - 정수는 기본적으로 JSON 숫자로 나타낼 수 없는 경우 문자열로 인코딩됩니다.
특수 부동소수점 값 처리 - API는 양의 무한대, 음의 무한대, 아님의 숫자, 음의 0"Inf"을 , "-Inf""NaN""-0"로 직렬화합니다.
Null 값 처리 - JSON null은 GQL null을 나타냅니다.

피드백

이 페이지가 도움이 되었나요?

Last updated on 2026-09-29

GQL 쿼리 API 참조

개요

주요 기능

필수 조건

Authentication

사용자가 위임한 액세스

애플리케이션 액세스

API 엔드포인트

쿼리 매개 변수

요청 헤더

요청 형식

기본 요청 구조

요청 필드

응답 형식

응답 구조

Status 개체

상태 코드

진단 레코드

원인

기타 상태 개체

결과 형식

테이블 결과

장기 실행 쿼리

단축 결과

생략된 결과

값 형식 및 인코딩

값 구조

기본 형식

숫자 유형

정수 형식

부동 소수점 형식

임시 형식

Graph 요소 참조 형식

복합 형식

Lists

Paths

테이블 serialization 최적화

오류 처리

전송 오류

애플리케이션 오류

상태 검사

az rest를 사용하는 전체 예제

curl을 사용하여 전체 예제

모범 사례

오류 처리

Security

값 표현

관련 콘텐츠

피드백

추가 리소스