LoginSignup
19
18

More than 5 years have passed since last update.

ドワンゴAdvent Calendar 2014Day 12
@shoito(Sho Ito)

ElasticsearchのREST API共通オプション

Posted at

はじめに

ElasticsearchはREST APIを提供していますが、それらにはいくつかの共通オプションが提供されています。
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'

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

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

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

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

format

REST APIの出力フォーマットとしては、JSON, YAML, Smile, CBORがサポートされています。
formatオプションを指定しなかった場合はJSON形式で出力されます。
リファレンスには、SmileとCBORの記述は見当たりませんがXContent周りのenumのコードを読むとサポートされているフォーマットを確認できます。

まずはデフォルトのJSONの例がこちらになります。
なお、各フォーマットでの出力結果を読みやすくするために、prettyオプションを付与しています。

curl 'http://localhost:9200/_cluster/stats?pretty&format=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の例がこちらになります。

curl 'http://localhost:9200/_cluster/stats?pretty&format=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の例がこちらです。
SmileはJSONベースのデータフォーマットですが、今のところRFCはなく、先頭にスマイルマーク:)があるのが特徴のようです。

curl 'http://localhost:9200/_cluster/stats?pretty&format=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の例がこちらです。
CBOR(Concise Binary Object Representation)は小さなコード/メッセージサイズでかつJSONベースの拡張可能なデータフォーマットです。
バージョン1.2.0からサポートされた、比較的新しく加わったフォーマットのようです。

curl 'http://localhost:9200/_cluster/stats?pretty&format=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'

{
  "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'

{
  "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以下を読むと詳細を把握できると思います。

19
18
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
19
18