How to work with the Yandex Query HTTP API
You can use the Query HTTP API to perform one-time operations and automate routine actions, such as making requests to data from scripts or programs on a schedule.
The Query HTTP API methods let you create and make requests to data, get request execution statuses and results, and stop requests. To make API requests, you need to authenticate.
Below are common approaches to working with the Query HTTP API:
Headers
When using the HTTP API, some headers are required and others are not.
Required headers
| Name | Description |
|---|---|
Authorization |
Authentication parameters. Type: String. Example: Authorization: Bearer <IAM token>. |
Optional headers
| Name | Description |
|---|---|
x-request-id |
Used for query diagnostics. Specify any string as a value. We recommend using highly unique values, such as GUID, to avoid collisions with IDs used to diagnose other queries. Type: String. Example: c8b4c0aa-8fc2-4159-8870-f4cb********. |
Idempotency-Key |
Idempotency key. Used in modifying operations. We recommend specifying this parameter to avoid unexpected situations. Type: String, UUID. Example: Idempotency-Key: c1700de3-b8cb-4d8a-9990-e4eb********. |
Errors
If an error occurs, Yandex Query returns a detailed error description in a JSON object, such as:
{
"message": "Failed to parse query",
"details": [
{
"position": {
"row": 0,
"column": 0
},
"message": "string",
"end_position": {
"row": 0,
"column": 0
},
"issue_code": 0,
"severity": "FATAL",
"issues": [
"string"
]
}
]
}
Incorrect JSON object fields:
| Name | Type | Description | Example |
|---|---|---|---|
message |
String | Error overview | "Failed to parse query" |
details |
An array of Issue objects |
Detailed description of an incorrect string |
Issue object
If an error occurs, Yandex Query returns detailed information specifying the error location and context, and the numbers of incorrect SQL query strings. The result is returned as an instance of the Issue object.
Error details may be represented as a hierarchy, meaning that a more general Issue may contain a number of detailed Issues with a more detailed description, and so on.
Sample hierarchy error
{
"issues": [
{
"issues": [
{
"position": {
"column": 1,
"row": 1
},
"severity": 1,
"endPosition": {
"column": 1,
"row": 1
},
"message": "Column references are not allowed without FROM"
},
{
"position": {
"column": 8,
"row": 1
},
"severity": 1,
"endPosition": {
"column": 8,
"row": 1
},
"message": "Column reference 'x'"
}
],
"severity": 1,
"message": "Parse Sql"
},
{
"issues": [
{
"position": {
"column": 1,
"row": 1
},
"severity": 1,
"endPosition": {
"column": 1,
"row": 1
},
"message": "Column references are not allowed without FROM"
},
{
"position": {
"column": 8,
"row": 1
},
"severity": 1,
"endPosition": {
"column": 8,
"row": 1
},
"message": "Column reference 'x'"
}
],
"severity": 1,
"message": "Parse Sql"
}
],
"severity": 1,
"message": "Failed to parse query"
}
Issue object fields:
| Name | Type | Description | Example |
|---|---|---|---|
message |
String | Error overview | "Failed to parse query" |
severity |
Number | Error severity. Possible values: Info, Warn, Error, and Fatal |
Warn |
position.row |
Number | Number of the code block start string causing the error | 1 |
position.column |
Number | Number of the character in the position.row string |
1 |
endPosition.row |
Number | Number of the code block end string causing the error | 1 |
endPosition.column |
Number | Number of the character in the endPosition.row string |
1 |
Issues |
Array | An array of nested Issues with error details |