{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"Ruby Client for TD-API","description":"Learn how to use the Ruby client library for Treasure API. List databases and tables, issue queries, manage jobs, and configure advanced options like proxies and timeouts.","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":"ruby-client-for-td-api","__idx":0},"children":["Ruby Client for TD-API"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This article explains how to use Ruby bindings for 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":["A table with some data."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Ruby 3.4 or newer"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"setup","__idx":2},"children":["Setup"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Add the following line to your ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Gemfile"]},"."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"ruby","header":{"controls":{"copy":{}}},"source":"gem 'td', \"~> 0.19.1\"\n","lang":"ruby"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["or run"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"gem install td-client\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"basic-use","__idx":3},"children":["Basic Use"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"list-databases-and-tables","__idx":4},"children":["List Databases and Tables"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"ruby","header":{"controls":{"copy":{}}},"source":"require 'td'\nrequire 'td-client'\n\ncln = TreasureData::Client.new(ENV['TD_API_KEY'])\n\ncln.databases.each { |db|\n  db.tables.each { |tbl|\n    p tbl.db_name\n    p tbl.table_name\n    p tbl.count\n  }\n}\n","lang":"ruby"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"issue-queries","__idx":5},"children":["Issue Queries"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The example below issues a query from a Ruby program. The query API is asynchronous--you can check for query completion by polling the job periodically (e.g. by issuing ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["job.finished?"]}," calls)."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"ruby","header":{"controls":{"copy":{}}},"source":"require 'td'\nrequire 'td-client'\ncln = TreasureData::Client.new(ENV['TD_API_KEY'])\njob = cln.query('testdb', 'SELECT COUNT(1) FROM www_access')\nuntil job.finished?\n  sleep 2\n  job.update_progress!\nend\njob.update_status!  # get latest info\njob.result_each { |row| p row }\n","lang":"ruby"},"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_each(&block)"]}," does not put the job result into memory. It iterates through the rows in a streaming fashion."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"list-and-get-the-status-of-jobs","__idx":6},"children":["List and Get the Status of Jobs"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following example lists and gets the status of jobs."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"ruby","header":{"controls":{"copy":{}}},"source":"require 'td'\nrequire 'td-client'\ncln = TreasureData::Client.new(ENV['TD_API_KEY'])\n\n# recent 20 jobs\ncln.jobs.length\n\n# recent 127 jobs of specific status\ncln.jobs(0, 127, 'running')\ncln.jobs(0, 127, 'success')\ncln.jobs(0, 127, 'error')\ncln.jobs(0, 127, 'killed')\n\n# get job status\ncln.job job_id\n\n# get job result\ncln.job_result job_id\n","lang":"ruby"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"advanced-use","__idx":7},"children":["Advanced Use"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"config","__idx":8},"children":["Config"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The Client API library constructor supports a number of options that can"," ","be provided as part of the optional ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["opts"]}," hash map to these methods:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["initialize"]},"(apikey, opts={}) (constructor)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Client.authenticate"]},"(user, password, opts={}) (class method)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Client.server_status"]},"(opts={}) (class method)"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"endpoint","__idx":9},"children":["Endpoint"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Add the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[":endpoint"]}," key to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["opts"]}," to provide an alternative endpoint for the API calls. For example, this might be a static IP address provided by Treasure Data on a case-by-case basis."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The default endpoint is: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://api.treasuredata.com"]}," and configure communication using SSL encryption over HTTPS; the same happens every time the provided endpoint is prefixed by ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"ruby","header":{"controls":{"copy":{}}},"source":"opts.merge({:endpoint => \"https://api-alternate.treasuredata.com\"})\n","lang":"ruby"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The endpoint can alternatively be provided by setting the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TD_API_SERVER"]}," environment variable. The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[":endpoint"]}," option takes precedence over the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TD_API_SERVER"]}," environment variable setting."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For communication through a Proxy, please see the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#proxy"},"children":["Proxy"]}," section below."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"connection-read-and-send-timeouts","__idx":10},"children":["Connection, Read, and Send Timeouts"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Three time outs can be specified:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Connection"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Read"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Send"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The timeouts are specified using the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[":connect_timeout"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[":read_timeout"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[":send_timeout"]}," keys respectively. The values for these keys is the number of seconds."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"ruby","header":{"controls":{"copy":{}}},"source":"opts.merge({:connect_timeout => 60,\n            :read_timeout    => 60,\n            :send_timeout    => 60})\n","lang":"ruby"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"ssl","__idx":11},"children":["SSL"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[":ssl"]}," key specifies whether SSL communication should be used when"," ","communicating with the default or custom endpoint."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This option is ignored if the use of SSL can be inferred from the URL scheme. For example, if the URL specifies https then SSL will be enabled."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"ssl-is-enabled-as-specified-by-the-ssl-option","__idx":12},"children":["SSL is enabled as specified by the :ssl option"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["opts.merge({:endpoint => \"api.treasuredata.com\", :ssl => true})"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"the-ssl-option-is-ignored-in-this-case","__idx":13},"children":["the ssl option is ignored in this case"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["opts.merge({:endpoint => \"https://api.treasuredata.com\", :ssl => false})"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"debug-mode","__idx":14},"children":["Debug Mode"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Enable debugging mode by setting the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TD_CLIENT_DEBUG"]}," environment variable:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"TD_CLIENT_DEBUG=1\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Currently debugging mode consists of:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["show request and response of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["HTTP"]},"/",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["HTTPS"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET"]}," REST API calls;"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["show request of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["HTTP"]},"/",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["HTTPS"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST"]},"/",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PUT"]}," REST API calls."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"proxy","__idx":15},"children":["Proxy"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If your network requires accessing our endpoint through a proxy (anonymous or"," ","private), the proxy settings can be specified using the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[":http_proxy"]}," option."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"anonymous-proxies","__idx":16},"children":["anonymous proxies"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["opts.merge({:http_proxy => \"http://myproxy.com:1234\"})"," ","opts.merge({:http_proxy => \"myproxy.com:1234\"})"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"private-proxies","__idx":17},"children":["private proxies"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["opts.merge({:http_proxy => \"https://username:password@myproxy.com:1234\"})"," ","opts.merge({:http_proxy => \"username:password@myproxy.com:1234\"})"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The proxy settings can alternatively be provided by setting the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["HTTP_PROXY"]}," environment variable. The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[":http_proxy"]}," option takes precedence over the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["HTTP_PROXY"]}," environment variable setting."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"additional-headers","__idx":18},"children":["Additional Header(s)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The Ruby client configures the communication with the Treasure Data REST API endpoints using the required HTTP Headers (including authorization, Date, User-Agent and Accept-Encoding, Content-Length, Content-Encoding where applicable). The user can specify any additional HTTP Header using the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[":headers"]}," option."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"ruby","header":{"controls":{"copy":{}}},"source":"opts.merge({:headers => \"MyHeader: myheadervalue;\"})\n","lang":"ruby"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To specify a custom User-Agent please see the option below."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"additional-user-agents","__idx":19},"children":["Additional User-Agent(s)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Add the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[":user_agent"]}," key to the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["opts"]}," hash to provide an additional user agent for all the interactions with the APIs."," ","The provided user agent string will be added to this default client library user agent ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TD-Client-Ruby: X.Y.Z"]}," where X.Y.Z is the version number of this Ruby Client library."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"api-reference","__idx":20},"children":["API Reference"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can find the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://www.rubydoc.info/gems/td-client/"},"children":["TD-Client API reference here"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"further-reading","__idx":21},"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-ruby"},"children":["GitHub Source Code"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/customer-data-platform/data-workbench/queries/hive/quickstart"},"children":["Hive Query Engine"]}]}]}]},"headings":[{"value":"Ruby Client for TD-API","id":"ruby-client-for-td-api","depth":1},{"value":"Prerequisites","id":"prerequisites","depth":2},{"value":"Setup","id":"setup","depth":2},{"value":"Basic Use","id":"basic-use","depth":2},{"value":"List Databases and Tables","id":"list-databases-and-tables","depth":3},{"value":"Issue Queries","id":"issue-queries","depth":3},{"value":"List and Get the Status of Jobs","id":"list-and-get-the-status-of-jobs","depth":3},{"value":"Advanced Use","id":"advanced-use","depth":2},{"value":"Config","id":"config","depth":3},{"value":"Endpoint","id":"endpoint","depth":3},{"value":"Connection, Read, and Send Timeouts","id":"connection-read-and-send-timeouts","depth":3},{"value":"SSL","id":"ssl","depth":3},{"value":"SSL is enabled as specified by the :ssl option","id":"ssl-is-enabled-as-specified-by-the-ssl-option","depth":1},{"value":"the ssl option is ignored in this case","id":"the-ssl-option-is-ignored-in-this-case","depth":1},{"value":"Debug Mode","id":"debug-mode","depth":3},{"value":"Proxy","id":"proxy","depth":3},{"value":"anonymous proxies","id":"anonymous-proxies","depth":1},{"value":"private proxies","id":"private-proxies","depth":1},{"value":"Additional Header(s)","id":"additional-headers","depth":3},{"value":"Additional User-Agent(s)","id":"additional-user-agents","depth":3},{"value":"API Reference","id":"api-reference","depth":2},{"value":"Further Reading","id":"further-reading","depth":2}],"frontmatter":{"seo":{"title":"Ruby Client for TD-API","description":"Learn how to use the Ruby client library for Treasure API. List databases and tables, issue queries, manage jobs, and configure advanced options like proxies and timeouts."}},"lastModified":"2026-06-01T09:09:59.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/apis/td-api/td-client/td-client-ruby","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}