{"id":6823,"library":"pytd","title":"pytd - Treasure Data Driver","description":"pytd is the official Treasure Data Driver for Python, providing a client for interacting with Treasure Data's services. It allows users to query data, load data into tables, and manage databases. The current version is 2.4.0, and it maintains a regular release cadence, typically with several updates per year.","status":"active","version":"2.4.0","language":"en","source_language":"en","source_url":"https://github.com/treasure-data/pytd","tags":["database","treasure data","etl","data warehouse","cloud","analytics"],"install":[{"cmd":"pip install pytd","lang":"bash","label":"Install pytd"}],"dependencies":[{"reason":"Core client for Treasure Data API interaction, required >= 1.7.0.","package":"td-client","optional":false},{"reason":"HTTP client library, required >= 2.0.0.","package":"urllib3","optional":false},{"reason":"Used for efficient data handling and serialization, required >= 14.0.1.","package":"pyarrow","optional":false},{"reason":"Used as the underlying SQL client for Trino/Presto queries (replaces presto-python-client since v2.0.0).","package":"trino-python-client","optional":false},{"reason":"Optional dependency for DataFrame operations, supported up to pandas 2.x.","package":"pandas","optional":true},{"reason":"Optional dependency, required by pandas, supported < 2.0.0.","package":"numpy","optional":true}],"imports":[{"note":"Directly importing Client from pytd.client is the standard practice for accessing the main client functionalities.","wrong":"import pytd","symbol":"Client","correct":"from pytd.client import Client"}],"quickstart":{"code":"import os\nfrom pytd.client import Client\n\n# Set your Treasure Data API key and server in environment variables\n# e.g., export TD_API_KEY=\"YOUR_API_KEY\"\n# e.g., export TD_API_SERVER=\"https://api.treasuredata.com\"\n\napi_key = os.environ.get('TD_API_KEY', '')\napi_server = os.environ.get('TD_API_SERVER', 'https://api.treasuredata.com')\n\nif not api_key:\n    print(\"Warning: TD_API_KEY environment variable not set. Client may fail to authenticate.\")\n\ntry:\n    # Initialize the client\n    client = Client(apikey=api_key, endpoint=api_server)\n\n    # List databases\n    databases = client.list_databases()\n    print(f\"Databases: {[db.name for db in databases]}\")\n\n    # Example: Execute a simple query (replace 'sample_datasets' and 'www_access' with your actual db/table)\n    # This part requires a valid database and table to exist in your Treasure Data account.\n    if databases and len(databases) > 0:\n        first_db_name = databases[0].name\n        print(f\"Using first database found: {first_db_name}\")\n        # Example query (uncomment and modify with an actual table in your account):\n        # query_result = client.query(f'SELECT count(*) FROM {first_db_name}.your_table_name_here')\n        # print(f\"Query result count: {query_result.fetchall()[0][0]}\")\n    else:\n        print(\"No databases found or API key/server invalid.\")\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\n    print(\"Please ensure your TD_API_KEY and TD_API_SERVER are correctly set and accessible, and you have network connectivity.\")","lang":"python","description":"This quickstart initializes a `pytd` client using environment variables for the API key and server. It then demonstrates how to list available databases. For actual data querying or loading, ensure your Treasure Data API key is valid and you have existing databases/tables that the client can access."},"warnings":[{"fix":"Upgrade your Python environment to 3.9 or newer. The current minimum requirement for `pytd 2.4.0` is Python 3.10.","message":"Python 3.8 support was dropped in `pytd` version 2.0.0. Users on Python 3.8 or older must upgrade their Python environment to 3.9+ (3.10+ recommended) to use `pytd >= 2.0.0`.","severity":"breaking","affected_versions":">= 2.0.0"},{"fix":"Ensure your environment is compatible with `trino-python-client`. If you have direct dependencies on `presto-python-client`, consider migrating them or pinning `pytd` to `< 2.0.0`.","message":"The underlying SQL client for Trino/Presto queries migrated from `presto-python-client` to `trino-python-client` in `pytd` version 2.0.0. While `pytd` abstracts this, direct interaction with the underlying driver or specific environments with `presto-python-client` dependencies might be affected.","severity":"breaking","affected_versions":">= 2.0.0"},{"fix":"Update your dependency pins for `td-client`, `urllib3`, and `pyarrow` to meet or exceed the specified minimum versions.","message":"Version 2.4.0 introduced increased minimum version requirements for core dependencies: `td-client >= 1.7.0`, `urllib3 >= 2.0.0`, and `pyarrow >= 14.0.1`. Installing `pytd 2.4.0` with older pinned versions of these dependencies will likely cause conflicts.","severity":"breaking","affected_versions":">= 2.4.0"},{"fix":"Upgrade `pytd` to version 1.7.0 or newer to ensure full compatibility with Pandas 2.x. Also ensure your NumPy version is less than 2.0.0.","message":"`pytd` added support for Pandas 2.x in version 1.7.0. If using Pandas DataFrames with `pytd` versions older than 1.7.0, you might encounter compatibility issues with Pandas 2.x. It's recommended to upgrade `pytd` when working with recent Pandas versions.","severity":"gotcha","affected_versions":"< 1.7.0 with Pandas >= 2.0"},{"fix":"Consider using `max_workers` and `chunk_record_size` in `load_table_from_dataframe` or `BulkImportWriter` for optimized performance with large datasets. Review `BulkImportWriter` options like `commit_timeout` and `perform_wait_callback` for fine-tuning based on your needs.","message":"For large data imports using `Client.load_table_from_dataframe` or `BulkImportWriter`, `pytd` offers performance features like parallel uploads (`max_workers`, `chunk_record_size`) introduced in 1.7.0/1.9.0. Failing to utilize these parameters can lead to significantly slower uploads.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z","problems":[]}