7 メタデータ・プロバイダの使用

この章では、メタデータ・プロバイダの機能と、メタデータ・プロバイダの各タイプについて説明し、その機能の理解に役立つ例も示します。

この章の内容は次のとおりです。

ハンドラがReplicatプロセスで実行されるように構成されている場合にのみ有効です。

Replicatプロセスには、Replicat構成ファイルの構文を使用して、ソース表からターゲット表へ、およびソース列からターゲット列へのマッピングを実行する機能があります。このマッピング構文は、Oracle GoldenGate Replicatのドキュメンテーションに含まれるドキュメントに記載されています。ソース・メタデータ定義は、Oracle GoldenGateの証跡ファイルに含まれています(または、12.2より古いOracle GoldenGateではソース定義ファイルによって)。レプリケーション・ターゲットがデータベースの場合、Replicatプロセスはターゲット・メタデータ定義をターゲット・データベースから取得します。しかし、これはビッグ・データ・アプリケーションや一般的なJava Deliveryにデータをプッシュする場合には不利です。ビッグ・データ・アプリケーションは一般的に、ターゲット・メタデータを提供しないため、Replicatのマッピングは実行できません。この欠点に対処するのが、メタデータ・プロバイダです。メタデータ・プロバイダを使用すると、AvroまたはHiveを使用してターゲット・メタデータを定義でき、続いてソース表からターゲット表へ、およびソース列からターゲット列へのReplicatマッピングが可能になります。メタデータ・プロバイダ使用は必須ではありません。ソースのOracle GoldenGate証跡ファイルに含まれるメタデータを出力に利用できる場合、メタデータ・プロバイダは使用しないでください。メタデータ・プロバイダは、次の場合に使用する必要があります。

ソース表名を、一致しないターゲット表名にマッピングする必要があります。
ソース列名を、一致しないターゲット列名にマッピングする必要があります。
ソース証跡ファイルからの特定の列を含め、それ以外の列を除外する必要があります。

Replicatマッピングには、Replicat構成ファイルで定義されているマッピングが静的であるという一般的な制限があります。Oracle GoldenGate 12.2には、ソースとしてOracleデータベースを使用するとき、DDL伝播の機能があります。したがって、メタデータ・プロバイダとReplicatマッピングを使用する際には、スキーマ展開の適切な処理が問題になることがあります。ユーザーは、スキーマ展開の特別なユースケースを考慮したうえで、必要な変更のためにメタデータ・プロバイダとReplicatマッピング構文をどのように更新するかを計画する必要があります。

COLMAPを使用してREPLICATでマップされる表ごとに、構成されたメタデータ・プロバイダからメタデータが取得され、そのメタデータがREPLICATによって列マッピング機能のために使用されます。

ユーザーは、1つのメタデータ・プロバイダ実装の構成を選択できます。現在は、HiveおよびAvroのメタデータ・プロバイダがサポートされています。HiveおよびAvroのメタデータ・プロバイダの構成については、次の項以降で説明します。

メタデータ・プロバイダはオプションであり、有効にするにはJavaアダプタ・プロパティ・ファイルでgg.mdp.typeを指定します。

シナリオ - いつメタデータ・プロバイダを使用するか

次のシナリオでは、メタデータ・プロバイダの構成は必要ありません。

GGという名前のソース・スキーマが、GGADPという名前のターゲット・スキーマにマップされるスキーマ名のマッピング。*

GG.TCUSTMERというスキーマが、GGADP.TCUSTMER_NEWという表名にマップされるスキーマと表名のマッピング。
```
MAP GG.*, TARGET GGADP.*;
(OR)
MAP GG.TCUSTMER, TARGET GG_ADP.TCUSTMER_NEW;
```
次のシナリオでは、メタデータ・プロバイダの構成が必要です。

ソース列名がターゲット列名に一致しない列名のマッピング。たとえば、ソース列CUST_CODEは、ターゲット列CUST_CODE_NEWにマップします
```
MAP GG.TCUSTMER, TARGET GG_ADP.TCUSTMER_NEW, COLMAP(USEDEFAULTS, CUST_CODE_NEW=CUST_CODE, CITY2=CITY);
```

7.1 Avroメタデータ・プロバイダ

Avroメタデータ・プロバイダは、Avroスキーマ・ファイルから表メタデータを取得する際に使用します。COLMAPを使用してREPLICATでマップされる表ごとに、Avroスキーマからメタデータが取得され、そのメタデータがREPLICATによって列マッピングのために使用されます。

この項の内容は次のとおりです。

7.1.1 詳細な機能

Avroメタデータ・プロバイダは、Avroスキーマ定義ファイルを使用してメタデータを使用します。AvroスキーマはJSONを使用して定義されます。Replicat.prmファイルでマップされる表ごとに、対応するAvroスキーマ定義ファイルを作成する必要があります。Avroスキーマの定義の詳細は、次のページを参照してください。

http://avro.apache.org/docs/current/gettingstartedjava.html#Defining+a+schema

Avroメタデータ・プロバイダ・スキーマ定義の構文は、次のとおりです。

{"namespace": "[$catalogname.]$schemaname",
"type": "record",
"name": "$tablename",
"fields": [
     {"name": "$col1", "type": "$datatype"},
     {"name": "$col2 ",  "type": "$datatype ", "primary_key":true}, 
     {"name": "$col3", "type": "$datatype ", "primary_key":true}, 
     {"name": "$col4", "type": ["$datatype","null"]}   
   ]
}
 
namespace            - name of catalog/schema being mapped
name                 - name of the table being mapped
fields.name          - array of column names
fields.type          - datatype of the column
fields.primary_key   - indicates the column is part of primary key.

Representing nullable and not nullable columns:

"type":"$datatype" - indicates the column is not nullable, where "$datatype" is the actual datatype.
"type": ["$datatype","null"] - indicates the column is nullable, where "$datatype" is the actual datatype

Avroメタデータ・プロバイダによってアクセスされるAvroスキーマ・ファイルは、命名規則によって次の形式になります。

[$catalogname.]$schemaname.$tablename.mdp.avsc
 
$catalogname    - name of the catalog if exists
$schemaname   - name of the schema
$tablename        - name of the table
.mdp.avsc           -  constant, which should be appended always

サポートされているAvroデータ型:

boolean
bytes
double
float
int
long
string

Avroデータ型の詳細は、https://avro.apache.org/docs/1.7.5/spec.html#schema_primitiveを参照してください。

7.1.2 実行時の前提条件

Avroスキーマ定義は、Replicatプロセスを開始する前に、Replicatのパラメータ・ファイルでマップされるすべての表について作成する必要があります。

7.1.3 クラスパス構成

Avroメタデータ・プロバイダに、追加のクラスパス設定は必要ありません。

7.1.4 Avroメタデータ・プロバイダの構成

この項では、Oracle GoldenGate Avroメタデータ・プロバイダの構成プロパティについて詳細に説明します

プロパティ	必須/オプション	有効な値	デフォルト	説明
`gg.mdp.type`	必須	`avro`	-	Avroメタデータ・プロバイダを選択します
`gg.mdp.schemaFilesPath`	必須	有効な値の例は、`/home/user/ggadp/avroschema/`	-	Avroスキーマ・ファイルのディレクトリのパス
`gg.mdp.charset`	オプション	有効なキャラクタ・セット	UTF-8	文字データ型で列のキャラクタ・セットを指定します。これは、ソース・データを証跡ファイルから正しいターゲットのキャラクタ・セットに変換します。
`gg.mdp.nationalCharset`	オプション	有効なキャラクタ・セット	UTF-8	文字データ型で列のキャラクタ・セットを指定します。これは、ソース・データを証跡ファイルから正しいターゲットのキャラクタ・セットに変換します。例: Oracle Databaseの場合、`NCHAR`や`NVARCHAR`などの列のキャラクタ・セットを指定します。

7.1.5 サンプル構成

この項では、Avroメタデータ・プロバイダを構成する例を示します。次の表でソースを検討してください。

TABLE GG.TCUSTMER {
     CUST_CODE VARCHAR(4) PRIMARY KEY,
     NAME VARCHAR(100),
     CITY VARCHAR(200),
     STATE VARCHAR(200)
}

ソースの列 CUST_CODE (GG.TCUSTMER)を、ターゲットのCUST_CODE2 (GG_AVRO.TCUSTMER_AVRO)に、またソースの列CITY (GG.TCUSTMER)をターゲットのCITY2 (GG_AVRO.TCUSTMER_AVRO)に、それぞれマップします。

Replicat .prmファイルでのマッピングは、次のとおりです。

MAP GG.TCUSTMER, TARGET GG_AVRO.TCUSTMER_AVRO, COLMAP(USEDEFAULTS, CUST_CODE2=CUST_CODE, CITY2=CITY);
 
Mapping definition in this example:
1.Source schema GG is mapped to target schema GG_AVRO
2.Source column CUST_CODE is mapped to target column CUST_CODE2
3.Source column CITY is mapped to target column CITY2
4.USEDEFAULTS specifies that rest of the columns names are same on both source and target (NAME and STATE columns).

上の例のAvroスキーマ定義ファイルは、次のとおりです。

ファイル・パス: /home/ggadp/avromdpGG_AVRO.TCUSTMER_AVRO.mdp.avsc

{"namespace": "GG_AVRO",
"type": "record",
"name": "TCUSTMER_AVRO",
"fields": [
     {"name": "NAME", "type": "string"},
    {"name": "CUST_CODE2",  "type": "string", "primary_key":true},
     {"name": "CITY2", "type": "string"},
     {"name": "STATE", "type": ["string","null"]}
]
}

Javaアダプタ・プロパティ・ファイルの構成には、次の指定が含まれます。

gg.mdp.type = avro
gg.mdp.schemaFilesPath = /home/ggadp/avromdp

前述の例について";"を区切り文字として使用した場合の、区切りテキスト・フォーマッタを使用した出力の例を次に示します。

I;GG_AVRO.TCUSTMER_AVRO;2013-06-02 22:14:36.000000;NAME;BG SOFTWARE CO;CUST_CODE2;WILL;CITY2;SEATTLE;STATE;WA

Oracle GoldenGate for Big Dataのインストールには、サンプルのReplicat構成ファイル、サンプルのJavaアダプタ・プロパティ・ファイル、サンプルのAvroスキーマが、次の場所に用意されています。

GoldenGate_install_directory/AdapterExamples/big-data/metadata_provider/avro

7.1.6 メタデータ変更イベント

ソース・データベース表でDDL変更がある場合、Avroスキーマ定義と、Replicat構成ファイルでのマッピングは、変更が必要な場合があります。メタデータ変更イベントがあった場合には、Replicatプロセスを中止または一時停止したいこともあります。Replicatプロセスは、Replicat構成ファイル(.prmファイル)に次の指定を追加すると中止できます。

DDL INCLUDE ALL, EVENTACTIONS (ABORT)

あるいは、レプリケーション構成ファイル(.prmファイル)に次の指定を追加すると一時停止できます。

DDL INCLUDE ALL, EVENTACTIONS (SUSPEND)

7.1.7 制限

Avroのbyteデータ型は、主キーとして使用できません。

Replicat構成ファイルに定義されているソースからターゲットへのマッピングは静的です。Oracle GoldenGate 12.2は、Oracleデータベースがレプリケーション・ソースの場合に、DDL伝播とソース・スキーマ展開をサポートします。ただし、Replicat構成ファイルで構成されるマッピングは静的なため、ソース・スキーマの展開が問題になる場合もあります。

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

この項の内容は次のとおりです。

7.1.8.1 無効なスキーマ・ファイルの場所

構成プロパティgg.mdp.schemaFilesPathで指定するAvroスキーマ・ファイル・ディレクトリの場所は、有効なディレクトリである必要があります。gg.mdp.schemaFilesPathプロパティで有効なディレクトリを構成しない場合、次の例外が発生します。

oracle.goldengate.util.ConfigException: Error initializing Avro metadata provider
Specified schema location does not exist. {/path/to/schema/files/dir}

7.1.8.2 無効なスキーマ・ファイル名

Replicat.prmファイルでマップされる表ごとに、対応するAvroスキーマ・ファイルを、gg.mdp.schemaFilesPathで指定されたディレクトリに作成する必要があります。

たとえば、次のシナリオを考えてみます。

マッピング:

MAP GG.TCUSTMER, TARGET GG_AVRO.TCUSTMER_AVRO, COLMAP(USEDEFAULTS, cust_code2=cust_code, CITY2 = CITY);

プロパティ:

gg.mdp.schemaFilesPath=/home/usr/avro/

GG_AVRO.TCUSTMER_AVRO.mdp.avscという名前のファイルを、/home/usr/avro/ディレクトリに作成する必要があります。つまり、/home/usr/avro/GG_AVRO.TCUSTMER_AVRO.mdp.avscとなります

/home/usr/avro/GG_AVRO.TCUSTMER_AVRO.mdp.avscファイルを作成しない場合、次の例外が発生します。

java.io.FileNotFoundException: /home/usr/avro/GG_AVRO.TCUSTMER_AVRO.mdp.avsc

7.1.8.3 スキーマ・ファイルでの無効なネームスペース

REPLICATマッピングで指定するターゲット・スキーマ名は、Avroスキーマ定義ファイルのネームスペースと同じである必要があります。

たとえば、次のシナリオを考えてみます。

マッピング:

MAP GG.TCUSTMER, TARGET GG_AVRO.TCUSTMER_AVRO, COLMAP(USEDEFAULTS, cust_code2 = cust_code, CITY2 = CITY);
 
Avro Schema Definition:
 
{
"namespace": "GG_AVRO",
..
}

このシナリオでは、Replicatマッピングで指定したターゲット・スキーマ名がAvroスキーマのネームスペースに一致しない場合、REPLICATが次の例外で異常終了します。

Unable to retrieve table matadata. Table : GG_AVRO.TCUSTMER_AVRO
Mapped [catalogname.]schemaname (GG_AVRO) does not match with the schema namespace {schema namespace}

7.1.8.4 スキーマ・ファイルでの無効な表名

Replicatマッピングで指定するターゲット表名は、Avroスキーマ定義ファイルでの名前と同じである必要があります。

たとえば、次のシナリオを考えてみます。

マッピング:

MAP GG.TCUSTMER, TARGET GG_AVRO.TCUSTMER_AVRO, COLMAP(USEDEFAULTS, cust_code2 = cust_code, CITY2 = CITY);
 
Avro Schema Definition:
 
{
"namespace": "GG_AVRO",
"name": "TCUSTMER_AVRO",
..
}

このシナリオでは、Replicatマッピングで指定したターゲット表名がAvroスキーマ名に一致しない場合、REPLICATが次の例外で異常終了します。

Unable to retrieve table matadata. Table : GG_AVRO.TCUSTMER_AVRO
Mapped table name (TCUSTMER_AVRO) does not match with the schema table name {table name}