{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"Python Client for TD-API","description":"Learn how to use the Python client library (td-client) for Treasure API. List databases, issue queries, manage jobs, and import data via streaming or bulk import.","siteUrl":"https://docs.treasuredata.com","lang":"en-US","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"python-client-for-td-api","__idx":0},"children":["Python Client for TD-API"]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"TD-Client vs. PyTD"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The td-client for Python wraps the functionality of the TD-API REST API; its capability is limited to what the TD-API can do. The ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/tools/pytd"},"children":["pytd"]}," library has direct access to trino(presto) and the plazma backend as well as multiple data ingestion methods and a variety of utility functions."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This article will explain how to use Python bindings for the TD-API REST API."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"prerequisites","__idx":1},"children":["Prerequisites"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Basic knowledge of Treasure Data, including the"," ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://toolbelt.treasuredata.com/"},"children":["Toolbelt"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Python 3.5+"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"installation","__idx":2},"children":["Installation"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The Python bindings are released on ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://pypi.org/project/td-client/"},"children":["PyPI"]}," ","as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["td-client"]},". You can install the"," ","package from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pip"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["easy_install"]},"."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"shell","header":{"controls":{"copy":{}}},"source":"pip install td-client\n","lang":"shell"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"list-databases-and-tables","__idx":3},"children":["List Databases and Tables"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The example below lists the databases and tables."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"python","header":{"controls":{"copy":{}}},"source":"import os\nimport tdclient\napikey = os.getenv(\"TD_API_KEY\")\nwith tdclient.Client(apikey) as client:\n    for db in client.databases():\n        for table in db.tables():\n            print(table.db_name)\n            print(table.table_name)\n            print(table.count)\n","lang":"python"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"issue-queries","__idx":4},"children":["Issue Queries"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The example below issues a SQL query from a Python program. The query API is asynchronous--you can check for query completion by polling the job periodically (i.e. by issuing ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["job.finished"]}," calls)."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"python","header":{"controls":{"copy":{}}},"source":"import os\nimport tdclient\napikey = os.getenv(\"TD_API_KEY\")\nwith tdclient.Client(apikey) as client:\n    job = client.query(\"sample_datasets\", \"SELECT COUNT(1) FROM www_access\")\n    # sleep until job's finish\n    job.wait()\n    for row in job.result():\n        print(row)\n","lang":"python"},"children":[]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Streaming Results"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["job.result()"]}," does not put the job result into memory. It iterates through the rows in a streaming fashion."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you would like to get the result’s schema, you need to call"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["job.result_schema"]}," after job finished."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"list-and-get-the-status-of-jobs","__idx":5},"children":["List and Get the Status of Jobs"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The example below lists and gets the status of jobs."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"python","header":{"controls":{"copy":{}}},"source":"import os\nimport tdclient\napikey = os.getenv(\"TD_API_KEY\")\nwith tdclient.Client(apikey) as client:\n    # recent 20 jobs\n    len(client.jobs())\n\n    # recent 127 jobs of specific status\n    client.jobs(0, 127, \"running\")\n    client.jobs(0, 127, \"success\")\n    client.jobs(0, 127, \"error\")\n    client.jobs(0, 127, \"killed\")\n\n    # get job status\n    client.job(job_id)\n\n    # get job result\n    client.job_result(job_id)\n","lang":"python"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"importing-data","__idx":6},"children":["Importing Data"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["There are two ways to import data via the Treasure API: in a streaming manner, similar to ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://www.fluentd.org/"},"children":["fluentd"]},", or in a batch manner via bulk import."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"streaming-import","__idx":7},"children":["Streaming Import"]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Streaming Import Delay"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Importing data in a streaming manner requires a certain amount of time to be ready to query since schema update will be executed with delay."]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"python","header":{"controls":{"copy":{}}},"source":"import sys\nimport tdclient\n\nwith tdclient.Client() as td:\n    for file_name in sys.argv[:1]:\n        td.import_file(\"mydb\", \"mytbl\", \"csv\", file_name)\n","lang":"python"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"bulk-import","__idx":8},"children":["Bulk Import"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Importing data into Treasure Data in batch manner."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"python","header":{"controls":{"copy":{}}},"source":"import sys\nimport tdclient\nimport uuid\nimport warnings\n\nif len(sys.argv) <= 1:\n    sys.exit(0)\n\nwith tdclient.Client() as client:\n    session_name = \"session-{}\".format(uuid.uuid1())\n    bulk_import = client.create_bulk_import(session_name, \"mydb\", \"mytbl\")\n    try:\n        for file_name in sys.argv[1:]:\n            part_name = \"part-{}\".format(file_name)\n            bulk_import.upload_file(part_name, \"json\", file_name)\n        bulk_import.freeze()\n    except:\n        bulk_import.delete()\n        raise\n    bulk_import.perform(wait=True)\n    if 0 < bulk_import.error_records:\n        warnings.warn(\"detected {} error records.\".format(bulk_import.error_records))\n    if 0 < bulk_import.valid_records:\n        print(\"imported {} records.\".format(bulk_import.valid_records))\n    else:\n        raise(RuntimeError(\"no records have been imported: {}\".format(bulk_import.name)))\n    bulk_import.commit(wait=True)\n    bulk_import.delete()\n\n","lang":"python"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"api-reference","__idx":9},"children":["API Reference"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Both the Python td-client API reference and file import parameters documentation can be found at ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://tdclient.readthedocs.io/"},"children":["tdclient.readthedocs.io"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"further-reading","__idx":10},"children":["Further Reading"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://github.com/treasure-data/td-client-python"},"children":["GitHub Repo"]}," - Source code for td-client python."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://tdclient.readthedocs.io/"},"children":["Python td-client API Reference"]}," - readthedocs library reference."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/td-api"},"children":["Treasure API Reference"]}," - REST API this td-client library wraps."]}]}]},"headings":[{"value":"Python Client for TD-API","id":"python-client-for-td-api","depth":1},{"value":"Prerequisites","id":"prerequisites","depth":2},{"value":"Installation","id":"installation","depth":2},{"value":"List Databases and Tables","id":"list-databases-and-tables","depth":2},{"value":"Issue Queries","id":"issue-queries","depth":2},{"value":"List and Get the Status of Jobs","id":"list-and-get-the-status-of-jobs","depth":2},{"value":"Importing Data","id":"importing-data","depth":2},{"value":"Streaming Import","id":"streaming-import","depth":3},{"value":"Bulk Import","id":"bulk-import","depth":3},{"value":"API Reference","id":"api-reference","depth":2},{"value":"Further Reading","id":"further-reading","depth":2}],"frontmatter":{"seo":{"title":"Python Client for TD-API","description":"Learn how to use the Python client library (td-client) for Treasure API. List databases, issue queries, manage jobs, and import data via streaming or bulk import."}},"lastModified":"2026-06-01T09:09:59.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/apis/td-api/td-client/td-client-python","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}