Python Client for YTsaurus

Warnings

• breaking Loading snapshots containing 'list nodes' can cause master-server crashes. This is a server-side breaking change, but can impact client operations.
  Fix: Ensure YTsaurus cluster administrators have applied the recommended mitigation by disabling `alert_on_list_node_load` in the dynamic configuration. List nodes are slated for complete removal in future major versions.
• breaking Tablet resource accounting changed default behavior from per-account to per-bundle for newly deployed clusters. This is a server-side change that may affect resource management and billing if not accounted for.
  Fix: Review your resource accounting and capacity planning, especially if you manage multiple tablet bundles or accounts on new YTsaurus deployments. Existing clusters are not affected by default.
• gotcha YSON C++ bindings (`ytsaurus-yson`) are not supported on Windows and require Rosetta 2 emulation for Apple M1/M2 platforms.
  Fix: On Windows, YSON will be handled by the slower pure-Python implementation. On Apple Silicon, use Rosetta 2 to run an x86_64 Python environment or be prepared for pure-Python YSON processing. Performance-critical workloads might require Linux environments.
• gotcha Mixing installation methods for `ytsaurus-client` and `ytsaurus-yson` (e.g., pip and system packages) can lead to hard-to-diagnose problems.
  Fix: Always install both `ytsaurus-client` and `ytsaurus-yson` using a consistent method, preferably `pip` within a virtual environment. Avoid using `sudo pip install` if possible.
• gotcha When using dynamic tables, there are strict limits on value size (16 MB per cell), row length (128-512 MB for an entire row across versions), number of values per row (1024), and rows per query (e.g., 100,000 for inserts, 1 million for selects).
  Fix: Design your data schema and queries to respect these limits. For frequent delta writes in aggregation columns, consider setting `@merge_rows_on_flush=%true` and configuring TTL deletion to manage versions efficiently.
• gotcha Small chunks (under 100 MB, ideally aiming for 512 MB average) in static tables can significantly increase master server load and slow down data reads.
  Fix: For tables with many small chunks, use `yt merge --src //your/table --dst //your/table --spec '{combine_chunks=true;mode=<mode>}'` to increase chunk size. In Python, `auto_merge_output={action=merge}` can be specified in configuration to automatically aggregate resulting tables.

Install

• pip install ytsaurus-client Core client library
• pip install ytsaurus-yson Optional YSON bindings (C++ for performance)
• pip install ytsaurus-client-yc-auth Optional for Yandex Cloud authentication

Imports

• YtClient

  import yt
  client = yt.YtClient(...)

  While `yt.wrapper` provides global functions, `yt.YtClient` is the recommended class for creating independent client instances and explicit configuration.
• yt.wrapper

  import yt.wrapper as ytw

  It is generally better to import `yt` and access `wrapper` or `YtClient` via `yt.` to avoid name collisions and maintain clarity, especially if using `yt.YtClient`.

Quickstart

This quickstart demonstrates how to initialize the YTsaurus client and perform basic operations like listing a directory and getting a node's attribute. It assumes `YT_PROXY` and `YT_TOKEN` environment variables are set for authentication and cluster proxy address. For a local setup, you might need `ytsaurus-local` and direct configuration.

import os
import yt
from yt.common import YtError

# Configure connection via environment variables for a runnable example
# In a real scenario, these would be set in your environment
# or passed explicitly in client config.
# Example: os.environ['YT_PROXY'] = 'your-yt-cluster-proxy'
# Example: os.environ['YT_TOKEN'] = os.environ.get('YT_TOKEN', 'your-oauth-token')

# Fallback for demonstration if environment variables are not set
# Replace with actual proxy if running locally without env vars set.
# For example: config=yt.config.Config(proxy='localhost:8000', token='your-token')
client = yt.YtClient(config=yt.default_config.get_config_from_env())

try:
    # Example: List the root directory of Cypress
    # This requires 'read' permission on '//'
    root_content = client.list("//", attributes=["type"]) # Get type attribute
    print(f"First 5 items in root directory: {[item.attributes.get('type', 'unknown') + ' ' + str(item) for item in root_content[:5]]}")

    # Example: Get an attribute of a system node
    node_type = client.get("//sys/@type")
    print(f"Type of //sys: {node_type}")

except YtError as e:
    print(f"YTsaurus Error: {e.message}")
    print("Please ensure YT_PROXY and YT_TOKEN environment variables are correctly set and you have access to the cluster.")
except Exception as e:
    print(f"An unexpected error occurred: {e}")