본문으로 건너뛰기

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

데이터 원본 목록 조회 응답 예시
[
{
"creatorName": "-",
"scope": "NONE",
"type": "STANDARD",
"name": "data_catalog"
},
{
"creatorName": "-",
"scope": "NONE",
"type": "ICEBERG",
"name": "test_catalog"
},
{
"creatorName": "testor1@kakaoenterprise.com",
"scope": "PUBLIC",
"type": "MYSQL",
"description": "",
"name": "data_query_cbt"
},
{
"creatorName": "testor1@kakaoenterprise.com",
"scope": "PRIVATE",
"type": "MYSQL",
"name": "testor1_mysql"
},
{
"creatorName": "testor2@kakaoenterprise.com",
"scope": "PUBLIC",
"type": "MYSQL",
"name": "testor2_public"
}
]
Response Elements
필드설명
scope데이터 원본 공개 범위
creatorName데이터 원본 생성자
name조회한 쿼리 정보
type데이터 소스의 타입
- DATA_CATALOG, MYSQL , POSTGRESQL
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",
"username": "string",
"password": "<base64 encoded string>"
}
Request Elements
필드필수 여부설명
type필수  데이터 원본의 유형
name필수데이터 원본의 이름
- 영문 소문자, 언더바(_), 숫자만 허용, 3~72자 제한
scope필수데이터 원본의 공개 범위
description선택데이터 원본의 설명
instanceId필수연결할 카카오클라우드 MySQL 인스턴스 아이디
username필수MySQL 계정 아이디
password필수MySQL 계정 비밀번호
⚠️ base64로 인코딩된 문자열로 입력

Example

Request Example
PostgreSQL 유형 데이터 원본 생성 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 '{
"type": "MYSQL",
"name": "test_mysql",
"scope": "PRIVATE",
"description": "test mysql",
"instanceId": "fbc16e9a-6352-11ef-952c-0a27e22384db",
"username": "admin",
"password": "YWRtaW4K"
}'
  • password는 문자열 admin을 base64로 변환한 YWRtaW4K를 입력

Response

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

PostgreSQL 데이터 원본 생성

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

Request

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

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}' \
--data-raw '{
"type": "POSTGRESQL",
"name": "test_postgresql",
"scope": "PRIVATE",
"description": "test postgresql",
"instanceId": "99fbe528-8014-47ee-b5bb-15c059562611",
"username": "admin",
"password": "YWRtaW4K",
"databaseName": "postgres"
}'
  • password는 문자열 admin을 base64로 변환한 YWRtaW4K를 입력

Response

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

데이터 원본 삭제

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

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

Request

메서드URI
DELETE{endpoint-url}/v1/data-query/data-source/{data-source-name}
데이터 원본 삭제 호출 방식
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_data_source' \
-H 'Credential-ID: {credential-id}' \
-H 'Credential-Secret: {credential-secret}'

Response

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