{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-@l10n/ja/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Java Client for TD-API","description":"Learn how to use the Java client library for Treasure API. Submit Hive and Trino queries, check job status, retrieve results, and perform bulk imports.","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":"java-client-for-td-api","__idx":0},"children":["Java Client for TD-API"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Using the Java client for  ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/td-api"},"children":["Treasure API"]},", you can:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Submit Hive/Trino(Presto) queries to Treasure Data."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Check the status of jobs (queries)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Retrieve query results."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Check the information of databases and tables."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Note that td-client-java 0.8.0 requires Java 1.8 or higher. And td-client-java-0.7.x requires Java7."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"install","__idx":1},"children":["Install"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can download a Jar file (td-client-java-(version)-shade.jar) from ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://repo1.maven.org/maven2/com/treasuredata/client/td-client/"},"children":["here"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For the information about the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://github.com/treasure-data/td-client-java/tree/0.7.x"},"children":["older versions"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use the following dependency settings for either Maven or the Standalone Jar file."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"xml","data-title":"Maven","header":{"title":"Maven","controls":{"copy":{}}},"source":"<dependency>\n  <groupId>com.treasuredata.client</groupId>\n  <artifactId>td-client</artifactId>\n  <version>(version)</version>\n</dependency>\n\n<!-- If you are not using any slf4 logger binder, add the following dependency, too. -->\n<dependency>\n  <groupId>ch.qos.logback</groupId>\n  <artifactId>logback-classic</artifactId>\n  <version>1.2.3</version>\n</dependency>\n","lang":"xml"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"xml","data-title":"Standalone Jar","header":{"title":"Standalone Jar","controls":{"copy":{}}},"source":"<dependency>\n  <groupId>com.treasuredata.client</groupId>\n  <artifactId>td-client</artifactId>\n  <version>(version)</version>\n  <classifier>shade</classifier>\n</dependency>\n","lang":"xml"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"basic-use","__idx":2},"children":["Basic Use"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"set-api-key","__idx":3},"children":["Set API Key"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Option 1 : Config file"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To use td-client-java, you need to set your API key in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["$HOME/.td/td.conf"]}," file."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"xml","header":{"controls":{"copy":{}}},"source":"[account]\n  user = (your TD account e-mail address)\n  apikey = <YOUR_API_KEY>\n","lang":"xml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Option 2: Environment variable"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["It is also possible to use the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TD_API_KEY"]}," environment variable. Add the following configuration to your shell configuration ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".bash_profile"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".zprofile"]},", etc."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"shell","header":{"controls":{"copy":{}}},"source":"export TD_API_KEY = YOUR_API_KEY\n","lang":"shell"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For Windows, add the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TD_API_KEY"]}," environment variable in the user preference panel."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"example-code","__idx":4},"children":["Example Code"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"java","header":{"controls":{"copy":{}}},"source":"import com.treasuredata.client.*;\nimport com.google.common.base.Function;\nimport org.msgpack.core.MessagePack;\nimport org.msgpack.core.MessageUnpacker;\nimport org.msgpack.value.ArrayValue;\n...\n\n// Create a new TD client by using configurations in $HOME/.td/td.conf\nTDClient client = TDClient.newClient();\ntry {\n\n// Retrieve database and table names\nList<TDDatabase> databaseNames = client.listDatabases();\nfor(TDDatabase db : databaseNames) {\n   System.out.println(\"database: \" + db.getName());\n   for(TDTable table : client.listTables(db.getName())) {\n      System.out.println(\" table: \" + table);\n   }\n}\n\n// Submit a new Trino(Presto) query (for Hive, use TDJobRequest.newHiveQuery)\nString jobId = client.submit(TDJobRequest.newTrinoQuery(\"sample_datasets\", \"select count(1) from www_access\"));\n\n// Wait until the query finishes\nExponentialBackOff backoff = new ExponentialBackOff();\nTDJobSummary job = client.jobStatus(jobId);\nwhile(!job.getStatus().isFinished()) {\n  Thread.sleep(backoff.nextWaitTimeMillis());\n  job = client.jobStatus(jobId);\n}\n\n// Read the detailed job information\nTDJob jobInfo = client.jobInfo(jobId);\nSystem.out.println(\"log:\\n\" + jobInfo.getCmdOut());\nSystem.out.println(\"error log:\\n\" + jobInfo.getStdErr());\n\n// Read the job results in msgpack.gz format\nclient.jobResult(jobId, TDResultFormat.MESSAGE_PACK_GZ, new Function<InputStream, Object>() {\n  @Override\n  public Object apply(InputStream input) {\n  try {\n    MessageUnpacker unpacker = MessagePack.newDefaultUnpacker(new GZIPInputStream(input));\n    while(unpacker.hasNext()) {\n       // Each row of the query result is array type value (e.g., [1, \"name\", ...])\n       ArrayValue array = unpacker.unpackValue().asArrayValue();\n       int id = array.get(0).asIntegerValue().toInt();\n    }\n  }\n});\n\n...\n\n}\nfinally {\n  // Never forget to close the TDClient.\n  client.close();\n}\n","lang":"java"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"bulk-upload","__idx":5},"children":["Bulk upload"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"java","header":{"controls":{"copy":{}}},"source":"// Create a new TD client by using configurations in $HOME/.td/td.conf\nTDClient client = TDClient.newClient();\n\nFile f = new File(\"./sess/part01.msgpack.gz\");\n\nTDBulkImportSession session = client.createBulkImportSession(\"session_name\", \"database_name\", \"table_name\");\nclient.uploadBulkImportPart(session.getName(), \"session_part01\", f);\n","lang":"java"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"data-connector-bulk-loading","__idx":6},"children":["Data Connector Bulk Loading"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"java","header":{"controls":{"copy":{}}},"source":"// Create a new TD client by using configurations in $HOME/.td/td.conf\nTDClient client = TDClient.newClient();\n\nclient.startBulkLoadSession(\"session_name\");\n","lang":"java"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"advanced-use","__idx":7},"children":["Advanced Use"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"proxy-server","__idx":8},"children":["Proxy Server"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you need to access Web through proxy, add the following configuration to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["$HOME/.td/td.conf"]}," file:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"[account]\n  user = (your TD account e-mail address)\n  apikey = (your API key)\n  td.client.proxy.host = (optional: proxy host name)\n  td.client.proxy.port = (optional: proxy port number)\n  td.client.proxy.user = (optional: proxy user name)\n  td.client.proxy.password = (optional: proxy password)\n"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"configuring-tdclient","__idx":9},"children":["Configuring TDClient"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To configure TDClient, use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TDClient.newBuilder()"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"java","header":{"controls":{"copy":{}}},"source":"TDClient client = TDClient\n    .newBuilder()\n    .setApiKey(\"(your api key)\")\n    .setEndpoint(\"api.ybi.idcfcloud.net\")   // For using a non-default endpoint\n    .build()\n","lang":"java"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["It is also possible to set the configuration with a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Properties"]}," object:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"java","header":{"controls":{"copy":{}}},"source":"Properties prop = new Properties();\n// Set your own properties\nprop.setProperty(\"td.client.retry.limit\", \"10\");\n...\n\n// This overrides the default configuration parameters with the given Properties\nTDClient client = TDClient.newBuilder().setProperties(prop).build();\n","lang":"java"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"configuration-parameters","__idx":10},"children":["Configuration Parameters"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The precedence of the configuration parameters are as follows:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Properties object passed to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TDClient.newBuilder().setProperties(Properties p)"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Parameters written in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["$HOME/.td/td.conf"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["System properties (passed with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["-D"]}," option when launching JVM)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Environment variable (only for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TD_API_KEY"]}," parameter)"]}]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Key"},"children":["Key"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Default Value"},"children":["Default Value"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["apikey"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["API key to access Treasure Data. You can also set this via ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TD_API_KEY"]}," environment variable."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["user"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Account e-mail address (unnecessary if ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["apikey"]}," is set)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["password"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Account password (unnecessary if ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["apikey"]}," is set)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["td.client.proxy.host"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["(optional) Proxy host e.g., \"myproxy.com\""]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["td.client.proxy.port"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["(optional) Proxy port e.g., \"80\""]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["td.client.proxy.user"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["(optional) Proxy user"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["td.client.proxy.password"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["(optional) Proxy password"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["td.client.usessl"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["true"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["(optional) Use SSL encryption"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["td.client.retry.limit"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["7"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["(optional) The maximum number of API request retry"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["td.client.retry.initial-interval"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["500"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["(optional) backoff retry interval = (interval) * (multiplier) ^ (retry count)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["td.client.retry.max-interval"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["60000"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["(optional) max retry interval"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["td.client.retry.multiplier"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["2.0"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["(optional) retry interval multiplier"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["td.client.connect-timeout"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["15000"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["(optional) connection timeout before reaching the API"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["td.client.read-timeout"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["60000"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["(optional) timeout when no data is coming from API"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["td.client.connection-pool-size"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["64"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["(optional) Connection pool size"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["td.client.endpoint"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["api.treasuredata.com"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["(optional) TD REST API endpoint name"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["td.client.port"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["80 for non-SSL, 443 for SSL connection"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["(optional) Treasure API port number"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"further-reading","__idx":11},"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-java"},"children":["GitHub Source Code"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://github.com/treasure-data/td-client-java/blob/master/CHANGES.txt"},"children":["Version information"]}]}]}]},"headings":[{"value":"Java Client for TD-API","id":"java-client-for-td-api","depth":1},{"value":"Install","id":"install","depth":2},{"value":"Basic Use","id":"basic-use","depth":2},{"value":"Set API Key","id":"set-api-key","depth":3},{"value":"Example Code","id":"example-code","depth":3},{"value":"Bulk upload","id":"bulk-upload","depth":3},{"value":"Data Connector Bulk Loading","id":"data-connector-bulk-loading","depth":3},{"value":"Advanced Use","id":"advanced-use","depth":2},{"value":"Proxy Server","id":"proxy-server","depth":3},{"value":"Configuring TDClient","id":"configuring-tdclient","depth":3},{"value":"Configuration Parameters","id":"configuration-parameters","depth":3},{"value":"Further Reading","id":"further-reading","depth":2}],"frontmatter":{"seo":{"title":"Java Client for TD-API","description":"Learn how to use the Java client library for Treasure API. Submit Hive and Trino queries, check job status, retrieve results, and perform bulk imports."}},"lastModified":"2026-06-01T09:09:59.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/ja/apis/td-api/td-client/td-client-java","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}