4 Elasticsearchハンドラの使用

Elasticsearchハンドラを使用すると、大量のデータをすばやく、ほぼリアルタイムで保存、検索および分析できます。

この章では、Elasticsearchハンドラの使用方法について説明します。

4.1 概要

Elasticsearchは、拡張性の高い、オープン・ソースのフルテキスト検索および分析エンジンです。Elasticsearchを使用すると、大量のデータをすばやく、ほぼリアルタイムで保存、検索および分析できます。通常、複雑な検索機能を備えたアプリケーションを駆動する基盤となるエンジンやテクノロジとして使用されます。

Elasticsearchハンドラでは、Elasticsearch Javaクライアントを使用してElasticsearchノードに接続し、データを受信します。https://www.elastic.coを参照してください。

4.2 機能の詳細

このトピックでは、Elasticsearchハンドラの機能について詳しく説明します。

4.2.1 Elasticsearchバージョン・プロパティについて

Elasticsearchハンドラは、Elasticsearchクラスタと通信するために、Elasticsearchトランスポート・クライアントとElasticsearch High Level RESTクライアントの2つの異なるクライアントをサポートしています。

  1. 5.x、6.xまたは7.xのバージョンを使用するトランスポート・クライアントを使用してElasticsearchクラスタに接続するには、gg.handler.name.version構成値をそれぞれ5.x、6.xまたは7.xに設定します。
  2. Elasticsearch High Level RESTクライアントを使用してElasticseachクラスタに接続するには、gg.handler.name.version構成値をREST7.0に設定します。RESTクライアントはElasticsearchバージョン7.xをサポートしています。

4.2.2 インデックスとタイプについて

Elasticsearchのインデックスは、類似した特性を持つドキュメントの集まりです。インデックスは小文字でのみ作成できます。Elasticsearchのタイプは、インデックス内の論理グループです。インデックスまたはタイプ内のすべてのドキュメントは、同じ番号およびタイプのフィールドを持つ必要があります。

Elasticsearchハンドラでは、ソース証跡スキーマをソース証跡表名と連結してインデックスが構築されます。ソース証跡の3つの部分からなる表名の場合、インデックスはソース・カタログ、スキーマおよび表名を連結して構成されます。

Elasticsearchハンドラでは、ソース表名がElasticsearchのタイプにマッピングされます。タイプ名は大文字と小文字を区別します。

表4-1 Elasticsearchのマッピング

ソース証跡 Elasticsearchのインデックス Elasticsearchのタイプ

schema.tablename

schema_tablename

tablename

catalog.schema.tablename

catalog_schema_tablename

tablename

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ハンドラ・トランスポート・クライアント依存性を参照してください。Elatisticsearch High Level RESTクライアントに必要なクライアントJARファイルのリストは、Elasticsearch High Level RESTクライアント依存性を参照してください。

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.name.type=elasticsearchおよびその他のElasticsearchプロパティを次のように指定してハンドラ・タイプを構成する必要があります。

表4-2 Elasticsearchハンドラの構成プロパティ

プロパティ 必須/オプション 有効な値 デフォルト 説明
gg.handlerlist

必須

名前(任意の名前)

なし

使用するハンドラのリスト。

gg.handler.name.type

必須

elasticsearch

なし

使用するハンドラのタイプ。たとえば、Elasticsearch、Kafka、Flume、HDFSなどです。

gg.handler.name.ServerAddressList

オプション

Server:Port[, Server:Port]

localhost:9300

Elasticsearchクラスタに接続するノードの連絡ポイントのカンマ区切りのリスト。

gg.handler.name.clientSettingsFile

必須

トランスポート・クライアントのプロパティ・ファイル。

なし

Elasticsearchハンドラで使用されるElasticsearchトランスポート・クライアントのプロパティを保持するクラスパスのファイル名。

gg.handler.name.version

オプション

5.x|6.x|7.x|REST7.x

7.x

有効な値5.x、6.xおよび7.xは、Elasticsearchトランスポート・クライアントを使用してElasticsearchクラスタと通信することを示します。RESTは、Elasticsearch High Level RESTクライアントを使用してElasticsearchクラスタと通信することを示します。
gg.handler.name.bulkWrite

オプション

true | false

false

このプロパティがtrueの場合、Elasticsearchハンドラでは、一括書込みAPIを使用してElasticsearchクラスタにデータが収集されます。一括書込みのバッチ・サイズは、ReplicatパラメータのMAXTRANSOPSを使用して制御できます。

gg.handler.name.numberAsString

オプション

true | false

false

このプロパティがtrueの場合、Elasticsearchハンドラでは、ソース証跡内のすべての数値列の値(Long、IntegerまたはDouble)が文字列としてElasticsearchクラスタに受信されます。

gg.handler.name.routingKeyMappingTemplate

オプション

実行時にルーティング・キーの値を解決できるように、定数値およびテンプレート・キーワードで構成された文字列。

なし

実行時にルーティング・キーを動的に解決するためのテンプレートを設定して、メッセージの送信先のElasticsearch内のシャードを制御します。デフォルトでは、Elasticsearchでルーティング・キーとして使用されるIDが使用されます。

gg.handler.elasticsearch.upsert

オプション

true | false

true

このプロパティがtrueの場合、UPDATE操作の実行時にドキュメントが存在しないとき、新規ドキュメントが挿入されます。

gg.handler.elasticsearch.routingTemplate

オプション ${columnValue[table1=column1,table2=column2,…] なし N/A
gg.handler.name.authType オプション none | basic | ssl なし Elasticsearch RESTクライアントの認証タイプを制御します。
  • none - 認証なし
  • basic - メッセージを暗号化せずにユーザー名とパスワードを使用するクライアント認証
  • ssl - 相互認証。クライアントはトラストストアを使用してサーバーを認証します。ユーザー名とパスワードを使用するサーバー認証クライアント。メッセージは暗号化されます。
gg.handler.name.basicAuthUsername オプション 有効なユーザー名 なし Elasticsearch RESTクライアントを認証するサーバーのユーザー名。認証タイプbasicおよびsslに指定する必要があります。
gg.handler.name.basicAuthPassword オプション 有効なパスワード なし Elasticsearch RESTクライアントを認証するサーバーのパスワード。認証タイプbasicおよびsslに指定する必要があります。
gg.handler.name.trustStore オプション トラストストア・ファイルのパスと名前。 なし Elasticsearchサーバーから受信した証明書を検証するElasticsearchクライアントのトラストストア。認証タイプがsslに設定されている場合は指定する必要があります。Elasticsearch RESTクライアントに対してのみ有効です。
gg.handler.name.trustStorePassword オプション トラストストアにアクセスするためのパスワード。 なし Elasticsearchサーバーから受信した証明書を検証するElasticsearch RESTクライアントのトラストストアのパスワード。認証タイプがsslに設定されている場合は指定する必要があります。
gg.handler.name.maxConnectTimeout オプション 正の整数 Apache HTTPコンポーネント・フレームワークのデフォルト値。 Elasticsearch RESTクライアントからElasticsearchサーバーへの接続が確立されるまでの最大待機時間を設定します。Elasticsearch RESTクライアントに対してのみ有効です。
gg.handler.name.maxSocketTimeout オプション 正の整数 Apache HTTPコンポーネント・フレームワークのデフォルト値。 リクエストの発行後にサービスからのレスポンスを待機する最大待機期間(ミリ秒)を設定します。大量のデータをプッシュする場合は、増やす必要がある場合があります。Elasticsearch RESTクライアントに対してのみ有効です。
gg.handler.name.proxyUsername オプション プロキシ・サーバーのユーザー名。 なし Elasticsearchへの接続でRESTクライアントおよびプロキシ・サーバー経由のルーティングを使用する場合、このプロパティはプロキシ・サーバーのユーザー名を設定します。ほとんどのプロキシ・サーバーでは、資格証明は必要ありません。
gg.handler.name.proxyPassword オプション プロキシ・サーバーのパスワード。 なし Elasticsearchへの接続でRESTクライアントおよびプロキシ・サーバー経由のルーティングを使用する場合、このプロパティはプロキシ・サーバーのパスワードを設定します。ほとんどのプロキシ・サーバーでは、資格証明は必要ありません。
gg.handler.name.proxyProtocol オプション http | https http Elasticsearchへの接続でRESTクライアントおよびプロキシ・サーバー経由のルーティングを使用する場合、このプロパティはプロキシ・サーバーのプロトコルを設定します。
gg.handler.name.proxyPort オプション プロキシ・サーバーのポート番号。 なし Elasticsearchへの接続でRESTクライアントおよびプロキシ・サーバー経由のルーティングを使用する場合、このプロパティはプロキシ・サーバーのポート番号を設定します。
gg.handler.name.proxyServer オプション プロキシ・サーバーのホスト名。 なし Elasticsearchへの接続でRESTクライアントおよびプロキシ・サーバー経由のルーティングを使用する場合、このプロパティはプロキシ・サーバーのホスト名を設定します。

例4-1 サンプルのハンドラ・プロパティ・ファイル:

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 RESTハンドラの場合

gg.handlerlist=elasticsearch
gg.handler.elasticsearch.type=elasticsearch
gg.handler.elasticsearch.ServerAddressList=localhost:9300
gg.handler.elasticsearch.version=rest7.x
gg.classpath=/path/to/elasticsearch/lib/*:/path/to/elasticsearch/modules/reindex/*:/path/to/elasticsearch/modules/lang-mustache/*:/path/to/elasticsearch/modules/rank-eval/*

4.3.2 トランスポート・クライアントの設定プロパティ・ファイルについて

Elasticsearchハンドラは、JavaのTransportクライアントを使用してElasticsearchクラスタとやりとりします。Elasticsearchクラスタには、shieldやx-packのような追加のプラグインがあり、追加の構成が必要な場合があります。

gg.handler.name.clientSettingsFileプロパティは、Elasticsearchクラスタのバージョンに基づく追加のクライアント設定のあるファイルを指している必要があります。Elasticsearchハンドラは、Javaクラスパスを使用してクライアント設定ファイルの検索とロードを試みます。Javaクラスパスには、プロパティ・ファイルのあるディレクトリが含まれている必要があります。

Elasticsearch (プラグインなし)のクライアント・プロパティ・ファイル:

cluster.name=Elasticsearch_cluster_name

Shieldプラグインは、SSLやIPフィルタリングなどの追加機能もサポートしています。プロパティは、client.propertiesファイルで設定できます。https://www.elastic.co/guide/en/shield/current/_using_elasticsearch_java_clients_with_shield.htmlを参照してください。

X-Packプラグインを使用するElasticsearch 5.xclient.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を参照)。

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ファイルで変更できます。

4.5 Shieldプラグインのサポートについて

Elasticsearchバージョン5.xでは、基本認証、SSLおよびIPフィルタリングを提供するShieldプラグインがサポートされています。Elasticsearch 6.xおよび7.xのX-Packプラグインにも同様の機能があります。追加のトランスポート・クライアントの設定は、gg.handler.name.clientSettingsFileプロパティを使用してElasticsearchハンドラで構成できます。

4.6 DDL処理について

Elasticsearchハンドラはソース証跡内のDDLレコードには反応しません。新規ソース表のデータ操作レコードにより、Elasticsearchクラスタでインデックスまたはタイプの自動作成が行われます。

4.7 トラブルシューティング

この項では、様々な問題のトラブルシューティングに役立つ情報を示します。

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プロパティを5.x、6.x、7.xまたはRESTに設定する必要があります。たとえば、gg.handler.name.version=7.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:]

この問題をデバッグするには、次のステップを実行します。

  1. Elasticsearchのサーバー・プロセスが実行中であることを確認します。

  2. クライアント・プロパティ構成ファイルで、cluster.nameプロパティを確認します。

  3. クライアント・プロパティ・ファイルで、x-PackまたはShieldプラグインの認証の資格証明を確認します。

  4. 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 ロギング

接続に成功すると、ハンドラのログ・ファイルに次のログ・メッセージが表示されます。

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**

4.9 Elasticsearchハンドラの既知の問題

Elasticsearch: 非常に大きな数を入力しようとしています

非常に大きな数値は、Elasticsearchのドキュメントでは不正確な値になります。たとえば、9223372036854775807、-9223372036854775808。これは、Elasticsearchサーバーの問題であり、Elasticsearchハンドラの制限ではありません。

この問題の回避策は、gg.handler.name.numberAsString=trueプロパティを使用してすべての数値を文字列として収集することです。

Elasticsearch: インデックスの問題

類似した列名で異なる列データ型を持つ複数の表がある場合、Elasticsearchハンドラでは同じインデックスにデータを入力できません。

証跡内のcatalog/schema/tablenameは、大文字と小文字を区別することがありますが、インデックス名は常に小文字です。