본문으로 건너뛰기

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 등

Request​

메서드URI
POST{endpoint-url}/v1/data-query/query
쿼리 실행 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 Header​
Request필수 여부설명
Credential-ID필수액세스 키 ID
Credential-Secret필수보안 액세스 키
Content-Type필수  application/json
X-Data-Source선택쿼리에 기본으로 적용할 데이터 원본 이름
X-Database선택쿼리에 기본으로 적용할 데이터베이스 이름
Request Body​
Request Body
{
  "query": "string",
  "resultConfig": {
    "bucketName": "string",
    "path": "string"
  },
  "reuseConfig": {
    "reuse": boolean,
    "maxReuseAge": integer
  }
}
Request Elements​
필드필수 여부설명
query필수  SQL로 작성한 쿼리문
ㄴ x-data-source, x-database 헤더에 명시한 데이터소스와 데이터베이스가 기본적인 테이블의 위치로 적용됩니다.
ㄴ x-data-source, x-database 헤더 없이 쿼리를 실행할 경우, 쿼리의 테이블명 앞에 데이터소스와 데이터베이스를 온점(.)으로 연결하여 명시해야 합니다.
ㄴ x-data-source, x-database 헤더 없이 쿼리문의 테이블명 앞에 데이터 소스와 데이터베이스를 명시하지 않으면 오류가 발생할 수 있습니다.
* SQL 사용에 대한 자세한 내용은 SQL Reference를 참고해 주세요.
resultConfig ▼쿼리 결과 데이터 정보
    bucketName필수쿼리 결과를 저장할 Object Storage 버킷 이름
    path필수쿼리 결과를 저장할 하위 상세 경로
- 지정한 path의 하위에 쿼리를 실행한 일자 폴더{YYYY}/{MM}/{DD}/가 자동으로 생성되며, 일자 경로 하위에 쿼리 실행 결과 파일이 저장됩니다.
- 결과 파일은 쿼리 결과 파일(.csv)과 메타데이터 파일(.metadata)로 두 가지 형식으로 저장됩니다.
- 자세한 설명은 쿼리 결과 데이터를 참고해 주세요.
reuseConfig ▼쿼리 결과 재사용 정보
    reuse선택쿼리 결과 재사용 여부
    maxReuseAge선택쿼리 결과 재사용 수명(분)
- 최소 1분부터 최대 1440(24시간)분까지 입력 가능합니다.
- reuse 를 true 로 설정한 경우 필수로 입력해야 합니다.

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​

쿼리 실행 응답 예시
{
  "queryInfo": {
    "queryId": "data-query-20240903-011848-HcejcLZBHz",
    "state": "QUEUED"
  }
}
Response Elements​
필드설명
queryId쿼리 ID
state쿼리 상태
응답 코드​
필드설명
202  성공
400잘못된 요청
401Credential 인증 실패
403권한 없음
404버킷을 찾을 수 없음
499서비스 에이전트가 해당 버킷에 필요한 권한이 없음

쿼리 결과 조회​

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

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

Request​

메서드URI
GET{endpoint-url}/v1/data-query/query/{query-id}?page={page-number}
쿼리 결과 조회 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}'
Path Params​
Path유형필수 여부설명
query-idstring필수  쿼리 ID
Query Params​
Request필수 여부설명
page-number선택    조회할 쿼리 결과의 페이지 번호를 입력
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/query/20241126-011848-HcejcLZBHz?page=0' \
    --header 'Credential-ID: {credential-id}' \
    --header 'Credential-Secret: {credential-secret}'
  • 쿼리 아이디 20241126-011848-HcejcLZBHz의 쿼리 결과를 조회합니다.
  • 쿼리 결과가 존재하는 경우 0페이지의 100행을 조회합니다.

Response​

쿼리 결과 조회 응답 예시
{
  "queryInfo": {
    "queryId": "20250327-153053-NvgfWymHmr",
    "state": "FINISHED",
    "queryStats": {
      "progressPercentage": 100,
      "inputRows": 232313,
      "inputDataSize": "25.6MB",
      "outputRows": 100,
      "outputDataSize": "12.81KB",
      "createdAt": 1743057053000,
      "completedAt": 1743057054000,
      "queryExecutionTime": "439ms",
      "elapsedTime": "668ms",
      "queuedTime": "102ms",
      "planningTime": "84ms"
    },
    "queryTextPreview": "select * from orders limit 100",
    "isScanned": true
  },
  "resultConfig": {
    "bucketName": "hailey-test",
    "path": "string/2025/03/27",
    "storageUrl": "hailey-test/string/2025/03/27",
    "storeType": "BASIC",
    "isStored": true
  },
  "reuseConfig": {
    "reuse": true,
    "expireAt": 1743057113000
  },
  "columnData": [
    {
      "name": "orderkey",
      "index": 1,
      "type": "bigint"
    },
    {
      "name": "custkey",
      "index": 2,
      "type": "bigint"
    }, ...
  ],
  "queryData": [
    [
      "20956642",
      "680917",
      "O",
      "91063.82",
      "1996-11-09",
      "3-MEDIUM",
      "Clerk#000005503",
      "0",
      "instructions sleep quickly. final ideas use slyly. carefully iron"
    ], ...
  ],
  "totalPages": 1,
  "totalElements": 100,
  "number": 0,
  "size": 100,
  "numberOfElements": 100
}
Response Elements​
필드설명
queryInfo ▼조회한 쿼리 정보
    queryId쿼리 ID
    state쿼리 상태
    queryStats ▼조회한 쿼리 정보
        progressPercentage쿼리 진행률
        inputRows입력 데이터 수
        inputDataSize입력 데이터 크기
        outputRows출력 데이터 수
        outputDataSize출력 데이터 크기
        createdAt쿼리 요청 시각
        completedAt쿼리 결과 저장이 완료된 시각
        queryExecutionTime쿼리 실행 시간
        elapsedTime쿼리 종료 시간
        queuedTime쿼리 실행 전 대기한 시간
        planningTime쿼리 계획에 걸린 시간
    queryTextPreview요청한 쿼리 미리보기
- 300자까지 표시
    isScanned데이터 스캔 발생 여부
resultConfig ▼쿼리 결과 데이터 정보
    bucketName쿼리 결과가 저장되는 Object Storage 버킷 이름
    path쿼리 결과가 저장되는 Object Storage 하위 경로
    storageUrl쿼리 결과가 저장되는 Object Storage 전체 경로
    storeType쿼리 결과 타입
- BASIC: 쿼리 결과가 일반적인 테이블 형태
- TEXT: 쿼리 결과가 텍스트 형태
    isStored쿼리 결과가 Object Storage에 저장되었는지 여부
reuseConfig ▼쿼리 결과 재사용 정보
    reuse쿼리 결과 재사용 여부
    expireAt쿼리 결과 만료 시간
columnData쿼리 결과의 칼럼 메타 데이터
queryData쿼리 결과 리스트
totalPages총 페이지 수
totalElements총 데이터 개수
size현재 페이지 크기
number현재 페이지 번호
numberOfElements페이지 내의 쿼리 결과 행 수
응답 코드​
필드설명
200   성공
400잘못된 요청
401Credential 인증 실패
403권한 없음
404존재하지 않는 쿼리 ID

쿼리 목록 조회​

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

Request​

메서드URI
GET{endpoint-url}/v1/data-query/query
쿼리 목록 조회 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}'
Query Params​
Request필수 여부설명
queryId선택    검색할 쿼리 ID
creatorName선택쿼리를 실행한 사용자를 입력
- 특정 사용자가 실행한 쿼리만 필터
states선택쿼리의 상태로 조회
- 입력 가능한 쿼리 상태 : QUEUED, RUNNING, FINISHED, ABORTED, FAILED (쿼리 상태 상세 보기)
page선택페이지 번호
size선택페이지 사이즈
sort선택정렬에 사용할 필드
- 입력 가능한 필드 : queryId, queryTextPreview, state, createdAt, elapsedTime, inputDataSize, creatorName, storageUrl
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/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":[
      {
         "queryInfo":{
            "queryId":"20250314-143349-49C99wBfqS",
            "state":"FINISHED",
            "queryStats":{
               "scannedDataSize":"0B",
               "createdAt":1741930429000,
               "elapsedTime":"9.83m"
            },
            "queryTextPreview":"select * from orders limit 100000000",
            "isScanned":false
         },
         "resultConfig":{
            "storageUrl":"testor1-bucket/data_query/result/2024/11/19"
         },
         "reuseConfig":{
            "reuse":false
         },
         "creatorName":"testor1@kakaoenterprise.com"
      },
      {
         "queryInfo":{
            "queryId":"20250314-143350-7DtipSZrfh",
            "state":"FINISHED",
            "queryStats":{
               "scannedDataSize":"0B",
               "createdAt":1741930430000,
               "elapsedTime":"9.52m"
            },
            "queryTextPreview":"select ...",
            "isScanned":false
         },
         "resultConfig":{
            "storageUrl":"testor1-bucket/data_query/result/2024/11/04"
         },
         "reuseConfig":{
            "reuse":false
         },
         "creatorName":"testor1@kakaoenterprise.com"
      },
      {
         "queryInfo":{
            "queryId":"20250317-084931-6sCSgTNeAf",
            "state":"FINISHED",
            "queryStats":{
               "scannedDataSize":"0B",
               "createdAt":1742168971000,
               "elapsedTime":"9.16m"
            },
            "queryTextPreview":"select ... A ...",
            "isScanned":true
         },
         "resultConfig":{
            "storageUrl":"testor2-bucket/result/2024/11/04"
         },
         "reuseConfig":{
            "reuse":true
         },
         "creatorName":"testor1@kakaoenterprise.com"
      }
   ],
   "pageable":{
      "pageNumber":0,
      "pageSize":3,
      "sort":{
         "unsorted":false,
         "sorted":true,
         "empty":false
      },
      "offset":0,
      "unpaged":false,
      "paged":true
   },
   "totalPages":6,
   "totalElements":104,
   "last":false,
   "numberOfElements":20,
   "size":3,
   "number":0,
   "sort":{
      "unsorted":false,
      "sorted":true,
      "empty":false
   },
   "first":true,
   "empty":false
}
Response Elements​
필드설명
content ▼조회한 쿼리 목록
    queryInfo ▼쿼리 정보
        queryId쿼리 ID
        state쿼리 상태 (쿼리 상태 상세 보기)
        queryStats ▼
            scannedDataSize스캔 데이터 크기
            createdAt쿼리 요청 시간
            elapsedTime쿼리 종료 시간
        queryTextPreview쿼리문의 300자까지 미리볼 수 있는 필드
        isScanned데이터 스캔 발생 여부
    resultConfig ▼쿼리 결과 데이터 정보
        storageUrl쿼리 결과가 저장되는 Object Storage 전체 경로
    reuseConfig ▼쿼리 결과 재사용 정보
        reuse쿼리 결과 재사용 여부
    creatorName쿼리를 실행한 사용자
pageable ▼페이징 관련 정보
    pageNumber현재 페이지 번호
    pageSize현재 페이지 크기
    sort ▼정렬 정보
        sorted정렬이 적용되었는지 여부
        unsorted정렬이 적용되지 않았는지 여부
        empty정렬 조건이 비어있는지 여부
    offset페이지의 시작 지점
    paged페이징 적용 여부
    unpaged페이징이 적용되지 않았는지 여부
totalPages총 페이지 수
totalElements총 데이터 개수
last현재 페이지가 마지막 페이지인지 여부
size현재 페이지 크기
first현재 페이지가 첫 페이지인지 여부
number현재 페이지 번호
empty현재 페이지가 비어있는지 여부
응답 코드​
필드설명
200  성공
400잘못된 요청
401Credential 인증 실패
403권한 없음
404존재하지 않는 쿼리 아이디

쿼리 중단​

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

Request​

메서드URI
PUT{endpoint-url}/v1/data-query/query/{query-id}/abort
쿼리 중단 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}'
Path Params​
Request필수 여부설명
query-Id필수중단할 쿼리 ID
Request Header​
Request필수 여부설명
Credential-ID필수액세스 키 ID
Credential-Secret필수보안 액세스 키

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잘못된 요청
401Credential 인증 실패
403권한 없음
409이미 종료된 쿼리

데이터 원본 목록 조회​

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

Request​

메서드URI
GET{endpoint-url}/v1/data-query/data-source
데이터 원본 목록 조회 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 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​

데이터 원본 목록 조회 응답 예시
[
  {
    "scope": "NONE",
    "creatorName": "-",
    "type": "DATA_CATALOG",
    "name": "data_catalog"
  },
  {
    "scope": "NONE",
    "creatorName": "-",
    "type": "DATA_CATALOG",
    "name": "test_catalog"
  },
  {
    "scope": "PUBLIC",
    "creatorName": "testor1@kakaoenterprise.com",
    "type": "MYSQL",
    "description": "",
    "name": "data_query_cbt"
  },
  {
    "scope": "PRIVATE",
    "creatorName": "testor1@kakaoenterprise.com",
    "type": "MYSQL",
    "name": "testor1_mysql"
  },
  {
    "scope": "PUBLIC",
    "creatorName": "testor2@kakaoenterprise.com",
    "type": "MYSQL",
    "name": "testor2_public"
  }
]
Response Elements​
필드설명
scope데이터 원본 공개 범위
creatorName데이터 원본 생성자
name조회한 쿼리 정보
type데이터 소스의 타입
- DATA_CATALOG, MYSQL
description데이터 원본의 설명
응답 코드​
필드설명
200  성공
400잘못된 요청
401Credential 인증 실패
403권한 없음

MySQL 데이터 원본 생성​

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

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

Request​

메서드URI
POST{endpoint-url}/v1/data-query/data-source
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}' \
    --header 'Content-Type: application/json' \
    --data-raw '{request body}'
Request Header​
Request필수 여부설명
Credential-ID필수    액세스 키 ID
Credential-Secret필수보안 액세스 키
Content-Type필수application/json
Request Body​
Request Body
{
  "type": "MYSQL",
  "name": "string",
  "scope": "PRIVATE|PUBLIC",
  "description": "string",
  "instanceId": "string",
  "mysqlUser": "string",
  "mysqlPassword": "string"
}
Request Elements​
필드필수 여부설명
type필수  데이터 원본의 유형
name필수데이터 원본의 이름
- 영문 소문자, 언더바(_), 숫자만 허용, 3~72자 제한
scope필수데이터 원본의 공개 범위
description선택데이터 원본의 설명
instanceId필수연결할 카카오클라우드 MySQL 인스턴스 아이디
mysqlUser필수MySQL 계정 아이디
mysqlPassword필수MySQL 계정 비밀번호
⚠️ base64로 인코딩된 문자열로 입력

Example​

Request Example​
MySQL 유형 데이터 원본 생성 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}'  \
    --header 'Content-Type: application/json'  \
    --data-raw '{
          "type": "MYSQL",
          "name": "test_mysql",
          "scope": "PRIVATE",
          "description": "test mysql",
          "instanceId": "fbc16e9a-6352-11ef-952c-0a27e22384db",
          "mysqlUser": "admin",
          "mysqlPassword": "YWRtaW4K"
        }'
  • mysqlPassword는 문자열 admin을 base64로 변환한 YWRtaW4K를 입력

Response​

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

MySQL 데이터 원본 삭제​

  • MySQL 유형의 데이터 원본을 삭제합니다.
안내

DATA_CATALOG 유형의 데이터 원본은 삭제할 수 없습니다.

Request​

메서드URI
DELETE{endpoint-url}/v1/data-query/data-source/{data-source-name}
MySQL 데이터 원본 삭제 호출 방식
curl -X DELETE 'https://data-query.kr-central-2.kakaocloud.com/v1/data-query/data-source/{data-source-name}' \
    --header 'Credential-ID: {credential-id}' \
    --header 'Credential-Secret: {credential-secret}' \
    --data-raw '{request body}'
Path Params​
path필수 여부설명
data-source-name필수    삭제할 데이터 원본 이름
Request Header​
Request필수 여부설명
Credential-ID필수    액세스 키 ID
Credential-Secret필수보안 액세스 키

Example​

Request Example​
MySQL 데이터 원본 삭제 요청 예시
curl -X DELETE 'https://<data query API 엔드포인트>/v1/data-query/data-source/test_mysql' \
    -H 'Credential-ID: {credential-id}' \
    -H 'Credential-Secret: {credential-secret}'

Response​

응답 코드​
필드설명
200  성공
400잘못된 요청
401Credential 인증 실패
403권한 없음
404데이터 원본 없음