21.4 マイグレータ・パラメータを指定するJSON構成フィールド

マイグレータ構成オブジェクトを引数としてPL/SQL DBMS_JSON_DUALITYサブプログラムinfer_schema、infer_and_generate_schemaおよびimport_allに渡すことで、JSONから二面性への移行を構成します。このようなオブジェクトのサポートされているフィールドについて説明します。

ノート:

初めて読むときはこのトピックをスキップして、後で参照することもできます。ここには、なにが使用可能なのかを把握するための情報が記載されています。

プロシージャimport_allは、構成フィールドerrorLog、errorLogSchemaおよびrejectLimitを使用する唯一のサブプログラムです。ファンクションinfer_schemaおよびinfer_and_generate_schemaのみが、構成フィールドhints、ingestLimit、minFieldFrequency、minTypeFrequency、normalize、outputFormat、softnessThreshold、tablespace、updatabilityおよびuseFlexFieldsを使用するサブプログラムです。

したがって、様々なDBMS_JSON_DUALITYマイグレータ・サブプログラムで実際に使用される構成フィールドは異なりますが、いくつか重複しています。これらのサブプログラムのいずれにも、任意の構成フィールドを渡すことができます。使用されないフィールドは無視されます。具体的には、これは、これらのサブプログラムのいずれにも共通の構成ドキュメントを渡すことができることを意味します。

JSON構成オブジェクトを受け入れるかわりに、PL/SQLサブプログラムimport、validate_schema_reportおよびvalidate_import_reportでは、一部の構成フィールドを使用するのと同じまたは同様の機能を持つ特定のJSON以外の引数を受け入れます。パラメータ名はフィールド名に似ており、ここでのフィールドの説明は一般的に、対応するパラメータにも適用されます。たとえば、ファンクションvalidate_import_reportのパラメータtable_nameは、構成フィールドtableNameに対応します。

マイグレータ構成フィールドを次に示します。tableNames以外はすべてオプションです。示されているフィールド以外のフィールドはいずれも使用すると、エラーが発生します。

• errorLog (オプション) - 使用する単一のエラー・ログを指定する文字列、または使用する複数(二面性ビューごとに1つずつ)のエラー・ログを指定する文字列の配列。

  フィールドerrorLogは、プロシージャimport_allにのみ使用されます。

• errorLogSchema (オプション) - エラー・ログを所有するデータベース・スキーマ(ユーザー)を指定する文字列。errorLogSchemaにエラー・ログ所有者を指定しない場合は、現在接続されているユーザーの名前が使用されます。

  フィールドerrorLogSchemaは、プロシージャimport_allにのみ使用されます。

• hints (オプション) - フィールドがリレーショナル・スキーマの生成時のコンバータの動作に対するオーバーライドを指定するJSONオブジェクトである要素を含むJSON配列。"ヒント"という名前は、単なる提案ではなく必須事項であるため、少し誤解を招くと言えます。なんらかの理由でヒントを順守できない場合、エラーが発生します。ヒントが無視されることはありません。エラーは、ヒントが正しく指定されていない場合にも発生します。

  ヒント・オブジェクトには次のフィールドが必要です(ない場合は、エラーが発生します):

  • type - この値は、マイグレータ動作のオーバーライドのタイプを指定する次の文字列のいずれかです:

    • "datatype" - 二面性ビュー定義の基礎となる表の列に使用するSQLデータ型を要求します。この列は、pathでターゲット指定したドキュメント・フィールドに対応します。フィールドvalueは、スカラーSQLデータ型(JSONおよびVECTOR型の"json"および"vector"を含む)を指定する文字列です。データ型名は大/小文字を区別せずに解釈され、CREATE TABLEで受け入れられる任意の列型を指定できます。

    • "key" - フィールドpathでターゲット指定したドキュメント・オブジェクト(またはオブジェクトの配列)の基礎となる表の識別列を要求します。フィールドvalueは、列が識別列であるスカラーJSONフィールドを指定する文字列であるか、またはそのようなフィールド名文字列の配列であり、その各列が表の識別列です(つまり、これらの列を組み合せて行を一意に識別します。例は、『JSONリレーショナル二面性開発者ガイド』の「カーレースの例、表」を参照してください)。

    • "normalize" - フィールドvalueがfalseの場合、フィールドpathでターゲット指定した、ドキュメント内のJSONデータが共有されないことを要求します。

      これは、infer_schemaおよびinfer_and_generate_schema (フィールドhintsは、これらのファンクションによってのみ使用されます)によって処理される入力ドキュメント・セット内のすべてのドキュメントに適用されます。ドキュメント・データのターゲット指定は、特定の種類のドキュメントに固有ではありません。table内の列から取得され、同じpath値でターゲット指定したデータを含む任意の種類のドキュメントに作用します。

      フィールドpathは、任意のレベル(パス$でターゲット指定した、ドキュメント内のルート・オブジェクトを含む)のオブジェクトをターゲットとする必要があります。pathでスカラー値または配列値をターゲット指定すると、エラーが発生します。

      実際には、指定された表は、指定されたパスのデータに対してロックされ(専用になり)、その逆も同様です。表は、入力ドキュメント・セットのどこにおいても、pathでターゲット指定したデータ以外のデータにはマップされません。したがって、指定されたパスでターゲット指定した(あらゆるドキュメント内の)データは、同じドキュメント内であっても異なるドキュメント内であっても、異なるパスのどの場所でも共有されません。パスで指定された場所にあるすべてのドキュメントで共有されます。

      ターゲット指定したオブジェクトの基礎となる表のみがロックされます。ターゲット指定したオブジェクト内のサブオブジェクトの基礎となるデータの共有は、それ独自の基礎となる表によって制御されます。

      フィールドvalueがtrueの場合、入力JSONデータを正規化しようとするのがデフォルトの動作であるため、このヒントは効果がありません。

  • table - ドキュメント・セット・データが二面性ビューの定義に使用される入力表を指定する文字列。

  • path - 入力JSONドキュメントのデータをターゲットとするSQL/JSONパス式の文字列。パスがターゲット指定するデータがない場合は、エラーが発生します。

  • value - 特定のtypeに固有の情報で、ヒントを定義する詳細を指定します。(これは、値が必ずしも文字列ではない唯一のヒント・フィールドです。normalizeの場合は、ブールです。)

  フィールドhintsは、ファンクションinfer_schemaおよびinfer_schema_and_generateにのみ使用されます。

• ingestLimit (オプション) — 各ドキュメント・セットで分析されるドキュメントの最大数。制限を超えてもエラーは発生せず、その他のドキュメントが検査されないだけです。

  デフォルト値は「100,000」です。

  フィールドingestLimitは、ファンクションinfer_schemaおよびinfer_schema_and_generateにのみ使用されます。

• minFieldFrequency (オプション) - 外れ値(高エントロピ)とみなされないフィールドの最小頻度。

  フィールドが特定のドキュメント・セットの出現の外れ値となるのは、ドキュメントのminFieldFrequencyパーセント未満でフィールドが出現する場合です。値ゼロ(0)パーセントは、外れ値とみなされるフィールドがないことを意味します。

  たとえば、コースの入力ドキュメントで、値25がminFieldFrequencyに使用されている場合、フィールドNotesは、コースのドキュメント・セットのドキュメントの25%未満で出現するため、出現の外れ値になります。

  デフォルトのminFieldFrequency値は5です。つまり、入力ドキュメント・セットのドキュメントの5%未満で出現するフィールドは高エントロピとみなされます。

  コンバータは、出現の外れ値フィールドを基礎となる列にマップしません。フレックス列が存在する場合、インポータは、列にマップされていないフィールド(出現の外れ値フィールドなど)すべてを、フィールドの場所に対応するフレックス列に格納します。

  ノート:

  このマニュアルに示す学生-教師-コースの例では、各ドキュメント・セットに含まれるドキュメントが非常に少ないため、出現の外れ値の判別および処理を示すために、25をminFieldFrequency値として使用します。

• minTypeFrequency (オプション) - 外れ値(高エントロピ)とみなされないフィールドの値の型の最小頻度。

  フィールドが特定のドキュメント・セットの型出現の外れ値または型の外れ値となるのは、ドキュメントのminTypeFrequencyパーセント未満で、その値のいずれかが特定の型で出現する場合です。値ゼロ(0)パーセントは、外れ値とみなされるフィールドがないことを意味します。

  たとえば、コースの入力ドキュメントで、値15がminTypeFrequencyに使用されている場合、学生のフィールドageは、ドキュメントの10%(15%未満)で文字列値を持つため、型の外れ値になります。(他のドキュメントでは数値を持ちます。)

  デフォルトのminTypeFrequency値は5です。つまり、入力ドキュメント・セットのドキュメントの5%未満でフィールドが特定の型を持つ場合は外れ値とみなされます。

  インポータは、まれな型の値をフィールドの一般的な型に変換しようとします。たとえば、lengthフィールドの一般的な型がnumberの場合、値"42"を持つlengthの出現は数値42に変換されます。変換の試行が失敗すると、その出現に関するエラーがログに記録されます。

  ノート:

  ここに示す例では、各ドキュメント・セットに含まれるドキュメントが非常に少ないため、型の外れ値の判別および処理を示すために、15をminTypeFrequency値として使用します。

• normalize (オプション) - コンバータが推測するリレーショナル表の正規化(共有)を試みる必要があるかどうかを示すブール値(true/false)。false値は、二面性ビューでサポートされるドキュメント内の各オブジェクトに、独自の基礎となる表(他の二面性ビューと共有されない表)があることを意味します。

  デフォルト値はtrue。

  フィールドnormalizeは、ファンクションinfer_schemaおよびinfer_schema_and_generateにのみ使用されます。

  この最上位構成フィールドnormalizeは、生成されるすべての表および二面性ビューの一般的なコンバータの動作に適用されます。一方、hintsフィールドのオブジェクト内のフィールドnormalizeは、特定のドキュメント・オブジェクトの基礎となる表の共有という、共有をよりきめ細かく防止します。

• outputFormat (オプション) — 出力データ定義言語(DDL)スクリプトの形式を定義する値を持つ文字列。

  デフォルト値は"executable"です。これは、DDLスクリプトを直接実行できることを意味します。PL/SQL EXECUTE IMMEDIATEを使用します。他の指定可能な値は"standalone"です。これは、個別に実行するSQLスクリプトでDDLスクリプトを使用できることを意味します。

  フィールドoutputFormatは、ファンクションinfer_schemaおよびinfer_schema_and_generateにのみ使用されます。

  生成されたDDLが32KBを超える場合は、"standalone"を使用する必要があります。そうでない場合、EXECUTE IMMEDIATEを起動するとエラーが発生します。"executable" DDLスクリプトは、入力データ・セット自体が非常に大きい場合、またはネストされた値のレベルが多数ある場合、大きすぎる可能性があります。

• rejectLimit (オプション) - ログに記録できるエラーの最大数。この制限を超えると、インポート操作は取り消され(失敗)、ロールバックされるため、エラー・ログは使用できません。デフォルトでは、制限はありません。

  フィールドrejectLimitは、プロシージャimport_allにのみ使用されます。

• softnessThreshold (オプション) - 入力データに許可される最小清浄度レベル。デフォルト値は99です。つまり、入力ドキュメントの99%以上に欠落した情報や正しくない情報がないようにする必要があります。

  フィールドsoftnessThresholdは、ファンクションinfer_schemaおよびinfer_schema_and_generateにのみ使用されます。

• sourceSchema (オプション) — 入力表(tableNames)を所有するデータベース・スキーマ(ユーザー)の名前を値とする文字列。

  指定しない場合、入力表の識別に使用されるデータベース・スキーマは、DDLの(実行時ではなく)生成時の現在のスキーマになります。

• tableNames (必須) — 元の外部ドキュメント・セットに対応するOracle Database転送表を指定する文字列の配列。各表には、特定のドキュメント・セットのドキュメントを格納するJSON型の列が必要です(dataという名前を付ける必要はありません)。

  フィールドviewNamesを指定する場合、配列の長さはフィールドtableNamesの長さと同じである必要があります。そうでない場合は、エラーが発生します(ログに記録されません)。

• tablespace (オプション) — 二面性ビューの基礎となるすべての表に使用する表領域の名前を値とする文字列。

  指定しない場合、出力DDLに表領域は指定されません。つまり、使用される表領域は、DDLコードの(生成時ではなく)実行時の現在の表領域になります。

  フィールドtablespaceは、ファンクションinfer_schemaおよびinfer_schema_and_generateにのみ使用されます。

• targetSchema (オプション) — 出力データベース・ビュー(viewNames)を所有するデータベース・スキーマ(ユーザー)の名前を値とする文字列。

  指定しない場合、出力DDLにデータベース・スキーマは指定されません。作成されるデータベース・オブジェクトの名前は修飾されません。つまり、使用されるスキーマは、DDLコードの(生成時ではなく)実行時の現在のスキーマになります。

• updatability (オプション) — 生成される二面性ビューを更新可能(true)にするか、更新不可(false)にするかを決定するブール値。trueの場合、注釈(「注釈(NO)UPDATE、(NO)INSERT、(NO)DELETEによる更新操作の許可/禁止」を参照)は、各ビューの更新可能性を最大限に高めるために設定されます。falseの場合、作成されるすべてのビューは読取り専用です。

  デフォルト値はtrue。

  フィールドupdatabilityは、ファンクションinfer_schemaおよびinfer_schema_and_generateにのみ使用されます。

• useFlexFields (オプション) — 二面性ビューの基礎となる表にフレックス列を追加するかどうかを決定するブール値。フレックス列は、アプリケーション実行時に、挿入または更新される受信ドキュメントの認識されないフィールドを格納するために使用されます。

  useFlexFieldsがtrueの場合、二面性ビュー<view-name>ごとに、ora$<view-name>_flexという名前のフレックス列が各表に追加され、サポートされているドキュメント内のオブジェクトの最上位フィールドの直下に配置されます。(特定のフレックス列に格納されているフィールドは、そのオブジェクトにネストされません。)

  デフォルト値はtrue。

  フィールドuseFlexFieldsは、コンバータ・ファンクションinfer_schemaおよびinfer_schema_and_generateによってのみ使用されます。

  インポータは、フィールドuseFlexFieldsを使用しません。ただし、フレックス列がコンバータによって作成されている場合、インポータは、列にマップされていないフィールドすべてを、フィールドの場所に対応するフレックス列に格納します。たとえば、出現の外れ値フィールドはこのように処理されます。フレックス列がない場合、インポータはマップされていないフィールドに関するエラーをレポートします。

• viewNames (オプション) — 作成する二面性ビューを指定する文字列の配列(ドキュメント・セットごとに1つ)。

  指定しない場合、_dualityが付加されたtableNamesがビュー名として使用されます。たとえば、表fooのドキュメントに対応するビューの名前は、デフォルトでfoo_dualityになります。

  フィールドviewNamesを指定する場合、配列の長さはフィールドtableNamesの長さと同じである必要があります。そうでない場合は、エラーが発生します(ログに記録されません)。