{"id":2849,"library":"yandex-query-client","title":"Yandex Query HTTP Client","description":"The `yandex-query-client` is the official Python HTTP client for Yandex Query, an interactive, fully managed service for running analytical and streaming queries on structured and semi-structured data using a common SQL dialect (YQL). The current version is 0.1.4, indicating it is an early-stage but actively maintained library. Its release cadence is currently irregular, consistent with a newer project.","status":"active","version":"0.1.4","language":"en","source_language":"en","source_url":"https://github.com/yandex-cloud/yandex-query-client","tags":["yandex","cloud","query","analytics","sql","yql","http-client"],"install":[{"cmd":"pip install yandex-query-client --upgrade","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Requires Python 3.8 or higher.","package":"python","optional":false}],"imports":[{"note":"Primary client class for interacting with Yandex Query.","symbol":"YQHttpClient","correct":"from yandex_query_client import YQHttpClient"},{"note":"Configuration class for the HTTP client, requiring IAM token and project ID.","symbol":"YQHttpClientConfig","correct":"from yandex_query_client import YQHttpClientConfig"}],"quickstart":{"code":"import os\nfrom yandex_query_client import YQHttpClient, YQHttpClientConfig\n\n# --- Configuration ---\n# Replace with your Yandex Cloud IAM token and Folder ID.\n# It is recommended to use environment variables for sensitive credentials.\nIAM_TOKEN = os.environ.get('YQ_IAM_TOKEN', 'YOUR_IAM_TOKEN')\nPROJECT = os.environ.get('YQ_FOLDER_ID', 'YOUR_FOLDER_ID')\n\nif IAM_TOKEN == 'YOUR_IAM_TOKEN' or PROJECT == 'YOUR_FOLDER_ID':\n    print(\"WARNING: Please set YQ_IAM_TOKEN and YQ_FOLDER_ID environment variables or replace placeholders.\")\n    # In a real application, you might raise an error or exit.\n    exit(\"Missing Yandex Query credentials.\")\n\nconfig = YQHttpClientConfig(IAM_TOKEN, PROJECT)\nclient = YQHttpClient(config)\n\n# --- Example: Run a simple query ---\nquery_text = \"SELECT 777;\"\nquery_name = \"my_sample_query\"\n\ntry:\n    print(f\"Creating query: '{query_text}' with name '{query_name}'...\")\n    query_id = client.create_query(query_text=query_text, name=query_name)\n    print(f\"Query created with ID: {query_id}\")\n\n    print(f\"Waiting for query {query_id} to succeed...\")\n    # wait_query_to_succeed returns the number of result sets\n    result_set_count = client.wait_query_to_succeed(query_id)\n    print(f\"Query {query_id} succeeded with {result_set_count} result set(s).\")\n\n    print(f\"Fetching results for query {query_id}...\")\n    # get_query_all_result_sets fetches all result sets\n    results = client.get_query_all_result_sets(query_id, result_set_count=result_set_count)\n\n    for i, result_set in enumerate(results):\n        print(f\"\\n--- Result Set {i+1} ---\")\n        # Access column names (if available)\n        column_names = [col.name for col in result_set.columns] if result_set.columns else []\n        print(f\"Columns: {column_names}\")\n\n        # Iterate through rows\n        for row in result_set.rows:\n            # Access values (example: assuming single column 'column0')\n            # The exact structure of 'row' might vary, often it's a list/tuple of values\n            print(f\"Row: {row}\")\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\n","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"0.1.x"},{"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.","message":"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).","severity":"gotcha","affected_versions":"0.1.x"},{"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.","message":"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.","severity":"gotcha","affected_versions":"0.1.x"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}