DBMS_DCATパッケージ

DBMS_DCATパッケージには、Autonomous AI DatabaseユーザーがOCIデータ・カタログのデータ検出および一元化されたメタデータ管理システムを活用するのに役立つファンクションおよびプロシージャが用意されています。

データ・カタログは、データ・レイクのオブジェクト・ストレージ・アセットからメタデータを収集します。収集プロセスによって論理エンティティが作成されます。論理エンティティは、列および関連付けられたデータ型を持つ表と考えることができます。DBMS_DCATプロシージャおよびファンクションは、Autonomous AI Databaseをデータ・カタログに接続し、アセットをデータベースと同期して、保護されたスキーマおよび外部表を作成します。その後、これらの外部表を使用してオブジェクト・ストアに問い合せ、外部データをAutonomous AI Databaseに格納されたデータと簡単に結合できます。これにより、管理プロセスが大幅に簡素化され、複数のOCIサービス(Autonomous AIデータベースを含む)で共有される、一元管理されたメタデータ・ストアが1つあります。また、Autonomous AI Databaseディクショナリ・ビューもあり、SQLを使用してデータ・カタログの内容を検査し、これらのデータ・カタログ・エンティティがAutonomous AI Databaseスキーマおよび表にどのようにマップされるかを示します。

データ・カタログのユーザーおよびロール

DBMS_DCATパッケージは、同期されたユーザー/スキーマ、dcat_adminユーザーおよびローカル・ユーザーをサポートします。このパッケージを使用できるようにするには、ユーザーにdcat_syncロールが必要です。

データカタログユーザー

• 同期されたユーザー/スキーマ

  同期された外部表は、データ・アセット/バケットの組合せに対応するデータベース・スキーマ、またはユーザーが設定したカスタム・プロパティに従って編成されます。同期されたスキーマは、データ・カタログの同期時に自動的に作成/削除されます。これらは、CREATE SESSION権限のない認証ユーザーとして作成されません。同期されたスキーマは、protected句を使用しても作成されるため、ローカル・ユーザー(PDB管理者でもない)によって変更できず、同期によってのみ変更できます。

• ユーザーdcat_admin

  ユーザーdcat_adminは、同期を実行し、同期された表に対するREAD権限を他のユーザーまたはロールに付与できるローカル・データベース・ユーザーです。このユーザーは、CREATE SESSION権限のない認証ユーザーとして作成されます。

• ローカル・ユーザー

  外部表を問い合せるデータベース・ユーザーには、同期された外部表に対するREAD権限がユーザーdcat_adminまたはADMINによって明示的に付与されている必要があります。デフォルトでは、同期が完了すると、ユーザーdcat_adminおよびADMINのみが同期された外部表にアクセスできます。

データ・カタログ・ロール

• dcat_sync

  dcat_syncロールには、DBMS_DCATパッケージを使用するために必要なすべての権限があります。APIを使用してデータ・カタログをナビゲートし、同期を実行できるようにするには、このロールが必要です。

必要な資格証明およびIAMポリシー

このトピックでは、Autonomous AI Databaseユーザーにデータ・カタログの管理およびオブジェクト・ストレージからの読取り権限を付与するために必要なOracle Cloud Infrastructure Identity and Access Management (IAM)ユーザー資格証明およびポリシーについて説明します。

OCIデータ・カタログの資格証明およびポリシーの要件

• データ・カタログ・インスタンスを管理する権限を持つ資格証明オブジェクトが必要です。OCIネイティブ認証またはリソース・プリンシパルの資格証明を含む資格証明オブジェクトがサポートされています。認証トークン・ユーザー・プリンシパルに基づく資格証明オブジェクトはサポートされていません。

  資格証明の管理の詳細は、「アクセス管理用のDBMS_CLOUD」を参照してください。

  OCIネイティブ認証の例については、例: OCIネイティブ認証資格証明オブジェクトの作成およびAutonomous AI DatabaseでOCIネイティブ認証を使用したオブジェクト・ストレージへのアクセスがサポートされるようになりましたを参照してください。

  リソース・プリンシパルの使用例は、例: Autonomous AI Databaseリソース・プリンシパルの使用およびリソース・プリンシパルを使用したAutonomous AI DatabaseからのOracle Cloud Infrastructureリソースへのアクセスを参照してください。

• Autonomous AI Databaseがデータ・カタログ・ネームスペースにカスタム・プロパティを追加するには、データ・カタログの管理権限が必要です。これらの権限により、スキーマ名、表名、列名などをオーバーライドできます。

  データ・カタログの権限の詳細は、各API操作に必要な権限を参照してください。

• Autonomous AI Databaseがデータ・ファイルを問い合せるには、バケットに対する読取りオブジェクト・ストレージ権限が必要です。

  Oracle Object Storageポリシーの例の詳細は、ポリシーの例を参照してください。

AWS Glueデータカタログの資格およびポリシー要件

Autonomous AI Databaseユーザーに、Amazon Web Services (AWS) Glue Data Catalogにアクセスし、S3オブジェクト・ストレージから読み取る権限を付与するには、次のユーザー資格証明およびポリシーが必要です:

• AWS Glueデータ・カタログにアクセスする権限を持つ資格証明オブジェクトが必要です。資格証明の管理の詳細は、「アクセス管理用のDBMS_CLOUD」を参照してください。

  AWS Glueデータカタログにアクセスするには、glue:GetDatabases、glue:GetTables、glue:GetTableの各権限が必要です。

  さらに、基礎となるS3オブジェクトを指す解決可能なHTTPS URLを生成するには、同期中に権限s3:GetBucketLocationが必要です。

• Autonomous AI Databaseがデータ・ファイルを問い合せるには、S3に格納されているファイルにアクセスする権限を持つ資格証明オブジェクトが必要です。

• AWS資格証明がサポートされています。AWS Amazon Resource Name (ARN)資格証明はサポートされていません。

例: OCIネイティブ認証資格証明オブジェクトの作成

この例では、データ・カタログまたはオブジェクト・ストア資格証明オブジェクトの作成時に使用できるOCIネイティブ認証資格証明を作成します。詳細は、それぞれDBMS_DCAT SET_DATA_CATALOG_CREDENTIALプロシージャおよびDBMS_DCAT SET_OBJECT_STORE_CREDENTIALプロシージャを参照してください。

OCIネイティブ認証では、DBMS_CLOUD.CREATE_CREDENTIALプロシージャにパラメータcredential_name、user_ocid、tenancy_ocid、private_keyおよびfingerprintが含まれています。このプロシージャの詳細は、「DBMS_CLOUD CREATE_CREDENTIALプロシージャ」を参照してください。

credential_nameは、資格証明オブジェクトの名前です。The user_ocid and tenancy_ocid parameters correspond to the user’s and tenancy’s OCIDs respectively.

private_keyパラメータは、生成された秘密キーをPEM形式で指定します。パスフレーズ付きで生成された秘密キーはサポートされていません。したがって、パスフレーズなしで鍵を生成する必要があります。パスフレーズなしで秘密キーを作成する方法の詳細は、「API署名キーの生成方法」を参照してください。また、このパラメータに指定する秘密キーには、ヘッダーまたはフッターなしのキー自体のみが含まれている必要があります(例: '—BEGIN RSA PRIVATE KEY—'、'—END RSA PRIVATE KEY— —')。

fingerprintパラメータは、公開キーをコンソールにアップロードした後、またはOpenSSLコマンドを使用して取得するフィンガープリントを指定します。フィンガープリントの取得の詳細は、公開キーのアップロード方法およびキーのフィンガープリントの取得方法を参照してください。

必要な情報がすべて収集され、秘密キーが生成されると、次のCREATE_CREDENTIALプロシージャを実行する準備が整います。

BEGIN
  DBMS_CLOUD.CREATE_CREDENTIAL (
    credential_name => 'OCI_NATIVE_CRED',
    user_ocid              => 'ocid
1.user.oc1..aaaaaaaatfn77fe3fxux3o5lego7glqjejrzjsqsrs64f4jsjrhbsk5qzndq',
    tenancy_ocid           => 'ocid1.tenancy.oc1..aaaaaaaapwkfqz3upqklvmelbm3j77nn3y7uqmlsod75rea5zmtmbl574ve6a',
    private_key            => 'MIIEogIBAAKCAQEA...t9SH7Zx7a5iV7QZJS5WeFLMUEv+YbYAjnXK+dOnPQtkhOblQwCEY3Hsblj7Xz7o=',
    fingerprint            => '4f:0c:d6:b7:f2:43:3c:08:df:62:e3:b2:27:2e:3c:7a');
END;
/

資格証明オブジェクトを作成すると、dba_credentials表に表示されます。

SELECT owner, credential_name
FROM dba_credentials
WHERE credential_name LIKE '%NATIVE%';

OWNER CREDENTIAL_NAME
----- ---------------
ADMIN OCI_NATIVE_CRED

例: Autonomous AI Database Resource Principalの使用

この例では、適切なリソース・メンバーを含む動的グループが作成され、動的グループにはデータ・カタログを管理する権限が付与され、動的グループにはオブジェクト・ストレージからの読取り権限が付与されます。

1. adb-grp-1という名前の動的グループを作成します。OCID ocid1.autonomousdatabase.oc1.iad.abuwcljr...fjkfeをリソース・メンバーとするAutonomous AI Databaseインスタンスを含む一致ルールをadb-grp-1に追加します。

   動的グループ一致ルール:

   resource.id = 'ocid1.autonomousdatabase.oc1.iad.abuwcljr...fjkfe'

2. mycompartmentコンパートメントのデータ・カタログ・インスタンスへのフル・アクセス権をadb-grp-1動的グループに付与するポリシーを定義します。

   allow dynamic-group adb-grp-1 to manage data-catalog-family in compartment mycompartment

3. adb-grp-1動的グループがmycompartmentという名前のコンパートメント内の任意のバケットを読み取ることを許可するポリシーを定義します。

   allow dynamic-group adb-grp-1 to read objects in compartment mycompartment

例: ユーザー・プリンシパルの使用

この例では、user1はグループadb-adminsのメンバーです。このグループのすべてのメンバーには、mycompartment内のすべてのデータ・カタログを管理し、mycompartmentのオブジェクト・ストアから読み取る権限が付与されます。

1. adb-adminsのメンバーであるユーザーが、mycompartment内のすべてのデータ・カタログを管理できるようにします。

   allow group adb-admins to manage data-catalog-family in compartment mycompartment

2. adb-adminsのメンバーであるユーザーが、mycompartment内の任意のバケット内の任意のオブジェクトを読み取ることができます。

   allow group adb-admins to read objects in compartment mycompartment

接続管理サブプログラムの要約

この表は、データ・カタログ接続の作成、問合せおよび削除に使用されるDBMS_DCATパッケージ・プロシージャを示しています。

SET_DATA_CATALOG_CREDENTIALプロシージャ

このプロシージャは、データ・カタログへの特定の接続で使用されるデータ・カタログ・アクセス資格証明を設定します。

構文

PROCEDURE DBMS_DCAT.SET_DATA_CATALOG_CREDENTIAL(
    credential_name VARCHAR2(128) DEFAULT NULL,
    dcat_con_id     VARCHAR2 DEFAULT NULL
  );

パラメータ

使用法

この資格証明には、データ・カタログの管理権限が必要です。データ・カタログ・ポリシーを参照してください。デフォルトはリソース・プリンシパルです。ポリシーおよびロールの構成によるクラウド・リソースへのアクセスを参照してください。

SET_OBJECT_STORE_CREDENTIALプロシージャ

このプロシージャは、オブジェクト・ストアにアクセスするために指定された一意の接続識別子によって使用される資格証明を設定します。オブジェクト・ストア・アクセス資格証明を変更すると、新しい資格証明を使用するように既存のすべての同期表が変更されます。

構文

PROCEDURE DBMS_DCAT.SET_OBJECT_STORE_CREDENTIAL(
    credential_name  VARCHAR2(128),
    dcat_con_id      IN VARCHAR2 DEFAULT NULL
  );

パラメータ

SET_DATA_CATALOG_CONNプロシージャ

このプロシージャは、指定されたデータ・カタログへの接続を作成します。メタデータとデータ・カタログを同期するには、接続が必要です。自律型AIデータベース・インスタンスは、複数のデータ・カタログ・インスタンスに接続でき、OCIデータ・カタログ、AWS Glueデータ・カタログおよびApache Iceberg RESTカタログへの接続をサポートしています。

構文

PROCEDURE DBMS_DCAT.SET_DATA_CATALOG_CONN (
   region         VARCHAR2 DEFAULT NULL,
   endpoint       VARCHAR2 DEFAULT NULL,
   catalog_id     VARCHAR2 DEFAULT NULL,
   dcat_con_id    VARCHAR2 DEFAULT NULL,
   catalog_type   VARCHAR2 DEFAULT NULL,
   token_endpoint VARCHAR2 DEFAULT Null
 );

パラメータ

使用法

このプロシージャをコールする必要があるのは、接続を設定するために1回のみです。接続プロセスの一環として、Autonomous AI Databaseはカスタム・プロパティをデータ・カタログに追加します。これらのカスタム・プロパティには、データ・カタログ・ユーザーがアクセスでき、デフォルト名(スキーマ、表および列の場合)および列データ型をオーバーライドできます。

接続を作成する前に、資格証明を作成して設定する必要があります。接続プロセスの詳細は、OCIデータ・カタログのデータ・カタログを使用した一般的なワークフローおよびAWS Glueデータ・カタログのAWS Glueデータ・カタログを使用した問合せのユーザー・ワークフローを参照してください。

例: 既知のOCIDとの接続

この例では、Autonomous AI Databaseは、uk-london-1リージョンのデータ・カタログに接続しています。catalog_idパラメータは、データ・カタログ・インスタンスにOracle Cloud Identifier (ocid)を使用します。データ・カタログのタイプは、AWS Glue Data CatalogまたはOCI Data Catalogによって自動的に決定されます。

BEGIN
  DBMS_DCAT.SET_DATA_CATALOG_CONN(
    region=>'uk-london-1',
    catalog_id=>'ocid1.datacatalog.oc1.uk-london-1...');
END;
/

例: AWS Glueデータカタログへの接続

接続とは、Autonomous AI DatabaseインスタンスとAWS Glue Data Catalogの間の関連付けです。接続に成功すると、Autonomous AI DatabaseインスタンスはAWS Glueと同期できます。各AWSアカウントには、リージョンごとに1つのAWS Glueデータカタログがあり、各カタログには、各リージョンに対応するサービスエンドポイントを使用してアクセスできます。Autonomous AI Databaseインスタンスは、API DBMS_DCAT.SET_DATA_CATALOG_CONNを呼び出して、カタログが存在するリージョンのエンドポイントを指定することで、AWS Glue Data Catalogに関連付けることができます。

AWS Glueエンドポイントおよび割当て制限を参照してください。

この例では、Autonomous AI Databaseは、uk-london-1リージョンのAWS Glue Data Catalogに接続しています。これはAWS Glueデータ・カタログ接続であるため、catalog_idパラメータは必要ありません。

BEGIN
  DBMS_DCAT.SET_DATA_CATALOG_CONN(
    region=>'uk-london-1',
    catalog_type=>'AWS_GLUE'
END;
/

例: データブリックUnity Iceberg RESTカタログへの接続

この例では、Autonomous AI Databaseは、(長期)個人アクセス・トークンを使用してDatabricks Unity Iceberg RESTカタログに接続しています。

DBMS_CLOUD.create_credential('MY_DATABRICKS_CRED','username', '<personal access token>');
DBMS_DCAT.set_data_catalog_credential(dcat_con_id=>'ICEBERG_CATALOG',credential_name=>'MY_DATABRICKS_CRED');
DBMS_DCAT.set_object_store_credential(dcat_con_id=>'ICEBERG_CATALOG',credential_name=>'SOMECRED');
DBMS_DCAT.set_data_catalog_conn (
  dcat_con_id  => 'ICEBERG_CATALOG',
  catalog_type => 'ICEBERG_UNITY',
  endpoint     => 'https://adb-...azuredatabricks.net/api/2.1/unity-catalog/iceberg/v1/');

この例では、Autonomous AI Databaseは、OAuthを使用してサービス・プリンシパルを持つDatabricks Unity Iceberg RESTカタログに接続しています。

DBMS_CLOUD.create_credential('MY_DATABRICKS_SP_CRED','<client id for the service principal>', '<client secret for the service principal>');
DBMS_DCAT.set_data_catalog_credential(dcat_con_id=>'ICEBERG_CATALOG',credential_name=>'MY_DATABRICKS_SP_CRED');
DBMS_DCAT.set_object_store_credential(dcat_con_id=>'ICEBERG_CATALOG',credential_name=>'MY_OS_CRED');
DBMS_DCAT.set_data_catalog_conn (
  dcat_con_id    => 'ICEBERG_CATALOG',
  catalog_type   => 'ICEBERG_UNITY',
  endpoint       => 'https://adb-...azuredatabricks.net/api/2.1/unity-catalog/iceberg/v1',
  token_endpoint => 'https://adb-...azuredatabricks.net/oidc/v1/token');

例: Apache Polaris Iceberg RESTカタログへの接続

この例では、Autonomous AI Databaseは、OAuthを使用してApache Polaris Iceberg RESTカタログに接続しています。

DBMS_CLOUD.create_credential('MY_POLARIS_CRED','<client id>', '<client secret>');
DBMS_DCAT.set_data_catalog_credential(dcat_con_id=>'ICEBERG_CATALOG',credential_name=>'MY_POLARIS_CRED');
DBMS_DCAT.set_object_store_credential(dcat_con_id=>'ICEBERG_CATALOG',credential_name=>'SOMECRED');
DBMS_DCAT.set_data_catalog_conn (
  dcat_con_id    => 'ICEBERG_CATALOG',
  catalog_type   => 'ICEBERG_POLARIS',
  endpoint       => 'https://dev-iceberg.subnet...vcn...oraclevcn.com/api/catalog/v1/quickstart_catalog',
  token_endpoint => 'https://dev-iceberg.subnet...vcn...oraclevcn.com/api/catalog/v1/oauth/tokens');

UNSET_DATA_CATALOG_CONNプロシージャ

このプロシージャは、既存のデータ・カタログ接続を削除します。

構文

ノート

ノート:このプロシージャを起動すると、以前の同期の一部として作成されたすべての保護されたスキーマおよび外部表が削除されます。データ・カタログのメタデータには影響しません。

PROCEDURE DBMS_DCAT.UNSET_DATA_CATALOG_CONN (
    dcat_con_id IN VARCHAR2 DEFAULT NULL
);

パラメータ

同期サブプログラムの要約

同期の実行、同期ジョブの作成と削除、および同期スキーマの削除は、この表に示す手順で実行できます。

ノート

ノート: 2022年4月4日に、sync_optionおよびgrant_readパラメータがDBMS_DCAT.RUN_SYNCプロシージャに追加されました。その日付より前に作成されたスケジュール済同期ジョブのパフォーマンスが正しいことを確認するには、スケジュール済同期ジョブを削除して再作成する必要があります。DBMS_DCAT.DROP_SYNC_JOBプロシージャおよびDBMS_DCAT.CREATE_SYNC_JOBプロシージャを参照してください。

RUN_SYNCプロシージャ

このプロシージャは同期操作を実行し、同期のエントリ・ポイントです。入力として、選択したデータ・カタログ・アセット、フォルダおよびエンティティのリストを取得し、外部表を作成、削除および変更してマテリアライズします。

sync_optionパラメータでは、RUN_SYNCプロシージャが実行する操作(SYNC、DELETEまたはREPLACE)を指定します。この操作は、synced_objectsパラメータのスコープ内のエンティティに対して実行されます。

RUN_SYNCプロシージャをコールするたびに、一意のoperation_idが返され、これを使用してUSER_LOAD_OPERATIONSビューを問い合せて同期のステータスおよび対応するlog_tableに関する情報を取得できます。DBMS_DCAT$SYNC_LOGビューを問い合せると、現行のユーザーが実行した最後の同期操作のlog_tableに簡単にアクセスできます。詳細は、DBMS_DCAT$SYNC_LOGビューおよびロードの監視およびトラブルシューティングを参照してください。

ノート

ノート: 2022年4月4日に、sync_optionおよびgrant_readパラメータがRUN_SYNCプロシージャに追加されました。その日付より前に作成されたスケジュール済同期ジョブのパフォーマンスが正しいことを確認するには、スケジュール済同期ジョブを削除して再作成する必要があります。DBMS_DCAT.DROP_SYNC_JOBプロシージャおよびDBMS_DCAT.CREATE_SYNC_JOBプロシージャを参照してください。

パーティション化された論理エンティティまたはグルー表の同期

RUN_SYNCプロシージャは、次の3つすべてに該当する場合に、論理エンティティ表またはGlue表ごとにパーティション化された外部表を作成します。

1. OCIデータ・カタログ論理エンティティまたはGlue表には、1つ以上のパーティション属性があります。

2. OCIデータ・カタログの場合、論理エンティティは接頭辞ベースのファイル名パターンから導出されます。正規表現ベースのパターンから導出されたパーティション化された論理エンティティはサポートされていません。

3. OCIデータ・カタログの場合、論理エンティティは、ハイブ・スタイルまたはハイブ以外のフォルダ形式に従ったパーティション・データに基づきます。オブジェクト名を使用した非ハイブ・スタイル形式に従ったパーティション・データに基づく論理エンティティはサポートされていません。

   • 例1。Hiveスタイルのパーティション化形式に接頭辞ベースのファイル名パターンが付いた、収集されたオブジェクトに基づく論理エンティティ。

     次のオブジェクトについて考えてみます。

     Bucket: MYBUCKET
     cluster1/db1.db/sales/country=USA/year=2020/month=01/sales1.csv
     cluster1/db1.db/sales/country=USA/year=2020/month=01/sales2.csv
     cluster1/db1.db/sales/country=USA/year=2020/month=02/sales1.csv

     開始フォルダ接頭辞がcluster1/db1.dbのファイル名パターンを使用してバケットを収集すると、country、yearおよびmonthの3つのパーティション属性を持つSALESという名前の論理エンティティが生成されます。パーティション化属性の型はPartitionで、非パーティション属性の型はPrimitiveです。

   • 例2。接頭辞ベースのファイル名パターンを持つHive以外のスタイル・パーティション化形式に従った、収集されたオブジェクトに基づく論理エンティティ。

     次のオブジェクトについて考えてみます。

     Bucket: MYBUCKET
     cluster2/db2.db/sales/USA/2020/01/sales1.csv
     cluster2/db2.db/sales/USA/2020/01/sales2.csv
     cluster2/db2.db/sales/USA/2020/02/sales1.csv

     開始フォルダ接頭辞がcluster2/db2.dbのファイル名パターンを使用してバケットを収集すると、name0、name1およびname2の3つのパーティション属性を持つSALESという名前の論理エンティティが生成されます。生成された論理エンティティと例1の唯一の違いは、パーティション化された属性の名前が自動生成され、例1ではURLから抽出される点です(それぞれcountry、yearおよびmonth)。

パーティション化された論理エンティティを同期する完全なエンドツーエンドの例は、例: パーティション化されたデータ・シナリオを参照してください。

パーティション化された論理エンティティ/グルー表の増分同期

RUN_SYNCプロシージャをコールするたびに、データベースと同期するOCIデータ・カタログ論理エンティティまたはAWS Glue表のセットが指定されます。論理エンティティ表またはGlue表が2つのRUN_SYNCコールに存在する場合、2回目のコールは既存の外部表を保持し、場合によっては変更します。次の表に、論理エンティティまたはGlue表がパーティション化されている場合にサポートされる論理エンティティまたはGlue表の変更を示します。

構文

PROCEDURE DBMS_DCAT.RUN_SYNC (
    synced_objects   IN  CLOB,
    sync_option      IN VARCHAR2 DEFAULT 'SYNC',
    error_semantics  IN VARCHAR2 DEFAULT 'SKIP_ERRORS',
    log_level        IN VARCHAR2 DEFAULT 'INFO',
    grant_read       IN VARCHAR2 DEFAULT NULL,
    dcat_con_id      IN VARCHAR2 DEFAULT NULL
 );
PROCEDURE DBMS_DCAT.RUN_SYNC (
    synced_objects   IN  CLOB,
    sync_option      IN VARCHAR2 DEFAULT 'SYNC',
    error_semantics  IN VARCHAR2 DEFAULT 'SKIP_ERRORS',
    log_level        IN VARCHAR2 DEFAULT 'INFO',
    grant_read       IN VARCHAR2 DEFAULT NULL,
    operation_id     OUT NOCOPY NUMBER,
    dcat_con_id      IN VARCHAR2 DEFAULT NULL
 );

パラメータ

例: すべてのOCIデータ・カタログ・エンティティの同期

次の例では、すべてのデータ・カタログ・エンティティが同期されます。

EXEC DBMS_DCAT.RUN_SYNC(synced_objects=>'{"asset_list":["*"]}');

例: すべてのOCIデータ・カタログ・データ・アセットを同期するためのsynced_objectsパラメータ

次に、データ・カタログ内のすべての(オブジェクト・ストレージ)データ・アセットを同期するためのsynced_objectsパラメータの例を示します。

{"asset_list" : ["*"]}

例: 特定のOCIデータ・カタログ・データ・アセットを同期するためのsynced_objectsパラメータ

次に、2つのデータ・アセットを同期するためのsynced_objectsパラメータの例を示します。

{"asset_list": [
        {
            "asset_id":"...-9e2e7f78fd5f"
        },
        {
            "asset_id":"...-9e2e7f74523"
        }
    ]}

例: データ・アセット内の特定のOCIデータ・カタログ・エンティティを同期するためのsynced_objectsパラメータ

次に、データ・アセット内の2つのエンティティを同期するためのsynced_objectsパラメータの例を示します。

{"asset_list": [
        {
            "asset_id":"...-9e2e7f78fd5f",
            "folder_list":[
                "f1",
                "f2"
           ]
        }
    ]}

例: データ・アセット内の特定のOCIデータ・カタログ・フォルダおよびエンティティを同期するためのsynced_objectsパラメータ

次に、データ・アセット内の2つのフォルダと2つのエンティティを同期するためのsynced_objectsパラメータの例を示します。

{"asset_list":[
        {
            "asset_id":"...-9e2e7f78fd5f",
            "entity_list": [
                "entity1",
                "entity2"
            ],
             "folder_list": [
                "f1",
                "f2"
            ]
        }
    ]}

例: すべてのAWS Glueデータカタログデータベースを同期するためのsynced_objectsパラメータ

次に、AWS Glueデータ・カタログ内のすべてのデータベースを同期するためのsynced_objectsパラメータの例を示します。

{"database_list":["*"]}

例: 2つのAWS Glueデータ・カタログ・データベースを同期するためのsynced_objectsパラメータ

次に、2つのAWS Glueデータ・カタログ・データベースを同期するためのsynced_objectsパラメータの例を示します。

{"database_list":[
    {"database":"tpcdscsv"},
    {"database":"tpcdsparquet"} ]}

例: 3つのAWS Glueデータ・カタログ・データベースを同期するためのsynced_objectsパラメータ

次に、AWS Glueデータ・カタログ・データベースから3つの表を同期するためのsynced_objectsパラメータの例を示します。

{"database_list":[
 {"database":"tpcdsparquet",
     "table_list": [ "tpcdsparquet_customer",
                     "tpcdsparquet_item",
                     "tpcdsparquet_web_sales" ] } ]}

例: DBMS_DCAT.run_syncを呼び出して、Icebergカタログ内のすべてのネームスペースを同期する

Icebergカタログの場合、このサンプル・コールはすべてのネームスペースを同期します。

DBMS_DCAT.run_sync(
  dcat_con_id     => 'MY_ICEBERG_CON',
  synced_objects  => '{"namespace_list" : ["*"]}',
  sync_option     => 'SYNC',
  error_semantics => 'STOP_ON_ERROR,
  log_level       => 'DEBUG',
  grant_read      => 'DB_USER');

例: DBMS_DCAT.run_syncを呼び出して、1つのIcebergネームスペースのすべての表と別のIcebergネームスペースのいくつかの表を同期します。

Icebergカタログの場合、このサンプル・コールはネームスペースwarehouseのすべての表とネームスペース["bigdata"、"tpcdsparquet"]の3つの表を同期します。

DBMS_DCAT.run_sync(
  dcat_con_id     => 'MY_ICEBERG_CON',
  synced_objects  => '{"namespace_list": [
                          { "namespace": ["warehouse"] },
                          { "namespace": ["bigdata", "tpcdsparquet"],
                                "table_list": [ "tpcdsparquet_customer",
                                                "tpcdsparquet_item",
                                                "tpcdsparquet_web_sales" ] } ]}',
  sync_option     => 'SYNC',
  error_semantics => 'STOP_ON_ERROR,
  log_level       => 'DEBUG',
  grant_read      => 'DB_USER');

CREATE_SYNC_JOBプロシージャ

このプロシージャは、RUN_SYNCを定期的に起動するスケジューラ・ジョブを作成します。

これは、同期するオブジェクトのセット、エラー・セマンティクス、ログ・レベルおよび繰返し間隔を入力として取ります。同期の動作の詳細は、DBMS_DCAT RUN_SYNCプロシージャを参照してください。

1つの同期ジョブのみが存在できます。forceパラメータがTRUEに設定されていないかぎり、別のジョブがすでに指定されている場合、CREATE_SYNC_JOBプロシージャは失敗します。forceをTRUEに設定すると、前のジョブが削除されます。

スケジューラ・ジョブが別の同期の進行中に実行しようとすると、スケジューラ・ジョブは失敗します。

ノート

ノート: 2022年4月4日に、sync_optionおよびgrant_readパラメータがRUN_SYNCプロシージャに追加されました。その日付より前に作成されたスケジュール済同期ジョブのパフォーマンスが正しいことを確認するには、スケジュール済同期ジョブを削除して再作成する必要があります。DBMS_DCAT.DROP_SYNC_JOBプロシージャおよびDBMS_DCAT.CREATE_SYNC_JOBプロシージャを参照してください。

構文

PROCEDURE DBMS_DCAT.CREATE_SYNC_JOB (
    synced_objects   IN CLOB,
    error_semantics  IN VARCHAR2 DEFAULT 'SKIP_ERRORS',
    log_level        IN VARCHAR2 DEFAULT 'INFO',
    repeat_interval  IN VARCHAR2,
    force            IN VARCHAR2 DEFAULT 'FALSE',
    grant_read       IN VARCHAR2 DEFAULT NULL,
    sync_option      IN VARCHAR2 DEFAULT 'SYNC',
    dcat_con_id      IN VARCHAR2 DEFAULT NULL
);

パラメータ

DROP_SYNC_JOBプロシージャ

このプロシージャは、指定された一意の接続識別子の既存の同期ジョブを削除します。

構文

PROCEDURE DBMS_DCAT.DROP_SYNC_JOB (
    dcat_con_id IN VARCHAR2 DEFAULT NULL
  );

パラメータ

DROP_SYNCED_SCHEMASプロシージャ

このプロシージャは、指定された一意の接続識別子について、以前に同期されたすべてのスキーマを削除します。

構文

PROCEDURE DBMS_DCAT.DROP_SYNCED_SCHEMAS (
    dcat_con_id IN VARCHAR2 DEFAULT NULL
  );

パラメータ

クイック・スタート

この項では、データベース内のOCIおよびAWS Glueクラウド・データ・ソースからメタデータを同期およびアクセスするために、Oracle Data Catalogのセキュアなクラウド資格証明および接続を構成するプロセスについて説明します。

OCI

次の手順では、OCI認証資格証明を設定し、これらの資格証明を使用するようにOracleデータ・カタログ接続を構成し、メタデータ同期操作を開始して、問合せおよび消費のために外部表を介してクラウド・データ・カタログ・メタデータをデータベース環境内からアクセスできるようにします。

BEGIN
  DBMS_CLOUD.CREATE_CREDENTIAL(
    credential_name => 'OCI_NATIVE_CRED',
    user_ocid       => 'ocid1.user....',
    tenancy_ocid    => 'ocid1.tenancy....',
    private_key     => '...PEM_WITHOUT_HEADERS...',
    fingerprint     => '4f:0c:d6:...:7a'
  );
END;
/

BEGIN
  DBMS_DCAT.SET_DATA_CATALOG_CONN(region => 'us-ashburn-1');
  DBMS_DCAT.SET_DATA_CATALOG_CREDENTIAL(dcat_con_id => NULL, credential_name => 'OCI_NATIVE_CRED');
  DBMS_DCAT.SET_OBJECT_STORE_CREDENTIAL(dcat_con_id => NULL, credential_name => 'OCI_NATIVE_CRED');
END;
/

DECLARE
  op NUMBER;
BEGIN
  DBMS_DCAT.RUN_SYNC(
    synced_objects  => q'{"asset_list":["*"]}',
    sync_option     => 'SYNC',
    error_semantics => 'STOP_ON_ERROR',
    log_level       => 'INFO',
    grant_read      => 'DATA_CONSUMERS',
    operation_id    => op
  );
END;
/

AWS Glue

次の手順では、資格証明を使用してAWSサービスで安全に接続および認証するOracle Databaseを準備し、AWS Glueカタログへのデータ・カタログ接続を設定し、選択したメタデータをAWS GlueからOracleにインポートして環境内で使用します。

BEGIN
  DBMS_CLOUD.CREATE_CREDENTIAL(
    credential_name => 'AWS_CRED',
    username        => '<aws_access_key_id>',
    password        => '<aws_secret_access_key>');
END;
/

BEGIN
  DBMS_DCAT.SET_DATA_CATALOG_CONN(region => 'eu-west-2', catalog_type => 'AWS_GLUE');
  DBMS_DCAT.SET_DATA_CATALOG_CREDENTIAL(dcat_con_id => NULL, credential_name => 'AWS_CRED');
  DBMS_DCAT.SET_OBJECT_STORE_CREDENTIAL(dcat_con_id => NULL, credential_name => 'AWS_CRED');
END;
/

BEGIN
  DBMS_DCAT.RUN_SYNC(
    synced_objects => q'{
      "database_list":[
        {"database":"tpcdsparquet",
         "table_list":["customer","item","web_sales"]}
      ]}',
    grant_read => 'DATA_CONSUMERS'
  );
END;
/

データ・カタログ・ビューの要約

Autonomous AI Databaseとのデータ・カタログ統合により、多数の表およびビューが提供されます。

次の表およびビューは、次のことを理解するのに役立ちます。

• 使用可能なデータ・カタログ・アセット。データベース、オブジェクト・ストアなど、あらゆるタイプのデータ・カタログ・アセットに関する情報を取得します。

• Autonomous AI Databaseと同期されたデータ・カタログのオブジェクト・ストレージ・アセットおよびエンティティに関する情報。これには、データ・カタログ・アイテム(アセット、フォルダおよびエンティティ)がAutonomous AI Databaseオブジェクト(スキーマおよび外部表)にどのようにマップされるかの詳細が含まれます。

• メタデータ同期実行。同期中に発生した問題など、同期ジョブの詳細を確認します。

この表は、DBMS_DCATパッケージによって提供される表およびビューを示しています。

ALL_CLOUD_CATALOG_DATABASESビュー

ビューALL_CLOUD_CATALOG_DATABASESを使用して、OCIデータ・カタログ・データ・アセットおよびAWS Glueデータ・カタログ・データベースに関する情報を表示します。

Data stored in S3 (N. California)

Data stored in S3 (N. California)

{ "catalog-id": "ocid1.datacatalog.oc1.ap-mumbai-1.amaaa...", "description": null, "display-name": "OBJECT_STORE_AT_ASHBURN", "external-key": "https://swiftobjectstorage.us-ashburn-1....", "key": "bc95181c-3ac3-4959-9e5f-4e460d3fb82a", "lifecycle-state": "ACTIVE", "time-created": "2022-09-26T22:56:01.395000+00:00", "type-key": "3ea65bc5-f60d-477a-a591-f063665339f9", "uri": "/dcat/20190325/dataAssets/bc95181c-3ac3-4959-9e5f-4e460d3fb82a" }

{ "Name": "dbmsdcatpoc", "Parameters": { "somekey": "somevalue" }, "CreateTime": "2022-06-15T09:45:35+01:00", "CreateTableDefaultPermissions": [ { "Principal": { "DataLakePrincipalIdentifier": "IAM_ALLOWED_PRINCIPALS" }, "Permissions": [ "ALL" ] } ], "CatalogId": "579294766787" }

ALL_CLOUD_CATALOG_TABLESビュー

ビューALL_CLOUD_CATALOG_TABLESは、OCIデータ・カタログのデータ・エンティティおよびAWS Glueデータ・カタログの表に関する情報を表示するために使用されます。

{  "business-name": null, "data-asset-key": "bc95181c-3ac3-4959-9e5f-...", "description": null, "display-name": "bikes_trips", "external-key": "LE: https://swiftobjectstorage.us-ashburn-1.oraclecloud.com/v1/..._trips", "folder-key": "9c4b542d-d6eb-4b83-bf59-...", "folder-name": "hive", "is-logical": true, "is-partition": false, "key": "fde30a69-a07c-478a-ab62-...", "lifecycle-state": "ACTIVE", "object-storage-url": "https://objectstorage.us-ashburn-1.oraclecloud.com/n/...", "path": "OBJECT_STORE_AT_ASHBURN/hive/hive", "pattern-key": "db21b3f1-1508-4045-aa80-...", "properties": { "default": { "CONTENT-LENGTH": "4310321", "LAST-MODIFIED": "Fri, 9 Oct 2020 20:16:52 UTC", "archivedPECount": "0", "dataEntityExpression": "{logicalEntity:[^/]+}.db/{logicalEntity:[^/]+}/.*", "harvestedFile": "bikes.db/trips/p_start_month=2019-09/000000_0", "patternName": "bikes_trips" }, "harvestProps": { "characterset": "UTF8", "compression": "none", "type": "PARQUET" } }, "realized-expression": "bikes.db/trips/.*", "time-created": "2022-09-26T22:56:35.063000+00:00", "time-updated": "2022-09-26T22:56:35.063000+00:00", "type-key": "6753c3af-7f88-44b9-be52-1d57bef462fb", "updated-by-id": "ocid1.user.oc1..r5l3tov7a", "uri": "/dcat/20190325/dataAssets/bc95181c-3ac3-4959-9e5f-..." }

{ "Name": "bikes_trips", "DatabaseName": "dbmsdcatpoc", "Owner": "owner", "CreateTime": "2022-06-23T13:24:20+01:00", "UpdateTime": "2022-06-23T13:24:20+01:00", "LastAccessTime": "2022-06-23T13:24:20+01:00", "Retention": 0, "StorageDescriptor": { "Columns": [ { "Name": "trip_duration", "Type": "int" }, { "Name": "start_month", "Type": "string" }, ... ], "Location": "s3://dbmsdcatpoc/hive/bikes.db/trips/", "InputFormat": "org.apache.hadoop.hive.ql.io.parquet.MapredParquetInputFormat", "OutputFormat": "org.apache.hadoop.hive.ql.io.parquet.MapredParquetOutputFormat", "Compressed": false, "NumberOfBuckets": -1, "SerdeInfo": { "SerializationLibrary": "org.apache.hadoop.hive.ql.io.parquet.serde.ParquetHiveSerDe", "Parameters": { "serialization.format": "1" } }, "BucketColumns": [], "SortColumns": [], "Parameters": { "CrawlerSchemaDeserializerVersion": "1.0", "CrawlerSchemaSerializerVersion": "1.0", "UPDATED_BY_CRAWLER": "crawler-bikes", "averageRecordSize": "86", "classification": "parquet", "compressionType": "none", "objectCount": "12", "recordCount": "404947", "sizeKey": "35312159", "typeOfData": "file" }, "StoredAsSubDirectories": false }, "PartitionKeys": [ { "Name": "p_start_month", "Type": "string" } ], "TableType": "EXTERNAL_TABLE", "Parameters": { "CrawlerSchemaDeserializerVersion": "1.0", "CrawlerSchemaSerializerVersion": "1.0", "UPDATED_BY_CRAWLER": "crawler-bikes", "averageRecordSize": "86", "classification": "parquet", "compressionType": "none", "objectCount": "12", "recordCount": "404947", "sizeKey": "35312159", "typeOfData": "file" }, "CreatedBy": "arn:aws:sts::579294766787:assumed-role/AWSGlueServiceRole-dbmsdcat/AWS-Crawler", "IsRegisteredWithLakeFormation": false, "CatalogId": "579294766787", "VersionId": "0" }

ALL_DCAT_ASSETSビュー

このデータベースにアクセスする権限があるデータ・カタログ・アセット。

ALL_DCAT_ATTRIBUTESビュー

このデータベースにアクセスする権限があるデータ・カタログ属性。

ALL_DCAT_CONNECTIONSビュー

このインスタンスに接続されているデータ・カタログに関する情報を含むビュー。

ALL_DCAT_ENTITIESビュー

このデータベースにアクセスする権限があるデータ・カタログ論理エンティティ。

ALL_DCAT_FOLDERSビュー

論理エンティティのデータファイルを含むオブジェクト・ストレージ・バケットのメタデータ。

ALL_DCAT_GLOBAL_ACCESSIBLE_CATALOGSビュー

このビューには、すべてのリージョンでアクセス可能なすべてのカタログが、各カタログのアクセス権限のレベルとともにリストされます。

ALL_DCAT_LOCAL_ACCESSIBLE_CATALOGSビュー

このビューには、現在のリージョンでアクセス可能なすべてのカタログが、各カタログのアクセス権限レベルとともにリストされます。

ALL_GLUE_DATABASESビュー

データカタログの資格情報にアクセスする権限があるAWS Glueデータカタログデータベース。

ALL_GLUE_TABLESビュー

このビューには、データ・カタログ資格証明がアクセスを許可されているすべてのAWS Glueデータ・カタログ表が表示されます。

DCAT_ATTRIBUTESビュー

論理エンティティ属性の外部表列へのマッピングをリストします。

DCAT_ENTITIESビュー

外部表への論理エンティティのマッピングについて説明します。

DBMS_DCAT$SYNC_LOGビュー

DBMS_DCAT$SYNC_LOGビューを使用すると、現行のユーザーが実行した最後の同期操作のログ表に簡単にアクセスできます。

RUN_SYNCプロシージャへのすべてのコールは、USER_LOAD_OPERATIONSのLOGFILE_TABLEフィールドが指す新しいログ表に記録されます。ログ表は2日後に自動的に削除され、ユーザーはDELETE_ALL_OPERATIONSプロシージャ(タイプはDCAT_SYNC)を使用してすべての同期ログをクリアできます。

DBMS_DCAT$SYNC_LOGビューは、最新のログ表を自動的に識別します。DBMS_DCAT$SYNC_LOGビューのスキーマを次に説明し、アクセス権限は個々のログ表のものと同じです。デフォルトでは、READはdbms_dcatロールおよびADMINユーザーに付与されます。

ログ表の形式は次のとおりです。

トラブルシューティング・ヒント

ここでは、一般的な問題に関してトラブルシューティングのヒントを示します。

• 必要なすべてのロールおよび権限が正しく割り当てられていることを確認します。
• リージョンおよびオブジェクト・ストアのURLが実際のデプロイメントと一致することを再確認します。
• 関連するユーザーまたはロールにGRANT READ権限が明示的に付与されていることを確認します。
• 同期の問題を診断するには、DBMS_DCAT$SYNC_LOG表で詳細なエラー・メッセージおよび操作ステータスを確認します。

ノート

ノート: USER_LOAD_OPERATIONS.LOGFILE_TABLEは、データ・ディクショナリを問い合せるか、ロード操作ログを追跡するOracleデータ・カタログ・ビューを使用して検索できます。