Run query

Available in VPC

Run a query.

Request

This section describes the request format. The method and URI are as follows:

Method	URI
POST	/api/v2/queries

Request headers

For information about the headers common to all Data Query APIs, see Data Query request headers.

Request body

You can include the following data in the body of your request:

Field	Type	Required	Description
`query`	String	Required	Execution query statement
`executionParameters`	Array	Optional	Query execution parameter
`timeout`	Integer	Optional	Maximum query execution time (second) 1-60 (default: 20)
`isReuse`	Boolean	Optional	Whether to reuse query results `true` \| `false` (default) `true`: Reuse `false`: Not reuse
`reuseMaxAge`	Integer	Conditional	Time allowed to reuse query results (minute) 1-10080 (default: 60) Required if `isReuse` is `true`. e.g., If 60 is entered: Reuse valid results if they were returnable 60 minutes before the query was executed.
`dataSource`	String	Optional	Query execution data source name
`database`	String	Optional	Query execution database name
`projectId`	Integer	Optional	Query execution project ID

Request example

The request example is as follows:

curl --location --request POST 'https://kr.dataquery.naverncp.com/api/v2/queries' \
--header 'x-ncp-apigw-timestamp: {Timestamp}' \
--header 'x-ncp-iam-access-key: {Access Key}' \
--header 'x-ncp-apigw-signature-v2: {API Gateway Signature}' \
--header 'Content-Type: application/json' \
--data '{
            "query": "SELECT * FROM public_data.korea_trade_insurance.exchange_rate where currency_code = ? and date > ?",
            "executionParameters": [
                "CNY",
                "2023.01.01"
            ],
            "timeout": 20,
            "isReuse": true,
            "reuseMaxAge": 60
}'

Response

This section describes the response format.

Response body

The response body includes the following data:

Field	Type	Required	Description
`id`	String	-	Execution ID
`columns`	Array	-	Column information: Column
`data`	Array	-	Query execution result Returns an array where each row is mapped one-to-one to the column order of `Column`. For composite type (`row`) columns, serializes as a string of the form `{field name=value}`. Separated by commas (,) if returning more than one.
`offset`	Long	-	Offset to use for page query If `isFinished` is `false`, use it for the next page query request.
`isFinished`	Boolean	-	Whether all pages have been queried `true` \| `false` `true`: Completed (Next page does not exist.) `false`: Incomplete (Next page exists.)

`Column`

The following describes Column.

Field	Type	Required	Description
`name`	String	-	Column name
`type`	String	-	Column type
`typeSignature`	Object	-	Column type information
`typeSignature.rawType`	String	-	Default type name
`typeSignature.arguments`	Array	-	Type parameter list: ClientTypeSignatureParameter

`ClientTypeSignatureParameter`

The following describes ClientTypeSignatureParameter.

Field	Type	Required	Description
`kind`	String	-	Type parameter type `TYPE` \| `NAMED_TYPE` \| `LONG` \| `VARIABLE`
`value`	Union	-	Type parameter value `Object` \| `Number` \| `String` `Object`: If `kind` is `TYPE` or `NAMED_TYPE` (composite type) `Number`: If `kind` is `LONG` `String`: If `kind` is `VARIABLE`
`value.fieldName`	Object	-	Field name object of composite type
`value.fieldName.name`	String	-	Field name
`value.typeSignature`	Object	-	Field type object of composite type
`value.typeSignature.rawType`	String	-	Default type name
`value.typeSignature.arguments`	Array	-	Type parameter list: ClientTypeSignatureParameter

Response status codes

For information about the HTTP status codes common to all Data Query APIs, see Data Query response status codes.

Response example

The response example is as follows:

{
    "id": "fc6b118d-****-****-****-f350f9881f24",
    "columns": [
        {
            "name": "currency_code",
            "type": "varchar",
            "typeSignature": {
                "rawType": "varchar",
                "arguments": [
                    {
                        "kind": "LONG",
                        "value": 2147483647
                    }
                ]
            }
        },
        {
            "name": "date",
            "type": "varchar",
            "typeSignature": {
                "rawType": "varchar",
                "arguments": [
                    {
                        "kind": "LONG",
                        "value": 2147483647
                    }
                ]
            }
        },
        {
            "name": "trade_rate",
            "type": "varchar",
            "typeSignature": {
                "rawType": "varchar",
                "arguments": [
                    {
                        "kind": "LONG",
                        "value": 2147483647
                    }
                ]
            }
        },
        {
            "name": "us_conversion_rate",
            "type": "varchar",
            "typeSignature": {
                "rawType": "varchar",
                "arguments": [
                    {
                        "kind": "LONG",
                        "value": 2147483647
                    }
                ]
            }
        }
    ],
    "data": [
        [
            "CNY",
            "2023.1.9",
            "184.56",
            "0.1456"
        ],
        [
            "CNY",
            "2023.1.17",
            "183.87",
            "0.149"
        ],
        [
            "CNY",
            "2023.1.30",
            "182.33",
            "0.1482"
        ],
        [
            "CNY",
            "2023.2.8",
            "184.89",
            "0.1472"
        ],
        ...
    ],
    "offset": 4845,
    "isFinished": true
}