4 Elasticsearchハンドラの使用
Elasticsearchハンドラについて説明します。Elasticsearchハンドラを使用すると、大量のデータをすばやく、ほぼリアルタイムで保存、検索および分析できます。
トピック:
4.1 概要
Elasticsearchは、拡張性の高い、オープン・ソースのフルテキスト検索および分析エンジンです。Elasticsearchを使用すると、大量のデータをすばやく、ほぼリアルタイムで保存、検索および分析できます。通常、複雑な検索機能を備えたアプリケーションを駆動する基盤となるエンジンやテクノロジとして使用されます。
Elasticsearchハンドラでは、Elasticsearch Javaクライアントを使用してElasticsearchノードに接続し、データを受信します。https://www.elastic.coを参照してください。
親トピック: Elasticsearchハンドラの使用
4.2 機能の詳細
トピック:
親トピック: Elasticsearchハンドラの使用
4.2.1 Elasticsearchバージョン・プロパティについて
Elasticsearchハンドラのプロパティgg.handler.name.version
は、Elasticsearchクラスタのバージョンに従って設定する必要があります。ElasticsearchハンドラはJavaのTransportクライアントを使用し、そのバージョンは、クラスタ内のノードと同じメジャー・バージョン(2.xまたは5.xなど)である必要があります。新しい機能はサポートされない可能性はありますが、Elasticsearchハンドラは、マイナー・バージョン(2.3.xなど)の異なるクラスタにも接続できます。
親トピック: 機能の詳細
4.2.2 インデックスとタイプについて
Elasticsearchのインデックスは、類似した特性を持つドキュメントの集まりです。インデックスは小文字でのみ作成できます。Elasticsearchのタイプは、インデックス内の論理グループです。インデックスまたはタイプ内のすべてのドキュメントは、同じ番号およびタイプのフィールドを持つ必要があります。
Elasticsearchハンドラでは、ソース証跡スキーマをソース証跡表名と連結してインデックスが構築されます。ソース証跡の3つの部分からなる表名の場合、インデックスはソース・カタログ、スキーマおよび表名を連結して構成されます。
Elasticsearchハンドラでは、ソース表名がElasticsearchのタイプにマッピングされます。タイプ名は大文字と小文字を区別します。
表4-1 Elasticsearchのマッピング
ソース証跡 | Elasticsearchのインデックス | Elasticsearchのタイプ |
---|---|---|
|
|
|
|
|
|
Elasticsearchクラスタにまだインデックスが存在しない場合は、Elasticsearchハンドラがデータを受信すると(ソース証跡でのINSERT
またはUPDATE
操作)、新しいインデックスが作成されます。
親トピック: 機能の詳細
4.2.3 ドキュメントについて
Elasticsearchのドキュメントは、インデックス付けのできる情報の基本単位です。インデックスまたはタイプ内に、必要な数のドキュメントを格納できます。各ドキュメントには_id
フィールドに基づく一意の識別子があります。
Elasticsearchハンドラでは、ソース証跡の主キー列の値がドキュメント識別子としてマッピングされます。
親トピック: 機能の詳細
4.2.4 主キーの更新について
Elasticsearchのドキュメント識別子はソース表の主キー列の値に基づいて作成されます。ドキュメント識別子は変更できません。Elasticsearchハンドラでは、DELETE
に続いてINSERT
を実行することによってソース主キーの更新操作が処理されます。INSERT
の実行中、新しいドキュメントのフィールドが必要なフィールド数よりも少ないことがあります。ソース表内のすべてのフィールドをINSERT
操作に含めるには、更新操作用にデータ全体のビフォア・イメージをキャプチャするように証跡のExtractを有効にするか、GETBEFORECOLS
を使用して必要な列のビフォア・イメージを書き込みます。
親トピック: 機能の詳細
4.2.5 データ型について
Elasticsearchでは次のデータ型がサポートされています。
-
32ビット整数
-
64ビット整数
-
Double
-
Date
-
String
-
Binary
親トピック: 機能の詳細
4.2.6 操作モード
Elasticsearchハンドラでは、パフォーマンスを向上させるために操作モードが使用されます。gg.handler.name.mode
プロパティはハンドラでは使用されません。
親トピック: 機能の詳細
4.2.7 操作処理のサポート
Elasticsearchハンドラでは、ソース表名がElasticsearchのタイプにマッピングされます。タイプ名は大文字と小文字を区別します。
ソース証跡の3つの部分からなる表名の場合、インデックスはソース・カタログ、スキーマおよび表名を連結して構成されます。
-
INSERT
-
Elasticsearchハンドラでは、インデックスが存在しない場合、新規インデックスが作成されて新規ドキュメントが挿入されます。
-
UPDATE
-
Elasticsearchのインデックスやドキュメントが存在する場合は、そのドキュメントが更新されます。Elasticsearchのインデックスやドキュメントが存在しない場合は、新規インデックスが作成され、
UPDATE
操作の列の値が新規ドキュメントとして挿入されます。 -
DELETE
-
Elasticsearchのインデックスやドキュメントが存在する場合は、そのドキュメントが削除されます。Elasticsearchのインデックスやドキュメントが存在しない場合は、フィールドがゼロの新規インデックスが作成されます。
TRUNCATE
操作はサポートされていません。
親トピック: 機能の詳細
4.2.8 接続について
クラスタは、データ全体を保持する1つまたは複数のノード(サーバー)の集合です。すべてのノードにわたるフェデレーテッド索引付けおよび検索機能が提供されます。
ノードはクラスタの一部であり、データを格納し、クラスタの索引付けおよび検索に参加する単一のサーバーです。
Elasticsearchハンドラのプロパティgg.handler.name.ServerAddressList
は、クラスタで使用可能なノードを指すように設定できます。
親トピック: 機能の詳細
4.3 Elasticsearchハンドラの設定および実行
Elasticsearchクラスタが正しく設定され、そのクラスタが稼働していることを確認する必要があります(https://www.elastic.co/guide/en/elasticsearch/reference/current/index.htmlを参照)。また、Kibanaを使用して設定を確認することもできます。
クラスパスの設定
プロパティgg.classpath
には、Javaのトランスポート・クライアントに必要なすべてのjarが含まれている必要があります。必要なクライアントJARファイルのバージョン別リストは、「Elasticsearchハンドラ・クライアント依存性」を参照してください。
Default location of 2.X JARs: Elasticsearch_Home/lib/* Elasticsearch_Home/plugins/shield/*
Default location of 5.X JARs: Elasticsearch_Home/lib/* Elasticsearch_Home/plugins/x-pack/* Elasticsearch_Home/modules/transport-netty3/* Elasticsearch_Home/modules/transport-netty4/* Elasticsearch_Home/modules/reindex/*
パス内のワイルドカード(*)は、(*)のワイルドカード文字により、そのディレクトリ内のすべてのJARファイルを関連するクラスパスに含めることができます。*.jar
は使用しないでください
正しく構成されたクラスパスの例を次に示します。
gg.classpath=Elasticsearch_Home/lib/*
トピック:
4.3.1 Elasticsearchハンドラの構成
Elasticsearchハンドラの構成可能な値は次のとおりです。これらのプロパティは、Javaアダプタ・プロパティ・ファイルにあります(Replicatプロパティ・ファイルにはありません)。
Elasticsearchハンドラの選択を有効にするには、まずgg.handler.jdbc.type=elasticsearch
およびその他のElasticsearchプロパティを次のように指定してハンドラ・タイプを構成する必要があります。
表4-2 Elasticsearchハンドラの構成プロパティ
プロパティ | 必須/オプション | 有効な値 | デフォルト | 説明 |
---|---|---|---|---|
gg.handlerlist |
必須 |
名前(任意の名前) |
なし |
使用するハンドラのリスト。 |
gg.handler.name.type |
必須 |
elasticsearch |
なし |
使用するハンドラのタイプ。たとえば、Elasticsearch、Kafka、Flume、HDFSなどです。 |
gg.handler.name.ServerAddressList |
オプション |
|
|
Elasticsearchクラスタに接続するノードの連絡ポイントのカンマ区切りのリスト。 |
gg.handler.name.clientSettingsFile |
必須 |
トランスポート・クライアントのプロパティ・ファイル。 |
なし |
Elasticsearchハンドラで使用されるElasticsearchトランスポート・クライアントのプロパティを保持するクラスパスのファイル名。 |
gg.handler.name.version |
オプション |
|
|
Elasticsearchハンドラで使用されるトランスポート・クライアントのバージョンで、これはElasticsearchクラスタとの互換性が必要です。 |
gg.handler.name.bulkWrite |
オプション |
|
|
このプロパティが |
gg.handler.name.numberAsString |
オプション |
|
|
このプロパティが |
gg.handler.elasticsearch.upsert |
オプション |
|
|
このプロパティが |
例4-1 サンプルのハンドラ・プロパティ・ファイル:
2.x Elasticsearchクラスタの場合:
gg.handlerlist=elasticsearch
gg.handler.elasticsearch.type=elasticsearch
gg.handler.elasticsearch.ServerAddressList=localhost:9300
gg.handler.elasticsearch.clientSettingsFile=client.properties
gg.handler.elasticsearch.version=2.x
gg.classpath=/path/to/elastic/lib/*
2.x Elasticsearchクラスタ(Shieldあり)の場合:
gg.handlerlist=elasticsearch
gg.handler.elasticsearch.type=elasticsearch
gg.handler.elasticsearch.ServerAddressList=localhost:9300
gg.handler.elasticsearch.clientSettingsFile=client.properties
gg.handler.elasticsearch.version=2.x
gg.classpath=/path/to/elastic/lib/*:/path/to/elastic/plugins/shield/*
5.x Elasticsearchクラスタの場合:
gg.handlerlist=elasticsearch
gg.handler.elasticsearch.type=elasticsearch
gg.handler.elasticsearch.ServerAddressList=localhost:9300
gg.handler.elasticsearch.clientSettingsFile=client.properties
gg.handler.elasticsearch.version=5.x
gg.classpath=/path/to/elastic/lib/*:/path/to/elastic/modules/transport-netty4/*:/path/to/elastic/modules/reindex/*
5.x Elasticsearchクラスタ(x-packあり)の場合:
gg.handlerlist=elasticsearch
gg.handler.elasticsearch.type=elasticsearch
gg.handler.elasticsearch.ServerAddressList=localhost:9300
gg.handler.elasticsearch.clientSettingsFile=client.properties
gg.handler.elasticsearch.version=5.x
gg.classpath=/path/to/elastic/lib/*:/path/to/elastic/plugins/x-pack/*:/path/to/elastic/modules/transport-netty4/*:/path/to/elastic/modules/reindex/*
サンプルのReplicat構成およびJavaアダプタのプロパティ・ファイルは、次のディレクトリにあります。
GoldenGate_install_directory/AdapterExamples/big-data/elasticsearch
親トピック: Elasticsearchハンドラの設定および実行
4.3.2 トランスポート・クライアントの設定プロパティ・ファイルについて
Elasticsearchハンドラは、JavaのTransportクライアントを使用してElasticsearchクラスタとやりとりします。Elasticsearchクラスタには、shieldやx-packのような追加のプラグインがあり、追加の構成が必要な場合があります。
gg.handler.name.clientSettingsFile
プロパティは、Elasticsearchクラスタのバージョンに基づく追加のクライアント設定のあるファイルを指している必要があります。Elasticsearchハンドラは、Javaクラスパスを使用してクライアント設定ファイルの検索とロードを試みます。Javaクラスパスには、プロパティ・ファイルのあるディレクトリが含まれている必要があります。
Elasticsearch 2.x(プラグインなし)のクライアント・プロパティ・ファイル:
cluster.name=Elasticsearch_cluster_name
Shieldプラグインを使用するElasticsearch 2.Xのクライアント・プロパティ・ファイル:
cluster.name=Elasticsearch_cluster_name
shield.user=shield_username:shield_password
Shieldプラグインは、SSLやIPフィルタリングなどの追加機能もサポートしています。プロパティはclient.properties
ファイルで設定できます(https://www.elastic.co/guide/en/elasticsearch/client/java-api/2.4/transport-client.htmlおよびhttps://www.elastic.co/guide/en/shield/current/_using_elasticsearch_java_clients_with_shield.htmlを参照)。
X-Packプラグインを使用するElasticsearch 5.xのclient.properties
ファイル:
cluster.name=Elasticsearch_cluster_name
xpack.security.user=x-pack_username:x-pack-password
X-Packプラグインも追加の機能をサポートしています。プロパティはclient.properties
ファイルで設定できます(https://www.elastic.co/guide/en/elasticsearch/client/java-api/5.1/transport-client.htmlおよびhttps://www.elastic.co/guide/en/x-pack/current/java-clients.htmlを参照)。
親トピック: Elasticsearchハンドラの設定および実行
4.4 パフォーマンスに関する考慮事項
Elasticsearchハンドラのgg.handler.name.bulkWrite
プロパティは、Elasticsearchクラスタにソース証跡レコードをプッシュする際に、一度に1つずつ行うか、または一括書込みAPIを使用して一括で行うかを判断するために使用されます。このプロパティがtrueの場合、ソース証跡の操作は、一般的なReplicatパラメータ・ファイルのMAXTRANSOPS
パラメータによってサイズを制御されるバッチでElasticsearchクラスタにプッシュされます。一括書込みAPIを使用するとパフォーマンスが向上します。
Elasticsearchは、ノード内で管理されるスレッド・プールのメモリー消費量を改善するために、異なるスレッド・プールを使用します。また、これらのプールの多くにはそれに関連付けられたキューも存在し、保留中のリクエストは廃棄されずに保持されます。
一括操作の場合、デフォルトのキュー・サイズは50(バージョン5.2)および200(バージョン5.3)です。
一括APIのエラーを回避するには、ReplicatのMAXTRANSOPS
サイズを一括スレッドのプール・キュー・サイズの最小値と一致するように設定する必要があります。thread_pool.bulk.queue_size
構成プロパティはelasticsearch.yaml
ファイルで変更できます。
親トピック: Elasticsearchハンドラの使用
4.5 Shieldプラグインのサポートについて
Elasticsearchバージョン2.xでは、基本認証、SSLおよびIPフィルタリングを提供するShieldプラグインがサポートされています。Elasticsearch 5.xのX-Packプラグインにも同様の機能があります。追加のトランスポート・クライアントの設定は、gg.handler.name.clientSettingsFile
プロパティを使用してElasticsearchハンドラで構成できます。
親トピック: Elasticsearchハンドラの使用
4.6 DDL処理について
Elasticsearchハンドラはソース証跡内のDDLレコードには反応しません。新規ソース表のデータ操作レコードにより、Elasticsearchクラスタでインデックスまたはタイプの自動作成が行われます。
親トピック: Elasticsearchハンドラの使用
4.7 トラブルシューティング
この項では、様々な問題のトラブルシューティングに役立つ情報を示します。
トピック:
- 不適切なJavaクラスパス
- Elasticsearchのバージョン不一致
- トランスポート・クライアントのプロパティ・ファイルが見つからない
- クラスタ接続の問題
- サポートされていないTRUNCATE操作
- 一括実行エラー
親トピック: Elasticsearchハンドラの使用
4.7.1 不適切なJavaクラスパス
最も一般的な初期エラーは、必要なすべてのクライアント・ライブラリを含めるクラスパスが正しくないことす。log4j
ログ・ファイルにClassNotFound
例外が作成されます。
また、gg.classpath
変数に表記上の誤りがある場合、クラスパス解決エラーの原因となる可能性があります。
Elasticsearchのトランスポート・クライアント・ライブラリには、Oracle GoldenGate for Big Data製品は付属していません。クライアント・ライブラリを正しく解決するには、Javaアダプタのプロパティ・ファイルでgg.classpath
プロパティを正しく構成する必要があります(「Elasticsearchハンドラの設定および実行」を参照)。
親トピック: トラブルシューティング
4.7.2 Elasticsearchのバージョン不一致
Elasticsearchクラスタのメジャー・バージョン番号と一致させるには、Elasticsearchハンドラのgg.handler.name.version
プロパティを2.xまたは5.xに設定する必要があります。
バージョン構成に誤りがあると、次のエラーが発生することがあります。
Error: NoNodeAvailableException[None of the configured nodes are available:] ERROR 2017-01-30 22:35:07,240 [main] Unable to establish connection. Check handler properties and client settings configuration. java.lang.IllegalArgumentException: unknown setting [shield.user]
必要なすべてのプラグインがインストールされていることを確認し、削除されたすべての設定に関するドキュメントの変更点を確認します。
親トピック: トラブルシューティング
4.7.3 トランスポート・クライアントのプロパティ・ファイルが見つからない
この例外を解決するには:
ERROR 2017-01-30 22:33:10,058 [main] Unable to establish connection. Check handler properties and client settings configuration.
gg.handler.name.clientSettingsFile
構成プロパティに、Elasticsearchトランスポート・クライアントの設定ファイル名が正しく設定されていることを確認します。gg.classpath
変数に正しいファイル名へのパスが含まれ、プロパティ・ファイルへのパスの最後にアスタリスク(*)のワイルドカードが含まれていないことを確認します。
親トピック: トラブルシューティング
4.7.4 クラスタ接続の問題
このエラーは、ElasticsearchハンドラがElasticsearchクラスタに接続できない場合に発生します。
Error: NoNodeAvailableException[None of the configured nodes are available:]
この問題をデバッグするには、次のステップを実行します。
-
Elasticsearchのサーバー・プロセスが実行中であることを確認します。
-
クライアント・プロパティ構成ファイルで、
cluster.name
プロパティを確認します。 -
クライアント・プロパティ・ファイルで、x-PackまたはShieldプラグインの認証の資格証明を確認します。
-
gg.handler.name.ServerAddressList
ハンドラ・プロパティを確認します。
親トピック: トラブルシューティング
4.7.5 サポートされていないTRUNCATE操作
Elasticsearchハンドラがソース証跡でTRUNCATE
操作を検出すると、次のエラーが発生します。
oracle.goldengate.util.GGException: Elasticsearch Handler does not support the operation: TRUNCATE
この例外エラー・メッセージは、RAeplicatプロセスが異常終了する前にハンドラのログ・ファイルに書き込まれます。Replicatのパラメータ・ファイルからGETTRUNCATES
パラメータを削除すると、このエラーが解決します。
親トピック: トラブルシューティング
4.7.6 一括実行エラー
DEBUG [main] (ElasticSearch5DOTX.java:130) - Bulk execute status: failures:[true] buildFailureMessage:[failure in bulk execution: [0]: index [cs2cat_s1sch_n1tab], type [N1TAB], id [83], message [RemoteTransportException[[UOvac8l][127.0.0.1:9300][indices:data/write/bulk[s][p]]]; nested: EsRejectedExecutionException[rejected execution of org.elasticsearch.transport.TransportService$7@43eddfb2 on EsThreadPoolExecutor[bulk, queue capacity = 50, org.elasticsearch.common.util.concurrent.EsThreadPoolExecutor@5ef5f412[Running, pool size = 4, active threads = 4, queued tasks = 50, completed tasks = 84]]];]
Elasticsearchが操作を処理するためのリソースが不足している可能性があります。MAXTRANSOPS
を使用してReplicatのバッチ・サイズを制限し、Elasticsearchの構成パラメータthread_pool.bulk.queue_size
の値と一致させることができます。
注意:
Elasticsearchのパラメータthread_pool.bulk.queue_size
の変更は、Elasticsearchノードの再起動後にのみ有効です。
親トピック: トラブルシューティング
4.8 ロギング
接続に成功すると、ハンドラのログ・ファイルに次のログ・メッセージが表示されます。
2.x Elasticsearchクラスタへの接続:
INFO 2017-01-31 01:43:38,814 [main] **BEGIN Elasticsearch client settings** INFO 2017-01-31 01:43:38,860 [main] key[cluster.name] value[elasticsearch-user1-myhost] INFO 2017-01-31 01:43:38,860 [main] key[request.headers.X-Found-Cluster] value[elasticsearch-user1-myhost] INFO 2017-01-31 01:43:38,860 [main] key[shield.user] value[es_admin:user1] INFO 2017-01-31 01:43:39,715 [main] Connecting to Server[myhost.us.example.com] Port[9300] INFO 2017-01-31 01:43:39,715 [main] Client node name: Smith INFO 2017-01-31 01:43:39,715 [main] Connected nodes: [{node-myhost}{vqtHikpGQP-IXieHsgqXjw}{10.196.38.196}{198.51.100.1:9300}] INFO 2017-01-31 01:43:39,715 [main] Filtered nodes: [] INFO 2017-01-31 01:43:39,715 [main] **END Elasticsearch client settings**
5.x Elasticsearchクラスタへの接続:
INFO [main] (Elasticsearch5DOTX.java:38) - **BEGIN Elasticsearch client settings** INFO [main] (Elasticsearch5DOTX.java:39) - {xpack.security.user=user1:user1_kibana, cluster.name=elasticsearch-user1-myhost, request.headers.X-Found-Cluster=elasticsearch-user1-myhost} INFO [main] (Elasticsearch5DOTX.java:52) - Connecting to Server[myhost.us.example.com] Port[9300] INFO [main] (Elasticsearch5DOTX.java:64) - Client node name: _client_ INFO [main] (Elasticsearch5DOTX.java:65) - Connected nodes: [{node-myhost}{w9N25BrOSZeGsnUsogFn1A}{bIiIultVRjm0Ze57I3KChg}{myhost}{198.51.100.1:9300}] INFO [main] (Elasticsearch5DOTX.java:66) - Filtered nodes: [] INFO [main] (Elasticsearch5DOTX.java:68) - **END Elasticsearch client settings**
親トピック: Elasticsearchハンドラの使用
4.9 Elasticsearchハンドラの既知の問題
Elasticsearch: 非常に大きな数を入力しようとしています
非常に大きな数値は、Elasticsearchのドキュメントでは不正確な値になります。たとえば、9223372036854775807、-9223372036854775808。これは、Elasticsearchサーバーの問題であり、Elasticsearchハンドラの制限ではありません。
この問題の回避策は、gg.handler.name.numberAsString=true
プロパティを使用してすべての数値を文字列として収集することです。
Elasticsearch: インデックスの問題
類似した列名で異なる列データ型を持つ複数の表がある場合、Elasticsearchハンドラでは同じインデックスにデータを入力できません。
証跡内のcatalog/schema/tablename
は、大文字と小文字を区別することがありますが、インデックス名は常に小文字です。
親トピック: Elasticsearchハンドラの使用