ElasticsearchのREST API共通オプション

##はじめに
ElasticsearchはREST APIを提供していますが、それらにはいくつかの[共通オプション](http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/common-options.html)が提供されています。
http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/common-options.html

この投稿では下記オプションを紹介します。

- pretty
 - 改行/インデントするなどして整形して出力する
 - true: 整形する
 - false: 整形しない
 - default: true
- format
 - 出力フォーマットを指定する
 - json,yaml,smile,cbor
- human
 - 人間が読みやすい形式の出力を含めるか指定する
 - true: 単位補正(msec→sec,bytes→kbなど)された形式を出力に含める
 - false: 単位補正したものを加えない
 - default: false
- flat_settings
 - 設定値をフラットな形式か読みやすい形式で出力するか指定する
 - true: 設定をフラットな形式で出力する
 - false: 設定を人間が読みやすい形式で出力する
 - default: false
- case
 - レスポンスのフィールド名をキャメルケースにするか指定する
 - camelCase: フィールド名をキャメルケースで出力する
 - default: 指定なしならスネークケース(underscore casing)

## pretty
これはデバッグ用途のオプションであり、trueの場合はAPIの出力に改行やインデントを追加し、人間が読みやすい形に整形して出力されます。
`pretty`, `pretty=true`

prettyオプションがない場合は次のように改行/インデントを含まず結果は1行で返されます。

curl 'http://localhost:9200/_stats'

```json
{"_shards":{"total":0,"successful":0,"failed":0},"_all":{"primaries":{},"total":{}},"indices":{}}
```

prettyを指定すると以下のように結果は整形して返されます。

curl 'http://localhost:9200/_stats?pretty'

```json
{
  "_shards" : {
    "total" : 0,
    "successful" : 0,
    "failed" : 0
  },
  "_all" : {
    "primaries" : { },
    "total" : { }
  },
  "indices" : { }
}
```

## format
REST APIの出力フォーマットとしては、[JSON](http://www.ietf.org/rfc/rfc4627.txt), [YAML](http://www.yaml.org/spec/1.2/spec.html), [Smile](http://wiki.fasterxml.com/SmileFormat), [CBOR](https://tools.ietf.org/html/rfc7049)がサポートされています。
formatオプションを指定しなかった場合はJSON形式で出力されます。
リファレンスには、SmileとCBORの記述は見当たりませんが[XContent周りのenumのコード](https://github.com/elasticsearch/elasticsearch/blob/master/src/main/java/org/elasticsearch/common/xcontent/XContentType.java)を読むとサポートされているフォーマットを確認できます。

まずはデフォルトの[JSON](http://www.ietf.org/rfc/rfc4627.txt)の例がこちらになります。
なお、各フォーマットでの出力結果を読みやすくするために、prettyオプションを付与しています。

curl 'http://localhost:9200/_cluster/stats?pretty&format=json'

```json
{
  "timestamp" : 1418302754693,
  "cluster_name" : "elasticsearch",
  "status" : "green",
  "indices" : {
    "count" : 0,
    "shards" : { },
    "docs" : {
      "count" : 0,
      "deleted" : 0
    },
...(略)
    "fs" : {
      "total_in_bytes" : 248391270400,
      "free_in_bytes" : 25177878528,
      "available_in_bytes" : 24915734528,
      "disk_reads" : 0,
      "disk_writes" : 0,
      "disk_io_op" : 0,
      "disk_read_size_in_bytes" : 0,
      "disk_write_size_in_bytes" : 0,
      "disk_io_size_in_bytes" : 0
    },
    "plugins" : [ ]
  }
}

```

次に、[YAML](http://www.yaml.org/)の例がこちらになります。

curl 'http://localhost:9200/_cluster/stats?pretty&format=yaml'

```yaml
---
timestamp: 1418302878846
cluster_name: "elasticsearch"
status: "green"
indices:
  count: 0
  shards: {}
  docs:
    count: 0
    deleted: 0
...(略)
  fs:
    total_in_bytes: 248391270400
    free_in_bytes: 25183444992
    available_in_bytes: 24921300992
    disk_reads: 0
    disk_writes: 0
    disk_io_op: 0
    disk_read_size_in_bytes: 0
    disk_write_size_in_bytes: 0
    disk_io_size_in_bytes: 0
  plugins: []
```

次に[Smile](http://wiki.fasterxml.com/SmileFormat)の例がこちらです。
SmileはJSONベースのデータフォーマットですが、今のところRFCはなく、先頭にスマイルマーク`:)`があるのが特徴のようです。

curl 'http://localhost:9200/_cluster/stats?pretty&format=smile'

```smile
:)
??timestamp%%.U??cluster_nameLelasticsearch?statusDgreen?indices??count??shards???docs?D??deleted???store??size_in_bytes??throttle_time_in_millis???fielddata??memory_size_in_bytes??evictions???filter_cache?L?M???id_cache?L???completion?I???segments?D??memory_in_bytes??index_writer_memory_in_bytes??index_writer_max_memory_in_bytes??version_map_memory_in_bytes??fixed_bit_set_memory_in_bytes???percolate??total??time_in_millis??current?L??memory_sizeB-1b?queries????nodes?D?Xmaster_only??data_only??master_dataclient???versions?D1.4.1??os??available_processorsȂmem??total_in_bytes%@???cpu???vendorDIntel?modelLMacBookAir4,2?mhz$8??total_coresȌtotal_socketsȏcores_per_socket$??cache_size_in_bytes?D?????process?g??percent???open_file_descriptors??min$??max$??avg$????jvm??max_uptime_in_millis$=z?b???versionD1.8.0?vm_name`Java HotSpot(TM) 64-Bit Server VM?vm_versionG25.0-b70?vm_vendorQOracle CorporationD???e??heap_used_in_bytes$H>_??heap_max_in_bytes$=@???threads$???fs?f%u(`??free_in_bytes%w??available_in_bytes%s)??disk_reads??disk_writes??disk_io_op??disk_read_size_in_bytes??disk_write_size_in_bytes??disk_io_size_in_bytes???plugins????
```

最後に[CBOR](https://tools.ietf.org/html/rfc7049)の例がこちらです。
CBOR(Concise Binary Object Representation)は小さなコード/メッセージサイズでかつJSONベースの拡張可能なデータフォーマットです。
[バージョン1.2.0からサポートされた](https://github.com/elasticsearch/elasticsearch/issues/4860)、比較的新しく加わったフォーマットのようです。

curl 'http://localhost:9200/_cluster/stats?pretty&format=cbor'

```cbor 
?itimestamp9?lcluster_namemelasticsearchfstatusegreengindices?ecountfshards??ddocs?ecountgdeleted?estore?msize_in_byteswthrottle_time_in_millis?ifielddata?tmemory_size_in_bytesievictions?lfilter_cache?tmemory_size_in_bytesievictions?hid_cache?tmemory_size_in_bytes?jcompletion?msize_in_bytes?hsegments?ecountomemory_in_bytesxindex_writer_memory_in_bytesx index_writer_max_memory_in_bytesxersion_map_memory_in_bytesxfixed_bit_set_memory_in_bytes?ipercolate?etotalntime_in_millisgcurrenttmemory_size_in_bytes kmemory_sizec-1bgqueries??enodes?ecount?etotalkmaster_onlyidata_onlykmaster_datafclient?hversions?e1.4.1?bos?tavailable_processorscmem?ntotal_in_bytesccpu??fvendoreIntelemodelmMacBookAir4,2cmhktotal_coresmtotal_socketspcores_per_socketscache_size_in_bytesecount???gprocess?ccpu?gpercent?uopen_file_descriptors?cmin?cmax?cavg???cjvm?tmax_uptime_in_millisʾhversions??gversione1.8.0gvm_namex!Java HotSpot(TM) 64-Bit Server VMjvm_versionh25.0-b70ivm_vendorrOracle Corporationecount??cmem?rheap_used_in_bytesC??qheap_max_in_bytes=??gthreads-?bfs?ntotal_in_bytes?Fmfree_in_bytesܛravailable_in_bytes?pjdisk_readskdisk_writesjdisk_io_opwdisk_read_size_in_bytesxdisk_write_size_in_bytesudisk_io_size_in_bytes?gplugins????
```

## human
これは、人間が読みやすい形式の出力を含めるか指定するオプションです。
下記の結果に含まれる`"max_uptime_in_millis":"6195482"`に対する`"max_uptime":"1.7h"`、`"heap_used_in_bytes": 99817208`に対する`"heap_used":"95.1m"`が`human`により追加されたフィールドです。

curl 'http://localhost:9200/_cluster/stats?pretty&format=json&human'

```
{
  "timestamp" : 1418308863094,
  "cluster_name" : "elasticsearch",
  "status" : "green",
...(略)
    "jvm" : {
      "max_uptime" : "1.7h",
      "max_uptime_in_millis" : 6195482,
      "versions" : [ {
        "version" : "1.8.0",
        "vm_name" : "Java HotSpot(TM) 64-Bit Server VM",
        "vm_version" : "25.0-b70",
        "vm_vendor" : "Oracle Corporation",
        "count" : 1
      } ],
      "mem" : {
        "heap_used" : "95.1mb",
        "heap_used_in_bytes" : 99817208,
        "heap_max" : "990.7mb",
        "heap_max_in_bytes" : 1038876672
      },
      "threads" : 46
    },
...(略)
}
```

## flat_settings
設定値をフラットな形式か読みやすい形式で出力するか指定するオプションです。
まず、オプションなしの例がこちらになります。

curl 'http://localhost:9200/_nodes/settings?pretty&format=json'

```javascript
{
  "cluster_name" : "elasticsearch",
  "nodes" : {
    "QOdnUTwoQpShVYbR8KYyNw" : {
      "name" : "Atum",
...(略)
      "settings" : {
        "name" : "Atum",
        "path" : {
          "logs" : "/Users/shoito/es-sandbox/elasticsearch-1.4.1/logs",
          "home" : "/Users/shoito/es-sandbox/elasticsearch-1.4.1"
        },
        "http" : {
          "cors" : {
            "enabled" : "true"
          }
        },
        "cluster" : {
          "name" : "elasticsearch"
        },
        "client" : {
          "type" : "node"
        },
        "foreground" : "yes"
      }
    }
  }
}
```

次にflast_settingsを追加し、settings以下の値をフラットな形式で取得する例です。

curl 'http://localhost:9200/_nodes/settings?pretty&format=json&flat_settings'

```javascript
{
  "cluster_name" : "elasticsearch",
  "nodes" : {
    "QOdnUTwoQpShVYbR8KYyNw" : {
      "name" : "Atum",
...(略)
      "settings" : {
        "path.home" : "/Users/shoito/es-sandbox/elasticsearch-1.4.1",
        "foreground" : "yes",
        "http.cors.enabled" : "true",
        "name" : "Atum",
        "cluster.name" : "elasticsearch",
        "path.logs" : "/Users/shoito/es-sandbox/elasticsearch-1.4.1/logs",
        "client.type" : "node"
      }
    }
  }
}
```

## case
レスポンスのフィールド名をキャメルケースにするか指定するオプションで、`?case=camelCase`のようにします。
このオプション指定がない場合は、デフォルトのスネークケース(アンダースコアケース)が指定された挙動になります。

下記はキャメルケースで結果を取得した例であり、`transportAddress`が`transport_address`でなくなったことが確認できます。

curl 'http://localhost:9200/_nodes/settings?pretty&format=json&flat_settings&case=camelCase'

```
{
  "cluster_name" : "elasticsearch",
  "nodes" : {
    "QOdnUTwoQpShVYbR8KYyNw" : {
      "name" : "Atum",
      "transportAddress" : "inet[/192.168.100.111:9300]",
...(略)
      }
    }
  }
}

```

## 最後に
REST APIに適用できる共通オプションをいくつかピックアップして紹介しました。
私自身はprettyとhumanのオプションはよく利用しています。
おかげでパイプを使ってjqに結果を渡す必要もありません。

ちなみに、ElasticsearchにどんなREST APIがあるか知りたい場合は、リファレンスを読むか、Githubリポジトリにある[rest-api-spec](https://github.com/elasticsearch/elasticsearch/tree/master/rest-api-spec/api)以下を読むと詳細を把握できると思います。