使用 DBMS_CATALOG 管理目录

DBMS_CATALOG 程序包提供了一整套用于管理 Oracle Autonomous AI Database 数据库目录的过程、函数和类型。

什么是目录？

catalog 定义为命名 schemas 的集合，其中每个目录都包含命名对象的集合，例如 TABLES 或 VIEWS。每个 Oracle 数据库都有一个本地目录—数据字典。此目录始终存在，无法删除。但还有其他目录示例，这些目录是在数据库外部定义的。
  • 通过数据库链接提供的一组对象
  • 通过 DBMS_SHARE（例如 Delta 共享）提供的一组共享对象；
  • 由 Iceberg REST 目录管理的一组 Iceberg 表；
  • 由第三方产品定义的一组对象，例如 Amazon Glue、Databricks Unity Catalog 或 Snowflakes Polaris；
  • 由 Oracle OCI 数据目录服务定义的一组对象。
  • 目录也可以被视为“域”或“数据产品”，这是一组针对特定业务目的分组在一起的对象。

有关 Data Studio 工具套件的目录工具的更多信息，请参阅目录工具。

在操作系统中，可以通过挂载文件系统来访问外部数据文件。类似地，您可以通过使用 DBMS_CATALOG 软件包挂载目录来访问自治 AI 数据库中的外部数据。

以下示例说明如何挂载外部 Iceberg REST 目录。要使用它，需要三条信息。

  • Iceberg REST 目录端点；
  • 用于调用此端点的身份证明（例如 Bearer 标记）；
  • 用于访问存储 Iceberg 数据文件的存储桶的凭证（例如用户名/密码）。
BEGIN
  -- Create a credential capable of accessing an external Iceberg REST catalog
  dbms_cloud.create_credential('ICEBERG_CATALOG_CRED', ...);

  -- Create a credential capable of accessing the bucket where the 
  -- Iceberg data files are stored.
  dbms_cloud.create_credential('ICEBERG_STORAGE_CRED', ...); 

  -- Mount the iceberg catalog
  dbms_catalog.mount_iceberg(
    catalog_name             => 'ICEBERG_CAT',
    endpoint                 => 'https://...',
    catalog_credential       => 'ICEBERG_CATALOG_CRED',
    data_storage_credential  => 'ICEBERG_STORAGE_CRED',
    catalog_type             => 'ICEBERG_UNITY');
END;
/

-- List tables in the iceberg catalog
SELECT owner, table_name 
FROM all_tables@iceberg_cat;

-- Read data from an iceberg table
SELECT *
FROM a_schema.a_table@iceberg_cat;

DBMS_CATALOG 用于定义和处理与目录相关的操作。

它提供了一整套用于管理 Oracle 自治数据库中的目录的过程、函数和类型。它支持诸如挂载和卸载目录、管理目录属性、处理凭证以及使用表、方案和对象等目录实体等操作。此程序包对于集成外部数据源和以安全高效的方式管理元数据至关重要。

安全模型

DBMS_CATALOG 软件包在 AUTHID CURRENT_USER 模型下运行，这意味着它使用当前用户的特权运行。您必须具有相应的权限才能执行诸如挂载目录、更新属性或管理凭证等操作。

注意：

很少有目录需要自治 AI 数据库来连接到外部 Internet 资源。因此，您必须将相关的外部地址添加到关联的数据库用户的访问控制列表中。例如，在 Azure 上启用对 Databricks Unity Iceberg 目录的访问时，您可能需要将两个地址列入白名单：一个用于访问 Iceberg REST API，另一个用于用户需要访问底层数据。
BEGIN
  dbms_network_acl_admin.append_host_ace(
    host => '*.azuredatabricks.net',
    lower_port => 443,
    upper_port => 443,
    ace => xs$ace_type(
      privilege_list => xs$name_list('http', 'http_proxy'),
      principal_name => 'DBUSER',
      principal_type => xs_acl.ptype_db));

  dbms_network_acl_admin.append_host_ace(
    host => '*.blob.core.windows.net',
    ace => xs$ace_type(
      privilege_list => xs$name_list('http', 'http_proxy'),
      principal_name =>  'DBUSER',
      principal_type => xs_acl.ptype_db));
END;
/

必须使用 DWROLE 才能运行 DBMS_CATALOG 方法。

运行以下命令向用户授予 DWROLE：
GRANT DWROLE TO MY_USER;

目录类型和常量

本节概述了软件包中定义的目录类型和关键常量。它介绍了用于组织各种目录源的不同目录类别，并概述了配置和管理目录属性和行为的基本常量。

目录类型为

程序包指定多种目录类型，用于对不同类别的目录进行分类和处理。它们是：
  • CATALOG_TYPE_SHARE:

    表示基于共享资源的目录，该目录主要用于在系统或用户之间共享数据。例如，像 Data Studio 的 Data Sharing 这样的数据共享服务使用基于共享的目录来安全地分发数据。

  • CATALOG_TYPE_DATA_CATALOG：表示外部数据目录，例如 AWS Glue 或 OCI Data Catalog。这些目录用作数据集元数据的集中系统信息库。例如，AWS Glue Data Catalog 可自动搜索和管理 S3 和 Redshift 等 AWS 服务中数据源的元数据，从而实现无缝的数据集成和查询。
  • CATALOG_TYPE_DB_LINK：表示从数据库链接构建的目录类别。通过此类型的目录，您可以访问和组织位于远程或外部数据库中的元数据和对象，并通过已建立的数据库进行连接。

    有关详细信息，请参阅使用数据库链接从 Oracle 和非 Oracle 数据库加载数据。

    ​
  • CATALOG_TYPE_VIRTUAL：表示提供对物理数据源的抽象的虚拟目录。虚拟目录不存储数据本身，而是提供一个统一的接口来查询不同的数据源，例如，在数据虚拟化平台中创建的虚拟视图。
  • CATALOG_TYPE_ICEBERG：表示 Iceberg 目录，用于管理以 Apache Iceberg 格式存储的表的元数据。Iceberg 是一种表格式，专为庞大的分析数据集而设计，支持模式演变和时差等功能。

    有关详细信息，请参阅管理目录。

常数

以下部分突出显示了定义目录属性和设置的基本常量。常量包括：
  • TYPE_CATALOG 和 NS_CATALOG：这将目录类型和名称空间定义为 CATALOG。
  • DEFAULT_CATALOG：默认目录名称设置为 LOCAL。
  • 用于管理目录行为和元数据高速缓存的属性常量，例如 PROP_IS_ENABLED、PROP_IS_SYNCHRONIZED、PROP_CACHE_ENABLED、PROP_CACHE_DURATION 等。

    常量名称 值 说明
    PROP_IS_ENABLED IS_ENABLED

    此属性确定当前是否为查询和搜索启用目录。

    有效值：

    • 是：目录将显示在 Data Studio UI 搜索对话框中，并且可以使用数据库链接语法在 SQL 查询中使用（例如，从 all_users@catalog 中选择用户名）。

    • 否：目录将列在 ALL_MOUNTED_CATALOGS 视图中，但不会包括在 Data Studio UI 搜索中，并且不能在数据库链接语法中使用。

    PROP_CACHE_ENABLED CACHE_ENABLED

    此属性确定是否应将远程方案中的元数据缓存在本地数据库中以提高性能。

    有效值

    • YES 将在首次访问时缓存元数据，并在 PROP_CACHE_DURATION 指定的时段内保留在高速缓存中。
    • 否：

      将不缓存元数据。所有访问目录中对象的尝试都将在查询时到达远程元数据源。
    PROP_CACHE_DURATION CACHE_DURATION

    元数据在过时之前应保留在高速缓存中的秒数。默认值为 3600 秒（一小时）。

    请注意，用户可以随时通过调用 DBMS_CATALOG.FLUSH_CATALOG_CACHE 手动刷新高速缓存。

    用户可以随时通过调用 DBMS_CATALOG.PREFILL_CATALOG_CACHE 来刷新高速缓存。

    PROP_CACHE_ASYNC 'CACHE_ASYNC'

    如果使用异步作业填充高速缓存，则显示此字段。

    有效值

    • 是：

      将使用在用户首次请求元数据时创建的 DBMS_SCHEDULER 作业缓存元数据。

    • 否：

      元数据将缓存请求元数据的用户的数据库会话。
    PROP_DEFAULT_SCHEMA DEFAULT_SCHEMA
    如果用户运行以下表单的查询，将默认选择远程方案的名称： 
    select * from table@catalog
    默认方案与本地数据库中的用户自己的方案具有相同的角色。
    PROP_DCAT_TYPE DATA_CATALOG_TYPE

    由 DBMS_CATALOG.MOUNT_DATA_CATALOG 挂载的目录的类型

    有效值

    • AWS_GLUE ：目录是在远程 AWS Glue 存储库的顶部定义的。
    • OCI_DCAT ：目录是在 OCI 数据目录实例的基础上定义的。

    注意：

    这是只读属性。
    PROP_CUSTOM CUSTOM

    定制属性是用户与目录、方案、表或目录中的其他对象关联的名称/值对。

    有两种方法可以指定定制属性：
    • 可以通过指定组合属性名称 'CUSTOM:MY_PROP' 和任意字符串值来设置单个定制属性 "MY_PROP" 表示。
      DBMS_CATALOG.UPDATE_CATALOG_PROPERTY(
   catalog_name     => 'some_catalog',
   catalog_property => 'CUSTOM:MY_PROP',
   new_value        => 'Property Value');
    • 您可以通过指定简单属性名称 'CUSTOM' 以及包含名称值对的 JSON 对象来指定一组客户属性。
      DBMS_CATALOG.UPDATE_CATALOG_PROPERTY(
   catalog_name     => 'some_catalog',
   catalog_property => 'CUSTOM',
   new_value        => '{"Property1" : "Value 1",
                         "Property2" : "Value 2",
                         ...}');

      注意：

      定制属性名称区分大小写，因此 CUSTOM:MY_PROP 与 CUSTOM:My_Prop 不同。

      要删除定制属性，请将该值设置为 NULL。

      自定义属性可以在 Data Studio UI 中用作搜索词。例如，通过在 DBMS_CATALOG.GET_TABLES 中指定 condition 参数，可以找到具有属性 MY_PROP 的所有表。
      SELECT table_name
FROM DBMS_CATALOG.GET_TABLES(
       catalog_name => 'some_catalog',
       conditions => '#MY_PROP');

      您还可以搜索特定值。

      SELECT table_name
FROM DBMS_CATALOG.GET_TABLES(
       catalog_name => 'some_catalog',
       conditions => '#MY_PROP="Property Value"');
    PROP_METADATA METADATA

    定制元数据与定制属性类似，但可以包含自由形式的 JSON。元数据随对象一起存储并且可以检索，但不能用作搜索词。

    有两种方法可以指定定制元数据：
    • 可以使用属性名称 'METADATA' 将整个元数据设置为 JSON。
      DBMS_CATALOG.UPDATE_CATALOG_PROPERTY(
   catalog_name     => 'some_catalog',
   catalog_property => 'METADATA',
   new_value        => '{"subObject":{"propName":"abc"}}');
    • 可以使用组合属性名称 'METADATA:path' 更新元数据的子组件，其中 path 是一些相对 JSON 路径。
      DBMS_CATALOG.UPDATE_CATALOG_PROPERTY(
   catalog_name     => 'some_catalog',
   catalog_property => 'METADATA:subObject.propName',
   new_value        => 'xyz');
    PROP_CONFIGURATION CONFIGURATION

    配置属性用于更新 Iceberg 目录的特定配置属性。它的工作方式与 CUSTOM 属性类似。

    BEGIN
  dbms_catalog.update_catalog_property(
    'iceberg_cat', 
    'CONFIGURATION:IS_CASE_SENSITIVE', 
    'YES');
END;
/

数据类型

DBMS_CATALOG 软件包引入了各种定制数据类型来管理目录相关信息。它们是：
  • credential_info 和 credential_info_map：这些是用于存储和映射身份证明信息的结构。
  • catalog_table 和 catalog_tables：这些记录和表用于存储详细的表元数据（例如，所有者、名称、说明和状态）。
  • catalog_schema 和 catalog_schemas：这些是方案元数据的记录和表。
  • catalog_object 和 catalog_objects：这些是目录中对象元数据的记录和表。
  • DBMS_CATALOG 程序包
    DBMS_CATALOG 程序包包括用于目录管理的各种子程序，这些子程序按功能分组。
  • DBMS_CATALOG 概要
    本节介绍 Oracle Autonomous AI Database 随附的 DBMS_CATALOG 子程序。

父主题：目录工具