ElasticsearchのAPI ConventionsのCommon optionsについて記す。
公式ドキュメント Common options を参考にした。
検証環境: 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_trace
urlパラメータを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を使用してコンテンツタイプを指定する必要がある。