对象和文件的 DBMS_CLOUD

本节介绍用于处理对象和文件的 DBMS_CLOUD 子程序。

Prerequisites

作为开发人员，您可以将 DBMS_CLOUD 过程与部署在 Oracle Public Cloud、Multicloud 或 Exadata Cloud@Customer 上的自治 AI 数据库结合使用。

根据部署选择，必须满足以下先决条件，才能将 DBMS_CLOUD 过程与 Amazon S3、Azure Blob Storage 和 Google Cloud Storage 服务提供商结合使用。

Oracle Public Cloud 或多云 Exadata Cloud@Customer

组管理员必须使用 NAT 网关配置出站连接，如下所述：

• 按照 Oracle Cloud Infrastructure 文档中的创建 NAT 网关中的说明，在自治 AI 数据库资源所在的虚拟云网络 (VCN) 中创建 NAT 网关。

• 创建 NAT 网关后，在自治 AI 数据库资源所在的 VCN 中添加路由规则和出站安全规则到每个子网，以便这些资源可以使用网关从 Azure AD 实例获取公钥：

  1. 转到子网的 Subnet Details（子网详细信息）页面。

  2. 在 Subnet Information（子网信息）选项卡中，单击子网的 Route Table（路由表）的名称以显示 Route Table Details（路由表详细信息）页面。

  3. 在现有路由规则表中，检查是否已存在具有以下特征的规则：

     • 目标：0.0.0.0/0

     • 目标类型：NAT 网关

     • 目标：刚在 VCN 中创建的 NAT 网关的名称

     如果不存在此类规则，请单击添加路由规则并添加具有这些特征的路由规则。

  4. 返回到子网的子网详细信息页面。

  5. 在子网的安全列表表中，单击子网的安全列表的名称以显示其安全列表详细信息页。

  6. 在侧边菜单的资源下，单击出站规则。

  7. 在现有出站规则表中，检查是否已存在具有以下特征的规则：

     • 目标类型： CIDR

     • 目标：0.0.0.0/0

     • IP 协议： TCP

     • 源端口范围：443

     • 目标端口范围：全部

     如果不存在此类规则，请单击添加出站规则并添加具有这些特征的出站规则。

您环境中的 HTTP 代理设置必须允许数据库访问云服务提供商。

这些设置由组管理员在创建 Exadata Cloud@Customer 基础结构时定义，如 Using the Console to Provision Exadata Database Service on Cloud@Customer 中所述。

注：只有在 Exadata 基础结构处于 Requires Activation 状态之前，才能编辑包括 HTTP 代理的网络配置。一旦激活，您就无法编辑这些设置。

为已预配的 Exadata 基础结构设置 HTTP 代理需要 My Oracle Support 中的服务请求 (SR)。有关详细信息，请参见在 My Oracle Support 中创建服务请求。

对象和文件的 DBMS_CLOUD 子程序

DBMS_CLOUD 程序包中用于对象和文件管理的子程序。

子程序	说明
COPY_COLLECT 操作	此过程将数据从云对象存储或目录中的文件加载到现有 SODA 集合中。
COPY_DATA 过程	此过程将数据从云对象存储或目录中的文件加载到现有自治 AI 数据库表中。
COPY_DATA Avro、ORC 或 Parquet 文件的过程	此过程将 format 参数 type 设置为值 orc、parquet 或 avro，可将数据从云中的 ORC、Parquet 或 Avro 文件或目录中的 ORC、Parquet 或 Avro 文件加载到现有 Autonomous AI Database 表中。 与文本文件类似，数据从源 ORC、Parquet 或 Avro 文件复制到预先存在的内部表中。
COPY_OBJECT 过程	此过程将文件从一个云对象存储桶复制到另一个云对象存储桶。
CREATE_EXTERNAL_TABLE 过程	此过程在云中的文件或目录中的文件上创建外部表。这允许您对来自自治 AI 数据库的外部数据运行查询。
Avro、ORC 或 Parquet 文件的 CREATE_EXTERNAL_TABLE 过程	此过程将 format 参数 type 设置为值 parquet、orc 或 avro，将在云中或目录中创建具有 Parquet、ORC 或 Avro 格式文件的外部表。 这允许您对来自自治 AI 数据库的外部数据运行查询。
CREATE_EXTERNAL_TEXT_INDEX 过程	此过程将在对象存储文件上创建文本索引。
CREATE_HYBRID_PART_TABLE 过程	此过程将创建混合分区表。这允许您对自治 AI 数据库中的混合分区数据运行查询。
DELETE_ALL_OPERATIONS 过程	此过程将清除在方案中的 user_load_operations 表中记录的所有数据加载操作，或清除指定类型的所有数据加载操作（如 type 参数所示）。
DELETE_FILE 过程	此过程从自治 AI 数据库上的指定目录中删除指定的文件
DELETE_OBJECT 过程	此过程将删除对象存储上的指定对象。
DELETE_OPERATION 过程	此过程接受 operation_id 作为输入，并删除与指定的 operation_id 关联的日志。
DROP_EXTERNAL_TEXT_INDEX 过程	此过程将删除对象存储文件上的文本索引。
EXPORT_DATA 过程	此过程根据查询结果将数据从自治 AI 数据库导出到云中的文件。使用重载表单可以使用 operation_id 参数。根据指定的 format 参数 type 选项，该过程以文本形式将行导出到云对象存储，选项包括 CSV、JSON、Parquet 或 XML
GET_OBJECT 过程和函数	此过程已重载。过程表单从 Cloud Object Storage 读取对象并将其复制到 Autonomous AI Database。函数表单从 Cloud Object Storage 读取对象，并将 BLOB 返回到 Autonomous AI Database。
LIST_FILES 函数	此函数列出指定目录中的文件。结果包括有关文件的文件名和其他元数据，例如文件大小（以字节为单位）、创建时间戳和上次修改时间戳。
LIST_OBJECTS 函数	此函数列出对象存储上指定位置中的对象。结果包括对象名称和有关对象的其他元数据，例如大小、校验和、创建时间戳和上次修改时间戳。
MOVE_OBJECT 过程	此过程将对象从一个云对象存储桶移到另一个云对象存储桶。
PUT_OBJECT 过程	此过程已重载。该过程以一种形式将文件从 Autonomous AI Database 复制到 Cloud Object Storage。该过程以另一种形式将 BLOB 从自治 AI 数据库复制到云对象存储。
SYNC_EXTERNAL_PART_TABLE 过程	此过程简化了从云中的文件更新外部分区表的过程。每当添加新分区或从外部分区表的对象存储源中删除分区时，都运行此过程。
VALIDATE_EXTERNAL_TABLE 过程	此过程验证外部表的源文件，生成日志信息，并将与为外部表指定的格式选项不匹配的行存储在自治 AI 数据库上的错误文件表中。
VALIDATE_EXTERNAL_PART_TABLE 过程	此过程验证外部分区表的源文件，生成日志信息，并将与为外部表指定的格式选项不匹配的行存储在自治 AI 数据库上的错误文件表中。
VALIDATE_HYBRID_PART_TABLE 过程	此过程验证混合分区表的源文件，生成日志信息，并将与为混合表指定的格式选项不匹配的行存储在自治 AI 数据库上的错误文件表中。

COPY_COLLECT 操作

此过程将数据从云对象存储或目录加载到 SODA 集合中。如果指定的 SODA 集合不存在，该过程将创建该集合。使用重载表单可以使用 operation_id 参数。

语法

DBMS_CLOUD.COPY_COLLECTION (
    collection_name   IN VARCHAR2,
    credential_name   IN VARCHAR2 DEFAULT NULL,
    file_uri_list     IN CLOB,
    format            IN CLOB     DEFAULT NULL
);

DBMS_CLOUD.COPY_COLLECTION (
    collection_name   IN VARCHAR2,
    credential_name   IN VARCHAR2 DEFAULT NULL,
    file_uri_list     IN CLOB,
    format            IN CLOB     DEFAULT NULL,
    operation_id      OUT NOCOPY NUMBER
);

参数

Parameter (参数)	说明
collection_name	要将数据加载到的 SODA 集合的名称。如果已存在具有此名称的集合，将加载指定的数据，否则将创建新集合。
credential_name	用于访问云对象存储的身份证明的名称。 使用 file_uri_list 指定目录时不使用此参数。
file_uri_list	此参数指定源文件 URI 的逗号分隔列表，或者指定一个或多个目录和源文件。 云源文件 URI 您可以在云源文件 URI 中的文件名中使用通配符和正则表达式。 正则表达式只能在 regexuri format 参数设置为 TRUE 时使用。 当 regexuri 参数设置为 FALSE 时，字符 "*" 和 "?" 被视为通配符。当 regexuri 参数设置为 TRUE 时，字符 "*" 和 "?" 是指定正则表达式模式的一部分。 仅 URI 中的文件名或子文件夹路径支持正则表达式模式，模式匹配与 REGEXP_LIKE 函数执行的模式匹配相同。 例如： file_uri_list => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o(/)*year=[0-9]+(/)*month=[0-9]+(/)*[a-z]+[1-3]??.csv' URI 的格式取决于您使用的云对象存储服务，有关详细信息，请参见 Cloud Object Storage URI Formats 。 有关 REGEXP_LIKE 条件的更多信息，请参见 Oracle Database 19c SQL Language Reference 或 Oracle Database 26ai SQL Language Reference 中的 REGEXP_LIKE Condition 。 目录 可以指定一个目录和一个或多个文件名，也可以使用逗号分隔的目录和文件名列表。指定目录的格式为：'MY_DIR:filename.ext'。默认情况下，目录名称 MY_DIR 是数据库对象，不区分大小写。文件名区分大小写。 可以使用通配符指定目录中的文件名。字符 "*" 可以用作表示多个字符的通配符，字符 "?" 可以用作表示单个字符的通配符。例如：'MY_DIR:*" 或 'MY_DIR:test?' 要指定多个目录，请使用逗号分隔的目录列表：例如：'MY_DIR1:*, MY_DIR2:test?' 使用双引号指定区分大小写的目录名称。例如：'"my_dir1":*, "my_dir2":Test?' 要包含引号字符，请使用两个引号。例如：'MY_DIR:''filename.ext'。这指定 filename 以引号 (') 开头。
format	描述源文件格式的选项。这些选项指定为 JSON 字符串。 支持的格式包括：characterset, compression, ignoreblanklines, jsonpath, maxdocsize, recorddelimiter, rejectlimit, unpackarray、keyassignment 和 keypath。 除了上述 JSON 数据格式之外，自治 AI 数据库还支持其他格式。有关自治 AI 数据库支持的格式参数的列表，请参见 Format Parameter 。
operation_id	使用此参数以 USER_LOAD_OPERATIONS 视图中相应 ID 的身份跟踪加载操作的进度和最终状态。

范例

BEGIN
    DBMS_CLOUD.CREATE_CREDENTIAL(
            credential_name => 'OBJ_STORE_CRED',
            username        => '[e-mail]',
            password        => 'password'
            );

    DBMS_CLOUD.COPY_COLLECTION(
            collection_name => 'myCollection',
            credential_name => 'OBJ_STORE_CRED',
            file_uri_list   => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/adbexample/b/json/o/myCollection.json'
            );
END;
/

COPY_DATA 过程

此过程将数据从云中的文件或目录中的文件加载到现有自治 AI 数据库表中。使用重载表单可以使用 operation_id 参数。

语法

DBMS_CLOUD.COPY_DATA (
    table_name        IN VARCHAR2,
    credential_name   IN VARCHAR2 DEFAULT NULL,
    file_uri_list     IN CLOB,
    schema_name       IN VARCHAR2,
    field_list        IN CLOB,
    format            IN CLOB);

DBMS_CLOUD.COPY_DATA (
    table_name        IN VARCHAR2,
    credential_name   IN VARCHAR2 DEFAULT NULL,
    file_uri_list     IN CLOB DEFAULT NULL,
    schema_name       IN VARCHAR2 DEFAULT NULL,
    field_list        IN CLOB DEFAULT NULL,
    format            IN CLOB DEFAULT NULL
    operation_id      OUT NOCOPY NUMBER);

参数

Parameter (参数)	说明
table_name	数据库上的目标表的名称。需要在运行 COPY_DATA 之前创建目标表。
credential_name	用于访问云对象存储的身份证明的名称。 使用 file_uri_list 指定目录时不使用此参数。
file_uri_list	您可以在云源文件 URI 中的文件名中使用通配符和正则表达式。 云源文件 URI 此参数指定源文件 URI 的逗号分隔列表，或者指定一个或多个目录和源文件。 正则表达式只能在 regexuri format 参数设置为 TRUE 时使用。 当 regexuri 参数设置为 FALSE 时，字符 "*" 和 "?" 被视为通配符。当 regexuri 参数设置为 TRUE 时，字符 "*" 和 "?" 是指定正则表达式模式的一部分。 仅 URI 中的文件名或子文件夹路径支持正则表达式模式，模式匹配与 REGEXP_LIKE 函数执行的模式匹配相同。 例如： file_uri_list => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o(/)*year=[0-9]+(/)*month=[0-9]+(/)*[a-z]+[1-3]??.csv' URI 的格式取决于您使用的云对象存储服务，有关详细信息，请参见 Cloud Object Storage URI Formats 。 有关 REGEXP_LIKE 条件的更多信息，请参见 Oracle Database 19c SQL Language Reference 中的 REGEXP_LIKE Condition 或 Oracle Database 26ai SQL Language Reference 。 目录 可以指定一个目录和一个或多个文件名，也可以使用逗号分隔的目录和文件名列表。指定目录的格式为：'MY_DIR:filename.ext'。默认情况下，目录名称 MY_DIR 是数据库对象，不区分大小写。文件名区分大小写。 可以使用通配符指定目录中的文件名。字符 "*" 可以用作表示多个字符的通配符，字符 "?" 可以用作表示单个字符的通配符。例如：'MY_DIR:*" 或 'MY_DIR:test?' 要指定多个目录，请使用逗号分隔的目录列表：例如：'MY_DIR1:*, MY_DIR2:test?' 使用双引号指定区分大小写的目录名称。例如：'"my_dir1":*, "my_dir2":Test?' 要包含引号字符，请使用两个引号。例如：'MY_DIR:''filename.ext'。这指定 filename 以引号 (') 开头。
schema_name	目标表所在的方案的名称。默认值为 NULL，表示目标表与运行该过程的用户在同一方案中。
field_list	标识源文件中的字段及其数据类型。默认值为 NULL，表示字段及其数据类型由 column_list 参数确定。此参数的语法与常规 Oracle 外部表中的 field_list 子句相同。有关详细信息，请参阅 Oracle Database 19c Utilities 或 Oracle Database 26ai Utilities 中的 field_list 。 当 format 参数 type 选项值为 json 时，将忽略此参数。 有关使用 field_list 的示例，请参见 CREATE_EXTERNAL_TABLE Procedure 。
format	描述源、日志和错误文件的格式的选项。有关选项列表以及如何指定值，请参阅格式参数。 有关 Avro、ORC 或 Parquet 文件格式选项，请参见 DBMS_CLOUD Package Format Options for Avro、ORC 或 Parquet 。
operation_id	使用此参数以 USER_LOAD_OPERATIONS 视图中相应 ID 的身份跟踪加载操作的进度和最终状态。

用法附注

默认记录分隔符为 detected newline。使用 detected newline 时，DBMS_CLOUD 会尝试自动查找要用作记录分隔符的正确换行符。DBMS_CLOUD 首先搜索 Windows 的换行符 \r\n。如果找到 Windows 换行符，则此字符将用作该过程中所有文件的记录分隔符。如果未找到 Windows 新行字符，DBMS_CLOUD 将搜索 UNIX/Linux 新行字符 \n，如果找到新行字符，则使用 \n 作为该过程中所有文件的记录分隔符。如果源文件使用不同记录分隔符的组合，则可能会遇到错误，例如 "KUP-04020: found record longer than buffer size supported"。在这种情况下，您需要修改源文件以使用相同的记录分隔符，或仅指定使用相同记录分隔符的源文件。

有关 recorddelmiter 格式选项的信息，请参阅格式参数。

示例

BEGIN
    DBMS_CLOUD.CREATE_CREDENTIAL(
            credential_name => 'DEF_CRED_NAME',
            username        => '[e-mail]',
            password        => 'password'
            );
END;
/

BEGIN
 DBMS_CLOUD.COPY_DATA(
    table_name =>'CHANNELS',
    credential_name =>'DEF_CRED_NAME',
    file_uri_list =>'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/channels.txt',
    format => json_object('delimiter' value ',')
 );
END;
/

BEGIN
    DBMS_CLOUD.COPY_DATA(
            table_name      => 'ORDERS',
            schema_name     => 'TEST_SCHEMA',
            credential_name => 'DEF_CRED_NAME',
	     file_uri_list   => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/adbexample/b/json/o/orde[r]s.tbl.1'
            format          =>  json_object('ignoreblanklines' value TRUE,
                                            'rejectlimit' value '0',
                                            'dateformat' value 'yyyy-mm-dd',
                                            'regexuri' value TRUE)
            );
END;
/

COPY_DATA Avro、ORC 或 Parquet 文件的过程

此过程将 format 参数 type 设置为值 avro、orc 或 parquet，可将数据从云中的 Avro、ORC 或 Parquet 文件或目录中的文件加载到现有 Autonomous AI Database 表中。

与文本文件类似，数据从源 Avro、ORC 或 Parquet 文件复制到预先存在的内部表中。

语法

DBMS_CLOUD.COPY_DATA (
    table_name        IN VARCHAR2,
    credential_name   IN VARCHAR2 DEFAULT NULL,
    file_uri_list     IN CLOB,
    schema_name       IN VARCHAR2 DEFAULT,
    field_list        IN CLOB DEFAULT,
    format            IN CLOB DEFAULT);

参数

Parameter (参数)	说明
table_name	数据库上的目标表的名称。需要在运行 COPY_DATA 之前创建目标表。
credential_name	用于访问云对象存储的身份证明的名称。 使用 file_uri_list 指定目录时不使用此参数。
file_uri_list	此参数指定源文件 URI 的逗号分隔列表，或者指定一个或多个目录和源文件。 云源文件 URI 您可以在云源文件 URI 中的文件名中使用通配符和正则表达式。 正则表达式只能在 regexuri format 参数设置为 TRUE 时使用。 当 regexuri 参数设置为 FALSE 时，字符 "*" 和 "?" 被视为通配符。当 regexuri 参数设置为 TRUE 时，字符 "*" 和 "?" 是指定正则表达式模式的一部分。 仅 URI 中的文件名或子文件夹路径支持正则表达式模式，模式匹配与 REGEXP_LIKE 函数执行的模式匹配相同。 例如： file_uri_list => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o(/)*year=[0-9]+(/)*month=[0-9]+(/)*[a-z]+[1-3]??.csv' URI 的格式取决于您使用的云对象存储服务，有关详细信息，请参见 Cloud Object Storage URI Formats 。 有关 REGEXP_LIKE 条件的更多信息，请参见 Oracle Database 19c SQL Language Reference 中的 REGEXP_LIKE Condition 或 Oracle Database 26ai SQL Language Reference 。 目录 可以指定一个目录和一个或多个文件名，也可以使用逗号分隔的目录和文件名列表。指定目录的格式为：'MY_DIR:filename.ext'。默认情况下，目录名称 MY_DIR 是数据库对象，不区分大小写。文件名区分大小写。 可以使用通配符指定目录中的文件名。字符 "*" 可以用作表示多个字符的通配符，字符 "?" 可以用作表示单个字符的通配符。例如：'MY_DIR:*" 或 'MY_DIR:test?' 要指定多个目录，请使用逗号分隔的目录列表：例如：'MY_DIR1:*, MY_DIR2:test?' 使用双引号指定区分大小写的目录名称。例如：'"my_dir1":*, "my_dir2":Test?' 要包含引号字符，请使用两个引号。例如：'MY_DIR:''filename.ext'。这指定 filename 以引号 (') 开头。
schema_name	目标表所在的方案的名称。默认值为 NULL，表示目标表与运行该过程的用户在同一方案中。
field_list	已忽略 Avro、ORC 或 Parquet 文件。 源中的字段按名称匹配外部表列。源数据类型将转换为外部表列数据类型。 有关 ORC 文件，请参见 DBMS_CLOUD Package ORC to Oracle Data Type Mapping 。 有关映射的详细信息，请参见 DBMS_CLOUD Package Parquet to Oracle Data Type Mapping 。 有关映射的详细信息，请参见 DBMS_CLOUD Package Avro to Oracle Data Type Mapping 。
format	描述源文件格式的选项。对于 Avro、ORC 或 Parquet 文件，仅支持两个选项：请参见 DBMS_CLOUD Package Format Options for Avro、ORC 或 Parquet 。

使用说明

• 与其他数据文件一样，Avro、ORC 和 Parquet 数据加载会生成可在表 dba_load_operations 和 user_load_operations 中查看的日志。每个装入操作都会向 dba[ user ]_load_operations 添加一条记录，该记录指示包含日志的表。

  日志表提供了有关加载的摘要信息。

• 对于 Avro、ORC 或 Parquet，当 format 参数 type 设置为值 avro、orc 或 parquet 时，BADFILE_TABLE 表始终为空。

  • 对于 Parquet 文件，PRIMARY KEY 约束条件错误会引发 ORA 错误。

  • 如果某个列的数据遇到转换错误，例如，目标列不够大，无法保存转换后的值，则该列的值将设置为 NULL。这不会产生被拒绝的记录。

COPY_OBJECT 过程

此过程将对象从一个云对象存储桶或文件夹复制到另一个云对象存储桶或文件夹。

源存储桶和目标存储桶或文件夹可以位于相同或不同的云对象存储提供程序中。

当源和目标位于不同的对象存储中或具有具有相同云提供商的不同账户时，您可以为源和目标位置提供单独的身份证明名称。

未提供目标身份证明名称时，默认情况下目标位置也使用源身份证明名称。

语法

DBMS_CLOUD.COPY_OBJECT (
    source_credential_name  IN  VARCHAR2 DEFAULT NULL,
    source_object_uri       IN  VARCHAR2,
    target_object_uri       IN  VARCHAR2,
    target_credential_name  IN  VARCHAR2 DEFAULT NULL
);

参数

Parameter (参数)	说明
source_credential_name	用于访问源云对象存储的身份证明的名称。 如果不提供 source_credential_name 值，则 credential_name 将设置为 NULL。
source_object_uri	指定指向源对象存储存储桶或文件夹位置的 URI。 此参数是必需的。 URI 的格式取决于云对象存储服务。有关详细信息，请参阅云对象存储 URI 格式。
target_object_uri	指定目标对象存储的 URI。 此参数是必需的。 URI 的格式取决于云对象存储服务。有关详细信息，请参阅云对象存储 URI 格式。
target_credential_name	用于访问目标云对象存储位置的身份证明的名称。 如果不提供 target_credential_name 值，则 target_object_uri 将设置为 source_credential_name 值。

范例

BEGIN
DBMS_CLOUD.COPY_OBJECT (
    source_credential_name => 'OCI_CRED',
    source_object_uri    => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname1/bgfile.csv',
    target_object_uri    => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname2/myfile.csv'
);
END;
/

CREATE_EXTERNAL_PART_TABLE 过程

此过程将在云中的文件或目录中的文件上创建外部分区表。这允许您对自治 AI 数据库中的外部数据运行查询。

语法

DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE (
    table_name           IN VARCHAR2,
    credential_name      IN VARCHAR2,
    partitioning_clause  IN CLOB,
    column_list          IN CLOB,
    field_list           IN CLOB DEFAULT,
    format               IN CLOB DEFAULT);


DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE (
    table_name           IN VARCHAR2,
    credential_name      IN VARCHAR2,
    file_uri_list        IN VARCHAR2,
    column_list          IN CLOB,
    field_list           IN CLOB DEFAULT,
    format               IN CLOB DEFAULT);

参数

Parameter (参数)	说明
table_name	外部表的名称。
credential_name	用于访问云对象存储的身份证明的名称。
partitioning_clause	指定完整的分区子句，包括各个分区的位置信息。 如果使用 partitioning_clause 参数，则不允许使用 file_uri_list 参数。
file_uri_list	此参数指定源文件 URI 的逗号分隔列表，或者指定一个或多个目录和源文件。 云源文件 URI 您可以在云源文件 URI 中的文件名中使用通配符和正则表达式。 正则表达式只能在 regexuri format 参数设置为 TRUE 时使用。 当 regexuri 参数设置为 FALSE 时，字符 "*" 和 "?" 被视为通配符。当 regexuri 参数设置为 TRUE 时，字符 "*" 和 "?" 是指定正则表达式模式的一部分。 仅 URI 中的文件名或子文件夹路径支持正则表达式模式，模式匹配与 REGEXP_LIKE 函数执行的模式匹配相同。 仅对象存储中的某个文件上创建的外部表支持此选项。 例如： file_uri_list => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o(/)*year=[0-9]+(/)*month=[0-9]+(/)*[a-z]+[1-3]??.csv' 如果使用参数 file_uri_list，则不允许使用 partitioning_clause 参数。 URI 的格式取决于云对象存储服务。有关详细信息，请参阅云对象存储 URI 格式。 有关 REGEXP_LIKE 条件的更多信息，请参见 Oracle Database 19c SQL Language Reference 中的 REGEXP_LIKE Condition 或 Oracle Database 26ai SQL Language Reference 。
column_list	外部表的列名和数据类型的逗号分隔列表。此参数具有以下要求，具体取决于使用 file_uri_list 参数指定的数据文件的类型： 非结构化文件需要 column_list 参数。使用非结构化文件（例如 CSV 文本文件）时，column_list 参数必须指定数据文件内的所有列名和数据类型以及从对象名称派生的分区列。 column_list 参数对于结构化文件是可选的。例如，对于 Avro、ORC 或 Parquet 数据文件，column_list 不是必需的。如果未包括 column_list，则 format 参数 partition_columns 选项必须包括列名 (name) 和数据类型 (type) 的规范。
field_list	标识源文件中的字段及其数据类型。默认值为 NULL，表示字段及其数据类型由 column_list 参数确定。此参数的语法与常规 Oracle 外部表中的 field_list 子句相同。有关详细信息，请参阅 Oracle Database 19c Utilities 或 Oracle Database 26ai Utilities 中的 field_list 。
format	当分区列从文件路径派生时，格式选项 partition_columns 指定 DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE 列名和分区列的数据类型，具体取决于数据文件的类型（结构化或非结构化）： 当 DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE 包含 column_list 参数且数据文件为非结构化文件（例如 CSV 文本文件）时，partition_columns 不包括数据类型。例如，对于此类型的 partition_columns 规范，请使用如下格式： '"partition_columns":["state","zipcode"]' 数据类型不是必需的，因为它是在 DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE column_list 参数中指定的。 如果 DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE 不包含 column_list 参数并且数据文件是结构化的（如 Avro、ORC 或 Parquet 文件），则 partition_columns 选项同时包括列名、name 子子句和数据类型 type 子子句。例如，以下内容显示了 partition_columns 规范： '"partition_columns":[ {"name":"country", "type":"varchar2(10)"}, {"name":"year", "type":"number"}, {"name":"month", "type":"varchar2(10)"}]' 如果数据文件是非结构化的，并且 type 子子句与 partition_columns 一起指定，则忽略 type 子子句。 对于不基于 Hive 格式的对象名称，partition_columns 指定的列的顺序必须与 file_uri_list 参数中指定的文件路径中对象名称中出现的顺序相匹配。 要查看所有描述源文件格式的 format 参数选项，请参见 Cloud Object Storage URI Formats 。

使用说明

• 不能同时使用 partitioning_clause 和 file_uri_list 参数调用此过程。

• 对于结构化数据文件（包括 Avro、Parquet 或 ORC 数据文件），指定 column_list 参数是可选的。如果未指定 column_list，则 format 参数 partition_columns 选项必须包括 name 和 type。

• 非结构化数据文件（例如 CSV 文本文件）需要 column_list 参数。

• 过程 DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE 支持受支持的云对象存储服务中的外部分区文件，包括：
  • Oracle Cloud Infrastructure Object Storage
  • Azure Blob 存储

  有关详细信息，请参阅云对象存储 URI 格式。

• 过程 DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE 支持目录（本地文件系统或网络文件系统）中的外部分区文件。

• 使用 file_uri_list 参数调用 DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE 时，在云对象存储文件名中指定的列的类型必须是以下类型之一：

  VARCHAR2(n)
  NUMBER(n)
  NUMBER(p,s)
  NUMBER
  DATE
  TIMESTAMP(9)
  

• 默认记录分隔符为 detected newline。使用 detected newline 时，DBMS_CLOUD 会尝试自动查找要用作记录分隔符的正确换行符。DBMS_CLOUD 首先搜索 Windows 的换行符 \r\n。如果找到 Windows 换行符，则此字符将用作该过程中所有文件的记录分隔符。如果未找到 Windows 新行字符，DBMS_CLOUD 将搜索 UNIX/Linux 新行字符 \n，如果找到新行字符，则使用 \n 作为该过程中所有文件的记录分隔符。如果源文件使用不同记录分隔符的组合，则可能会遇到错误，例如 "KUP-04020: found record longer than buffer size supported"。在这种情况下，您需要修改源文件以使用相同的记录分隔符，或仅指定使用相同记录分隔符的源文件。

  有关 recorddelmiter 格式选项的信息，请参见 Cloud Object Storage URI Formats 。

• 使用 DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE 创建的外部分区表包括两个不可见的列 file$path 和 file$name。这些列有助于确定记录来自哪个文件。

  • file$path：指定文件路径文本，直到对象名称的开头。

  • file$name：指定对象名称，包括存储桶名称之后的所有文本。

示例

示例：使用 partitioning_clause 参数。

BEGIN
   DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE(
      table_name =>'PET1',
      credential_name =>'OBJ_STORE_CRED',
      format => json_object('delimiter' value ',', 'recorddelimiter' value 'newline', 'characterset' value 'us7ascii'),
      column_list => 'col1 number, col2 number, col3 number',
      partitioning_clause => 'partition by range (col1)
                                (partition p1 values less than (1000) location
                                    ( ''&base_URL//file_11.txt'')
                                 ,
                                 partition p2 values less than (2000) location
                                    ( ''&base_URL/file_21.txt'')
                                 ,
                                 partition p3 values less than (3000) location
                                    ( ''&base_URL/file_31.txt'')
                                 )'
     );
   END;
/


BEGIN
    DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE(
       table_name          => 'PET',
       format              => json_object('delimiter'value ','),
       column_list         => 'name varchar2(20), gender varchar2(10), salary number',
       partitioning_clause => 'partition by range (salary)
              (   -- Use test1.csv in the DEFAULT DIRECTORY DATA_PUMP_DIR
                  partition p1 values less than (100) LOCATION (''test1.csv''),
                   -- Use test2.csv in a specified directory MY_DIR
                  partition p2 values less than (300) DEFAULT DIRECTORY MY_DIR LOCATION (''test2.csv'')        )'   );
END;
/

示例：将 file_uri_list 和 column_list 参数与非结构化数据文件结合使用。

BEGIN
  DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE(
   table_name => 'MYSALES',
   credential_name => 'DEF_CRED_NAME',
   file_uri_list     => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/*.csv',
   column_list       => 'product varchar2(100), units number, country varchar2(100), year number, month varchar2(2)',
   field_list        => 'product, units', --[Because country, year and month are not in the file, they are not listed in the field list]
   format            => '{"type":"csv", "partition_columns":["country","year","month"]}');
END;
/

示例：将不带 column_list 参数的 file_uri_list 与结构化数据文件结合使用。

BEGIN
  DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE(
  table_name => 'MYSALES',
  credential_name => 'DEF_CRED_NAME',
  DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE(
    table_name      => 'MYSALES',
    credential_name => 'DEF_CRED_NAME',
    file_uri_list   => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/*.parquet',
    format          =>
        json_object('type' value 'parquet', 'schema' value 'first',
                    'partition_columns' value
                          json_array(
                                json_object('name' value 'country', 'type' value 'varchar2(100)'),
                                json_object('name' value 'year', 'type' value 'number'),
                                json_object('name' value 'month', 'type' value 'varchar2(2)')
                          )
         )
    );
END;
/

示例：使用存储在 C3 对象存储桶中的对象创建外部分区表。

BEGIN
  DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE(
     table_name => 'USAGE_EXTP',
     credential_name => 'OBJECT_STORAGE_CREDENTIAL',
     file_uri_list => 'https://objectstorage.mydomain.com/n/mytenancy/b/mybucket/o/usage-data/*usage-data*.parquet',
     format => json_object(
          'type' value 'parquet', 'schema' value 'first',
          'partition_columns' value json_array(
                json_object('name' value 'year', 'type' value 'number'),         
                json_object('name' value 'month', 'type' value 'number'),
                json_object('name' value 'day', 'type' value 'number')
          )
     )
   );
END;
/

CREATE_EXTERNAL_TABLE 过程

此过程会在云中的文件或目录中的文件上创建外部表。这允许您对自治 AI 数据库中的外部数据运行查询。

语法

DBMS_CLOUD.CREATE_EXTERNAL_TABLE (
    table_name       IN VARCHAR2,
    credential_name  IN VARCHAR2,
    file_uri_list    IN CLOB,
    column_list      IN CLOB,
    field_list       IN CLOB DEFAULT,
    format           IN CLOB DEFAULT);

参数

Parameter (参数)	说明
table_name	外部表的名称。
credential_name	用于访问云对象存储的身份证明的名称。 使用 file_uri_list 指定目录或表超链接 URL 时，不使用此参数。
file_uri_list	此参数指定源文件 URI 的逗号分隔列表，或者指定一个或多个目录和源文件。 云源文件 URI 您可以在云源文件 URI 中的文件名中使用通配符和正则表达式。 正则表达式只能在 regexuri format 参数设置为 TRUE 时使用。 当 regexuri 参数设置为 FALSE 时，字符 "*" 和 "?" 被视为通配符。当 regexuri 参数设置为 TRUE 时，字符 "*" 和 "?" 是指定正则表达式模式的一部分。 仅 URI 中的文件名或子文件夹路径支持正则表达式模式，模式匹配与 REGEXP_LIKE 函数执行的模式匹配相同。 仅对象存储中的某个文件上创建的外部表支持此选项。 例如： file_uri_list => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o(/)*year=[0-9]+(/)*month=[0-9]+(/)*[a-z]+[1-3]??.csv' URI 的格式取决于您使用的云对象存储服务，有关详细信息，请参见 Cloud Object Storage URI Formats 。 有关 REGEXP_LIKE 条件的更多信息，请参见 Oracle Database 19c SQL Language Reference 中的 REGEXP_LIKE Condition 或 Oracle Database 26ai SQL Language Reference 。 目录 可以指定一个目录和一个或多个文件名，也可以使用逗号分隔的目录和文件名列表。指定目录的格式为：'MY_DIR:filename.ext'。默认情况下，目录名称 MY_DIR 是数据库对象，不区分大小写。文件名区分大小写。 可以使用通配符指定目录中的文件名。字符 "*" 可以用作表示多个字符的通配符，字符 "?" 可以用作表示单个字符的通配符。例如：'MY_DIR:*" 或 'MY_DIR:test?' 要指定多个目录，请使用逗号分隔的目录列表：例如：'MY_DIR1:*, MY_DIR2:test?' 使用双引号指定区分大小写的目录名称。例如：'"my_dir1":*, "my_dir2":Test?' 要包含引号字符，请使用两个引号。例如：'MY_DIR:''filename.ext'。这指定 filename 以引号 (') 开头。
column_list	外部表的列名和数据类型的逗号分隔列表。
field_list	标识源文件中的字段及其数据类型。默认值为 NULL，表示字段及其数据类型由 column_list 参数确定。此参数的语法与常规 Oracle Database 外部表中的 field_list 子句相同。有关 field_list 的更多信息，请参见 Oracle Database 19c Utilities 或 Oracle Database 26ai Utilities 中的 field_definitions 子句下的 ORACLE_LOADER Access Driver field_list 。
format	描述源文件格式的选项。有关选项列表以及如何指定值，请参阅格式参数。 有关 Avro、ORC 或 Parquet 格式文件，请参见 CREATE_EXTERNAL_TABLE Procedure for Avro，ORC，or Parquet Files 。

使用说明

• 过程 DBMS_CLOUD.CREATE_EXTERNAL_TABLE 支持受支持的云对象存储服务（包括 Azure Blob 存储）中的外部分区文件。

  身份证明是表级属性；因此，外部文件必须位于同一对象存储中。

  有关详细信息，请参阅云对象存储 URI 格式。

• 默认记录分隔符为 detected newline。使用 detected newline 时，DBMS_CLOUD 会尝试自动查找要用作记录分隔符的正确换行符。DBMS_CLOUD 首先搜索 Windows 的换行符 \r\n。如果找到 Windows 换行符，则此字符将用作该过程中所有文件的记录分隔符。如果未找到 Windows 新行字符，DBMS_CLOUD 将搜索 UNIX/Linux 新行字符 \n，如果找到新行字符，则使用 \n 作为该过程中所有文件的记录分隔符。如果源文件使用不同记录分隔符的组合，则可能会遇到错误，例如 "KUP-04020: found record longer than buffer size supported"。在这种情况下，您需要修改源文件以使用相同的记录分隔符，或仅指定使用相同记录分隔符的源文件。

  有关 recorddelimiter 格式选项的信息，请参阅格式参数。

示例

示例：基于对象存储中的 CSV 文件创建外部表。

BEGIN
   DBMS_CLOUD.CREATE_EXTERNAL_TABLE(
      table_name =>'WEATHER_REPORT_DOUBLE_DATE',
      credential_name =>'OBJ_STORE_CRED',
      file_uri_list =>'&base_URL/Charlotte_NC_Weather_History_Double_Dates.csv',
      format => json_object('type' value 'csv', 'skipheaders' value '1'),
      field_list => 'REPORT_DATE DATE''mm/dd/yy'',
                     REPORT_DATE_COPY DATE ''yyyy-mm-dd'',
                     ACTUAL_MEAN_TEMP,
                     ACTUAL_MIN_TEMP,
                     ACTUAL_MAX_TEMP,
                     AVERAGE_MIN_TEMP,
                     AVERAGE_MAX_TEMP,
                     AVERAGE_PRECIPITATION',
      column_list => 'REPORT_DATE DATE,
                     REPORT_DATE_COPY DATE,
                     ACTUAL_MEAN_TEMP NUMBER,
                     ACTUAL_MIN_TEMP NUMBER,
                     ACTUAL_MAX_TEMP NUMBER,
                     AVERAGE_MIN_TEMP NUMBER,
                     AVERAGE_MAX_TEMP NUMBER,
                     AVERAGE_PRECIPITATION NUMBER');
   END;
/

SELECT * FROM WEATHER_REPORT_DOUBLE_DATE where
   actual_mean_temp > 69 and actual_mean_temp < 74

示例：使用存储在 C3 对象存储桶中的对象创建外部表。

BEGIN
  DBMS_CLOUD.CREATE_EXTERNAL_TABLE(
     table_name =>'CHANNELS_EXT',
     credential_name =>'OBJECT_STORAGE_CREDENTIAL',
     file_uri_list => '<https://objectstorage.mydomain.com/n/mytenancy/b/mybucket/o/channels.txt>',
     format => json_object('delimiter' value ','),
     column_list => 'CHANNEL_ID NUMBER, CHANNEL_DESC VARCHAR2(20), CHANNEL_CLASS VARCHAR2(20)'
  );
END;
/

适用于 Apache Iceberg 的 CREATE_EXTERNAL_TABLE 过程

此过程在支持的配置中为 Apache Iceberg 表创建外部表。

支持以下特定配置：

• AWS 上的 Iceberg 表：

  • 在 AWS Glue Data Catalog 中注册的 Iceberg 表，使用 Spark 或 Athena 创建。

    有关详细信息，请参阅使用 AWS Glue 连接器读取和写入包含 ACID 事务处理的 Apache Iceberg 表并执行时间旅行和使用 Iceberg 表。

  • 通过直接提供根元数据文件的 URL 存储在 AWS S3 上的 Iceberg 表。

• OCI 上的 Iceberg 表：

  • 使用 Hadoop 目录使用 OCI 数据流生成的 Iceberg 表。

    有关详细信息，请参阅 Oracle 数据流示例和使用 Hadoop 目录。

  • 通过直接提供根元数据文件的 URL 存储在 OCI 对象存储上的 Iceberg 表。

语法

DBMS_CLOUD.CREATE_EXTERNAL_TABLE (
    table_name       IN VARCHAR2,
    credential_name  IN VARCHAR2 DEFAULT NULL,
    file_uri_list    IN CLOB,
    column_list      IN CLOB DEFAULT NULL,
    field_list       IN CLOB DEFAULT NULL,
    format           IN CLOB DEFAULT NULL
);

参数

Parameter (参数)	说明
table_name	外部表的名称。
credential_name	用于访问数据文件、元数据文件和 Iceberg 目录（如果使用）的身份证明的名称。 对于 AWS 和 OCI 配置，应按 CREATE_CREDENTIAL Procedure 中所述创建凭证。 AWS Amazon 资源名称 (ARN) 身份证明当前不受支持。
file_uri_list	如果指定了 Iceberg 目录，则必须为 NULL（请参见下面的 format 参数）。如果未使用冰山目录，则 file_uri_list 必须包含冰山元数据文件的 URI。
column_list	必须为 NULL，因为列名和类型自动从 Iceberg 元数据派生。 列名与底层数据文件（Parquet、Avro、ORC）中的名称匹配。Oracle 数据类型使用 Iceberg 与 Parquet、Avro 和 ORC 数据类型之间的 Parquet/Avro/ORC 映射推导得出。因此，用户无法指定 column_list。
field_list	必须为 NULL，因为列名和数据类型会自动从 Iceberg 元数据派生。
format	format 参数具有不同的结构，具体取决于 Iceberg 表的类型以及用于创建外部表的信息，例如来自数据目录或直接元数据 URI 的信息。 有关详细信息，请参阅 Iceberg Support on OCI Data Flow Samples 和 DBMS_CLOUD URI Formats 。

格式参数示例

• 在 AWS Iceberg table using an AWS Glue Catalog 上创建表时，如下所示：

  format => json_object('access_protocol' value
         json_object('protocol_type' value 'iceberg',
                     'protocol_config' value
                      json_object('iceberg_catalog_type' value   'aws_glue',
                                  'iceberg_glue_region'  value   'glue region',
                                  'iceberg_table_path'   value   'database_name.table_name')));
  

  其中，access_protocol 参数包含具有两个元素的 JSON 对象，如下所示：

  • protocol_type：必须是 'iceberg'
  • protocol_config：用于指定冰山目录详细信息的嵌套 JSON 对象。
    • iceberg_catalog_type：必须为 'aws_glue'
    • iceberg_glue_region：目录区域，例如 'us-west-1'
    • iceberg_table_path：glue database.glue table name 路径。

• 在 AWS Iceberg table using a metadata file URI 上创建表时，如下所示：

  format => json_object('access_protocol' value
         json_object('protocol_type' value 'iceberg')
  

• 在 OCI Data Flow 使用 HadoopCatalog 目录创建的 OCI Iceberg 表上创建表时，如下所示：

  format => json_object('access_protocol' value
         json_object('protocol_type'   value 'iceberg',
                     'protocol_config' value
                     json_object('iceberg_catalog_type'  value   'hadoop',
                                 'iceberg_warehouse'     value   '<OCI folder URI>',
                                 'iceberg_table_path'    value   'database_name.table_name')));
  

  其中，access_protocol 参数包含具有两个元素的 JSON 对象，如下所示：

  • protocol_type：必须为 'iceberg'
  • protocol_config：用于指定冰山目录详细信息的嵌套 JSON 对象。
    • iceberg_catalog_type：必须为 'hadoop'
    • iceberg_warehouse：以本机 URI 格式生成表时使用的仓库目录路径。
    • iceberg_table_path：创建表时使用的 database_name.table name 路径。

• 通过 OCI Iceberg table using the URI of the metadata file 创建表时，如下所示：

  format => json_object('access_protocol' value
         json_object('protocol_type' value 'iceberg')
  

  其中，access_protocol 参数包含具有一个元素的 JSON 对象，protocol_type 必须为 'iceberg'。

Avro、ORC 或 Parquet 文件的 CREATE_EXTERNAL_TABLE 过程

此过程将 format 参数 type 设置为值 avro、orc 或 parquet，将在云中或目录中创建包含 Avro、ORC 或 Parquet 格式文件的外部表。

这允许您对来自自治 AI 数据库的外部数据运行查询。

语法

DBMS_CLOUD.CREATE_EXTERNAL_TABLE (
    table_name       IN VARCHAR2,
    credential_name  IN VARCHAR2 DEFAULT NULL,
    file_uri_list    IN CLOB,
    column_list      IN CLOB,
    field_list       IN CLOB DEFAULT,
    format           IN CLOB DEFAULT);

参数

Parameter (参数)	说明
table_name	外部表的名称。
credential_name	用于访问云对象存储的身份证明的名称。 使用 file_uri_list 指定目录时不使用此参数。
file_uri_list	此参数指定源文件 URI 的逗号分隔列表，或者指定一个或多个目录和源文件。 云源文件 URI 您可以在云源文件 URI 中的文件名中使用通配符和正则表达式。 正则表达式只能在 regexuri format 参数设置为 TRUE 时使用。 当 regexuri 参数设置为 FALSE 时，字符 "*" 和 "?" 被视为通配符。当 regexuri 参数设置为 TRUE 时，字符 "*" 和 "?" 是指定正则表达式模式的一部分。 仅 URI 中的文件名或子文件夹路径支持正则表达式模式，模式匹配与 REGEXP_LIKE 函数执行的模式匹配相同。 仅对象存储中的某个文件上创建的外部表支持此选项。 例如： file_uri_list => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o(/)*year=[0-9]+(/)*month=[0-9]+(/)*[a-z]+[1-3]??.parquet' URI 的格式取决于您使用的云对象存储服务，有关详细信息，请参见 Cloud Object Storage URI Formats 。 有关 REGEXP_LIKE 条件的更多信息，请参见 Oracle Database 19c SQL Language Reference 中的 REGEXP_LIKE Condition 或 Oracle Database 26ai SQL Language Reference 。 目录 可以指定一个目录和一个或多个文件名，也可以使用逗号分隔的目录和文件名列表。指定目录的格式为：'MY_DIR:filename.ext'。默认情况下，目录名称 MY_DIR 是数据库对象，不区分大小写。文件名区分大小写。 可以使用通配符指定目录中的文件名。字符 "*" 可以用作表示多个字符的通配符，字符 "?" 可以用作表示单个字符的通配符。例如：'MY_DIR:*" 或 'MY_DIR:test?' 要指定多个目录，请使用逗号分隔的目录列表：例如：'MY_DIR1:*, MY_DIR2:test?' 使用双引号指定区分大小写的目录名称。例如：'"my_dir1":*, "my_dir2":Test?' 要包含引号字符，请使用两个引号。例如：'MY_DIR:''filename.ext'。这指定 filename 以引号 (') 开头。
column_list	（可选）该字段在指定时将覆盖 format->schema 参数，该参数指定自动派生方案、列和数据类型。有关详细信息，请参见 format 参数。 为 Avro、ORC 或 Parquet 源指定了 column_list 时，列名必须与文件中找到的列匹配。Oracle 数据类型必须适当地映射到 Avro、ORC 或 Parquet 数据类型。 有关 Parquet 文件的详细信息，请参见 DBMS_CLOUD Package Parquet to Oracle Data Type Mapping 。 有关 ORC 文件的详细信息，请参见 DBMS_CLOUD Package ORC to Oracle Data Type Mapping 。 有关 Avro 文件的详细信息，请参见 DBMS_CLOUD Package Avro to Oracle Data Type Mapping 。
field_list	已忽略 Avro、ORC 或 Parquet 文件。 源中的字段按名称匹配外部表列。源数据类型将转换为外部表列数据类型。 有关 ORC 文件，请参阅 DBMS_CLOUD Package ORC to Oracle Data Type Mapping 有关 Parquet 文件的详细信息，请参见 DBMS_CLOUD Package Parquet to Oracle Data Type Mapping 。 有关 Avro 文件的详细信息，请参见 DBMS_CLOUD Package Avro to Oracle Data Type Mapping 。
format	有关 Avro、ORC 或 Parquet type 源文件，请参见 DBMS_CLOUD Package Format Options for Avro、ORC 或 Parquet 。

示例

• ORC

  format => '{"type":"orc", "schema": "all"}'
  

  format => json_object('type' value 'orc', 'schema' value 'first')
  

• Avro

  format => '{"type":"avro", "schema": "all"}'
  

  format => json_object('type' value 'avro', 'schema' value 'first')
  

• Parquet

  format => '{"type":"parquet", "schema": "all"}'
  

  format => json_object('type' value 'parquet', 'schema' value 'first')
  

提示：有关 Oracle SQL 中的列名映射和列名转换用法的信息，请参阅 DBMS_CLOUD Package Avro，ORC，and Parquet to Oracle Column Name Mapping 。

CREATE_EXTERNAL_TEXT_INDEX 过程

此过程将在对象存储文件上创建文本索引。

CREATE_EXTERNAL_TEXT_INDEX 过程在 location_uri 位置指定的对象存储文件上创建文本索引。对于对位置 URI 上的文件执行的任何新添加或删除，将定期刷新索引。

语法

DBMS_CLOUD.CREATE_EXTERNAL_TEXT_INDEX (
      credential_name  IN  VARCHAR2 DEFAULT NULL,
      location_uri     IN  VARCHAR2,
      index_name       IN  VARCHAR2,
      format           IN  CLOB     DEFAULT NULL
);

参数

Parameter (参数)	说明
credential_name	用于访问云对象存储位置的身份证明的名称。对于公共存储桶 URI、预先验证的存储桶 URI 或预先签名存储桶 URI，可以指定 NULL。 如果不提供 credential_name 值，则 credential_name 将设置为 NULL 值。
location_uri	此参数指定源文件 URI 的逗号分隔列表。 您可以在云源文件 URI 中的文件名中使用通配符和正则表达式。 此参数是必需的。 云源文件 URI 此参数指定源文件 URI 的逗号分隔列表，或者指定一个或多个目录和源文件。 正则表达式只能在 regexuri format 参数设置为 TRUE 时使用。 当 regexuri 参数设置为 FALSE 时，字符 "*" 和 "?" 被视为通配符。当 regexuri 参数设置为 TRUE 时，字符 "*" 和 "?" 是指定正则表达式模式的一部分。 仅 URI 中的文件名或子文件夹路径支持正则表达式模式，模式匹配与 REGEXP_LIKE 函数执行的模式匹配相同。 使用正则表达式示例： location_uri => 'https://objectstorage.my$region.oraclecloud.com/n/namespace-string/b/bucketname/o(/)*year=[0-9]+(/)*month=[0-9]+(/)*[a-z]+[1-3]??.csv' 使用通配符的示例： location_uri => 'https://objectstorage.my$region.oraclecloud.com/n/namespace-string/b/bucketname/o/year=????/month=??/*.csv URI 的格式取决于您使用的云对象存储服务，有关详细信息，请参见 Cloud Object Storage URI Formats 。 有关 REGEXP_LIKE 条件的更多信息，请参见 REGEXP_LIKE Condition 。
index_name	指定要在位于 `location_uri` 位置的文件上构建的索引的名称。 此参数是必需的。
format	指定其他配置选项。选项指定为 JSON 字符串。 支持的格式选项包括： refresh_rate：以分钟为单位指定刷新本地索引的频率。新文件上载和删除将导致索引刷新。默认值为 5 分钟。 binary_files：指定要索引的文件的内容是否为二进制文件。例如，PDF、MS-Word 和默认值为 FALSE。 stop_words：指定在创建索引时可以提供的停止词列表。 stop_words 值指示它是停止词列表还是停止词表。当向 JSON 数组提供 stop words 参数时，它将被视为列表，否则 stop words 参数将被视为表名，其列 "STOP_WORDS" 用于读取 stop words 列表。 您可以使用以下方法指定停止词： JSON 数组：例如：format := '{"stop_words":["king","queen"]}' 停止字表名称：例如：format := '{"stop_words":"STOP_WORDS_TABLE"}' 如果不提供 format 参数，则 format 将设置为 NULL 值。

范例

BEGIN
DBMS_CLOUD.CREATE_EXTERNAL_TEXT_INDEX (
        credential_name => 'DEFAULT_CREDENTIAL',
        location_uri    => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/ts_data/'
        index_name      => 'EMP',
        format          => JSON_OBJECT ('refresh_rate' value 10)
);
END;
/

CREATE_HYBRID_PART_TABLE 过程

此过程将创建混合分区表。这样，您可以使用云中的数据库对象和文件或目录中的数据库对象和文件，对来自自治 AI 数据库的混合分区数据运行查询。

语法

DBMS_CLOUD.CREATE_HYBRID_PART_TABLE (
    table_name           IN VARCHAR2,
    credential_name      IN VARCHAR2,
    partitioning_clause  IN CLOB,
    column_list          IN CLOB,
    field_list           IN CLOB DEFAULT,
    format               IN CLOB DEFAULT);

参数

Parameter (参数)	说明
table_name	外部表的名称。
credential_name	用于访问云对象存储的身份证明的名称。
partitioning_clause	指定完整的分区子句，包括各个分区的位置信息。 要使用目录，分区子句支持 LOCATION 和 DEFAULT DIRECTORY 值。 您可以在云源文件 URI 中的文件名中使用通配符和正则表达式。 正则表达式只能在 regexuri format 参数设置为 TRUE 时使用。 当 regexuri 参数设置为 FALSE 时，字符 "*" 和 "?" 被视为通配符。当 regexuri 参数设置为 TRUE 时，字符 "*" 和 "?" 是指定正则表达式模式的一部分。 仅 URI 中的文件名或子文件夹路径支持正则表达式模式，模式匹配与 REGEXP_LIKE 函数执行的模式匹配相同。目录名称不支持正则表达式模式。 例如： partitioning_clause => 'partition by range (col1) (partition p1 values less than (1000) external location ( ''https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o(/)*year=[0-9]+(/)*month=[0-9]+(/)*[a-z]+[1-3]??.txt''),... 有关 REGEXP_LIKE 条件的更多信息，请参见 Oracle Database 19c SQL Language Reference 中的 REGEXP_LIKE Condition 或 Oracle Database 26ai SQL Language Reference 。
column_list	外部表的列名和数据类型的逗号分隔列表。
field_list	标识源文件中的字段及其数据类型。默认值为 NULL，表示字段及其数据类型由 column_list 参数确定。此参数的语法与常规 Oracle 外部表中的 field_list 子句相同。有关详细信息，请参阅 Oracle Database 19c Utilities 或 Oracle Database 26ai Utilities 中的 field_list 。
format	描述源文件格式的选项。有关选项列表以及如何指定值，请参阅格式参数。

使用说明

• 过程 DBMS_CLOUD.CREATE_HYBRID_PART_TABLE 支持受支持的云对象存储服务（包括 Azure Blob 存储）中的外部分区文件。

  身份证明是表级属性；因此，外部文件必须位于同一对象存储中。

  有关详细信息，请参阅云对象存储 URI 格式。

• 过程 DBMS_CLOUD.CREATE_HYBRID_PART_TABLE 支持目录（本地文件系统或网络文件系统）中的混合分区文件。

• 使用 DBMS_CLOUD.CREATE_HYBRID_PART_TABLE 创建的外部分区表包括两个不可见的列 file$path 和 file$name。这些列有助于确定记录来自哪个文件。

  • file$path：指定文件路径文本，直到对象名称的开头。

  • file$name：指定对象名称，包括存储桶名称后面的所有文本。

示例

BEGIN
   DBMS_CLOUD.CREATE_HYBRID_PART_TABLE(
      table_name =>'HPT1',
      credential_name =>'OBJ_STORE_CRED',
      format => json_object('delimiter' value ',', 'recorddelimiter' value 'newline', 'characterset' value 'us7ascii'),
      column_list => 'col1 number, col2 number, col3 number',
      partitioning_clause => 'partition by range (col1)
                                (partition p1 values less than (1000) external location
                                    ( ''&base_URL/file_11.txt'')
                                 ,
                                 partition p2 values less than (2000) external location
                                    ( ''&base_URL/file_21.txt'')
                                 ,
                                 partition p3 values less than (3000)
                                 )'
     );
   END;
/

BEGIN
   DBMS_CLOUD.CREATE_HYBRID_PART_TABLE(
    table_name  => 'HPT1',
    format      => json_object('delimiter'value ',', 'recorddelimiter'value 'newline'),
    column_list => 'NAME VARCHAR2(30), GENDER VARCHAR2(10), BALANCE number',
    partitioning_clause => 'partition by range (B  2  ALANCE)
               (partition p1 values less than (1000) external DEFAULT DIRECTORY DATA_PUMP_DIR LOCATION (''Scott_male_1000.csv''),
                partition p2 values less than (2000) external DEFAULT DIRECTORY DATA_PUMP_DIR LOCATION (''Mary_female_3000.csv''),
                partition p3 values less than (3000))' );
END;
/

DELETE_ALL_OPERATIONS 过程

此过程将清除在方案中的 user_load_operations 表中记录的所有数据加载操作，或清除指定类型的所有数据加载操作（如 type 参数所示）。

语法

DBMS_CLOUD.DELETE_ALL_OPERATIONS (
	type      IN VARCHAR DEFAULT NULL);

参数

Parameter (参数)	说明
type	指定要删除的操作类型。可以在 user_load_operations 表的 TYPE 列中找到类型值。 如果未指定 type，将删除所有行。

用法附注

DBMS_CLOUD.DELETE_ALL_OPERATIONS 不会删除当前正在运行的操作（处于“正在运行”状态的操作）。

DELETE_FILE 过程

此过程将指定文件从自治 AI 数据库上的指定目录中删除。

语法

DBMS_CLOUD.DELETE_FILE (
      directory_name     IN VARCHAR2,
      file_name          IN VARCHAR2,
      force              IN BOOLEAN DEFAULT FALSE);

参数

Parameter (参数)	说明
directory_name	自治 AI 数据库实例上目录的名称。
file_name	要删除的文件的名称。
force	如果文件不存在，则忽略并且不报告错误。有效值包括：TRUE 和 FALSE。默认值为 FALSE。

注：要与 ADMIN 以外的用户一起运行 DBMS_CLOUD.DELETE_FILE，您需要向该用户授予对包含该文件的目录的写入权限。例如，以 ADMIN 身份运行以下命令以向 atpc_user 授予写入权限：

GRANT WRITE ON DIRECTORY data_pump_dir TO atpc_user;

范例

BEGIN
   DBMS_CLOUD.DELETE_FILE(
      directory_name =>  'DATA_PUMP_DIR',
      file_name => 'exp1.dmp' );
   END;
/

DELETE_OBJECT 过程

此过程将删除对象存储上的指定对象。

语法

DBMS_CLOUD.DELETE_OBJECT (
       credential_name      IN VARCHAR2,
       object_uri           IN VARCHAR2,
       force                IN BOOLEAN DEFAULT FALSE);

参数

Parameter (参数)	说明
credential_name	用于访问云对象存储的身份证明的名称。
object_uri	要删除的对象或文件 URI。URI 的格式取决于您使用的云对象存储服务，有关详细信息，请参见 Cloud Object Storage URI Formats 。
force	如果对象不存在，则忽略并且不报告错误。有效值包括：TRUE 和 FALSE。默认值为 FALSE。

范例

BEGIN
   DBMS_CLOUD.DELETE_OBJECT(
       credential_name => 'DEF_CRED_NAME',
       object_uri => 'https://objectstorage.us-ashburn-1.oraclecloud.com/n/namespace-string/b/bucketname/o/exp1.dmp' );
   END;
/

DELETE_OPERATION 过程

此过程将清除在方案中的 user_load_operations 或 dba_load_operations 表中记录的指定操作 ID 的数据加载条目。

语法

DBMS_CLOUD.DELETE_OPERATION (
	id      IN NUMBER);

参数

Parameter (参数)	说明
id	指定与要删除的日志文件条目关联的操作 ID。

范例

SELECT id FROM user_load_operations WHERE type LIKE '%BAD%';
EXEC DBMS_CLOUD.DELETE_OPERATION(id);

DROP_EXTERNAL_TEXT_INDEX 过程

此过程将删除对象存储文件上的文本索引。

DROP_EXTERNAL_TEXT_INDEX 过程将删除使用 CREATE_EXTERNAL_TEXT_INDEX 过程创建的指定索引。

语法

DBMS_CLOUD.DROP_EXTERNAL_TEXT_INDEX (
      index_name       IN  VARCHAR2,
);

参数

Parameter (参数)	说明
index_name	指定要删除的索引的名称。 索引名称必须与创建索引时提供的名称匹配。 此参数是必需的。

范例

BEGIN
DBMS_CLOUD.DROP_EXTERNAL_TEXT_INDEX (
        index_name => 'EMP',
);
END;
/

EXPORT_DATA 过程

此过程根据查询结果从自治 AI 数据库导出数据。此过程已重载，支持将文件写入云或目录。

根据 format type 参数，该过程将文件以 CSV、JSON、Parquet 或 XML 格式的文本文件导出到云或目录位置。

语法

DBMS_CLOUD.EXPORT_DATA (
      credential_name   IN VARCHAR2 DEFAULT NULL,
      file_uri_list     IN CLOB,
      format            IN CLOB,
      query             IN CLOB);

DBMS_CLOUD.EXPORT_DATA (
      credential_name   IN VARCHAR2 DEFAULT NULL,
      file_uri_list     IN CLOB DEFAULT NULL,
      format            IN CLOB DEFAULT NULL,
      query             IN CLOB DEFAULT NULL,
      operation_id      OUT NOCOPY NUMBER);

参数

Parameter (参数)	说明
credential_name	用于访问云对象存储的身份证明的名称。 不包括凭证参数时，这将指定目录的输出。
file_uri_list	存在不同的表单，具体取决于格式参数的值以及是否包括身份证明参数： 当 format 参数 type 值为 json 时：将基于 file_uri_list 参数的值使用生成的文件名保存对象存储上的 JSON 或指定目录位置。有关详细信息，请参阅文本输出文件命名（CSV、JSON、Parquet 或 XML）。 当 format 参数 type 值为 datapump 时，file_uri_list 是转储文件的逗号分隔列表。这指定要在对象存储上创建的文件。file_uri_list 不支持使用通配符和替代字符。 如果未指定 credential_name 参数，则在 file_uri_list 中提供目录名称。 URI 的格式取决于您使用的云对象存储服务，有关详细信息，请参见 Cloud Object Storage URI Formats 。
format	提供导出格式选项的 JSON 字符串。 支持的选项为： type：type format 选项是必需的，必须具有以下值之一：csv | datapump | json | parquet | xml。 请参见 DBMS_CLOUD Package Format Options for EXPORT_DATA 。
query	使用此参数可以指定 SELECT 语句，以便仅导出所需的数据。该查询确定导出为文本文件 CSV、JSON、Parquet 或 XML 或转储文件的文件的内容。例如： SELECT warehouse_id, quantity FROM inventories 当 format type 值为 json 时，将检查每个查询结果，如果不是 JSON（由以下函数确定）：JSON_OBJECT_T.parse()，DBMS_CLOUD.EXPORT_DATA 将转换查询以包括 JSON_OBJECT 函数，将行转换为 JSON。有关详细信息，请参阅 Oracle Database 19c SQL Language Reference 中的 JSON_OBJECT 或 Oracle Database 26ai SQL Language Reference 和 JSON_OBJECT_T Object Type 中的 Oracle Database 19c PL/SQL Packages and Types Reference 或 Oracle Database 26ai PL/SQL Packages and Types Reference 。 例如： SELECT JSON_OBJECT(* RETURNING CLOB) from(SELECT warehouse_id, quantity FROM inventories)
operation_id	使用此参数可以跟踪导出操作的进度和最终状态，并将其作为 USER_LOAD_OPERATIONS 视图中的相应 ID。

使用说明

• 如果需要，您提供的 query 参数值可以是高级查询，例如包含联接或子查询的查询。

• 根据指定的格式参数，DBMS_CLOUD.EXPORT_DATA 将在云对象存储上输出指定查询的结果，或者以 CSV、JSON、Parquet 或 XML 文件格式输出到目录位置。

  有关对 CSV、JSON、Parquet 或 XML 输出文件使用 DBMS_CLOUD.EXPORT_DATA 的更多信息，请参见 Export Data to Object Store as Text Using DBMS_CLOUD.EXPORT_DATA 和 Export data to a Directory Using DBMS_CLOUD.EXPORT_DATA 。

• 对于 CSV、JSON 或 XML 输出，默认情况下，当生成的文件包含 10MB 数据时，将创建新输出文件。但是，如果结果数据少于 10MB，则可能会有多个输出文件，具体取决于自治 AI 数据库实例的数据库服务和 ECPU 数（如果数据库使用 OCPU，则为 OCPU）。

  有关详细信息，请参阅文本输出文件命名（CSV、JSON、Parquet 或 XML）。

  对于 CSV、JSON 或 XML，默认输出文件块大小为 10MB。可以使用 format 参数 maxfilesize 选项更改此值。有关更多信息，请参见 DBMS_CLOUD Package Format Options for EXPORT_DATA 。

• 对于 CSV、JSON 或 XML 输出，默认情况下，当生成的文件包含 10MB 数据时，将创建新输出文件。但是，如果结果数据少于 10MB，则可能会有多个输出文件，具体取决于自治 AI 数据库实例的数据库服务和 ECPU 数（如果数据库使用 OCPU，则为 OCPU）。

  有关详细信息，请参阅文本输出文件命名（CSV、JSON、Parquet 或 XML）。

• parquet 输出格式只能与专用 Exadata 基础结构上自治 AI 数据库的高中数据库服务一起使用。

“输出到目录”的 `DBMS_CLOUD.EXPORT_DATA` 的使用说明

• 提供的目录必须存在，您必须以 ADMIN 用户身份登录，或者具有对该目录的 WRITE 访问权限。

• DBMS_CLOUD.EXPORT_DATA 不会创建目录。

• 该过程不会覆盖文件。例如，如果 file_uri_list 中存在转储文件，则 DBMS_CLOUD.EXPORT_DATA 会报告错误，例如：

ORA-31641: unable to create dump file  "/u02/exports/123.dmp"
ORA-27038: created file already exists

示例

示例：DBMS_CLOUD.EXPORT_DATA，格式为 type 参数，值为 json。

BEGIN
   DBMS_CLOUD.EXPORT_DATA(
      credential_name => 'OBJ_STORE_CRED',
      file_uri_list   => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/exp1.json',
      query           => 'SELECT * FROM DEPT',
      format          => JSON_OBJECT('type' value 'json', 'compression' value 'gzip'));
     );
   END;
/

示例：DBMS_CLOUD.EXPORT_DATA，格式为 type 参数，值为 xml。

BEGIN
   DBMS_CLOUD.EXPORT_DATA(
      credential_name => 'OBJ_STORE_CRED',
      file_uri_list   => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/exp1.xml',
      query           => 'SELECT * FROM DEPT',
      format          => JSON_OBJECT('type' value 'xml', 'compression' value 'gzip'));
     );
   END;
/

示例：DBMS_CLOUD.EXPORT_DATA，格式为 type 参数，值为 csv。

BEGIN
   DBMS_CLOUD.EXPORT_DATA(
      credential_name => 'OBJ_STORE_CRED',
      file_uri_list   => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/exp.csv',
      query           => 'SELECT * FROM DEPT',
      format          => JSON_OBJECT('type' value 'csv', 'delimiter' value '|', 'compression' value 'gzip', 'header' value true ));
     );
   END;
/

GET_OBJECT 过程和函数

此过程已重载。过程表单从 Cloud Object Storage 读取对象并将其复制到 Autonomous AI Database。函数表单从 Cloud Object Storage 读取对象，并将 BLOB 返回到 Autonomous AI Database。

语法

DBMS_CLOUD.GET_OBJECT (
       credential_name      IN VARCHAR2,
       object_uri           IN VARCHAR2,
       directory_name       IN VARCHAR2,
       file_name            IN VARCHAR2 DEFAULT  NULL,
       startoffset          IN NUMBER DEFAULT  0,
       endoffset            IN NUMBER DEFAULT  0,
       compression          IN VARCHAR2 DEFAULT  NULL);

DBMS_CLOUD.GET_OBJECT(
       credential_name      IN VARCHAR2 DEFAULT NULL,
       object_uri           IN VARCHAR2,
       startoffset          IN NUMBER DEFAULT  0,
       endoffset            IN NUMBER DEFAULT  0,
       compression          IN VARCHAR2 DEFAULT  NULL)
RETURN BLOB;

参数

Parameter (参数)	说明
credential_name	用于访问云对象存储的身份证明的名称。
object_uri	对象或文件 URI。URI 的格式取决于您使用的云对象存储服务，有关详细信息，请参见 Cloud Object Storage URI Formats 。
directory_name	数据库上的目录的名称。（见下文脚注 1）
file_name	指定要创建的文件的名称。如果未指定文件名，则文件名取自 object_uri 参数中最后一个斜杠之后。对于特殊情况，例如，文件名包含斜杠时，请使用 file_name 参数。
startoffset	过程开始读取的偏移量（字节）。
endoffset	偏移（以字节为单位），直到过程停止读取。
compression	指定用于存储对象的压缩。当 compression 设置为‘ AUTO ’时，文件将被解压缩（值‘ AUTO ’表示使用 Gzip 压缩使用 object_uri 指定的对象）。

脚注 1

注：要与 ADMIN 以外的用户一起运行 DBMS_CLOUD.GET_OBJECT，您需要向该用户授予对该目录的 WRITE 权限。例如，以 ADMIN 身份运行以下命令以向 atpc_user 授予写入权限：

GRANT WRITE ON DIRECTORY data_pump_dir TO atpc_user;

返回值

函数形式从对象存储读取，DBMS_CLOUD.GET_OBJECT 返回 BLOB。

示例

BEGIN
   DBMS_CLOUD.GET_OBJECT(
     credential_name => 'OBJ_STORE_CRED',
     object_uri => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/file.txt',
     directory_name => 'DATA_PUMP_DIR');
END;
/

示例：从对象存储中的文件读取字符数据。

SELECT to_clob(
     DBMS_CLOUD.GET_OBJECT(
       credential_name => 'OBJ_STORE_CRED',
       object_uri => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/file.txt'))
FROM DUAL;

示例：将存储在对象存储上的图像添加到数据库的 BLOB 中。

DECLARE
   l_blob BLOB := NULL;
BEGIN
   l_blob := DBMS_CLOUD.GET_OBJECT(
     credential_name => 'OBJ_STORE_CRED',
     object_uri => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/MyImage.gif' );
END;
/

在此示例中，namespace-string 是 Oracle Cloud Infrastructure 对象存储名称空间，bucketname 是存储桶名称。有关详细信息，请参阅了解对象存储名称空间。

LIST_FILES 函数

此函数列出指定目录中的文件。结果包括有关文件的文件名和其他元数据，例如文件大小（以字节为单位）、创建时间戳和上次修改时间戳。

语法

DBMS_CLOUD.LIST_FILES (
	directory_name      IN VARCHAR2)
       RETURN TABLE;

参数

Parameter (参数)	说明
directory_name	数据库上的目录的名称。此参数支持通配符。

使用说明

• 要与 ADMIN 以外的用户一起运行 DBMS_CLOUD.LIST_FILES，您需要向该用户授予对该目录的读取权限。例如，以 ADMIN 身份运行以下命令以向 atpc_user 授予读取权限：

  GRANT READ ON DIRECTORY data_pump_dir TO atpc_user;
  

• 这是返回类型为 DBMS_CLOUD_TYPES.list_object_ret_t 的流水线表函数。
• DBMS_CLOUD.LIST_FILES 不会获取校验和值，并且会为此字段返回 NULL。
• DBMS_CLOUD.LIST_FILES 支持使用 directory:filename 语法选择性地过滤文件。文件名中支持通配符。

示例

示例：使用以下查询将 DBMS_CLOUD.LIST_FILES 用作可为每个文件返回一行的流水线函数。

SELECT * FROM DBMS_CLOUD.LIST_FILES('DATA_PUMP_DIR');

OBJECT_NAME       BYTES   CHECKSUM      CREATED              LAST_MODIFIED
------------ ---------- ----------    ---------------------  ---------------------
cwallet.sso        2965               2018-12-12T18:10:47Z   2019-11-23T06:36:54Z

还可以通过指定文件或使用通配符将 DBMS_CLOUD.LIST_FILES 与 DIRECTORY:FILE 语法一起使用。* 和 ？是支持的通配符。

示例：使用通配符列出目录 DATA_PUMP_DIR 中以 "f" 开头的所有 CSV 文件。

SELECT * FROM DBMS_CLOUD.LIST_FILES('DATA_PUMP_DIR:f*.csv');

示例：在指定文件名的目录 DATA_PUMP_DIR 中列出文件 f1.csv。

SELECT * FROM DBMS_CLOUD.LIST_FILES('DATA_PUMP_DIR:f1.csv');

LIST_OBJECTS 函数

此函数列出对象存储上指定位置中的对象。结果包括对象名称和有关对象的其他元数据，例如大小、校验和、创建时间戳和上次修改时间戳。

语法

DBMS_CLOUD.LIST_OBJECTS (
       credential_name      IN VARCHAR2,
       location_uri         IN VARCHAR2)
   RETURN TABLE;

参数

Parameter (参数)	说明
credential_name	用于访问云对象存储的身份证明的名称。
location_uri	对象存储存储桶或文件夹 URI。URI 的格式取决于您使用的云对象存储服务，有关详细信息，请参见 Cloud Object Storage URI Formats 。 支持通配符有选择地列出 URI 中的文件或子文件夹。字符 "*" 和 "?" 视为通配符。 使用通配符的示例： location_uri => 'https://objectstorage.my$region.oraclecloud.com/n/namespace-string/b/bucketname/o/year=????/month=??/*.csv'

使用说明

• 根据对象存储的功能，DBMS_CLOUD.LIST_OBJECTS 不会为某些属性返回值，在这种情况下，字段的返回值为 NULL。

  所有受支持的对象存储将返回 OBJECT_NAME、BYTES 和 CHECKSUM 字段的值。下表显示了对按对象存储列出的字段 CREATED 和 LAST_MODIFIED 的支持：

  对象存储库	CREATED	LAST_MODIFIED
  Oracle Cloud Infrastructure 原生	返回时间戳	返回时间戳
  Oracle Cloud Infrastructure Swift	返回 NULL	返回时间戳
  Amazon S3	返回 NULL	返回时间戳
  兼容 Amazon S3	返回 NULL	返回时间戳
  Azure	返回时间戳	返回时间戳

• 校验和值为 MD5 校验和。这是基于对象内容计算的 32 个字符的十六进制数字。

• 这是返回类型为 DBMS_CLOUD_TYPES.list_object_ret_t 的流水线表函数。

范例

这是一个流水线函数，为每个对象返回一行。例如，使用以下查询可使用此函数：

SELECT * FROM DBMS_CLOUD.LIST_OBJECTS('OBJ_STORE_CRED',
    'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/');

OBJECT_NAME   BYTES              CHECKSUM                       CREATED         LAST_MODIFIED
------------ ---------- -------------------------------- --------------------- --------------------
cwallet.sso   2965      2339a2731ba24a837b26d344d643dc07 2019-11-23T06:36:54Z

在此示例中，namespace-string 是 Oracle Cloud Infrastructure 对象存储名称空间，bucketname 是存储桶名称。有关详细信息，请参阅了解对象存储名称空间。

MOVE_OBJECT 过程

此过程将对象从一个云对象存储桶或文件夹移到另一个云对象存储桶或文件夹。

源存储桶和目标存储桶或文件夹可以位于相同或不同的云对象存储提供程序中。

当源和目标位于不同的对象存储中或具有具有相同云提供商的不同账户时，您可以为源和目标位置提供单独的身份证明名称。

未提供目标身份证明名称时，默认情况下目标位置也使用源身份证明名称。

语法

DBMS_CLOUD.MOVE_OBJECT (
    source_credential_name  IN  VARCHAR2 DEFAULT NULL,
    source_object_uri       IN  VARCHAR2,
    target_object_uri       IN  VARCHAR2,
    target_credential_name  IN  VARCHAR2 DEFAULT NULL
);

参数

Parameter (参数)	说明
source_credential_name	用于访问源云对象存储的身份证明的名称。 如果不提供 source_credential_name 值，则 credential_name 将设置为 NULL。
source_object_uri	指定指向源对象存储存储桶或文件夹位置的 URI。 此参数是必需的。 URI 的格式取决于云对象存储服务。有关详细信息，请参阅云对象存储 URI 格式。
target_object_uri	指定目标对象存储存储桶或文件夹的 URI，需要在其中移动文件。 此参数是必需的。 URI 的格式取决于云对象存储服务。有关详细信息，请参阅云对象存储 URI 格式。
target_credential_name	用于访问目标云对象存储位置的身份证明的名称。 如果不提供 target_credential_name 值，则 target_object_uri 将设置为 source_credential_name 值。

范例

BEGIN
DBMS_CLOUD.MOVE_OBJECT (
    source_credential_name => 'OCI_CRED',
    source_object_uri    => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname1/bgfile.csv',
    target_object_uri    => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname2/myfile.csv'
);
END;
/

PUT_OBJECT 过程

此过程已重载。该过程以一种形式将文件从 Autonomous AI Database 复制到 Cloud Object Storage。该过程以另一种形式将 BLOB 从自治 AI 数据库复制到云对象存储。

语法

DBMS_CLOUD.PUT_OBJECT (
       credential_name      IN VARCHAR2,
       object_uri           IN VARCHAR2,
       directory_name       IN VARCHAR2,
       file_name            IN VARCHAR2
       compression          IN VARCHAR2 DEFAULT  NULL);

DBMS_CLOUD.PUT_OBJECT (
       credential_name      IN VARCHAR2,
       object_uri           IN VARCHAR2,
       contents             IN BLOB
       compression          IN VARCHAR2 DEFAULT  NULL);

参数

Parameter (参数)	说明
credential_name	用于访问云对象存储的身份证明的名称。
object_uri	对象或文件 URI。URI 的格式取决于您使用的云对象存储服务，有关详细信息，请参见 Cloud Object Storage URI Formats 。
directory_name	数据库上的目录的名称。（见下文脚注 1）
contents	指定要从自治 AI 数据库复制到云对象存储的 BLOB。
file_name	指定目录中的文件的名称。
compression	指定用于存储对象的压缩。 默认值：NULL

脚注 1

注：要与 ADMIN 以外的用户一起运行 DBMS_CLOUD.PUT_OBJECT，您需要向该用户授予对该目录的读取权限。例如，以 ADMIN 身份运行以下命令以向 atpc_user 授予读取权限：

GRANT READ ON DIRECTORY data_pump_dir TO atpc_user;

范例

要在数据库内处理后处理 BLOB 数据，然后将数据直接存储在对象存储中的文件中，请执行以下操作：

DECLARE
      my_blob_data BLOB;
BEGIN
 /* Some processing producing BLOB data and populating my_blob_data */
DBMS_CLOUD.PUT_OBJECT(
     credential_name => 'OBJ_STORE_CRED',
     object_uri => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/my_new_file',
     contents => my_blob_data));
END;
/

使用说明

根据您的云对象存储，您传输的对象大小受到如下限制：

云对象存储服务	对象传输大小限制
Oracle Cloud Infrastructure Object Storage	50 GB
Amazon S3	5 GB
Azure Blob 存储	256 MB
兼容 Amazon S3	由对象存储提供程序设置。有关详细信息，请参阅提供商的文档。

Oracle Cloud Infrastructure 对象存储不允许在未提供身份证明的情况下将文件写入公共存储桶（Oracle Cloud Infrastructure 允许用户从公共存储桶下载对象）。因此，必须提供具有有效身份证明的身份证明名称，才能使用 PUT_OBJECT 将对象存储在 Oracle Cloud Infrastructure 公共存储桶中。

有关详细信息，请参阅云对象存储 URI 格式。

SYNC_EXTERNAL_PART_TABLE 过程

此过程简化了从云中的文件更新外部分区表的过程。每当添加新分区或从外部分区表的对象存储源中删除分区时，都运行此过程。

语法

DBMS_CLOUD.SYNC_EXTERNAL_PART_TABLE (
	table_name        IN VARCHAR2,
	schema_name       IN VARCHAR2 DEFAULT,
	update_columns    IN BOOLEAN DEFAULT);

参数

Parameter (参数)	说明
table_name	目标表的名称。需要在运行 DBMS_CLOUD.SYNC_EXTERNAL_PART_TABLE 之前创建目标表。
schema_name	目标表所在的方案的名称。默认值为 NULL，表示目标表与运行该过程的用户位于同一方案中。
update_columns	新文件可能会对方案进行更改。支持的更新包括：新列、删除的列。对现有列的更新，例如数据类型更改会引发错误。 默认值：False

VALIDATE_EXTERNAL_PART_TABLE 过程

此过程验证外部分区表的源文件，生成日志信息，并将与为外部表指定的格式选项不匹配的行存储在自治 AI 数据库上的 badfile 表中。使用重载表单可以使用 operation_id 参数。

语法

DBMS_CLOUD.VALIDATE_EXTERNAL_PART_TABLE (
       table_name                 IN VARCHAR2,
       partition_name             IN CLOB DEFAULT,
       subpartition_name          IN CLOB DEFAULT,
       schema_name                IN VARCHAR2 DEFAULT,
       rowcount                   IN NUMBER DEFAULT,
       partition_key_validation   IN BOOLEAN DEFAULT,
       stop_on_error              IN BOOLEAN DEFAULT);

DBMS_CLOUD.VALIDATE_EXTERNAL_PART_TABLE (
       table_name                 IN VARCHAR2,
       operation_id               OUT NUMBER,
       partition_name             IN CLOB DEFAULT,
       subpartition_name          IN CLOB DEFAULT,
       schema_name                IN VARCHAR2 DEFAULT,
       rowcount                   IN NUMBER DEFAULT,
       partition_key_validation   IN BOOLEAN DEFAULT,
       stop_on_error              IN BOOLEAN DEFAULT);

参数

Parameter (参数)	说明
table_name	外部表的名称。
operation_id	使用此参数以 USER_LOAD_OPERATIONS 视图中相应 ID 的身份跟踪加载操作的进度和最终状态。
partition_name	如果已定义，则仅验证特定分区。如果未指定，则按顺序读取所有分区，直到达到 rowcount。
subpartition_name	如果已定义，则仅验证特定子分区。如果未指定，则按顺序从所有外部分区或子分区读取，直到达到 rowcount。
schema_name	外部表所在的方案的名称。默认值为 NULL，表示外部表与运行该过程的用户处在相同的方案中。
rowcount	要扫描的行数。默认值为 NULL，表示将扫描源文件中的所有行。
partition_key_validation	仅供内部使用。请勿使用此参数。
stop_on_error	确定在拒绝行时是否应停止验证。默认值为 TRUE，表示验证停止在第一个被拒绝的行。将值设置为 FALSE 将指定验证不会在第一个被拒绝的行处停止，并验证所有行，直到为 rowcount 参数指定的值为止。

VALIDATE_EXTERNAL_TABLE 过程

此过程验证外部表的源文件，生成日志信息，并将与为外部表指定的格式选项不匹配的行存储在自治 AI 数据库上的 badfile 表中。使用重载表单可以使用 operation_id 参数。

语法

DBMS_CLOUD.VALIDATE_EXTERNAL_TABLE (
	table_name      IN VARCHAR2,
	schema_name     IN VARCHAR2 DEFAULT,
	rowcount        IN NUMBER DEFAULT,
	stop_on_error   IN BOOLEAN DEFAULT);

DBMS_CLOUD.VALIDATE_EXTERNAL_TABLE(
	table_name      IN VARCHAR2,
	operation_id    OUT NOCOPY NUMBER,
	schema_name     IN VARCHAR2 DEFAULT NULL,
	rowcount        IN NUMBER DEFAULT 0,
	stop_on_error   IN BOOLEAN DEFAULT TRUE);

参数

Parameter (参数)	说明
table_name	外部表的名称。
operation_id	使用此参数以 USER_LOAD_OPERATIONS 视图中相应 ID 的身份跟踪加载操作的进度和最终状态。
schema_name	外部表所在的方案的名称。默认值为 NULL，表示外部表与运行该过程的用户处在相同的方案中。
rowcount	要扫描的行数。默认值为 NULL，表示将扫描源文件中的所有行。
stop_on_error	确定在拒绝行时是否应停止验证。默认值为 TRUE，表示验证停止在第一个被拒绝的行。将该值设置为 FALSE 将指定验证不会在第一个被拒绝的行停止，并验证所有行，直到为 rowcount 参数指定的值为止。 如果外部表引用 Avro、ORC 或 Parquet 文件，则验证将停止在第一个被拒绝的行。 当外部表指定 format 参数 type 设置为值 avro、orc 或 parquet 时，参数 stop_on_error 始终具有值 TRUE。因此，对于引用 Avro、ORC 或 Parquet 文件的外部表，表错误文件始终为空。

用法附注

DBMS_CLOUD.VALIDATE_EXTERNAL_TABLE 可与分区的外部表和混合分区表一起使用。这可能会从所有外部分区读取数据，直到达到 rowcount 或应用 stop_on_error。您无法控制以何种顺序读取哪个分区或分区的某些部分。

VALIDATE_HYBRID_PART_TABLE 过程

此过程验证混合分区表的源文件，生成日志信息，并将与为混合表指定的格式选项不匹配的行存储在自治 AI 数据库上的 badfile 表中。使用重载表单可以使用 operation_id 参数。

语法

DBMS_CLOUD.VALIDATE_HYBRID_PART_TABLE (
       table_name                 IN VARCHAR2,
       partition_name             IN CLOB DEFAULT,
       subpartition_name          IN CLOB DEFAULT,
       schema_name                IN VARCHAR2 DEFAULT,
       rowcount                   IN NUMBER DEFAULT,
       partition_key_validation   IN BOOLEAN DEFAULT,
       stop_on_error              IN BOOLEAN DEFAULT);

DBMS_CLOUD.VALIDATE_HYBRID_PART_TABLE (
       table_name                 IN VARCHAR2,
       operation_id               OUT NUMBER,
       partition_name             IN CLOB DEFAULT,
       subpartition_name          IN CLOB DEFAULT,
       schema_name                IN VARCHAR2 DEFAULT,
       rowcount                   IN NUMBER DEFAULT,
       partition_key_validation   IN BOOLEAN DEFAULT,
       stop_on_error              IN BOOLEAN DEFAULT);

参数

Parameter (参数)	说明
table_name	外部表的名称。
operation_id	使用此参数以 USER_LOAD_OPERATIONS 视图中相应 ID 的身份跟踪加载操作的进度和最终状态。
partition_name	如果已定义，则仅验证特定分区。如果未指定，则按顺序从所有外部分区读取，直到达到 rowcount。
subpartition_name	如果已定义，则仅验证特定子分区。如果未指定，则按顺序从所有外部分区或子分区读取，直到达到 rowcount。
schema_name	外部表所在的方案的名称。默认值为 NULL，表示外部表与运行该过程的用户处在相同的方案中。
rowcount	要扫描的行数。默认值为 NULL，表示将扫描源文件中的所有行。
partition_key_validation	仅供内部使用。请勿使用此参数。
stop_on_error	确定在拒绝行时是否应停止验证。默认值为 TRUE，表示验证停止在第一个被拒绝的行。将值设置为 FALSE 将指定验证不会在第一个被拒绝的行处停止，并验证所有行，直到为 rowcount 参数指定的值为止。

相关内容

• 云对象存储 URI 格式

• 格式参数

• DBMS_CLOUD Avro、ORC 和 Parquet 支持