ElasticsearchのAPI ConventionsのCommon options

ElasticsearchのAPI ConventionsのCommon optionsについて記す。

公式ドキュメント Common options を参考にした。

www.elastic.co

検証環境: Elasticsearch 6.0.0-rc1

以下に示すオプションはすべてのREST APIに適用できる。

Pretty Results

リクエストに ?pretty=true を追加すると、整形されたフォーマットのJSONが返ってくる。また、?format=yamlとするとyaml形式で返すように設定できる。

bash-3.2$ curl -XGET 'localhost:9200/bank/_search' -H 'Content-Type: application/json' -d'
>  {
>    "query": { "match": { "account_number": 20 } }
>  }
>  '
{"took":86,"timed_out":false,"_shards":{"total":5,"successful":5,"skipped":0,"failed":0},"hits":{"total":1,"max_score":1.0,"hits":[{"_index":"bank","_type":"account","_id":"20","_score":1.0,"_source":{"account_number":20,"balance":16418,"firstname":"Elinor","lastname":"Ratliff","age":36,"gender":"M","address":"282 Kings Place","employer":"Scentric","email":"elinorratliff@scentric.com","city":"Ribera","state":"WA"}}]}}bash-3.2$ 
bash-3.2$ curl -XGET 'localhost:9200/bank/_search?pretty' -H 'Content-Type: application/json' -d'
>  {
>    "query": { "match": { "account_number": 20 } }
>  }
>  '
{
  "took" : 2,
  "timed_out" : false,
  "_shards" : {
    "total" : 5,
    "successful" : 5,
    "skipped" : 0,
    "failed" : 0
  },
  "hits" : {
    "total" : 1,
    "max_score" : 1.0,
    "hits" : [
      {
        "_index" : "bank",
        "_type" : "account",
        "_id" : "20",
        "_score" : 1.0,
        "_source" : {
          "account_number" : 20,
          "balance" : 16418,
          "firstname" : "Elinor",
          "lastname" : "Ratliff",
          "age" : 36,
          "gender" : "M",
          "address" : "282 Kings Place",
          "employer" : "Scentric",
          "email" : "elinorratliff@scentric.com",
          "city" : "Ribera",
          "state" : "WA"
        }
      }
    ]
  }
}
bash-3.2$ curl 'http://localhost:9200/_cluster/stats?pretty&format=yaml'
---
_nodes:
  total: 1
  successful: 1
  failed: 0
cluster_name: "elasticsearch"
timestamp: 1509863391130
status: "yellow"
indices:
  count: 4
  shards:
    total: 20
    primaries: 20
    replication: 0.0
    index:
      shards:
        min: 5
        max: 5
        avg: 5.0
      primaries:
        min: 5
        max: 5
        avg: 5.0
      replication:
        min: 0.0
        max: 0.0
        avg: 0.0
  docs:
    count: 1004
    deleted: 0
  store:
    size_in_bytes: 518275
  fielddata:
    memory_size_in_bytes: 0
    evictions: 0
  query_cache:
    memory_size_in_bytes: 0
    total_count: 0
    hit_count: 0
    miss_count: 0
    cache_size: 0
    cache_count: 0
    evictions: 0
  completion:
    size_in_bytes: 0
  segments:
    count: 9
    memory_in_bytes: 47322
    terms_memory_in_bytes: 24887
    stored_fields_memory_in_bytes: 2808
    term_vectors_memory_in_bytes: 0
    norms_memory_in_bytes: 2816
    points_memory_in_bytes: 39
    doc_values_memory_in_bytes: 16772
    index_writer_memory_in_bytes: 0
    version_map_memory_in_bytes: 0
    fixed_bit_set_memory_in_bytes: 0
    max_unsafe_auto_id_timestamp: -1
    file_sizes: {}
nodes:
  count:
    total: 1
    data: 1
    coordinating_only: 0
    master: 1
    ingest: 1
  versions:
  - "6.0.0-rc1"
  os:
    available_processors: 4
    allocated_processors: 4
    names:
    - name: "Mac OS X"
      count: 1
    mem:
      total_in_bytes: 17179869184
      free_in_bytes: 3254730752
      used_in_bytes: 13925138432
      free_percent: 19
      used_percent: 81
  process:
    cpu:
      percent: 0
    open_file_descriptors:
      min: 216
      max: 216
      avg: 216
  jvm:
    max_uptime_in_millis: 1755709
    versions:
    - version: "1.8.0_121"
      vm_name: "Java HotSpot(TM) 64-Bit Server VM"
      vm_version: "25.121-b13"
      vm_vendor: "Oracle Corporation"
      count: 1
    mem:
      heap_used_in_bytes: 180956032
      heap_max_in_bytes: 1038876672
    threads: 47
  fs:
    total_in_bytes: 249795969024
    free_in_bytes: 141083049984
    available_in_bytes: 140820905984
  plugins: []
  network_types:
    transport_types:
      netty4: 1
    http_types:
      netty4: 1
bash-3.2$ curl 'http://localhost:9200/_cluster/stats?pretty&format=json'
{
  "_nodes" : {
    "total" : 1,
    "successful" : 1,
    "failed" : 0
  },
  "cluster_name" : "elasticsearch",
  "timestamp" : 1509863398151,
  "status" : "yellow",
  "indices" : {
    "count" : 4,
    "shards" : {
      "total" : 20,
      "primaries" : 20,
      "replication" : 0.0,
      "index" : {
        "shards" : {
          "min" : 5,
          "max" : 5,
          "avg" : 5.0
        },
        "primaries" : {
          "min" : 5,
          "max" : 5,
          "avg" : 5.0
        },
        "replication" : {
          "min" : 0.0,
          "max" : 0.0,
          "avg" : 0.0
        }
      }
    },
    "docs" : {
      "count" : 1004,
      "deleted" : 0
    },
    "store" : {
      "size_in_bytes" : 518275
    },
    "fielddata" : {
      "memory_size_in_bytes" : 0,
      "evictions" : 0
    },
    "query_cache" : {
      "memory_size_in_bytes" : 0,
      "total_count" : 0,
      "hit_count" : 0,
      "miss_count" : 0,
      "cache_size" : 0,
      "cache_count" : 0,
      "evictions" : 0
    },
    "completion" : {
      "size_in_bytes" : 0
    },
    "segments" : {
      "count" : 9,
      "memory_in_bytes" : 47322,
      "terms_memory_in_bytes" : 24887,
      "stored_fields_memory_in_bytes" : 2808,
      "term_vectors_memory_in_bytes" : 0,
      "norms_memory_in_bytes" : 2816,
      "points_memory_in_bytes" : 39,
      "doc_values_memory_in_bytes" : 16772,
      "index_writer_memory_in_bytes" : 0,
      "version_map_memory_in_bytes" : 0,
      "fixed_bit_set_memory_in_bytes" : 0,
      "max_unsafe_auto_id_timestamp" : -1,
      "file_sizes" : { }
    }
  },
  "nodes" : {
    "count" : {
      "total" : 1,
      "data" : 1,
      "coordinating_only" : 0,
      "master" : 1,
      "ingest" : 1
    },
    "versions" : [
      "6.0.0-rc1"
    ],
    "os" : {
      "available_processors" : 4,
      "allocated_processors" : 4,
      "names" : [
        {
          "name" : "Mac OS X",
          "count" : 1
        }
      ],
      "mem" : {
        "total_in_bytes" : 17179869184,
        "free_in_bytes" : 3263537152,
        "used_in_bytes" : 13916332032,
        "free_percent" : 19,
        "used_percent" : 81
      }
    },
    "process" : {
      "cpu" : {
        "percent" : 0
      },
      "open_file_descriptors" : {
        "min" : 216,
        "max" : 216,
        "avg" : 216
      }
    },
    "jvm" : {
      "max_uptime_in_millis" : 1762721,
      "versions" : [
        {
          "version" : "1.8.0_121",
          "vm_name" : "Java HotSpot(TM) 64-Bit Server VM",
          "vm_version" : "25.121-b13",
          "vm_vendor" : "Oracle Corporation",
          "count" : 1
        }
      ],
      "mem" : {
        "heap_used_in_bytes" : 183416688,
        "heap_max_in_bytes" : 1038876672
      },
      "threads" : 47
    },
    "fs" : {
      "total_in_bytes" : 249795969024,
      "free_in_bytes" : 141083049984,
      "available_in_bytes" : 140820905984
    },
    "plugins" : [ ],
    "network_types" : {
      "transport_types" : {
        "netty4" : 1
      },
      "http_types" : {
        "netty4" : 1
      }
    }
  }
}

人間が読みやすい出力結果

人間にとって読みやすい形（例えば、"exists_time": "1h"または"size": "1kb"）またはコンピュータにとって読みやすい形（例えば、"exists_time_in_millis": 3600000または"size_in_bytes": 1024）で出力結果を返すことができる。人間にとって読みやすい形を含めない場合は?human=falseとクエリ文字列に追加する。humanパラメータのデフォルトは falseである。

bash-3.2$ curl 'http://localhost:9200/_cluster/stats?pretty&human=false'
{
  "_nodes" : {
    "total" : 1,
    "successful" : 1,
    "failed" : 0
  },
  "cluster_name" : "elasticsearch",
  (省略)
    "segments" : {
      "count" : 9,
      "memory_in_bytes" : 47322,
      "terms_memory_in_bytes" : 24887,
      "stored_fields_memory_in_bytes" : 2808,
      "term_vectors_memory_in_bytes" : 0,
      "norms_memory_in_bytes" : 2816,
      "points_memory_in_bytes" : 39,
      "doc_values_memory_in_bytes" : 16772,
      "index_writer_memory_in_bytes" : 0,
      "version_map_memory_in_bytes" : 0,
      "fixed_bit_set_memory_in_bytes" : 0,
      "max_unsafe_auto_id_timestamp" : -1,
      "file_sizes" : { }
    }
  (省略)
bash-3.2$ curl 'http://localhost:9200/_cluster/stats?pretty&human=true'
{
  "_nodes" : {
    "total" : 1,
    "successful" : 1,
    "failed" : 0
  },
  "cluster_name" : "elasticsearch",
  (省略)
    "segments" : {
      "count" : 9,
      "memory" : "46.2kb",
      "memory_in_bytes" : 47322,
      "terms_memory" : "24.3kb",
      "terms_memory_in_bytes" : 24887,
      "stored_fields_memory" : "2.7kb",
      "stored_fields_memory_in_bytes" : 2808,
      "term_vectors_memory" : "0b",
      "term_vectors_memory_in_bytes" : 0,
      "norms_memory" : "2.7kb",
      "norms_memory_in_bytes" : 2816,
      "points_memory" : "39b",
      "points_memory_in_bytes" : 39,
      "doc_values_memory" : "16.3kb",
      "doc_values_memory_in_bytes" : 16772,
      "index_writer_memory" : "0b",
      "index_writer_memory_in_bytes" : 0,
      "version_map_memory" : "0b",
      "version_map_memory_in_bytes" : 0,
      "fixed_bit_set" : "0b",
      "fixed_bit_set_memory_in_bytes" : 0,
      "max_unsafe_auto_id_timestamp" : -1,
      "file_sizes" : { }
    }
  (省略)

日時の単位

フォーマットされた日時のほとんどのパラメータが受け入れる - rangeクエリのgtやlt、またdaterangeクエリの集計機能としてfromやtoパラメータも使用できる。 。

サポートされている日時の単位は以下の通りである。

日時の単位	意味
y	年
M	月
w	週
d	日
h	時間
H	時間
m	分
s	秒

以下のようにパラメータを追加することもできる。

パラメータを追加した時間	意味
now+1h	現在の時刻+1時間
now+1h+1m	現在の時刻+1時間+1分
now+1h/d	現在の時刻に1時間を加え、最も近い日に切り捨てる
2015-01-01||+1M/d	2015-01-01に1ヶ月を加え、最も近い日に切り捨てる

レスポンスフィルタリング

リクエストを送るときにほしいパラメータを指定すれば、そのパラメータに応じてレスポンスが返ってくるというもの。*でワイルドカードも使える。

bash-3.2$ curl -XGET 'localhost:9200/_search?q=mill&filter_path=took,hits.hits._id,hits.hits._score&pretty'
{
  "took" : 14,
  "hits" : {
    "hits" : [
      {
        "_id" : "472",
        "_score" : 4.89784
      },
      {
        "_id" : "136",
        "_score" : 4.8485627
      },
      {
        "_id" : "970",
        "_score" : 4.388994
      },
      {
        "_id" : "345",
        "_score" : 4.388994
      }
    ]
  }
}
bash-3.2$ curl -XGET 'localhost:9200/_search?q=mill&pretty'
{
  "took" : 17,
  "timed_out" : false,
  "_shards" : {
    "total" : 20,
    "successful" : 20,
    "skipped" : 0,
    "failed" : 0
  },
  "hits" : {
    "total" : 4,
    "max_score" : 4.89784,
    "hits" : [
      {
        "_index" : "bank",
        "_type" : "account",
        "_id" : "472",
        "_score" : 4.89784,
        "_source" : {
          "account_number" : 472,
          "balance" : 25571,
          "firstname" : "Lee",
          "lastname" : "Long",
          "age" : 32,
          "gender" : "F",
          "address" : "288 Mill Street",
          "employer" : "Comverges",
          "email" : "leelong@comverges.com",
          "city" : "Movico",
          "state" : "MT"
        }
      },
      {
        "_index" : "bank",
        "_type" : "account",
        "_id" : "136",
        "_score" : 4.8485627,
        "_source" : {
          "account_number" : 136,
          "balance" : 45801,
          "firstname" : "Winnie",
          "lastname" : "Holland",
          "age" : 38,
          "gender" : "M",
          "address" : "198 Mill Lane",
          "employer" : "Neteria",
          "email" : "winnieholland@neteria.com",
          "city" : "Urie",
          "state" : "IL"
        }
      },
      {
        "_index" : "bank",
        "_type" : "account",
        "_id" : "970",
        "_score" : 4.388994,
        "_source" : {
          "account_number" : 970,
          "balance" : 19648,
          "firstname" : "Forbes",
          "lastname" : "Wallace",
          "age" : 28,
          "gender" : "M",
          "address" : "990 Mill Road",
          "employer" : "Pheast",
          "email" : "forbeswallace@pheast.com",
          "city" : "Lopezo",
          "state" : "AK"
        }
      },
      {
        "_index" : "bank",
        "_type" : "account",
        "_id" : "345",
        "_score" : 4.388994,
        "_source" : {
          "account_number" : 345,
          "balance" : 9812,
          "firstname" : "Parker",
          "lastname" : "Hines",
          "age" : 38,
          "gender" : "M",
          "address" : "715 Mill Avenue",
          "employer" : "Baluba",
          "email" : "parkerhines@baluba.com",
          "city" : "Blackgum",
          "state" : "KY"
        }
      }
    ]
  }
}

flat settings

flat_settingsは、設定の表示方法に関わるものだ。flat_settingsがtrueになっている場合はフラット形式で返される。

bash-3.2$ curl -XGET 'localhost:9200/bank/_settings?flat_settings=true&pretty'
{
  "bank" : {
    "settings" : {
      "index.creation_date" : "1509088848646",
      "index.number_of_replicas" : "1",
      "index.number_of_shards" : "5",
      "index.provided_name" : "bank",
      "index.uuid" : "yaVaZLiLT2G0RyA-vBn5nw",
      "index.version.created" : "6000051"
    }
  }
}
bash-3.2$ curl -XGET 'localhost:9200/bank/_settings?flat_settings=false&pretty'
{
  "bank" : {
    "settings" : {
      "index" : {
        "creation_date" : "1509088848646",
        "number_of_shards" : "5",
        "number_of_replicas" : "1",
        "uuid" : "yaVaZLiLT2G0RyA-vBn5nw",
        "version" : {
          "created" : "6000051"
        },
        "provided_name" : "bank"
      }
    }
  }
}

パラメータ

RESTパラメータはunderscore casingを使用する規約に従う(HTTPを使用する場合HTTP URLパラメータにマップする)。

ブール値

REST APIのはブール値にtrueまたはfalseを用いる。

数値

REST APIはnative JSON number typesをサポートする上でstringとしてnumbered parametersを提供する。

時間の単位

以下の時間の単位をサポートしている。

時間の単位	意味
d	days
h	hours
m	minutes
s	seconds
ms	milliseconds
micros	microseconds
nanos	nanoseconds

バイトサイズの単位

以下のバイトサイズの単位をサポートしている。*1kb=1024b

バイトの単位	意味
b	バイト
kb	キロバイト
mb	メガバイト
gb	ギガバイト
tb	テラバイト
pb	ペタバイト

Unit-less quantities

以下のUnit-less quantitiesをサポートしている。

Unit-less quantities	意味
``	Single
k	キロ
m	メガ
g	ギガ
t	テラ
p	ペタ

距離の単位

以下の距離の単位をサポートしている。*1マイル≒1.6km 1海里=1852m

距離の単位	意味
mi or miles	マイル
yd or yards	ヤード
ft or feet	フィード
in or inch	インチ
km or kilometers	キロメートル
m or meters	メートル
cm or centimeters	センチメートル
mm or millimeters	ミリメートル
NM, nmi or nauticalmiles	海里

Fuzziness

一部のクエリおよびAPIでは、fuzzinessパラメータを使用してinexact fuzzy matching(厳密ではないあいまいなクエリな一致)をサポートする。
textやkeywordフィールドはLevenshtein distance(https://ja.wikipedia.org/wiki/%E3%83%AC%E3%83%BC%E3%83%99%E3%83%B3%E3%82%B7%E3%83%A5%E3%82%BF%E3%82%A4%E3%83%B3%E8%B7%9D%E9%9B%A2)として解釈される。
fuzzinessパラメータは次のように指定することができる。

• 0,1,2
  Levenshtein distanceの最大値（または編集した数）
• AUTO
  その語の長さに基づいてedit distanceを生成する
  長さ:
  0..2 正確に一致する必要がある
  3..5 1つの編集を許可
  >5 2つの編集を許可

AUTOは一般にfuzzinessに好ましい値であるべきである。

スタックトレースの有効化

エラーを返すときのデフォルトではエラーのスタックトレースが含まれない。スタックトレースを有効にするには、error_traceurlパラメータをtrueに設定する。

bash-3.2$ curl -XPOST 'localhost:9200/bank/_search?size=surprise_me&pretty'
{
  "error" : {
    "root_cause" : [
      {
        "type" : "illegal_argument_exception",
        "reason" : "Failed to parse int parameter [size] with value [surprise_me]"
      }
    ],
    "type" : "illegal_argument_exception",
    "reason" : "Failed to parse int parameter [size] with value [surprise_me]",
    "caused_by" : {
      "type" : "number_format_exception",
      "reason" : "For input string: \"surprise_me\""
    }
  },
  "status" : 400
}
bash-3.2$ curl -XPOST 'localhost:9200/bank/_search?size=surprise_me&error_trace=true&pretty'
{
  "error" : {
    "root_cause" : [
      {
        "type" : "illegal_argument_exception",
        "reason" : "Failed to parse int parameter [size] with value [surprise_me]",
        "stack_trace" : "[Failed to parse int parameter [size] with value [surprise_me]]; nested: IllegalArgumentException[Failed to parse int parameter [size] with value [surprise_me]]; nested: NumberFormatException[For input string: \"surprise_me\"];\n\tat org.elasticsearch.ElasticsearchException.guessRootCauses(ElasticsearchException.java:618)\n\tat 
(省略)
org.elasticsearch.rest.RestRequest.paramAsInt(RestRequest.java:273)\n\t... 52 more\n"
      }
    ],
    "type" : "illegal_argument_exception",
    "reason" : "Failed to parse int parameter [size] with value [surprise_me]",
    "caused_by" : {
      "type" : "number_format_exception",
      "reason" : "For input string: \"surprise_me\"",
      "stack_trace" : "java.lang.NumberFormatException: For input string: \"surprise_me\"\n\tat java.lang.NumberFormatException.forInputString(NumberFormatException.java:65)\n\tat java.lang.Integer.parseInt(Integer.java:580)\n\tat java.lang.Integer.parseInt(Integer.java:615)\n\tat org.elasticsearch.rest.RestRequest.paramAsInt(RestRequest.java:273)\n\tat 
(省略)
io.netty.util.concurrent.SingleThreadEventExecutor$5.run(SingleThreadEventExecutor.java:858)\n\tat java.lang.Thread.run(Thread.java:745)\n"
    },
    "stack_trace" : "java.lang.IllegalArgumentException: Failed to parse int parameter [size] with value [surprise_me]\n\tat org.elasticsearch.rest.RestRequest.paramAsInt(RestRequest.java:275)\n\tat 
(省略)
org.elasticsearch.rest.RestRequest.paramAsInt(RestRequest.java:273)\n\t... 52 more\n"
  },
  "status" : 400
}

Content-Type Requirements

リクエストのbodyで送られるコンテンツのタイプは、Content-Typeヘッダーを使用して指定する必要がある。ほとんどのAPIはJSON,YAML,CBOR,SMILEをサポートしている。bulk APIとmulti-search APIはNDJSON,JSON,SMILEをサポートしている。

さらに、sourceクエリ文字列パラメータを使用する場合は、クエリ文字列パラメータを使用してコンテンツタイプを指定する必要がありsource_content_typeます。

また、source query string parameterを使用する場合は、source_content_type query string parameterを使用してコンテンツタイプを指定する必要がある。