DBMS_DCAT 子程序概要

此表列出了用于创建、查询和删除数据目录连接的 DBMS_DCAT 程序包过程。

子程序	说明
SET_DATA_CATALOG_CREDENTIAL 过程	设置数据目录的特定连接所使用的数据目录访问身份证明
SET_OBJECT_STORE_CREDENTIAL 过程	设置给定唯一连接标识符用于访问对象存储的身份证明
SET_DATA_CATALOG_CONN 过程	创建与给定数据目录的连接
UNSET_DATA_CATALOG_CONN 过程	删除现有数据目录连接

SET_DATA_CATALOG_CREDENTIAL 过程

此过程设置与数据目录的特定连接使用的数据目录访问身份证明。

语法

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

参数

Parameter (参数)	说明
credential_name	用于访问数据目录的身份证明。
dcat_con_id	唯一的数据目录连接标识符。此身份证明用于 dcat_con_id 标识的连接。默认值为 Null。

此身份证明必须具有“管理数据目录”权限；请参阅数据目录策略。

SET_OBJECT_STORE_CREDENTIAL 过程

此过程设置给定唯一连接标识符用于访问对象存储的身份证明。更改对象存储访问身份证明将更改所有现有同步表以使用新身份证明。

语法

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

参数

Parameter (参数)	说明
credential_name	外部表用于访问对象存储的身份证明。
dcat_con_id	唯一的数据目录连接标识符。默认值为空值。

SET_DATA_CATALOG_CONN 过程

此过程将创建与给定数据目录的连接。需要连接才能将元数据与数据目录同步。Autonomous AI Database 实例可以连接到多个数据目录实例，并支持连接到 OCI Data Catalogs 和 AWS Glue Data Catalogs。

语法

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
 );

参数

Parameter (参数)	说明
region	“数据目录”区域。如果指定了 endpoint，则 region 是可选的。如果同时指定了 endpoint 和 region，则 endpoint 优先。默认值为 NULL。
endpoint	数据目录端点。如果指定了 region，则 endpoint 是可选的。如果同时指定了 endpoint 和 region，则 endpoint 优先。默认值为 NULL。
catalog_id	数据目录实例的唯一 Oracle Cloud 标识符 (OCID)。连接到 AWS Glue 数据目录时，catalog_id 是可选的。
dcat_con_id	唯一的数据目录连接标识符。连接到多个数据目录时，此标识符是必需的，并且仅连接到一个数据目录时是可选的。它用于在后续调用或查询视图时引用数据目录连接。如果未指定标识符，此过程将生成 NULL 连接标识符。dcat_con_id 适用以下限制： 它在自治 AI 数据库实例中必须唯一。 它必须以字母开头。 它可以包含字母数字字符、下划线 (_)、美元符号 ($) 和井号 (#)。 它的长度必须至少为 16 个字符。
catalog_type	要连接的数据目录的类型。允许的值： OCI_DCAT - OCI 数据目录 AWS_GLUE - AWS Glue 数据目录 NULL - 从提供的区域或端点自动检测目录类型。
token_endpoint	用于 OAuth 验证的访问令牌端点。默认值为 NULL。

用途

您只需调用此过程一次即可设置连接。在连接过程中，自治 AI 数据库将定制属性添加到数据目录。数据目录用户可以访问这些定制属性，并允许您覆盖默认名称（用于方案、表和列）和列数据类型。

在创建连接之前，必须创建和设置身份证明。有关连接过程的说明，请参阅 Typical Workflow with Data Catalog （适用于 OCI 数据目录）和 User Workflow for Querying with AWS Glue Data Catalog （适用于 AWS Glue 数据目录）。

示例

示例：使用已知 OCID 进行连接

在此示例中，自治 AI 数据库正在连接到 uk-london-1 区域中的数据目录。catalog_id 参数使用数据目录实例的 Oracle Cloud 标识符 (ocid)。自动确定数据目录的类型：AWS Glue 数据目录或 OCI 数据目录。

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

示例：连接到 AWS Glue 数据目录

连接是自治 AI 数据库实例与 AWS Glue 数据目录之间的关联。连接成功后，自治 AI 数据库实例能够与 AWS Glue 同步。每个 AWS 账户每个区域都有一个 AWS Glue 数据目录，每个目录都可以使用每个区域的对应服务端点进行访问。可以通过调用 API DBMS_DCAT.SET_DATA_CATALOG_CONN 并指定目录所在区域的端点，将自治 AI 数据库实例与 AWS Glue 数据目录关联。

请参阅 AWS Glue 端点和限额。

在此示例中，自治 AI 数据库正在连接到 uk-london-1 区域中的 AWS Glue 数据目录。由于这是 AWS Glue 数据目录连接，因此不需要 catalog_id 参数。

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

UNSET_DATA_CATALOG_CONN 过程

此过程将删除现有数据目录连接。

语法

注：调用此过程将删除作为先前同步的一部分创建的所有受保护方案和外部表。它不影响数据目录中的元数据。

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

参数

Parameter (参数)	说明
dcat_con_id	唯一的数据目录连接标识符。默认值为空值。

同步子程序

可以按照此表中列出的过程运行同步、创建和删除同步作业以及删除同步方案。

注： 2022 年 4 月 4 日，sync_option 和 grant_read 参数已添加到 DBMS_DCAT.RUN_SYNC 过程。为了确保在该日期之前创建的调度同步作业的正确性能，您需要删除并重新创建调度同步作业。请参见 DROP_SYNC_JOB Procedure 和 CREATE_SYNC_JOB Procedure 。

子程序	说明
CREATE_SYNC_JOB 过程	创建调度程序作业以定期调用 RUN_SYNC
DROP_SYNC_JOB 过程	删除给定唯一连接标识符的现有同步作业
DROP_SYNCED_SCHEMAS 过程	删除给定唯一连接标识符的所有以前同步的方案
RUN_SYNC 过程	运行同步操作

RUN_SYNC 过程

此过程运行同步操作，是同步的入口点。作为输入，它将获取所选数据目录资产、文件夹和实体的列表，并通过创建、删除和变更外部表来实体化这些资产。

sync_option 参数指定 RUN_SYNC 过程执行的操作：SYNC、DELETE 或 REPLACE。该操作对 synced_objects 参数作用域内的实体执行。

Every call to the RUN_SYNC procedure returns a unique operation_id that can be used to query the USER_LOAD_OPERATIONS view to obtain information about the status of the sync and the corresponding log_table. 可以查询 DBMS_DCAT$SYNC_LOG 视图，以便于当前用户执行的最后一次同步操作访问 log_table。有关详细信息，请参见 DBMS_DCAT$SYNC_LOG View 。

注： 2022 年 4 月 4 日，sync_option 和 grant_read 参数已添加到 DBMS_DCAT.RUN_SYNC 过程。为了确保在该日期之前创建的调度同步作业的正确性能，您需要删除并重新创建调度同步作业。请参见 DROP_SYNC_JOB Procedure 和 CREATE_SYNC_JOB Procedure 。

同步分区逻辑实体或胶水表

RUN_SYNC 过程会为每个逻辑实体或 Glue 表创建分区的外部表（当以下全部三个都适用时）：

1. OCI 数据目录逻辑实体或 Glue 表具有一个或多个分区属性。

2. 对于 OCI 数据目录，逻辑实体派生自基于前缀的文件名模式。不支持从基于正则表达式的模式派生的分区逻辑实体。

3. 对于 OCI 数据目录，逻辑实体基于采用 hive 样式或非 hive 文件夹格式的分区数据。不支持基于使用对象名称遵循非 Beehive 样式格式的分区数据的逻辑实体。

   • 示例 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 的文件名模式收集存储桶会生成一个名为 SALES 的逻辑实体，该实体具有三个分区属性：country、year 和 month。已分区属性的类型是 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 的文件名模式收集存储桶会生成一个名为 SALES 的逻辑实体，该实体具有三个分区属性：name0、name1 和 name2。生成的逻辑实体与示例 1 之间的唯一区别是，分区属性的名称是自动生成的，而在示例 1 中，它们是从 URL 中提取的（分别为 country、year 和 month）。

有关同步分区逻辑实体的完整端到端示例，请参见 Example：A Partitioned Data Scenario 。

分区逻辑实体/胶水表的增量同步

每次调用 RUN_SYNC 过程都会指定一组要与数据库同步的 OCI 数据目录逻辑实体或 AWS Glue 表。当逻辑实体或 Glue 表存在于两个 RUN_SYNC 调用中时，第二个调用将保留并可能更改现有外部表。下表显示了对逻辑实体或 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
 );

参数

Parameter (参数)	说明
synced_objects	此参数是一个 JSON 文档，用于指定要同步的数据目录对象。 对于 OCI 数据目录，JSON 文档以多个粒度指定一组实体：数据资产、文件夹（对象存储存储桶）或逻辑实体。It contains an asset_list that is either an array of asset objects or an array containing a single "*" string that stands for 'sync all (object store) data assets in the catalog'. 对于 AWS Glue 数据目录，JSON 文档以多个粒度指定表列表：数据库和表。该文档指定数据库列表。用户可以通过指定数据库中的单个表来限制要同步的表集。
sync_option	（可选）共有三个选项： SYNC（默认）- 此选项可确保在自治 AI 数据库中表示数据目录中 synced_objects 范围内的内容。如果从数据目录中删除了逻辑实体或 Glue 表（自上次同步操作以来），则会在自治 AI 数据库中删除它。在 synced_objects 范围内执行以下操作： 为新数据目录实体添加表 删除已删除数据目录实体的表 更新现有表的属性（例如名称、列和数据类型） DELETE- 删除 synced_objects 范围中的表。 REPLACE- 将当前同步的所有对象替换为 synced_objects 范围中的对象。
error_semantics	（可选）此参数指定错误行为。如果设置为 SKIP_ERRORS，同步将尝试继续，尽管单个实体遇到错误。如果设置为 STOP_ON_ERROR，则该过程将在首次出现错误时失败。默认值为 SKIP_ERRORS。
log_level	（可选）此参数指定增加日志记录详细信息级别的以下值：(OFF，FATAL，ERROR，WARN，INFO，DEBUG，TRACE，ALL)。默认值为 INFO。
grant_read	（可选）此参数是对通过此调用 RUN_SYNC 处理的所有外部表自动授予 READ 权限的用户/角色的列表。对于与 synced_objects 参数指定的实体对应的所有新外部表或现有外部表，grant_read 列表中的所有用户/角色都具有 READ 权限。RUN_SYNC 过程保留已授予的对已同步外部表的权限。
operation_id	（可选）此参数用于在 USER_LOAD_OPERATIONS 中查找同步的对应条目并确定日志表的名称。 注意：没有返回 operation_id 的 RUN_SYNC 版本可用，因此用户可以查询 USER_LOAD_OPERATIONS 以获取最新同步。
dcat_con_id	此参数是创建与数据目录的连接时指定的唯一数据目录连接标识符。请参见 SET_DATA_CATALOG_CONN Procedure 。此参数标识用于同步的连接，并成为派生方案名称的一部分。有关如何派生方案名称的说明，请参阅同步映射。参数默认值为 NULL。

示例

示例：同步所有 OCI 数据目录实体。

在以下示例中，将同步所有数据目录实体。

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

示例：用于同步所有 OCI 数据目录数据资产的 synced_objects 参数。

以下是用于同步数据目录中的所有（对象存储）数据资产的 synced_objects 参数示例。

{"asset_list" : ["*"]}

示例：用于同步特定 OCI 数据目录数据资产的 synced_objects 参数。

下面是用于同步两个数据资产的 synced_objects 参数示例。

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

示例：用于同步数据资产中特定 OCI 数据目录实体的 synced_objects 参数。

下面显示了用于同步数据资产中的两个实体的示例 synced_objects 参数。

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

示例：用于同步数据资产中特定 OCI 数据目录文件夹和实体的 synced_objects 参数。

下面显示了用于同步数据资产中的两个文件夹和两个实体的示例 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":["*"]}

示例：用于同步两个 AWS Glue 数据目录数据库的 synced_objects 参数。

下面显示了用于同步两个 AWS Glue 数据目录数据库的示例 synced_objects 参数。

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

示例：用于同步三个 AWS Glue 数据目录数据库的 synced_objects 参数。

下面显示了用于从 AWS Glue 数据目录数据库同步三个表的示例 synced_objects 参数。

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

CREATE_SYNC_JOB 过程

此过程创建调度程序作业以定期调用 RUN_SYNC

它将要同步的对象集、错误语义、日志级别和重复间隔用作输入。有关同步如何工作的更多详细信息，请参见 RUN_SYNC Procedure 。

只能有一个同步作业。如果已指定其他作业，则 CREATE_SYNC_JOB 过程将失败，除非强制参数设置为 TRUE。如果强制设置为 TRUE，则会删除上一个作业。

如果计划程序作业尝试在另一个同步正在进行时运行，则计划程序作业将失败。

注： 2022 年 4 月 4 日，sync_option 和 grant_read 参数已添加到 DBMS_DCAT.RUN_SYNC 过程。为了确保在该日期之前创建的调度同步作业的正确性能，您需要删除并重新创建调度同步作业。请参见 DROP_SYNC_JOB Procedure 和 CREATE_SYNC_JOB Procedure 。

语法

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
);

参数

Parameter (参数)	说明
synced_objects	指定要同步的对象的 JSON 对象，如 RUN_SYNC 过程所述。请参见 RUN_SYNC Procedure 。
error_semantics	（可选）为 RUN_SYNC 指定的错误行为。默认值为 SKIP_ERRORS。
log_level	（可选）为 RUN_SYNC 指定的日志记录级别。默认值为 INFO。
repeat_interval	作业的重复间隔，其语义与 DBMS_SCHEDULER.CREATE_JOB 过程的重复间隔参数相同。有关 repeat_interval 的详细信息，请参阅创建作业概览。
force	（可选）如果为 TRUE，则先删除现有同步作业。如果为 FALSE，则 CREATE_SYNC_JOB 过程会在同步作业已存在时失败。默认值为 FALSE。
grant_read	（可选）要在同步的外部表上授予 READ 的用户/角色列表，如过程 RUN_SYNC 中所述。请参见 RUN_SYNC Procedure 。
sync_option	（可选）有关已通过以前的 RUN_SYNC 操作同步的实体的行为，如过程 RUN_SYNC 中所述。请参见 RUN_SYNC Procedure 。
dcat_con_id	此参数是创建到数据目录的连接时指定的唯一数据目录连接标识符。请参见 SET_DATA_CATALOG_CONN Procedure 。此参数标识用于同步的连接，并成为派生方案名称的一部分。有关如何派生方案名称的说明，请参阅同步映射。参数默认值为 NULL。

DROP_SYNC_JOB 过程

此过程将删除给定唯一连接标识符的现有同步作业。

语法

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

参数

Parameter (参数)	说明
dcat_con_id	唯一的数据目录连接标识符。默认值为空值。

DROP_SYNCED_SCHEMAS 过程

此过程将删除给定唯一连接标识符的所有以前同步的方案。

语法

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

参数

Parameter (参数)	说明
dcat_con_id	唯一的数据目录连接标识符。默认值为空值。