Treasure Data API Library for Python

Warnings

• gotcha Confusing `td-client` with other Python libraries or tools named 'TDClient'. Be aware that 'td-client' (this library) is specifically for the Treasure Data REST API. Other packages like `pytd` offer different functionalities (e.g., pandas integration, direct Trino/Presto access), and 'TDClient' may also refer to a non-Python Student Aid Internet Gateway (SAIG) client.
  Fix: Verify that `td-client` is the correct library for your needs, especially if you intend to interact with the Treasure Data REST API. For pandas integration or direct database access, consider `pytd`.
• gotcha Incorrect API key or endpoint configuration can lead to authentication or connection errors. The client expects the API key to be passed via the `apikey` argument or read from the `TD_API_KEY` environment variable. The endpoint can be configured via the `endpoint` argument or `TD_API_SERVER` environment variable.
  Fix: Always use environment variables (`TD_API_KEY`, `TD_API_SERVER`) for sensitive information and flexible configuration. Ensure the API key is valid and the endpoint matches your Treasure Data region (e.g., `https://api.us01.treasuredata.com`).
• gotcha When importing CSV or TSV data, proper parsing of column types is crucial. The `upload_file` and `create_bulk_import` methods accept `dtypes` and `converters` parameters to specify how individual columns should be interpreted. The default behavior is 'guess', which might not always be accurate.
  Fix: Explicitly define `dtypes` (e.g., `{'col1': 'int'}`) or `converters` (e.g., `{'col2': int}`) when dealing with CSV/TSV data to ensure correct type conversion and prevent data integrity issues.
• gotcha SSL certificate verification is important for secure communication but can sometimes cause issues in certain environments. The library documentation recommends installing `certifi` for more robust SSL verification.
  Fix: Ensure `certifi` is installed (`pip install certifi`) to enable proper SSL certificate verification. If encountering SSL errors in a controlled environment, consult documentation for trusted certificate configurations rather than disabling verification outright.

Install

• pip install td-client Install core library
• pip install certifi Recommended for SSL certificate verification

Imports

• Client

  from tdclient import Client

  The primary client class for interacting with the Treasure Data API.
• tdclient

  import tdclient

  Commonly imported as a module to access its components, e.g., `tdclient.Client`.

Quickstart

This quickstart initializes the `td-client` with an API key (preferably from an environment variable) and then lists the 20 most recent jobs in your Treasure Data account. It demonstrates basic client setup and interaction.

import os
import tdclient

# Ensure TD_API_KEY environment variable is set with your Treasure Data API key.
# Optionally, set TD_API_SERVER to override the default endpoint (https://api.treasuredata.com).
# Example: export TD_API_KEY="YOUR_TREASURE_DATA_API_KEY"
# Example: export TD_API_SERVER="https://api.us01.treasuredata.com"

api_key = os.environ.get("TD_API_KEY", "")
api_server = os.environ.get("TD_API_SERVER", "https://api.treasuredata.com")

if not api_key:
    raise ValueError("TD_API_KEY environment variable not set. Please set it to your Treasure Data API key.")

try:
    with tdclient.Client(apikey=api_key, endpoint=api_server) as client:
        print("Listing recent jobs:")
        # Retrieve and print details of the 20 most recent jobs
        for job in client.jobs():
            print(f"  Job ID: {job.job_id}, Type: {job.type}, Status: {job.status}, Created At: {job.created_at}")
except Exception as e:
    print(f"An error occurred: {e}")