본문으로 건너뛰기

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잘못된 요청
401Credential 인증 실패
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잘못된 요청
401Credential 인증 실패
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잘못된 요청
401Credential 인증 실패
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잘못된 요청
401Credential 인증 실패
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잘못된 요청
401Credential 인증 실패
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잘못된 요청
401Credential 인증 실패
403권한 없음
409데이터 원본 이름 중복