Ruby Client for TD-API

This article explains how to use Ruby bindings for REST API.

Prerequisites

• Basic knowledge of Treasure Data, including the Toolbelt .
• A table with some data. An example is provided in the What TD can do for you .
• Ruby 1.9 or newer

Setup

Add the following line to your Gemfile.

gem 'td', "~> 0.10.22"

or run

gem install td-client

Basic Use

List Databases and Tables

require 'td'
require 'td-client'
cln = TreasureData::Client.new(ENV['TD_API_KEY'])
cln.databases.each { |db|
  db.tables.each { |tbl|
    p tbl.db_name
    p tbl.table_name
    p tbl.count
  }
}

Issue Queries

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 job.finished? calls).

require 'td'
require 'td-client'
cln = TreasureData::Client.new(ENV['TD_API_KEY'])
job = cln.query('testdb', 'SELECT COUNT(1) FROM www_access')
until job.finished?
  sleep 2
  job.update_progress!
end
job.update_status!  # get latest info
job.result_each { |row| p row }

List and Get the Status of Jobs

The following example lists and gets the status of jobs.

require 'td'
require 'td-client'
cln = TreasureData::Client.new(ENV['TD_API_KEY'])

# recent 20 jobs
cln.jobs.length

# recent 127 jobs of specific status
cln.jobs(0, 127, 'running')
cln.jobs(0, 127, 'success')
cln.jobs(0, 127, 'error')
cln.jobs(0, 127, 'killed')

# get job status
cln.job job_id

# get job result
cln.job_result job_id

Advanced Use

Config

The Client API library constructor supports a number of options that can be provided as part of the optional opts hash map to these methods:

• initialize (apikey, opts={}) (constructor)
• Client.authenticate (user, password, opts={}) (class method)
• Client.server_status (opts={}) (class method)

Endpoint

Add the :endpoint key to 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.

The default endpoint is: https://api.treasuredata.com and cofigure communication using SSL encryption over HTTPS; the same happens every time the provided endpoint is prefixed by https.

Example

opts.merge({:endpoint => "https://api-alternate.treasuredata.com"})

The endpoint can alternatively be provided by setting the TD_API_SERVER environment variable. The :endpoint option takes precedence over the TD_API_SERVER environment variable setting.

For communication through a Proxy, please see the Proxy section below.

Connection, Read, and Send Timeouts

Three time outs can be specified:

• Connection
• Read
• Send

The timeoust are specified using the :connect_timeout, :read_timeout, :send_timeout keys respectively. The values for these keys is the number of seconds.

Example

opts.merge({:connect_timeout => 60,
            :read_timeout    => 60,
            :send_timeout    => 60})

SSL

The :ssl key specifies whether SSL communication should be used when communicating with the default or custom endpoint.

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.

Example

# SSL is enabled as specified by the :ssl option
opts.merge({:endpoint => "api.treasuredata.com", :ssl => true})

# the ssl option is ignored in this case
opts.merge({:endpoint => "https://api.treasuredata.com", :ssl => false})

Debug Mode

Enable debugging mode by setting the TD_CLIENT_DEBUG environment variable:

TD_CLIENT_DEBUG=1

Currently debugging mode consists of:

• show request and response of HTTP / HTTPS GET REST API calls;
• show request of HTTP / HTTPS POST / PUT REST API calls.

Proxy

If your network requires accessing our endpoint through a proxy (anonymous or private), the proxy settings can be specified using the :http_proxy option.

Example

# anonymous proxies
opts.merge({:http_proxy => "http://myproxy.com:1234"})
opts.merge({:http_proxy => "myproxy.com:1234"})

# private proxies
opts.merge({:http_proxy => "https://username:password@myproxy.com:1234"})
opts.merge({:http_proxy => "username:password@myproxy.com:1234"})

The proxy settings can alternatively be provided by setting the HTTP_PROXY environment variable. The :http_proxy option takes precedence over the HTTP_PROXY environment variable setting.

Additional Header(s)

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 :headers option.

Example

opts.merge({:headers => "MyHeader: myheadervalue;"})

To specify a custom User-Agent please see the option below.

Additional User-Agent(s)

Add the :user_agent key to the 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 TD-Client-Ruby: X.Y.Z where X.Y.Z is the version number of this Ruby Client library.

API Reference

You can find the TD-Client API reference here.

Further Reading

• GitHub Source Code
• The Hive Query Engine