Working with the Yandex Query HTTP API
With the Query HTTP API, you can both perform one-time operations and automate routine tasks, e.g., querying data from scripts or programs on a schedule.
The Query HTTP API methods allow you to create, run, and stop queries, as well as retrieve their statuses and results. To make API requests, first you need to authenticate.
Below are the common approaches to working with the Query HTTP API:
Headers
When working with the HTTP API, some headers are mandatory while others are optional.
Mandatory headers
| Header | Description |
|---|---|
Authorization |
Authentication parameters. Type: String. Example: Authorization: Bearer <IAM token>. |
Optional headers
| Header | Description |
|---|---|
x-request-id |
This header is used for query diagnostics. You can specify an arbitrary string as its value. We recommend using unique values, e.g., GUIDs, to avoid collisions with diagnostic identifiers of other requests. Type: String. Example: c8b4c0aa-8fc2-4159-8870-f4cb********. |
Idempotency-Key |
Idempotency key. This header is used in write operations to prevent duplicate actions and side effects when the same request is submitted multiple times. Type: String,UUID. Example: Idempotency-Key: c1700de3-b8cb-4d8a-9990-e4eb********. |
Errors
When an error occurs, Yandex Query returns a detailed error description in a JSON object, e.g.:
{
"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"
]
}
]
}
Error JSON object fields:
| Field | Type | Description | Example |
|---|---|---|---|
message |
String | Error overview | "Failed to parse query" |
details |
Array of Issue objects |
Detailed error description |
Issue object
When an error occurs, Yandex Query returns detailed information about its location, context, and the line numbers of the SQL query containing the error. This information is wrapped in an Issue object instance.
Error information may be hierarchical, i.e., a higher-level Issue may contain multiple lower-level Issue objects with more detailed descriptions, etc.
Error hierarchy example
{
"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:
| Field | Type | Description | Example |
|---|---|---|---|
message |
String | Error overview | "Failed to parse query" |
severity |
Number | Error severity. The possible values are Info, Warn, Error, or Fatal |
Warn |
position.row |
Number | The starting line number of the code block that triggered the error | 1 |
position.column |
Number | The character position in the position.row line |
1 |
endPosition.row |
Number | The ending line number of the code block that triggered the error | 1 |
endPosition.column |
Number | The character position in the endPosition.row line |
1 |
Issues |
Array | An array of nested Issue objects containing error details |