Amazon Elasticsearch Service
開発者ガイド (API バージョン 2015-01-01)

Amazon Elasticsearch Service でのデータのインデックス作成の概要

Elasticsearch では REST API を使用するため、ドキュメントのインデックス作成にはさまざまな方法があります。curl などの標準クライアントを使用することも、HTTP リクエストの送信が可能な任意のプログラミング言語を使用することもできます。やり取りのプロセスをさらに単純化するため、Elasticsearch には多くのプログラミング言語に対応するクライアントが用意されています。上級ユーザーは、直接「Amazon Elasticsearch Service への HTTP リクエストの署名」に進むことができます。

新しいデータの到着が徐々に増加する場合 (小規模ビジネスからの顧客注文など) は、到着するドキュメントのインデックス作成に _index API を使用できます。データフローがそれほど頻繁ではない場合 (マーケティングウェブサイトに対する週 1 回の更新など) は、ファイルを生成して _bulk API に送信することもできます。ドキュメント数が多い場合は、リクエストをまとめて _bulk API を使用すると、優れたパフォーマンスを実現できます。ただし、ドキュメントのサイズが非常に大きい場合は、_index API を使用して、個々のドキュメントにインデックスを作成する必要があります。

他の AWS サービスからのデータの統合については、「Amazon Elasticsearch Service にストリーミングデータをロードする」を参照してください。

インデックス作成の概要

データを検索するには、データにインデックスを作成する必要があります。インデックス作成は、データを高速に取得できるように検索エンジンがデータを整理する方法です。その結果として生成される構造体がインデックスと呼ばれています。

Elasticsearch のデータの基本単位は JSON ドキュメントです。インデックス内では、Elasticsearch によってドキュメントがタイプ (ユーザーが定義する任意のデータカテゴリ) 別に整理され、一意の ID で識別されます。

_index API に対するリクエストは次のようになります。

PUT elasticsearch_domain/index/type/id { "A JSON": "document" }

_bulk API に対するリクエストは少し異なっており、インデックス、タイプ、ID をバルクデータ内で指定する必要があります。

POST elasticsearch_domain/_bulk { "index": { "_index" : "index", "_type" : "type", "_id" : "id" } } { "A JSON": "document" }

バルクデータは特定の形式に従う必要があり、最終行を含めてすべての行末には改行文字 (\n) が必要になります。以下に基本的な形式を示します。

action_and_metadata\n optional_document\n action_and_metadata\n optional_document\n ...

簡単なサンプルファイルについては、「ステップ 2: インデックス作成のためにデータを Amazon ES ドメインにアップロードする」を参照してください。

Elasticsearch では、まだ存在しないインデックスにドキュメントを追加すると、インデックスの自動作成が行われます。また、リクエスト内で ID を指定しなかった場合は、ID の自動生成が行われます。下に示す簡単な例では、movies インデックスを自動的に作成し、movie というドキュメントタイプを設定して、ドキュメントに対するインデックス作成と一意の ID の割り当てを行っています。

POST elasticsearch_domain/movies/movie {"title": "Spirited Away"}

重要

ID の自動生成を使用するには、POST の代わりに PUT メソッドを使用する必要があります。

ドキュメントが存在することを確認するには、次の検索を実行できます。

GET elasticsearch_domain/movies/_search?pretty

レスポンスの内容は次のようになります。

"hits" : { "total" : 1,   "max_score" : 1.0,   "hits" : [   {     "_index" : "movies",       "_type" : "movie",       "_id" : "AV4WaTnYxBoJaZkSFeX9",       "_score" : 1.0,       "_source" : {         "title" : "Spirited Away"       }     }   ] }

ID の自動生成には明らかな欠点があります。コードのインデックス作成ではドキュメント ID が指定されないため、後でドキュメントを更新することが容易ではありません。7 の ID を指定するには、次のリクエストを使用します。

PUT elasticsearch_domain/movies/movie/7 {"title": "Spirited Away"}

Elasticsearch バージョン 6.0 以降で作成したインデックスには、1 つのドキュメントタイプのみを含めることができます。今後のバージョンの Elasticsearch との互換性を最適化するため、すべてのインデックスに単一のタイプ _doc を使用します。

PUT elasticsearch_domain/more-movies/_doc/1 {"title": "Back to the Future"}

5 つのプライマリシャードと 1 つのレプリカをデフォルトでインデックスのデフォルトに設定します。デフォルト以外の設定を指定する場合は、ドキュメントを追加する前にそのインデックスを作成します。

PUT elasticsearch_domain/more-movies {"settings": {"number_of_shards": 6, "number_of_replicas": 2}}

注記

サンプルコードについては、「Amazon Elasticsearch Service への HTTP リクエストの署名」を参照してください。

インデックスの命名制限

Elasticsearch インデックスには、以下の命名制限があります。

  • すべての文字を小文字にする必要があります。

  • インデックスの名前を _ または - から始めることはできません。

  • インデックス名にスペース、カンマ、"*+/\|?#>< を含めることはできません。

インデックス、タイプ、またはドキュメント ID 名に機密情報を含めないでください。Elasticsearch は、これらの名前を Uniform Resource Identifier (URI) で使用します。サーバーおよびアプリケーションは、HTTP リクエストを頻繁に記録します。このため、URI に機密情報が含まれている場合、不要なデータ漏えいにつながる可能性があります。

2018-10-03T23:39:43 198.51.100.14 200 "GET https://elasticsearch_domain/dr-jane-doe/flu-patients-2018/202-555-0100/ HTTP/1.1"

関連する JSON ドキュメントを表示するアクセス許可がない場合でも、Dr. Doe の患者 (電話番号は 202-555-0100) が 2018 年にインフルエンザにかかったことを、この架空のログ行から推測することが可能です。

レスポンスサイズの削減

_index および _bulk API のレスポンスには、多くの情報が含まれています。この情報は、リクエストのトラブルシューティングや、再試行ロジックの実装には役立ちますが、帯域幅を広く使用する場合があります。この例では、32 バイトのドキュメントのインデックスを作成すると、レスポンスは 339 バイト (ヘッダーを含む) になります。

PUT elasticsearch_domain/more-movies/_doc/1 {"title": "Back to the Future"}

レスポンス

{ "_index": "more-movies", "_type": "_doc", "_id": "1", "_version": 4, "result": "updated", "_shards": { "total": 2, "successful": 2, "failed": 0 }, "_seq_no": 3, "_primary_term": 1 }

このレスポンスサイズは一見小さく見えますが、1 日あたり 1,000,000 ドキュメント — 1 秒あたり約 11.5 ドキュメントのインデックス — を作成した場合、339 バイト/1 レスポンスは、1 か月あたり 10.17 GB のダウンロードトラフィックになります。

データ転送コストが懸念される場合は、filter_path パラメータを使用して Elasticsearch レスポンスのサイズを削減できますが、失敗したリクエストの識別や再試行のために必要なフィールドを除外しないように注意してください。このフィールドはクライアントによって異なります。filter_path パラメータは、すべての Elasticsearch REST API で動作しますが、頻繁に呼び出す API (例: _index_bulk API) を使用する場合に特に便利です。

PUT elasticsearch_domain/more-movies/_doc/1?filter_path=result,_shards.total {"title": "Back to the Future"}

レスポンス

{ "result": "updated", "_shards": { "total": 2 } }

フィールドを含める代わりに、- プリフィックスを使用してフィールドを除外することができます。filter_path は、ワイルドカードもサポートしています。

POST elasticsearch_domain/_bulk?filter_path=-took,-items.index._* { "index": { "_index": "more-movies", "_type": "_doc", "_id": "1" } } {"title": "Back to the Future"} { "index": { "_index": "more-movies", "_type": "_doc", "_id": "2" } } {"title": "Spirited Away"}

レスポンス

{ "errors": false, "items": [ { "index": { "result": "updated", "status": 200 } }, { "index": { "result": "updated", "status": 200 } } ] }