对象和文件的 DBMS

Prerequisites

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

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

Oracle Public Cloud 或多云
Exadata Cloud@Customer

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

按照 Oracle Cloud Infrastructure 文档中的创建 NAT 网关中的说明，在 Autonomous Database 资源所在的虚拟云网络 (Virtual Cloud Network，VCN) 中创建 NAT 网关。
创建 NAT 网关后，向每个子网（在 VCN 中）添加路由规则和出站安全规则，Autonomous Database 资源位于其中，以便这些资源可以使用网关从 Azure AD 实例获取公钥：
1. 转到子网的子网详细信息页。
2. 在子网信息选项卡中，单击子网的路由表的名称以显示其路由表详细信息页。
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_COLLECTION 过程	此过程将数据从云对象存储或目录中的文件加载到现有 SODA 集合中。
COPY_DATA 过程	此过程将数据从 Cloud Object Storage 或目录中的文件加载到现有 Autonomous Database 表中。
COPY_DATA Avro、ORC 或 Parquet 文件的过程	将 `format` 参数 `type` 设置为值 `orc`、`parquet` 或 `avro` 的此过程将数据从云中的 ORC、Parquet 或 Avro 文件或目录中的 ORC、Parquet 或 Avro 文件加载到现有 Autonomous Database 表中。与文本文件类似，数据将从源 ORC、Parquet 或 Avro 文件复制到预先存在的内部表中。
COPY_OBJECT 过程	此过程将文件从一个云对象存储存储桶复制到另一个存储桶。
CREATE_EXTERNAL_TABLE 过程	此过程针对云中的文件或目录中的文件创建外部表。这样，您可以对 Autonomous Database 中的外部数据运行查询。
CREATE_EXTERNAL_TABLE Avro、ORC 或 Parquet 文件的过程	将 `format` 参数 `type` 设置为值 `parquet`、`orc` 或 `avro` 的此过程会在云或目录中创建具有 Parquet、ORC 或 Avro 格式文件的外部表。这样，您可以对 Autonomous Database 中的外部数据运行查询。
CREATE_EXTERNAL_TEXT_INDEX 过程	此过程在对象存储文件上创建文本索引。
CREATE_HYBRID_PART_TABLE 过程	此过程将创建混合分区表。这样，您可以从 Autonomous Database 对混合分区数据运行查询。
DELETE_ALL_OPERATIONS 过程	此过程将清除方案中 `user_load_operations` 表中记录的所有数据加载操作，或者清除指定类型的所有数据加载操作，如 `type` 参数所示。
DELETE_FILE 过程	此过程从 Autonomous Database 上的指定目录中删除指定的文件
DELETE_OBJECT 过程	此过程将删除对象存储上的指定对象。
DELETE_OPERATION 过程	此过程接受 `operation_id` 作为输入并删除与指定 `operation_id` 关联的日志。
DROP_EXTERNAL_TEXT_INDEX 过程	此过程将删除对象存储文件上的文本索引。
EXPORT_DATA 过程	此过程根据查询结果将数据从 Autonomous Database 导出到云中的文件。使用重载的表单可以使用 `operation_id` 参数。根据指定的 `format` 参数 `type` 选项，该过程将行作为包含 CSV、JSON、Parquet 或 XML 选项的文本导出到云对象存储
GET_OBJECT 过程和函数	此过程重载。该过程表单从 Cloud Object Storage 中读取对象并将其复制到 Autonomous Database 。函数表单从 Cloud Object Storage 读取对象，并将 `BLOB` 返回到 Autonomous Database 。
LIST_FILES 函数	此函数列出指定目录中的文件。结果包括有关文件的文件名和其他元数据，例如以字节为单位的文件大小、创建时间戳和上次修改时间戳。
LIST_OBJECTS 函数	此函数列出对象存储上指定位置中的对象。结果包括对象名称以及有关对象的其他元数据，例如大小、校验和、创建时间戳和上次修改时间戳。
MOVE_OBJECT 过程	此过程将对象从一个云对象存储桶移至另一个云对象存储桶。
PUT_OBJECT 过程	此过程重载。此过程以一种形式将文件从 Autonomous Database 复制到云对象存储。在另一种形式中，该过程将 `BLOB` 从 Autonomous Database 复制到云对象存储。
SYNC_EXTERNAL_PART_TABLE 过程	此过程简化了从云中的文件更新外部分区表的过程。只要添加了新分区，或者从外部分区表的对象存储源中删除了分区，便可运行此过程。
VALIDATE_EXTERNAL_TABLE 过程	此过程验证外部表的源文件，生成日志信息，并将与为外部表指定的格式选项不匹配的行存储在 Autonomous Database 上的 badfile 表中。
VALIDATE_EXTERNAL_PART_TABLE 过程	此过程验证外部分区表的源文件，生成日志信息，并将与为外部表指定的格式选项不匹配的行存储在 Autonomous Database 上的 badfile 表中。
VALIDATE_HYBRID_PART_TABLE 过程	此过程验证混合分区表的源文件，生成日志信息，并将与为混合表指定的格式选项不匹配的行存储在 Autonomous Database 上的 badfile 表中。

COPY_COLLECTION 过程

此过程将数据从云对象存储或从目录加载到 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 的格式取决于您使用的云对象存储服务，有关详细信息，请参见云对象存储 URI 格式。有关 `REGEXP_LIKE` 条件的详细信息，请参阅 Oracle Database 19c SQL Language Reference 或 Oracle Database 23ai 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 数据格式外，Autonomous Database 还支持其他格式。有关 Autonomous Database 支持的格式参数列表，请参阅格式参数。
`operation_id`	使用此参数以 `USER_LOAD_OPERATIONS` 视图中的相应 ID 跟踪加载操作的进度和最终状态。

范例

BEGIN
    DBMS_CLOUD.CREATE_CREDENTIAL(
            credential_name => 'OBJ_STORE_CRED',
            username        => 'user_name@oracle.com',
            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 过程

此过程将数据从云中的文件或目录中的文件加载到现有 Autonomous Database 表中。使用重载的表单可以使用 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 的格式取决于您使用的云对象存储服务，有关详细信息，请参见云对象存储 URI 格式。有关 `REGEXP_LIKE` 条件的详细信息，请参阅 Oracle Database 19c SQL Language Reference 或 Oracle Database 23ai 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` 以引号 (`'`) 开头。
`schema_name`	目标表所在的方案的名称。默认值为 NULL，表示目标表与运行该过程的用户处于相同的方案中。
`field_list`	标识源文件中的字段及其数据类型。默认值为 NULL，表示字段及其数据类型由 column_list 参数确定。此参数的语法与常规 Oracle 外部表中的 `field_list` 子句相同。有关详细信息，请参阅 Oracle Database 19c Utilities 或 Oracle Database 23ai 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 格式选项的信息，请参见 Format Parameter 。

示例

BEGIN
    DBMS_CLOUD.CREATE_CREDENTIAL(
            credential_name => 'DEF_CRED_NAME',
            username        => 'user_name@oracle.com',
            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;
/

Avro、ORC 或 Parquet 文件的 COPY_DATA 过程

将 format 参数 type 设置为值 avro、orc 或 parquet 的此过程会将数据从云中的 Avro、ORC 或 Parquet 文件或目录中的文件加载到现有 Autonomous 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 的格式取决于您使用的云对象存储服务，有关详细信息，请参见云对象存储 URI 格式。有关 `REGEXP_LIKE` 条件的详细信息，请参阅 Oracle Database 19c SQL Language Reference 或 Oracle Database 23ai 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` 以引号 (`'`) 开头。
`schema_name`	目标表所在的方案的名称。默认值为 NULL，表示目标表与运行该过程的用户处于相同的方案中。
`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 文件，仅支持两个选项：请参见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 的格式取决于云对象存储服务。有关更多信息，请参见 Cloud Object Storage URI Formats 。
`target_object_uri`	指定目标对象存储的 URI。此参数是必需的。 URI 的格式取决于云对象存储服务。有关更多信息，请参见 Cloud Object Storage URI Formats 。
`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 过程

此过程基于云中的文件或目录中的文件创建外部分区表。这样，您可以对 Autonomous Database 中的外部数据运行查询。

语法

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 的格式取决于云对象存储服务。有关更多信息，请参见 Cloud Object Storage URI Formats 。有关 `REGEXP_LIKE` 条件的详细信息，请参阅 Oracle Database 19c SQL Language Reference 或 Oracle Database 23ai SQL Language Reference 中的 REGEXP_LIKE Condition 。
`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 23ai 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)"}]'` 如果数据文件是非结构化的，并且使用 `partition_columns` 指定了 `type` 子子句，则忽略 `type` 子子句。对于不基于蜂窝格式的对象名称，`partition_columns` 指定的列的顺序必须与它们在 `file_uri_list` 参数中指定的文件路径中以对象名称显示的顺序匹配。要查看所有描述源文件格式的 `format` 参数选项，请参见 Cloud Object Storage URI Formats 。

使用说明

不能同时使用 partitioning_clause 和 file_uri_list 参数调用此过程。
指定 column_list 参数对于结构化数据文件（包括 Avro、Parquet 或 ORC 数据文件）是可选的。如果未指定 column_list，则 format 参数 partition_columns 选项必须同时包括 name 和 type。
非结构化数据文件（例如 CSV 文本文件）需要 column_list 参数。
DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE 过程支持受支持的云对象存储服务中的外部分区文件，包括：
- Oracle Cloud Infrastructure 对象存储
- Azure Blob 存储
有关更多信息，请参见 Cloud Object Storage URI Formats 。
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;
/

CREATE_EXTERNAL_PART_TABLE 对象存储的 C3 过程

您可以使用 DBMS_CLOUD 程序包来使用存储在 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 过程

此过程基于云中的文件或目录中的文件创建外部表。这样，您可以对 Autonomous Database 中的外部数据运行查询。

语法

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 的格式取决于您使用的云对象存储服务，有关详细信息，请参见云对象存储 URI 格式。有关 `REGEXP_LIKE` 条件的详细信息，请参阅 Oracle Database 19c SQL Language Reference 或 Oracle Database 23ai 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` 以引号 (`'`) 开头。
`column_list`	外部表的列名和数据类型的逗号分隔列表。
`field_list`	标识源文件中的字段及其数据类型。默认值为 NULL，表示字段及其数据类型由 `column_list` 参数确定。此参数的语法与常规 Oracle Database 外部表中的 `field_list` 子句相同。有关 `field_list` 的更多信息，请参见 Oracle Database 19c Utilities 或 Oracle Database 23ai Utilities 中 field_definitions 子句下的 ORACLE_LOADER Access Driver field_list。
`format`	描述源文件格式的选项。有关选项列表以及如何指定值的信息，请参阅设置参数格式。有关 Avro、ORC 或 Parquet 格式文件，请参见 CREATE_EXTERNAL_TABLE Procedure for Avro、ORC 或 Parquet Files 。

使用说明

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

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

有关更多信息，请参见 Cloud Object Storage URI Formats 。
默认记录分隔符为 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 格式选项的信息，请参见 Format Parameter 。

范例

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

CREATE_EXTERNAL_TABLE 对象存储的 C3 过程

您可以使用 DBMS_CLOUD 程序包来使用存储在 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;
/

CREATE_EXTERNAL_TABLE Apache Iceberg 的过程

此过程在支持的配置中为 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 过程中所述创建身份证明。 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 Glue 目录的 AWS Iceberg 表的示例格式参数

使用 AWS Glue 目录在 AWS Iceberg 表上创建表时，format 参数示例如下所示：

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 路径。

使用元数据文件 URI 的 AWS Iceberg 表的示例格式参数

使用元数据文件 URI 在 AWS Iceberg 表上创建表时，format 参数样例如下所示：

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

使用 HadoopCatalog 目录的 OCI Iceberg 表的示例格式参数

通过 OCI Data Flow 使用 HadoopCatalog 目录创建的 OCI Iceberg 表创建表时，示例 format 参数如下所示：

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 表的示例格式参数，使用元数据文件的 URI

使用元数据文件的 URI 在 OCI Iceberg 表上创建表时，示例 format 参数如下所示：

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 格式文件创建外部表。

这样，您可以对 Autonomous Database 中的外部数据运行查询。

语法

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 的格式取决于您使用的云对象存储服务，有关详细信息，请参见云对象存储 URI 格式。有关 `REGEXP_LIKE` 条件的详细信息，请参阅 Oracle Database 19c SQL Language Reference 或 Oracle Database 23ai 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` 以引号 (`'`) 开头。
`column_list`	（可选）此字段在指定时将覆盖 `format->schema` 参数，该参数指定自动派生方案、列和数据类型。有关详细信息，请参见格式参数。为 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')

示例参数

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

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

Avro、ORC 或 Parquet 列名映射至 Oracle 列名

有关 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，可以指定 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 过程

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

语法

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 或 Oracle Database 23ai SQL Language Reference 中的 REGEXP_LIKE Condition 。
`column_list`	外部表的列名和数据类型的逗号分隔列表。
`field_list`	标识源文件中的字段及其数据类型。默认值为 NULL，表示字段及其数据类型由 column_list 参数确定。此参数的语法与常规 Oracle 外部表中的 `field_list` 子句相同。有关详细信息，请参阅 Oracle Database 19c Utilities 或 Oracle Database 23ai Utilities 中的 field_list 。
`format`	描述源文件格式的选项。有关选项列表以及如何指定值的信息，请参阅设置参数格式。

使用说明

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

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

有关更多信息，请参见 Cloud Object Storage URI Formats 。
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 (参数) 说明

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

type

指定要删除的操作类型。可以在 user_load_operations 表的 TYPE 列中找到类型值。

如果未指定 type，将删除所有行。

使用说明

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

DELETE_FILE 过程

此过程从 Autonomous Database 上的指定目录中删除指定的文件。

语法

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

参数

Parameter (参数)	说明
`directory_name`	Autonomous Database 实例上的目录名称。
`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 的格式取决于您使用的云对象存储服务，有关详细信息，请参见云对象存储 URI 格式。
`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 (参数) 说明

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

index_name

指定要删除的索引的名称。

索引名称必须与创建索引时提供的名称匹配。

此参数是必需的。

范例

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

EXPORT_DATA 过程

此过程基于查询结果从 Autonomous Database 导出数据。此过程超载，支持将文件写入云或目录。

根据 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` 时：对象存储上的 JSON 或到指定目录位置的 JSON 将根据 `file_uri_list` 参数的值使用生成的文件名保存。有关详细信息，请参阅文本输出文件命名（CSV、JSON、Parquet 或 XML）。当 `format` 参数 `type` 值为 `datapump` 时，`file_uri_list` 是转储文件的逗号分隔列表。这指定要在对象存储上创建的文件。`file_uri_list` 不支持使用通配符和替代字符。如果未指定 `credential_name` 参数，则会在 `file_uri_list` 中提供目录名称。 URI 的格式取决于您正在使用的云对象存储服务，有关详细信息，请参见云对象存储 URI 格式。
`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 23ai SQL Language Reference 和 JSON_OBJECT_T Object Type （请参见 Oracle Database 19c PL/SQL Packages and Types Reference ）或 Oracle Database 23ai 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 文件格式将指定的查询结果输出到云对象存储或目录位置。

有关将 DBMS_CLOUD.EXPORT_DATA 与 CSV、JSON、Parquet 或 XML 输出文件一起使用的更多信息，请参见 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，则可能有多个输出文件，具体取决于数据库服务以及 Autonomous Database 实例的 ECPU 数（如果数据库使用 OCPU，则为 OCPU）。

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

CSV、JSON 或 XML 的默认输出文件块大小为 10MB。可以使用 format 参数 maxfilesize 选项更改此值。有关更多信息，请参见DBMS_CLOUD Package Format Options for EXPORT_DATA 。
对于 Parquet 输出，每个生成的文件小于 128MB，可以生成多个输出文件。但是，如果结果数据少于 128MB，则可能有多个输出文件，具体取决于数据库服务以及 Autonomous Database 实例的 ECPU 数（如果数据库使用 OCPU，则为 OCPU）。

有关详细信息，请参阅文本输出的文件命名（CSV、JSON、Parquet 或 XML）。
Parquet 输出格式只能与专用 Exadata 基础结构上的 Autonomous Database 的中高数据库服务一起使用。

输出到目录的 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 Database 。函数表单从 Cloud Object Storage 读取对象，并将 BLOB 返回到 Autonomous 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 的格式取决于您使用的云对象存储服务，有关详细信息，请参见云对象存储 URI 格式。
`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 是存储桶名称。有关更多信息，请参见 Understanding Object Storage Namespaces 。

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 语法选择性地过滤文件。文件名中支持通配符。

示例：

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

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 语法一起使用。* 和？是支持的通配符。

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

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

示例 2：在指定文件名的目录 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 是存储桶名称。有关更多信息，请参见 Understanding Object Storage Namespaces 。

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 的格式取决于云对象存储服务。有关更多信息，请参见 Cloud Object Storage URI Formats 。
`target_object_uri`	指定需要将文件移动到的目标对象存储存储桶或文件夹的 URI。此参数是必需的。 URI 的格式取决于云对象存储服务。有关更多信息，请参见 Cloud Object Storage URI Formats 。
`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 Database 复制到云对象存储。在另一种形式中，该过程将 BLOB 从 Autonomous Database 复制到云对象存储。

语法

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 的格式取决于您使用的云对象存储服务，有关详细信息，请参见云对象存储 URI 格式。
`directory_name`	Autonomous Database 上目录的名称。 ^英尺 1
`contents`	指定要从 Autonomous Database 复制到云对象存储的 `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 对象存储	50 GB
Amazon S3	5 GB
Azure Blob 存储	256 MB
Amazon S3 兼容	由对象存储提供方设置。有关更多信息，请参阅提供商的文档。

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

有关更多信息，请参见 Cloud Object Storage URI Formats 。

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 (参数) 说明

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

table_name

目标表的名称。在运行 DBMS_CLOUD.SYNC_EXTERNAL_PART_TABLE 之前，需要创建目标表。

schema_name

目标表所在的方案的名称。默认值为 NULL，表示目标表与运行该过程的用户处于相同的方案中。

update_columns

新文件可能会对方案进行更改。支持的更新包括：新列、删除的列。对现有列的更新，例如数据类型更改会引发错误。

默认值：False

VALIDATE_EXTERNAL_PART_TABLE 过程

此过程验证外部分区表的源文件，生成日志信息，并将与为外部表指定的格式选项不匹配的行存储在 Autonomous Database 上的 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 过程

此过程验证外部表的源文件，生成日志信息，并将与为外部表指定的格式选项不匹配的行存储在 Autonomous Database 上的 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 文件的外部表，表 badfile 始终为空。

使用说明

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

VALIDATE_HYBRID_PART_TABLE 过程

此过程验证混合分区表的源文件，生成日志信息，并将与为混合表指定的格式选项不匹配的行存储在 Autonomous Database 上的 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` 参数指定的值为止。