CREATE_TAGS_FROM_VIEW¶

説明

ストアドプロシージャ CREATE_TAGS_FROM_VIEW を使用すると、Virtual DataPort ビューから情報を取得して、タグ割り当てを読み込むことができます。そのビューは事前定義されたスキーマに従っている必要があり、事前定義された構造に従ってデータを返す必要があります。

任意のタイプのビューを指定できるので、たとえば、タグを CSV ファイルで定義しておくことや、 REST API 経由で JSON データソースを使用して外部システムにアクセスすることができます。

構文

CREATE_TAGS_FROM_VIEW (
      input_database_view_name : text
      , input_view_name : text
      , input_action : text
      , input_unassign_tags_mode : text
      , input_unused_external_tags_mode : text
      , input_incremental : boolean
)

• input_database_view_name: このプロシージャが実行するビューが含まれるデータベースの名前。

• input_view_name: このプロシージャが実行するビューの名前。

• input_action: このプロシージャがビューから読み込んだ情報で実行する必要がある動作を示します。以下の 2 つの値を指定できます。

  • READ: プロシージャはビューを実行して取得した情報を返します (デフォルト)。

  • CREATE: プロシージャはビューを実行して取得した情報を返し、さらにその情報を Virtual DataPort に保存します。

• input_unassign_tags_mode: Virtual DataPort が、実行したビューで見つかったデータベースのビューと列に割り当てられている既存のタグに対して実行する動作を示します。以下の 2 つの値を指定できます。

  • ALL: ビューまたは列から、既存のすべてのタグの割り当てが解除されます。これは、タグ割り当てをこのプロシージャでのみ実行する場合に使用するオプションです。

  • ONLY_EXTERNAL: ビューまたは列から、外部システムからインポートされた既存のタグ (このプロシージャを使用してインポートされたタグなど) のみの割り当てが解除されます。このオプションは、タグを手動でビューまたは列に定義するのに役立ちますが、このプロシージャを使用して情報をインポートすることも可能です。(デフォルト)。

• input_unused_external_tags_mode: Virtual DataPort が、このプロシージャからインポートしたタグのうち、ビューまたは列でもはや使用されていないタグに対して実行する動作を示します。以下に示す値を指定できます。

  • RETAIN: タグは Virtual DataPort から削除されません。(デフォルト)。

  • DROP_UNASSIGNED: ビューまたは列でもはや使用されていないタグは Virtual DataPort から削除されます。他のエレメント (グローバルセキュリティポリシー など) で使用されているタグは存続する可能性があります。その場合、このオプションではタグは削除されません。

  • DROP_UNASSIGNED_CASCADE: ビューまたは列でもはや使用されていないタグは Virtual DataPort から削除され、他のエレメント (グローバルセキュリティポリシー など) が削除されたタグを使用していた場合はそれらのエレメントも削除されます。

• input_incremental: 実行されるビューがデータを増分で (前回の読み込み以降の新しい変更のみ) 返すかどうかを示します。ビューまたはその列が変更された場合、そのビューのタグ一式がデータに存在している必要があります。

出力スキーマには以下のフィールドがあります。

• element_type: 現在のタプルで返されるエレメントのタイプ。指定できる値は、 database、 tag 、 view 、および column です。

• database_name: 現在のエレメントが database の場合はそのデータベースの名前、それ以外の場合は現在のエレメントを含むデータベースの名前。

• view_name: 現在のエレメントがビューまたは列の場合はビューの名前。

• column_name: 現在のエレメントが列の場合は列の名前。

• tag: 現在のエレメントがタグの場合はタグの名前。

• tag_description: 現在のエレメントがタグの場合はタグの説明。

• assignment_status: 現在のタプルがタグ割り当てを表す場合に、タグが正しく割り当てられているかどうかを示します。

必要な権限

このプロシージャを呼び出すことができるのは管理者のみです。

ビューの定義

このプロシージャは、入力ビューに少なくとも一定の列名を持つスキーマが存在することを想定しています。正しいスキーマに従ってインターフェイスを定義し、実装として必要なビューを割り当てることをお勧めします。

想定しているスキーマを以下に示します。

CREATE OR REPLACE INTERFACE VIEW i_tags_definition (
        element_type:text,
        database_name:text,
        view_name:text,
        column_name:text,
        tag:text,
        tag_description:text
    )

このプロシージャは、次のクエリを実行して、このビューからデータを抽出します。

SELECT element_type, database_name, view_name, column_name, tag, tag_description
FROM <input_database_name>.<input_view_name>

データ構造

このビューは、実行する必要がある変更を理解するために、Virtual DataPort が想定する構造に従ってデータを返す必要があります。

返すデータには、以下のセクションが必要です。

• データベース: 影響を受けるデータベースを、データベース 1 つにつき 1 行(つまり element_type に値 database 、列 database_name に名前がそれぞれ格納された行) で返します。

  返すデータベースのビューのみが影響を受けるので、 input_action の値が CREATE であるとき、あるビューがデータに含まれない場合はそのビューがタグを持たないものと見なされます。そのため、タグの割り当ては解除されます。また、この割り当て解除は、以下に示すように input_unassign_tags_mode パラメータに依存する可能性があります。あるビューがデータに含まれる場合、そのタグ操作情報は完全である (つまり、結果に含まれるタグは保持され、それ以外は削除される) 必要があります。以下の表の 1 行目を参照してください。

  • input_unassign_tags_mode の値が ALL の場合、ビューのタグはすべて削除されます。値が ONLY_EXTERNAL の場合、このプロシージャのように、外部システムからインポートしたタグが削除されます。

  • input_incremental の値が true であり、返されたデータでビューに空のタグの割り当てがある場合のみ、ビューのタグが削除されます。割り当てが解除されるタグは、 input_unassign_tags_mode パラメータの値に依存します。

• Tag descriptions: タグに説明を追加する必要がある場合、タグ 1 つにつき 1 行でこの情報を返します。element_type の値が tag の場合、 tag 列で名前、 tag_description 列で説明を返す必要があります。タグに説明が存在しない場合、空の値を使用してそのタグに対応するタプルを返す必要はありません。以下の表の 2 行目を参照してください。

• Assignments: ビューまたは列へのタグの割り当て。

  • ビュー: ビューに割り当てるタグを、割り当て 1 つにつき 1 行で返す必要があります。element_type の値は view 、 database_name はビューが含まれるデータベース、 view_name はビューの名前です。最後に、 tag 列はタグの名前です。以下の表の 3 行目を参照してください。

  • 列: 列に割り当てるタグを、割り当て 1 つにつき 1 行で返す必要があります。element_type の値は column 、 database_name はビューが含まれるデータベース、 view_name はビューの名前、 column_name は列の名前です。最後に、 tag 列はタグの名前です。以下の表の 4 行目を参照してください。

  • 増分: 増分読み込みを実行する場合のデータ構造に関する注意事項。

    • 新しい割り当てのみが含まれる必要があります。

    • ビューまたはその列の割り当てが変更された場合、ビューとその列の すべてのタグ操作情報 がデータに含まれる必要があります。

    • ビューにもはやタグが存在しない場合、ビューとその列からすべてのタグを削除するために、タグが存在しないビューを参照するタプルが含まれる必要があります。これは、 element_type が view 、 database_name と view_name でビューを特定し、さらに他の情報を含むタプルを意味します。以下の表の 5 行目を参照してください。

例

以下の表は、ビューでどのようにデータを返す必要があるかを表す例を示します。順序は重要ではありません。

• 行 1 ～ 2 はタグ操作の影響を受けるデータベースです。

• 行 3 ～ 5 は使用されているタグの一部の説明です。

• 行 6 ～ 8 はビューに対するタグの割り当てです。たとえば、行 6 は、ビュー hr.employees に対するタグ hr_data の割り当てを示します。

• 行 9 から最終行までは、列に対するタグの割り当てです。たとえば、行 10 は、ビュー hr.employees の列 first_name に対するタグ pii の割り当てです。

上記のデータを CSV ファイルに書き込み、 区切り形式ファイル のデータソースを使用して、Virtual DataPort ビューを作成できます。このビューは、このプロシージャが想定しているスキーマに従ったインターフェイスの実装として使用できます。例として、前述の i_tags_definition について説明します。

次の図に、インターフェイス i_tags_definition 、およびその実装である、前述のデータから作成する 区切り形式ファイル 基本ビューを示します。注: 実装ビューには、任意のタイプおよび任意の複雑さを使用できます。

インターフェイス i_tags_definition の定義¶

ここで、プロシージャ CREATE_TAGS_FROM_VIEW を実行し、インターフェイス i_tags_definition を使用してタグ定義を読み込みます。

SELECT element_type, database_name, view_name, column_name, tag, tag_description
   FROM CREATE_TAGS_FROM_VIEW()
      WHERE input_database_view_name = 'admin'
         AND input_view_name = 'i_tags_definition'
         AND input_action = 'READ';

input_action の値は READ なので、プロシージャはデータの取得のみ行います。

プロシージャ CREATE_TAGS_FROM_VIEW がインターフェイス i_tags_definition にアクセスして返すデータ¶

返されたデータが正しいことを確認したら、タグ割り当てはそのままで、入力パラメータ input_action に値 CREATE を指定して、プロシージャを呼び出すことができます。

SELECT element_type, database_name, view_name, column_name, tag, tag_description
   FROM CREATE_TAGS_FROM_VIEW()
      WHERE input_database_view_name = 'admin'
         AND input_view_name = 'i_tags_definition'
         AND input_action = 'CREATE';

これで、影響を受けるビューまたは列にタグが割り当てられます。

プロシージャ CREATE_TAGS_FROM_VIEW を CREATE オプションで実行した後のビュー customer_payments¶

プロシージャ CREATE_TAGS_FROM_VIEW を CREATE オプションで実行した後のビュー employees¶

以下の表に、タグの割り当てを解除する方法の例を示します。

• 行 1 はタグ解除の影響を受けるデータベースです。データに列が含まれていないので、ビューの関連付けられているタグは割り当てを解除されます。

ここで、タグの割り当て解除はそのままで、プロシージャを呼び出すことができます。

SELECT element_type, database_name, view_name, column_name, tag, tag_description
   FROM CREATE_TAGS_FROM_VIEW()
      WHERE input_database_view_name = 'admin'
         AND input_view_name = 'i_tags_definition'
         AND input_action = 'CREATE';

これで、影響を受けるビューと列にはタグが割り当てられていません。

タグの割り当てを解除するためにプロシージャ CREATE_TAGS_FROM_VIEW を CREATE オプションで実行した後のビュー employees¶

次に、 増分読み込み を実行します。達成したいことを以下に示します。

• ビュー customer_payments とその列からタグを削除します。ビューを参照するタプルを、タグ割り当てなしで、データに含める必要があります。

• ビュー store_managers に新しいタグを説明付きで追加します。タグの説明を含むタプルおよびビューへの割り当てを含むタプルをデータに含める必要があります。

• ビュー store_managers の列 username に新しいタグを説明なしで追加します。列への割り当てを含むタプルをデータに含める必要があります。

• 最後に、 store_managers の列にタグ pii と hidden の割り当てを追加します。これらの割り当てを含むタプルをデータに含める必要があります。

新しい CSV ファイルには、以下のデータが必要です。

区切り形式ファイル データソースで新しいファイルを参照した後、プロシージャを input_incremental = true で実行する必要があります。

SELECT element_type, database_name, view_name, column_name, tag, tag_description, assignment_status
   FROM CREATE_TAGS_FROM_VIEW()
      WHERE input_database_view_name = 'admin'
         AND input_view_name = 'i_tags_definition'
         AND input_action = 'CREATE'
         AND input_incremental = true;

実行後、ビュー customer_payments にはタグがなく、ビュー employees には実行前と同じタグがあり、ビュー store_managers には新しいタグが割り当てられています。

プロシージャ CREATE_TAGS_FROM_VIEW を input_incremental = true で実行した後のビュー customer_payments¶

最後に、もう一度、増分読み込みを実行します。前の例では、ビュー store_managers に次のタグを追加するのを忘れていました。

• staff_id 列と store_id 列にタグ id を追加

• ビューにタグ staff_data を追加

したがって、変更するビューが store_managers なので、追加する必要があるのはこのビューとその列に対するタグ操作情報のみです。

新しい CSV ファイルには、以下のデータが必要です。

このビューに対する すべての タグ操作情報(既存のタグと新しいタグ) がデータに含まれる必要があります。

区切り形式ファイル データソースで新しいファイルを参照した後、プロシージャを input_incremental = true で実行する必要があります。

SELECT element_type, database_name, view_name, column_name, tag, tag_description, assignment_status
   FROM CREATE_TAGS_FROM_VIEW()
      WHERE input_database_view_name = 'admin'
         AND input_view_name = 'i_tags_definition'
         AND input_action = 'CREATE'
         AND input_incremental = true;

実行後、ビュー store_managers には新しいタグ store_data が割り当てられ、 staff_id 列と store_id 列にはタグ id が割り当てられています。他のビューは変更されません。

プロシージャ CREATE_TAGS_FROM_VIEW を input_incremental = true で実行した後のビュー store_managers¶