Data Query Open API

Here is how to use the Data Query Open API.

API endpoint

The endpoint URL for Data Query API requests is as follows:

Data Query endpoint URL format
https://data-query.kr-central-2.kakaocloud.com

Run query

Request to execute a query.

info

Some queries do not return data as a result, so the query result may not be saved as a file.
e.g., CREATE TABLE, CREATE SCHEMA, DROP TABLE, DROP SCHEMA, SHOW SCHEMAS, SHOW TABLES, etc.

Request

Method	URI
POST	`{endpoint-url}/v1/data-query/query`

Run query Request
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: {data source name}' \
    --header 'X-Database: {database name}' \
    --data-raw '{Request body}'

Request header

Request	Required	Description
Credential-id	Yes	Access key id
Credential-secret	Yes	Secret access key
Content-Type	Yes	application/json
X-Data-Source	Optional	Name of the default data source to apply to the query
X-Database	Optional	Name of the default database to apply to the query

Request body

Request body
{
  "query": "string",
  "resultConfig": {
    "bucketName": "string",
    "path": "string"
  },
  "reuseConfig": {
    "reuse": boolean,
    "maxReuseAge": integer
  }
}

Request elements

Field	Required	Description
query	Yes	Query written in SQL ㄴ The data source and database specified in the `x-data-source` and `x-database` headers are applied as the default table location. ㄴ If you run the query without these headers, you must prefix the table names in the query with the data source and database, separated by a dot (`.`). ㄴ If you omit them, errors may occur. * For more details on SQL usage, see the SQL Reference.
resultConfig ▼		Query result data information
bucketName	Yes	Name of the Object Storage bucket to store the query result
path	Yes	Subdirectory path to store the query result - A folder with the execution date `{YYYY}/{MM}/{DD}/` is automatically created under the specified path, and the result file is saved inside it. - The result includes a query result file (`.csv`) and a metadata file (`.metadata`). - For details, refer to Query result data.
reuseConfig ▼		Query result reuse information
reuse	Optional	Whether to reuse the query result
maxReuseAge	Optional	Query result reuse lifespan (in minutes) - Can be set from 1 to 1440 minutes (24 hours). - Required if `reuse` is set to `true`.

Example

Request example

Run query 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"
    }'

The nation table, which does not specify a data source or database, is automatically assigned the location defined in the headers: test_datasource and test_database.
The region table explicitly specifies its data source and database, which take precedence over the headers.
As a result, the executed query is equivalent to: select * from test_datasource.test_database.nation, test_datasource.test_database2.region limit 100.
The query result is saved as two files (.csv, .metadata) under data_query/result/2024/11/26 in the test-bucket bucket.

Response

Run query response example
{
  "queryInfo": {
    "queryId": "data-query-20240903-011848-HcejcLZBHz",
    "state": "QUEUED"
  }
}

Response eements

Field	Description
queryId	Query ID
state	Query status

Response codes

Code	Description
202	Success
400	Bad request
401	Credential authentication failed
403	Forbidden
404	Bucket not found
499	Service agent lacks required permissions on the specified bucket

Retrieve query result

Retrieve the query result and detailed information.
You can check the query status, basic statistics, and part of the result in paginated form.

info

Query results are provided in pages of 100 rows, up to a maximum of 1,000 rows (pages 0–9).

Request

Method	URI
GET	`{endpoint-url}/v1/data-query/query/{query-id}?page={page-number}`

Retrieve query result request

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 parameters

Path	Type	Required	Description
query-id	string	Yes	Query ID

Query parameters

Request	Required	Description
page-number	Optional	Page number of the query result to retrieve

Request headers

Request	Required	Description
Credential-id	Yes	Access key id
Credential-secret	Yes	Secret access key

Example

Request example

Retrieve query result 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}'

Retrieve the query result of query ID 20241126-011848-HcejcLZBHz.
If the query result exists, 100 rows from page 0 will be retrieved.

Response

Retrieve query result response example
{
  "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 eements

Field	Description
queryInfo ▼	Information about the retrieved query
queryId	Query ID
state	Query state
queryStats ▼	Statistics about the retrieved query
progressPercentage	Query progress
inputRows	Number of input rows
inputDataSize	Size of input data
outputRows	Number of output rows
outputDataSize	Size of output data
createdAt	Time the query was requested
completedAt	Time the query result was stored
queryExecutionTime	Time taken to execute the query
elapsedTime	Time taken until the query completed
queuedTime	Time the query waited before execution
planningTime	Time spent planning the query
queryTextPreview	Preview of the submitted query - Displays up to 300 characters
isScanned	Indicates whether data scanning occurred
resultConfig ▼	Information about the query result data
bucketName	Name of the Object Storage bucket where the result is stored
path	Sub-path in Object Storage where the result is stored
storageUrl	Full path in Object Storage where the result is stored
storeType	Type of query result - `BASIC`: general tabular format - `TEXT`: text format
isStored	Whether the query result is stored in Object Storage
reuseConfig ▼	Information about result reuse
reuse	Whether the result is reused
expireAt	Expiration time of the reused result
columnData	Metadata about the query result columns
queryData	List of query results
totalPages	Total number of pages
totalElements	Total number of records
size	Number of results per page
number	Current page number
numberOfElements	Number of records on the current page

Response codes

Code	Description
200	Success
400	Bad request
401	Credential authentication failed
403	Forbidden
404	Query ID not found

Retrieve query list

Retrieve executed query list.
Check summary information of executed queries.

Request

method	URI
GET	`{endpoint-url}/v1/data-query/query`

Retrieve query list request

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 parameters

Request	Required	Description
queryId	optional	query ID to search
creatorName	optional	user who executed the query - filter by queries executed by a specific user
states	optional	search by query state - valid states: `QUEUED`, `RUNNING`, `FINISHED`, `ABORTED`, `FAILED` (see query status details)
page	optional	page number
size	optional	page size
sort	optional	field to sort by - valid fields: queryId, queryTextPreview, state, createdAt, elapsedTime, inputDataSize, creatorName, storageUrl

Request header

Request	Required	Ddscription
Credential-id	required	Access key id
Credential-secret	required	Secret access key

Example

Request example

Retrieve query list 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 (page number): 0
size (page size): 3
sort by elapsedTime in descending order
filter query info with state FAILED or FINISHED only

Response

Retrieve query list response example
{
   "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 eements

Field	Description
content ▼	List of queried queries
queryInfo ▼	Query information
queryId	Query ID
state	Query state (see query status details)
queryStats ▼	Query statistics
scannedDataSize	Scanned data size
createdAt	Query request time
elapsedTime	Query completion time
queryTextPreview	Query text preview up to 300 characters
isScanned	Whether data scanning occurred
resultConfig ▼	Query result data information
storageUrl	Full path to the Object Storage where query results are saved
reuseConfig ▼	Query result reuse information
reuse	Whether query results are reused
creatorName	User who executed the query
pageable ▼	Paging information
pageNumber	Current page number
pageSize	Current page size
sort ▼	Sorting information
sorted	Whether sorting is applied
unsorted	Whether sorting is not applied
empty	Whether sorting conditions are empty
offset	Starting point of the page
paged	Whether paging is applied
unpaged	Whether paging is not applied
totalPages	Total number of pages
totalElements	Total number of data elements
last	Whether the current page is the last page
size	Current page size
first	Whether the current page is the first page
number	Current page number
empty	Whether the current page is empty

Response codes

Field	Description
200	Success
400	Bad request
401	Credential authentication failure
403	forbidden
404	query id not found

Abort query

Aborts query execution.
Does not work if query state is FINISHED, FAILED, or ABORTED.

Request

Method	URI
PUT	`{endpoint-url}/v1/data-query/query/{query-id}/abort`

Abort query request
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 parameters

Request	Required	Description
query-id	required	id of the query to abort

Request header

Request	Required	Description
Credential-id	required	Access key id
Credential-secret	required	Secret access key

Example

Request example

Abort query 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}'

Aborts query execution with query id 20241104-071200-TkMfjvIieD

Response

Status code

Field	Description
200	Success
400	Bad request
401	Credential authentication failed
403	Forbidden
409	Query already terminated

Retrieve data source list

Retrieve the list of data sources connected to data query.

Request

Method	URI
GET	`{endpoint-url}/v1/data-query/data-source`

Retrieve data source list request
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	Required	Description
Credential-id	Required	Access key id
Credential-secret	Required	Secret access key

Example

Request example

Retrieve data source list request
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

Retrieve data source list 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 eements

Field	Description
scope	data source visibility scope
creatorName	data source creator
name	retrieved query information
type	data source type - `DATA_CATALOG`, `MYSQL` , `POSTGRESQL`
Description	Description of the data source

response codes

Field	Description
200	Success
400	Bad request
401	Credential authentication failed
403	Forbidden

Create MySQL data source

Creates a MySQL type data source.

info

DATA_CATALOG type data sources are automatically created when a catalog is created in the Data Catalog service.

Request

Method	URI
POST	`{endpoint-url}/v1/data-query/data-source`

Create MySQL data source request
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	Required	Description
Credential-id	Required	Access key ID
Credential-secret	Required	Secret access key
Content-Type	Required	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

Field	Required	Description
type	Required	Type of data source
name	Required	Name of data source - Allows only lowercase English letters, underscores (_), and numbers; length 3 to 72 characters
scope	Required	Data source public scope
description	Optional	Description of the data source
instanceId	Required	KakaoCloud MySQL instance ID to connect
username	Yes	MySQL account ID
password	Yes	MySQL account password ⚠️ Must be provided as a base64-encoded string

Example

Request example

Create MySQL data source 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}'  \
    --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"
        }'

Enter YWRtaW4K, which is the base64-encoded string of admin, as the password.

Response

Status code

Field	Description
200	Success
400	Bad request
401	Credential authentication failed
403	Forbidden
409	Duplicate data source name

Create PostgreSQL data source

Creates a data source of type PostgreSQL.

Request

Method	URI
POST	`{endpoint-url}/v1/data-query/data-source`

Call API to create PostgreSQL-type data source
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

Header	Required	Description
Credential-ID	Yes	Access key ID
Credential-Secret	Yes	Secret access key

Request body

Request Body
{
  "type": "POSTGRESQL",
  "name": "string",
  "description": "string",
  "instanceId": "string",
  "scope": "PRIVATE|PUBLIC",
  "username": "string",
  "password": "<base64 encoded string>",
  "databaseName": "string"
}

Request elements

Field	Required	Description
type	Yes	Type of the data source
name	Yes	Name of the data source - Lowercase letters, numbers, underscores only - 3–72 characters
description	No	Description of the data source
instanceId	Yes	ID of the KakaoCloud PostgreSQL instance to connect
username	Yes	PostgreSQL account ID
password	Yes	PostgreSQL account password ⚠️ Must be provided as a base64-encoded string
databaseName	Yes	Name of the PostgreSQL database
scope	Yes	Visibility scope of the data source

Example

Request example

Example API call to create PostgreSQL data source
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 '{
      "type": "POSTGRESQL",
      "name": "test_postgresql",
      "scope": "PRIVATE",
      "description": "test postgresql",
      "instanceId": "99fbe528-8014-47ee-b5bb-15c059562611",
      "username": "admin",
      "password": "YWRtaW4K",
      "databaseName": "postgres"
    }'

Enter YWRtaW4K, which is the base64-encoded string of admin, as the password.

Response

Response codes

Code	Description
200	Success
400	Bad request
401	Credential authentication failed
403	Forbidden
409	Data source name already exists

Delete MySQL data source

Delete a MySQL type data source.

info

DATA_CATALOG type data sources cannot be deleted.

Request

Method	URI
DELETE	`{endpoint-url}/v1/data-query/data-source/{data-source-name}`

Delete data source API call example
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 parameters

Path	Required	Description
data-source-name	Required	Name of the data source to be deleted

Request header

Request	Required	Description
Credential-id	Required	Access key ID
Credential-secret	Required	Secret access key

Example

Request example

MySQL data source delete request example
curl -X DELETE 'https://<data query API endpoint>/v1/data-query/data-source/test_data_source' \
    -H 'Credential-ID: {credential-id}' \
    -H 'Credential-Secret: {credential-secret}'

Response

Status code

Field	Description
200	Success
400	Bad request
401	Credential authentication failed
403	Forbidden
404	Data source not found

API endpoint​

Run query​

Request​

Request header​

Request body​

Request elements​

Example​

Request example​

Response​

Response eements​

Response codes​

Retrieve query result​

Request​

Path parameters​

Query parameters​

Request headers​

Example​

Request example​

Response​

Response eements​

Response codes​

Retrieve query list​

Request​

Query parameters​

Request header​

Example​

Request example​

Response​

Response eements​

Response codes​

Abort query​

Request​

Path parameters​

Request header​

Example​

Request example​

Response​

Status code​

Retrieve data source list​

Request​

Request header​

Example​

Request example​

Response​

Response eements​

response codes​

Create MySQL data source​

Request​

Request header​

Request body​

Request elements​

Example​

Request example​

Response​

Status code​

Create PostgreSQL data source​

Request​

Request header​

Request body​

Request elements​

Example​

Request example​

Response​

Response codes​

Delete MySQL data source​

Request​

Path parameters​

Request header​

Example​

Request example​

Response​

Status code​

API endpoint

Run query

Request

Request header

Request body

Request elements

Example

Request example

Response

Response eements

Response codes

Retrieve query result

Request

Path parameters

Query parameters

Request headers

Example

Request example

Response

Response eements

Response codes

Retrieve query list

Request

Query parameters

Request header

Example

Request example

Response

Response eements

Response codes

Abort query

Request

Path parameters

Request header

Example

Request example

Response

Status code

Retrieve data source list

Request

Request header

Example

Request example

Response

Response eements

response codes

Create MySQL data source

Request

Request header

Request body

Request elements

Example

Request example

Response

Status code

Create PostgreSQL data source

Request

Request header

Request body

Request elements

Example

Request example

Response

Response codes

Delete MySQL data source

Request

Path parameters

Request header

Example

Request example

Response

Status code