Yandex Query HTTP Client

Warnings

• gotcha Authentication requires a valid Yandex Cloud IAM token and a specific Folder ID. IAM tokens have an expiration period, which can cause authentication failures for long-running processes if not refreshed. Ensure your application handles token renewal or uses a service account key for persistent access.
  Fix: Store IAM token and Folder ID in environment variables (`YQ_IAM_TOKEN`, `YQ_FOLDER_ID`). Implement logic to refresh IAM tokens if using temporary credentials, or configure service accounts with appropriate roles (e.g., `yq.editor`) for automated access.
• gotcha The library is in an early development stage (version 0.1.x). While official, minor version updates may introduce API changes or breaking modifications without a major version increment (e.g., a 0.2.0 release might contain breaking changes).
  Fix: Always pin the exact version (`yandex-query-client==0.1.4`) in production environments and thoroughly test updates before deployment. Refer to the GitHub repository's `CHANGELOG.md` (if available) or commit history for specific changes between versions.
• gotcha Yandex Query uses YQL, a specific SQL dialect, which may have differences from standard SQL implementations. Queries written for other SQL databases might require adjustments to work correctly with Yandex Query.
  Fix: Consult the Yandex Query Language (YQL) documentation for syntax and feature specifics when constructing queries. Test your YQL queries directly in the Yandex Cloud console before integrating them into your application if you encounter unexpected behavior.

Install

• pip install yandex-query-client --upgrade Install latest version

Imports

• YQHttpClient

  from yandex_query_client import YQHttpClient

  Primary client class for interacting with Yandex Query.
• YQHttpClientConfig

  from yandex_query_client import YQHttpClientConfig

  Configuration class for the HTTP client, requiring IAM token and project ID.

Quickstart

This quickstart demonstrates how to initialize the Yandex Query client, create a simple SQL query, wait for its completion, and retrieve the results. It highlights the essential steps for basic interaction with the Yandex Query service. Ensure `YQ_IAM_TOKEN` and `YQ_FOLDER_ID` environment variables are set or replaced with actual values for authentication and operation within a specific Yandex Cloud folder.

import os
from yandex_query_client import YQHttpClient, YQHttpClientConfig

# --- Configuration ---
# Replace with your Yandex Cloud IAM token and Folder ID.
# It is recommended to use environment variables for sensitive credentials.
IAM_TOKEN = os.environ.get('YQ_IAM_TOKEN', 'YOUR_IAM_TOKEN')
PROJECT = os.environ.get('YQ_FOLDER_ID', 'YOUR_FOLDER_ID')

if IAM_TOKEN == 'YOUR_IAM_TOKEN' or PROJECT == 'YOUR_FOLDER_ID':
    print("WARNING: Please set YQ_IAM_TOKEN and YQ_FOLDER_ID environment variables or replace placeholders.")
    # In a real application, you might raise an error or exit.
    exit("Missing Yandex Query credentials.")

config = YQHttpClientConfig(IAM_TOKEN, PROJECT)
client = YQHttpClient(config)

# --- Example: Run a simple query ---
query_text = "SELECT 777;"
query_name = "my_sample_query"

try:
    print(f"Creating query: '{query_text}' with name '{query_name}'...")
    query_id = client.create_query(query_text=query_text, name=query_name)
    print(f"Query created with ID: {query_id}")

    print(f"Waiting for query {query_id} to succeed...")
    # wait_query_to_succeed returns the number of result sets
    result_set_count = client.wait_query_to_succeed(query_id)
    print(f"Query {query_id} succeeded with {result_set_count} result set(s).")

    print(f"Fetching results for query {query_id}...")
    # get_query_all_result_sets fetches all result sets
    results = client.get_query_all_result_sets(query_id, result_set_count=result_set_count)

    for i, result_set in enumerate(results):
        print(f"\n--- Result Set {i+1} ---")
        # Access column names (if available)
        column_names = [col.name for col in result_set.columns] if result_set.columns else []
        print(f"Columns: {column_names}")

        # Iterate through rows
        for row in result_set.rows:
            # Access values (example: assuming single column 'column0')
            # The exact structure of 'row' might vary, often it's a list/tuple of values
            print(f"Row: {row}")

except Exception as e:
    print(f"An error occurred: {e}")