Contact UsGet started

How to work with the Yandex Query HTTP API

Written by
Updated at May 13, 2024

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
Previous
SDK
Next
Authentication