# 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](https://toolbelt.treasuredata.com/).
- A table with some data.
- Ruby 1.9 or newer


## Setup

Add the following line to your `Gemfile`.


```bash
gem 'td', "~> 0.10.22"
```

or run


```bash
gem install td-client
```

## Basic Use

### List Databases and Tables


```ruby
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).


```ruby
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 }
```

div
b
td-client vs pytd
`job.result_each(&block)` does not put the job result into memory. It iterates through the rows in a streaming fashion.

### List and Get the Status of Jobs

The following example lists and gets the status of jobs.


```ruby
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**


```ruby
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](#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**


```ruby
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:


```bash
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**


```ruby
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](https://www.rubydoc.info/gems/td-client/).

## Further Reading

- [GitHub Source Code](https://github.com/treasure-data/td-client-ruby)
- The [Hive Query Engine](https://docs.treasuredata.com/display/public/PD/About+Hive+Query+Engine)