Data Query Open API

Data Query Open API 사용 방법은 다음과 같습니다.

API 엔드포인트

API 요청을 위한 Data Query API 엔드포인트 URL은 다음과 같습니다.

Data Query 엔드포인트 URL 형식

https://data-query.kr-central-2.kakaocloud.com

쿼리 실행

쿼리 실행을 요청합니다.

안내

일부 쿼리문은 실행 결과로 반환되는 데이터가 없기 때문에 쿼리 결과가 파일로 저장되지 않을 수 있습니다.
ex) CREATE TABLE, CREATE SCHEMA, DROP TABLE, DROP SCHEMA, SHOW SCHEMAS, SHOW TABLES 등

쿼리 실행 API 호출 방식

curl -X POST 'https://data-query.kr-central-2.kakaocloud.com/v1/data-query/query' \
    --header 'Credential-ID: {credential-id}' \
    --header 'Credential-Secret: {credential-secret}' \
    --header 'Content-Type: application/json' \
    --header 'X-Data-Source: {데이터 원본 이름}' \
    --header 'X-Database: {데이터베이스 이름}'
    --data-raw '{request body}'

Request

Request Header

Request	필수 여부	설명
Content-Type	필수	application/json
Credential-ID	필수	액세스 키 ID
Credential-Secret	필수	보안 액세스 키
X-Data-Source	선택	쿼리에 기본으로 적용할 데이터 원본 이름
X-Database	선택	쿼리에 기본으로 적용할 데이터베이스 이름

Request Body

Request Body

{
  "query": "string",
  "bucketName": "string",
  "path": "string"
}

Request Elements

필드	필수 여부	설명
query	필수	SQL로 작성한 쿼리문 ㄴ x-data-source, x-database 헤더에 명시한 데이터소스와 데이터베이스가 기본적인 테이블의 위치로 적용됩니다. ㄴ x-data-source, x-database 헤더 없이 쿼리를 실행할 경우, 쿼리의 테이블명 앞에 데이터소스와 데이터베이스를 마침표(.)로 연결하여 명시해야 합니다. ㄴ x-data-source, x-database 헤더 없이 쿼리문의 테이블명 앞에 데이터 소스와 데이터베이스를 명시하지 않으면 오류가 발생할 수 있습니다. * SQL 사용에 대한 자세한 내용은 SQL Reference를 참고해 주세요.
bucketName	필수	쿼리 결과를 저장할 Object Storage 버킷 이름
path	필수	쿼리 결과를 저장할 하위 상세 경로 - 지정한 path의 하위에 쿼리를 실행한 일자(YYYY/MM/DD)가 자동으로 생성되며, 일자 경로 하위에 쿼리 실행 결과 파일이 저장됩니다. - 결과 파일은 쿼리 결과 파일(.csv)과 메타데이터 파일(.metadata)로 두 가지 형식으로 저장됩니다. - 자세한 설명은 쿼리 결과 데이터를 참고해 주세요.

Example

Request Example

쿼리 실행 호출 예시

curl -X 'POST'
    'https://https://data-query.kr-central-2.kakaocloud.com/v1/data-query/query' \
    --header 'Credential-ID: {credential-id}' \
    --header 'Credential-Secret: {credential-secret}' \
    --header 'Content-Type: application/json' \
    --header 'x-data-source: test_datasource' \
    --header 'x-database: test_database' \
    --data-raw '{
      "query": "select * from nation, test_datasource.test_database.region limit 100",
      "bucketName": "test-bucket",
      "path": "data_query/result"
    }'

• 데이터 원본과 데이터베이스를 지정하지 않은 nation 테이블은 헤더에 입력한 test_datasource와 test_database가 자동으로 nation 테이블의 위치로 지정됩니다.
• region 테이블은 데이터 원본과 데이터베이스를 지정했으므로 헤더보다 우선합니다.
• 결과적으로 select * from test_datasource.test_database.nation, test_datasource.test_database2.region limit 100 과 동일한 쿼리가 실행됩니다.
• 쿼리 실행 결과는 test-bucket 버킷 하위의 data_query/result/2024/11/26 하위에 .csv, .metadata 두 개의 파일로 저장됩니다.

Response

쿼리 실행 응답 예시

{
  "queryId": "data-query-20241126-011848-HcejcLZBHz",
  "state": "QUEUED",
  "storageUrl": "data_query/result/2024/11/26"
}

Response Elements

필드	설명
queryId	쿼리 ID
state	쿼리 상태
storageUrl	쿼리 결과가 저장되는 Object Storage 전체 경로

응답 코드

필드	설명
200	성공
400	잘못된 요청
401	Credential 인증 실패
403	권한 없음
404	버킷을 찾을 수 없음
499	서비스 에이전트가 해당 버킷에 필요한 권한이 없음

쿼리 결과 조회

• 쿼리 결과 및 상세 정보를 조회합니다.
• 쿼리의 상태와 기본적인 통계, 쿼리 결과의 일부를 페이지 형태로 확인할 수 있습니다.

안내

쿼리 결과는 페이지 당 100행을 기준으로 최대 1000행(0~9 페이지)까지 제공됩니다.

쿼리 결과 조회 API 호출 방식

curl -X GET 'https://data-query.kr-central-2.kakaocloud.com/v1/data-query/query/{query-id}?page={page-number}' \
    --header 'Credential-ID: {credential-id}' \
    --header 'Credential-Secret: {credential-secret}'

Request

Request Header

Request	필수 여부	설명
Credential-ID	필수	액세스 키 ID
Credential-Secret	필수	보안 액세스 키

Query Params

Request	필수 여부	설명
page	선택	조회할 쿼리 결과의 페이지 번호를 입력

Example

Request Example

쿼리 결과 조회 호출 예시

curl -X GET 'https://data-query.kr-central-2.kakaocloud.com/v1/data-query/query/20241126-011848-HcejcLZBHz?page=0' \
    --header 'Credential-ID: {credential-id}' \
    --header 'Credential-Secret: {credential-secret}'

• 쿼리 아이디 20241126-011848-HcejcLZBHz의 쿼리 결과를 조회합니다.
• 쿼리 결과가 존재하는 경우 0페이지의 100행을 조회합니다.

Response

쿼리 결과 조회 응답 예시

{
  "queryInfo": {
    "queryId": "20241126-011848-HcejcLZBHz",
    "state": "FINISHED",
    "queryStats": {
      "progressPercentage": 100,
      "inputDataPositions": 5467,
      "inputDataSize": "867KB",
      "outputPositions": 5,
      "outputDataSize": "1014B",
      "createdAt": 1726140663000,
      "completedAt": 1726140663000,
      "queryExecutionTime": "284ms",
      "elapsedTime": "345ms",
      "queuedTime": "18ms",
      "planningTime": "17ms"
    },
    "queryTextPreview": "select * from nation, test_datasource.test_database2.region limit 100",
    "storageUrl": "data_query/result/2024/11/26",
    "storeType": "BASIC",
    "isStored": true
  },
  "columnData": [
    {
      "name": "custkey",
      "index": 1,
      "type": "bigint"
    },
    {
      "name": "name",
      "index": 2,
      "type": "varchar"
    },
    {
      "name": "address",
      "index": 3,
      "type": "varchar"
    }
  ],
  "queryData": [
    [
      "622064",
      "Customer#000622064",
      "NcIPVzgQ9Cn b178vS47OQa7fvXMKzDO, owXcL"
    ],
    [
      "622065",
      "Customer#000622065",
      "JNVqKJDq56ehUlTxwmNYA"
    ],
    [
      "622066",
      "Customer#000622066",
      "TgRjkw88fDtnIws PBEhSVOh5L5yp8Tag7Eb9n"
    ]
  ],
  "totalPages": 1,
  "totalElements": 3,
  "number": 0,
  "size": 100,
  "numberOfElements": 3
}

Response Elements

필드	설명
queryInfo ▼	조회한 쿼리 정보
queryId	쿼리 ID
state	쿼리 상태
queryTextPreview	요청한 쿼리 미리보기 - 300자까지 표시
storageUrl	쿼리 결과가 저장되는 Object Storage 전체 경로
storeType	쿼리 결과 타입 - BASIC: 쿼리 결과가 일반적인 테이블 형태 - TEXT: 쿼리 결과가 텍스트 형태
isStored	쿼리 결과가 Object Storage에 저장되었는지 여부
columnData	쿼리 결과의 칼럼 메타 데이터
queryData	쿼리 결과 리스트
queryStats ▼	조회한 쿼리 정보
progressPercentage	쿼리 진행률
inputDataPositions	입력 데이터 수
inputDataSize	입력 데이터 크기
outputPositions	출력 데이터 수
outputDataSize	출력 데이터 크기
createdAt	쿼리 요청 시각
completedAt	쿼리 결과 저장이 완료된 시각
queryExecutionTime	쿼리 실행 시간
elapsedTime	쿼리 종료 시간
queuedTime	쿼리 실행 전 대기한 시간
planningTime	쿼리 계획에 걸린 시간
totalPages	총 페이지 수
totalElements	총 데이터 개수
size	현재 페이지 크기
number	현재 페이지 번호
numberOfElements	페이지 내의 쿼리 결과 행 수

응답 코드

필드	설명
200	성공
400	잘못된 요청
401	Credential 인증 실패
403	권한 없음
404	존재하지 않는 쿼리 ID

쿼리 목록 조회

• 실행한 쿼리 목록을 조회합니다.
• 실행한 쿼리에 대한 요약 정보를 확인할 수 있습니다.

쿼리 목록 조회 API 호출 방식

curl -X GET 'https://data-query.kr-central-2.kakaocloud.com/v1/data-query/query' \
    --header 'Credential-ID: {credential-id}' \
    --header 'Credential-Secret: {credential-secret}'

Request

Request Header

Request	필수 여부	설명
Credential-ID	필수	액세스 키 ID
Credential-Secret	필수	보안 액세스 키

Query Params

Request	설명
queryId	검색할 쿼리 ID
creatorName	쿼리를 실행한 사용자를 입력 - 특정 사용자가 실행한 쿼리만 필터
states	쿼리의 상태로 조회 - 입력 가능한 쿼리 상태 : QUEUED, RUNNING, FINISHED, ABORTED, FAILED (쿼리 상태 상세 보기)
page	페이지 번호
size	페이지 사이즈
sort	정렬에 사용할 필드 - 입력 가능한 필드 : queryId, queryTextPreview, state, createdAt, elapsedTime, inputDataSize, creatorName, storageUrl

Example

Request Example

쿼리 목록 조회 호출 예시

curl -X GET 'https://data-query.kr-central-2.kakaocloud.com/v1/data-query/query?page=0&size=3&sort=elapsedTime,desc&states=FAILED&states=FINISHED' \
    --header 'Credential-ID: {credential-id}' \
    --header 'Credential-Secret: {credential-secret}'

• page(페이지 번호) : 0, size(페이지 사이즈) : 3
• elapsedTime 기준으로 내림차순 정렬
• 쿼리 상태가 FAILED 이거나 FINISHED 인 쿼리정보만 필터

Response

쿼리 목록 조회 응답 예시

{
  "content": [
    {
      "queryId": "20241119-115211-0CQzr5LrKo",
      "queryTextPreview": "select * from orders",
      "state": "FINISHED",
      "createdAt": 1731984732000,
      "elapsedTime": "1.47m",
      "inputDataSize": "1.62GB",
      "creatorName": "testor1@kakaoenterprise.com",
      "storageUrl": "testor1-bucket/data_query/result/2024/11/19",
      "errorMessage": null
    },
    {
      "queryId": "20241104-054632-lkO34lXzJR",
      "queryTextPreview": "SELECT\n ...",
      "state": "FINISHED",
      "createdAt": 1730699192000,
      "elapsedTime": "10.23s",
      "inputDataSize": "318.24MB",
      "creatorName": "testor1@kakaoenterprise.com",
      "storageUrl": "testor1-bucket/data_query/result/2024/11/04",
      "errorMessage": null
    },
    {
      "queryId": "20241104-071200-TkMfjvIieD",
      "queryTextPreview": "SELECT ... A ...",
      "state": "FINISHED",
      "createdAt": 1730704320000,
      "elapsedTime": "5.89s",
      "inputDataSize": "318.24MB",
      "creatorName": "testor2@kakaoenterprise.com",
      "storageUrl": "testor2-bucket/result/2024/11/04",
      "errorMessage": null
    }
  ],
  "pageable": {
    "pageNumber": 0,
    "pageSize": 3,
    "sort": {
      "sorted": true,
      "unsorted": false,
      "empty": false
    },
    "offset": 0,
    "paged": true,
    "unpaged": false
  },
  "totalElements": 59,
  "totalPages": 20,
  "last": false,
  "numberOfElements": 3,
  "first": true,
  "size": 3,
  "number": 0,
  "sort": {
    "sorted": true,
    "unsorted": false,
    "empty": false
  },
  "empty": false
}

Response Elements

필드	설명
content ▼	조회한 쿼리 목록
queryId	쿼리 ID
queryTextPreview	쿼리문의 300자까지 미리볼 수 있는 필드
state	쿼리 상태 (쿼리 상태 상세 보기)
createdAt	쿼리 요청 시각
elapsedTime	쿼리 종료 시간
inputDataSize	입력 데이터 크기
creatorName	쿼리를 실행한 사용자
storageUrl	쿼리 결과가 저장되는 오브젝트 스토리지 전체 경로
errorMessage	쿼리가 실패했을 경우 에러 메시지
pageable ▼	페이징 관련 정보
pageNumber	현재 페이지 번호
pageSize	현재 페이지 크기
sort ▼	정렬 정보
sorted	정렬이 적용되었는지 여부
unsorted	정렬이 적용되지 않았는지 여부
empty	정렬 조건이 비어있는지 여부
offset	페이지의 시작 지점
paged	페이징 적용 여부
unpaged	페이징이 적용되지 않았는지 여부
totalPages	총 페이지 수
totalElements	총 데이터 개수
last	현재 페이지가 마지막 페이지인지 여부
size	현재 페이지 크기
first	현재 페이지가 첫 페이지인지 여부
number	현재 페이지 번호
empty	현재 페이지가 비어있는지 여부

응답 코드

필드	설명
200	성공
400	잘못된 요청
401	Credential 인증 실패
403	권한 없음
404	존재하지 않는 쿼리 아이디

쿼리 중단

• 쿼리 실행을 중단합니다.
• 쿼리 상태가 FINISHED, FAILED, ABORTED 일 때는 동작하지 않습니다.

쿼리 중단 API 호출 방식

curl -X PUT 'https://data-query.kr-central-2.kakaocloud.com/v1/data-query/query/{query-id}/abort' \
    --header 'Credential-ID: {credential-id}' \
    --header 'Credential-Secret: {credential-secret}'

Request

Request Header

Request	필수 여부	설명
Credential-ID	필수	액세스 키 ID
Credential-Secret	필수	보안 액세스 키

Query Params

Request	설명
queryId	중단할 쿼리 ID

Example

Request Example

쿼리 중단 호출 예시

curl -X PUT 'https://data-query.kr-central-2.kakaocloud.com/v1/data-query/query/20241104-071200-TkMfjvIieD' \
    --header 'Credential-ID: {credential-id}' \
    --header 'Credential-Secret: {credential-secret}'

• 쿼리 아이디가 20241104-071200-TkMfjvIieD인 쿼리 실행을 중단

Response

응답 코드

필드	설명
200	성공
400	잘못된 요청
401	Credential 인증 실패
403	권한 없음
409	이미 종료된 쿼리

데이터 원본 목록 조회

• Data Query와 연결된 데이터 원본의 목록을 조회합니다.

데이터 원본 목록 조회 API 호출 방식

curl -X GET 'https://data-query.kr-central-2.kakaocloud.com/v1/data-query/data-source' \
    --header 'Credential-ID: {credential-id}' \
    --header 'Credential-Secret: {credential-secret}'

Request

Request Header

Request	필수 여부	설명
Credential-ID	필수	액세스 키 ID
Credential-Secret	필수	보안 액세스 키

Example

Request Example

데이터 원본 목록 조회 호출 예시

curl -X GET 'https://data-query.kr-central-2.kakaocloud.com/v1/data-query/data-source' \
    --header 'Credential-ID: {credential-id}' \
    --header 'Credential-Secret: {credential-secret}'

Response

데이터 원본 목록 조회 응답 예시

[
  {
    "name": "data_catalog",
    "dataSourceType": "DATA_CATALOG"
  },
  {
    "name": "test_catalog",
    "dataSourceType": "DATA_CATALOG"
  },
  {
    "name": "testor1_mysql",
    "dataSourceType": "MYSQL"
  },
  {
    "name": "testor2_mysql",
    "description": "mysql test",
    "dataSourceType": "MYSQL"
  }
]

Response Elements

필드	설명
name	조회한 쿼리 정보
dataSourceType	데이터 소스의 타입 - DATA_CATALOG, MYSQL
description	데이터 원본의 설명

응답 코드

필드	설명
200	성공
400	잘못된 요청
401	Credential 인증 실패
403	권한 없음

MySQL 데이터 원본 생성

• MySQL 유형의 데이터 원본을 생성합니다.

안내

DATA_CATALOG 유형의 데이터 원본은 Data Catalog 서비스에서 카탈로그 생성 시 자동으로 생성됩니다.

MySQL 유형 데이터 원본 생성 API 호출 방식

curl -X POST 'https://data-query.kr-central-2.kakaocloud.com/v1/data-query/data-source' \
    --header 'Credential-ID: {credential-id}' \
    --header 'Credential-Secret: {credential-secret}'
    --data-raw '{request body}'

Request

Request Header

Request	필수 여부	설명
Credential-ID	필수	액세스 키 ID
Credential-Secret	필수	보안 액세스 키

Request Body

Request Body

{
  "dataSourceType": "MYSQL",
  "dataSourceName": "string",
  "description": "string",
  "instanceId": "string",
  "mysqlUser": "string",
  "mysqlPassword": "<base64 encoded string>"
}

Request Elements

필드	필수 여부	설명
dataSourceType	필수	데이터 원본의 유형
dataSourceName	필수	데이터 원본의 이름 - 영문 소문자, 언더바(_), 숫자만 허용, 3~72자 제한
description	선택	데이터 원본의 설명
instanceId	필수	연결할 카카오클라우드 MySQL 인스턴스 아이디
mysqlUser	필수	MySQL 계정 아이디
mysqlPassword	필수	MySQL 계정 비밀번호 ⚠️ base64로 인코딩된 문자열로 입력

Example

Request Example

쿼리 목록 조회 호출 예시

curl -X GET 'https://data-query.kr-central-2.kakaocloud.com/v1/data-query/data-source' \
    --header 'Credential-ID: {credential-id}' \
    --header 'Credential-Secret: {credential-secret}'
    --data-raw '{
          "dataSourceType": "MYSQL",
          "dataSourceName": "test_mysql",
          "description": "test mysql",
          "instanceId": "fbc16e9a-6352-11ef-952c-0a27e22384db",
          "mysqlUser": "admin",
          "mysqlPassword": "YWRtaW4K"
        }'

• mysqlPassword는 문자열 admin을 base64로 변환한 YWRtaW4K를 입력

응답 코드

필드	설명
200	성공
400	잘못된 요청
401	Credential 인증 실패
403	권한 없음
409	데이터 원본 이름 중복