对象和文件的 DBMS_CLOUD
Prerequisites
作为开发人员,您可以将 DBMS_CLOUD 过程与部署在 Oracle Public Cloud 、 Multicloud 或 Exadata Cloud@Customer 上的 Autonomous Database 结合使用。
根据部署选择,必须满足以下先决条件,才能将 DBMS_CLOUD 过程与 Amazon S3 、Azure Blob Storage 和 Google Cloud Storage 服务提供商一起使用。
- 按照 Oracle Cloud Infrastructure 文档中的创建 NAT 网关中的说明,在 Autonomous Database 资源所在的虚拟云网络 (Virtual Cloud Network,VCN) 中创建 NAT 网关。
- 创建 NAT 网关后,向 每个子网(在 VCN 中)添加路由规则和出站安全规则,Autonomous Database 资源位于其中,以便这些资源可以使用网关从 Azure AD 实例获取公钥:
- 转到子网的子网详细信息页。
- 在子网信息选项卡中,单击子网的路由表的名称以显示其路由表详细信息页。
- 在现有路由规则表中,检查是否已存在具有以下特征的规则:
- 目标:0.0.0.0/0
- 目标类型:NAT 网关
- 目标:刚在 VCN 中创建的 NAT 网关的名称
如果不存在此类规则,请单击添加路由规则并添加具有这些特征的路由规则。
- 返回到子网的子网详细信息页。
- 在子网的安全列表表中,单击子网的安全列表的名称以显示其安全列表详细信息页。
- 在侧边菜单的资源下,单击出站规则。
- 在现有出站规则表中,检查是否已存在具有以下特征的规则:
- 目标类型: CIDR
- 目标:0.0.0.0/0
- IP 协议: TCP
- 源端口范围: 443
- 目标端口范围:全部
如果不存在此类规则,请单击添加出站规则并添加具有这些特征的出站规则。
环境中的 HTTP 代理设置必须允许数据库访问云服务提供商。
注意:
只有在 Exadata 基础结构处于 Requires Activation 状态之前,才能编辑包括 HTTP 代理的网络配置。一旦激活,就无法编辑这些设置。为已预配的 Exadata 基础结构设置 HTTP 代理需要在 My Oracle Support 中创建服务请求 (SR)。有关详细信息,请参见在 My Oracle Support 中创建服务请求。
对象和文件的 DBMS_CLOUD 子程序
DBMS_CLOUD 软件包中用于对象和文件管理的子程序。
子程序 | 说明 |
---|---|
此过程将数据从云对象存储或目录中的文件加载到现有 SODA 集合中。 | |
此过程将数据从 Cloud Object Storage 或目录中的文件加载到现有 Autonomous Database 表中。 | |
将 format 参数 type 设置为值 orc 、parquet 或 avro 的此过程将数据从云中的 ORC、Parquet 或 Avro 文件或目录中的 ORC、Parquet 或 Avro 文件加载到现有 Autonomous Database 表中。
与文本文件类似,数据将从源 ORC、Parquet 或 Avro 文件复制到预先存在的内部表中。 |
|
此过程将文件从一个云对象存储存储桶复制到另一个存储桶。 | |
此过程针对云中的文件或目录中的文件创建外部表。这样,您可以对 Autonomous Database 中的外部数据运行查询。 | |
将 format 参数 type 设置为值 parquet 、orc 或 avro 的此过程会在云或目录中创建具有 Parquet、ORC 或 Avro 格式文件的外部表。
这样,您可以对 Autonomous Database 中的外部数据运行查询。 |
|
此过程在对象存储文件上创建文本索引。 |
|
此过程将创建混合分区表。这样,您可以从 Autonomous Database 对混合分区数据运行查询。 | |
此过程将清除方案中 user_load_operations 表中记录的所有数据加载操作,或者清除指定类型的所有数据加载操作,如 type 参数所示。
|
|
此过程从 Autonomous Database 上的指定目录中删除指定的文件 | |
此过程将删除对象存储上的指定对象。 | |
此过程接受 |
|
此过程将删除对象存储文件上的文本索引。 |
|
此过程根据查询结果将数据从 Autonomous Database 导出到云中的文件。使用重载的表单可以使用 operation_id 参数。根据指定的 format 参数 type 选项,该过程将行作为包含 CSV、JSON、Parquet 或 XML 选项的文本导出到云对象存储 |
|
此过程重载。该过程表单从 Cloud Object Storage 中读取对象并将其复制到 Autonomous Database 。函数表单从 Cloud Object Storage 读取对象,并将 BLOB 返回到 Autonomous Database 。
|
|
此函数列出指定目录中的文件。结果包括有关文件的文件名和其他元数据,例如以字节为单位的文件大小、创建时间戳和上次修改时间戳。 | |
此函数列出对象存储上指定位置中的对象。结果包括对象名称以及有关对象的其他元数据,例如大小、校验和、创建时间戳和上次修改时间戳。 | |
此过程将对象从一个云对象存储桶移至另一个云对象存储桶。 | |
此过程重载。此过程以一种形式将文件从 Autonomous Database 复制到云对象存储。在另一种形式中,该过程将 BLOB 从 Autonomous Database 复制到云对象存储。
|
|
此过程简化了从云中的文件更新外部分区表的过程。只要添加了新分区,或者从外部分区表的对象存储源中删除了分区,便可运行此过程。 |
|
此过程验证外部表的源文件,生成日志信息,并将与为外部表指定的格式选项不匹配的行存储在 Autonomous Database 上的 badfile 表中。 | |
此过程验证外部分区表的源文件,生成日志信息,并将与为外部表指定的格式选项不匹配的行存储在 Autonomous Database 上的 badfile 表中。 | |
此过程验证混合分区表的源文件,生成日志信息,并将与为混合表指定的格式选项不匹配的行存储在 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 (参数) | 说明 |
---|---|
|
数据将加载到其中的 SODA 集合的名称。如果已存在具有此名称的集合,则将加载指定的数据,否则将创建新集合。 |
|
用于访问云对象存储的身份证明的名称。 使用 |
|
此参数指定源文件 URI 的逗号分隔列表,或者指定一个或多个目录和源文件。 云源文件 URI 您可以在云源文件 URI 中的文件名中使用通配符和正则表达式。 仅当 当 URI 中的文件名或子文件夹路径仅支持正则表达式模式,并且模式匹配与 例如:
URI 的格式取决于您使用的云对象存储服务,有关详细信息,请参见云对象存储 URI 格式。 有关 目录 可以指定一个目录和一个或多个文件名,也可以使用目录和文件名的逗号分隔列表。指定目录的格式为: 可以使用通配符指定目录中的文件名。字符 "*" 可以用作多个字符的通配符,字符 "?" 可以用作单个字符的通配符。例如: 要指定多个目录,请使用逗号分隔的目录列表:例如: 使用双引号指定区分大小写的目录名称。例如: 要包括引号字符,请使用两个引号。例如: |
|
描述源文件格式的选项。这些选项指定为 JSON 字符串。 支持的格式包括: 除了提及的 JSON 数据格式外,Autonomous Database 还支持其他格式。有关 Autonomous Database 支持的格式参数列表,请参阅格式参数。 |
|
使用此参数以 |
范例
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 (参数) | 说明 |
---|---|
|
数据库上目标表的名称。需要在运行 |
|
用于访问云对象存储的身份证明的名称。 使用 |
|
您可以在云源文件 URI 中的文件名中使用通配符和正则表达式。 云源文件 URI 此参数指定源文件 URI 的逗号分隔列表,或者指定一个或多个目录和源文件。 仅当 当 URI 中的文件名或子文件夹路径仅支持正则表达式模式,并且模式匹配与 例如:
URI 的格式取决于您使用的云对象存储服务,有关详细信息,请参见云对象存储 URI 格式。 有关 目录 可以指定一个目录和一个或多个文件名,也可以使用目录和文件名的逗号分隔列表。指定目录的格式为: 可以使用通配符指定目录中的文件名。字符 "*" 可以用作多个字符的通配符,字符 "?" 可以用作单个字符的通配符。例如: 要指定多个目录,请使用逗号分隔的目录列表:例如: 使用双引号指定区分大小写的目录名称。例如: 要包括引号字符,请使用两个引号。例如: |
|
目标表所在的方案的名称。默认值为 NULL,表示目标表与运行该过程的用户处于相同的方案中。 |
|
标识源文件中的字段及其数据类型。默认值为 NULL,表示字段及其数据类型由 column_list 参数确定。此参数的语法与常规 Oracle 外部表中的 当 有关使用 |
|
描述源文件、日志文件和错误文件的格式的选项。有关选项列表以及如何指定值的信息,请参阅设置参数格式。 有关 Avro、ORC 或 Parquet 文件格式选项,请参见 DBMS_CLOUD Package Format Options for Avro、ORC 或 Parquet 。 |
|
使用此参数以 |
使用说明
默认记录分隔符为 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 (参数) | 说明 |
---|---|
|
数据库上目标表的名称。需要在运行 |
|
用于访问云对象存储的身份证明的名称。 使用 |
|
此参数指定源文件 URI 的逗号分隔列表,或者指定一个或多个目录和源文件。 云源文件 URI 您可以在云源文件 URI 中的文件名中使用通配符和正则表达式。 仅当 当 URI 中的文件名或子文件夹路径仅支持正则表达式模式,并且模式匹配与 例如:
URI 的格式取决于您使用的云对象存储服务,有关详细信息,请参见云对象存储 URI 格式。 有关 目录 可以指定一个目录和一个或多个文件名,也可以使用目录和文件名的逗号分隔列表。指定目录的格式为: 可以使用通配符指定目录中的文件名。字符 "*" 可以用作多个字符的通配符,字符 "?" 可以用作单个字符的通配符。例如: 要指定多个目录,请使用逗号分隔的目录列表:例如: 使用双引号指定区分大小写的目录名称。例如: 要包括引号字符,请使用两个引号。例如: |
|
目标表所在的方案的名称。默认值为 NULL,表示目标表与运行该过程的用户处于相同的方案中。 |
|
忽略 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 。 |
|
描述源文件格式的选项。对于 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 (参数) | 说明 |
---|---|
|
用于访问源云对象存储的身份证明的名称。 如果未提供 |
|
指定指向源对象存储存储桶或文件夹位置的 URI。 此参数是必需的。 URI 的格式取决于云对象存储服务。有关更多信息,请参见 Cloud Object Storage URI Formats 。 |
|
指定目标对象存储的 URI。 此参数是必需的。 URI 的格式取决于云对象存储服务。有关更多信息,请参见 Cloud Object Storage URI Formats 。 |
|
用于访问目标云对象存储位置的身份证明的名称。 如果未提供 |
范例
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 (参数) | 说明 |
---|---|
|
外部表的名称。 |
|
用于访问云对象存储的身份证明的名称。 |
|
指定完整的分区子句,包括各个分区的位置信息。 如果使用 |
|
此参数指定源文件 URI 的逗号分隔列表,或者指定一个或多个目录和源文件。 云源文件 URI 您可以在云源文件 URI 中的文件名中使用通配符和正则表达式。 仅当 当 URI 中的文件名或子文件夹路径仅支持正则表达式模式,并且模式匹配与 只有在对象存储中为文件创建的外部表支持此选项。 例如:
如果使用参数 URI 的格式取决于云对象存储服务。有关更多信息,请参见 Cloud Object Storage URI Formats 。 有关 |
|
外部表的列名和数据类型的逗号分隔列表。此参数具有以下要求,具体取决于使用
|
|
标识源文件中的字段及其数据类型。默认值为 NULL,表示字段及其数据类型由 column_list 参数确定。此参数的语法与常规 Oracle 外部表中的 |
|
格式选项
如果数据文件是非结构化的,并且使用 对于不基于蜂窝格式的对象名称, 要查看所有描述源文件格式的 |
使用说明
-
不能同时使用
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_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 (参数) | 说明 |
---|---|
|
外部表的名称。 |
|
用于访问云对象存储的身份证明的名称。 使用 |
|
此参数指定源文件 URI 的逗号分隔列表,或者指定一个或多个目录和源文件。 云源文件 URI 您可以在云源文件 URI 中的文件名中使用通配符和正则表达式。 仅当 当 URI 中的文件名或子文件夹路径仅支持正则表达式模式,并且模式匹配与 只有在对象存储中为文件创建的外部表支持此选项。 例如:
URI 的格式取决于您使用的云对象存储服务,有关详细信息,请参见云对象存储 URI 格式。 有关 可以指定一个目录和一个或多个文件名,也可以使用目录和文件名的逗号分隔列表。指定目录的格式为: 可以使用通配符指定目录中的文件名。字符 "*" 可以用作多个字符的通配符,字符 "?" 可以用作单个字符的通配符。例如: 要指定多个目录,请使用逗号分隔的目录列表:例如: 使用双引号指定区分大小写的目录名称。例如: 要包括引号字符,请使用两个引号。例如: |
|
外部表的列名和数据类型的逗号分隔列表。 |
|
标识源文件中的字段及其数据类型。默认值为 NULL,表示字段及其数据类型由 |
|
描述源文件格式的选项。有关选项列表以及如何指定值的信息,请参阅设置参数格式。 有关 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 Apache Iceberg 的过程
此过程在支持的配置中为 Apache Iceberg 表创建外部表。
- AWS 上的 Iceberg 表:
- 在 AWS Glue Data Catalog 中注册的 Iceberg 表,使用 Spark 或 Athena 创建。
有关详细信息,请参阅使用 AWS Glue 连接器读取和写入包含 ACID 事务处理的 Apache Iceberg 表并执行时间旅行和使用 Iceberg 表。
- 通过直接提供根元数据文件的 URL 存储在 AWS S3 上的 Iceberg 表。
- 在 AWS Glue Data Catalog 中注册的 Iceberg 表,使用 Spark 或 Athena 创建。
- OCI 上的 Iceberg 表:
- 使用 Hadoop 目录使用 OCI 数据流生成的 Iceberg 表。
有关详细信息,请参阅 Oracle 数据流示例和使用 Hadoop 目录。
- 通过直接提供根元数据文件的 URL 存储在 OCI 对象存储上的 Iceberg 表。
- 使用 Hadoop 目录使用 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 (参数) | 说明 |
---|---|
|
外部表的名称。 |
|
用于访问数据文件、元数据文件和 Iceberg 目录(如果使用)的身份证明的名称。 对于 AWS 和 OCI 配置,应按 CREATE_CREDENTIAL 过程中所述创建身份证明。 AWS Amazon 资源名称 (ARN) 身份证明当前不受支持。 |
|
如果指定了 Iceberg 目录,则必须为 NULL(请参见下面的 format 参数)。如果未使用冰山目录,则 file_uri_list 必须包含冰山元数据文件的 URI。
|
|
必须为 NULL,因为列名和类型自动从 Iceberg 元数据派生。 列名与底层数据文件(Parquet、Avro、ORC)中的名称匹配。Oracle 数据类型使用 Iceberg 与 Parquet、Avro 和 ORC 数据类型之间的 Parquet/Avro/ORC 映射推导得出。因此,用户无法指定 |
|
必须为 NULL,因为列名和数据类型会自动从 Iceberg 元数据派生。 |
|
有关详细信息,请参阅 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 表的示例格式参数
format
参数样例如下所示:format => json_object('access_protocol' value
json_object('protocol_type' value 'iceberg')
使用 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
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 (参数) | 说明 |
---|---|
|
外部表的名称。 |
|
用于访问云对象存储的身份证明的名称。 使用 |
|
此参数指定源文件 URI 的逗号分隔列表,或者指定一个或多个目录和源文件。 云源文件 URI 您可以在云源文件 URI 中的文件名中使用通配符和正则表达式。 仅当 当 URI 中的文件名或子文件夹路径仅支持正则表达式模式,并且模式匹配与 只有在对象存储中为文件创建的外部表支持此选项。 例如:
URI 的格式取决于您使用的云对象存储服务,有关详细信息,请参见云对象存储 URI 格式。 有关 目录 可以指定一个目录和一个或多个文件名,也可以使用目录和文件名的逗号分隔列表。指定目录的格式为: 可以使用通配符指定目录中的文件名。字符 "*" 可以用作多个字符的通配符,字符 "?" 可以用作单个字符的通配符。例如: 要指定多个目录,请使用逗号分隔的目录列表:例如: 使用双引号指定区分大小写的目录名称。例如: 要包括引号字符,请使用两个引号。例如: |
|
(可选)此字段在指定时将覆盖 为 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 。 |
|
忽略 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 。 |
|
有关 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 (参数) | 说明 |
---|---|
|
用于访问云对象存储位置的身份证明的名称。对于公共、预先验证的或预先签名的存储桶 URI,可以指定 NULL。 如果未提供 |
location_uri |
指定对象存储存储存储桶或文件夹 URI。 此参数是必需的。 URI 的格式取决于云对象存储服务。有关更多信息,请参见 DBMS_CLOUD Package File Cloud Object Storage URI Formats 。 |
index_name |
指定要在位于 location_uri 位置的文件上构建的索引的名称。
此参数是必需的。 |
|
指定其他配置选项。选项指定为 JSON 字符串。 支持的格式选项包括:
可以使用以下方法指定停止词:
如果未提供 |
范例
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 (参数) | 说明 |
---|---|
|
外部表的名称。 |
|
用于访问云对象存储的身份证明的名称。 |
|
指定完整的分区子句,包括各个分区的位置信息。 要使用目录,分区子句支持 您可以在云源文件 URI 中的文件名中使用通配符和正则表达式。 仅当 当 URI 中的文件名或子文件夹路径仅支持正则表达式模式,并且模式匹配与 例如:
有关 |
|
外部表的列名和数据类型的逗号分隔列表。 |
|
标识源文件中的字段及其数据类型。默认值为 NULL,表示字段及其数据类型由 column_list 参数确定。此参数的语法与常规 Oracle 外部表中的 |
|
描述源文件格式的选项。有关选项列表以及如何指定值的信息,请参阅设置参数格式。 |
使用说明
-
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 (参数) | 说明 |
---|---|
|
指定要删除的操作类型。可以在 如果未指定 |
使用说明
-
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 (参数) | 说明 |
---|---|
|
Autonomous Database 实例上的目录名称。 |
|
要删除的文件的名称。 |
force |
如果文件不存在,则忽略并不报告错误。有效值包括: |
注意:
要对 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 (参数) | 说明 |
---|---|
|
用于访问云对象存储的身份证明的名称。 |
object_uri |
要删除的对象或文件 URI。URI 的格式取决于您使用的云对象存储服务,有关详细信息,请参见云对象存储 URI 格式。 |
force |
如果对象不存在,则忽略并且不报告错误。有效值包括: |
范例
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。 |
范例
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 过程
根据 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 (参数) | 说明 |
---|---|
|
用于访问云对象存储的身份证明的名称。 不包括身份证明参数时,这将指定目录的输出。 |
|
有不同的表单,具体取决于格式参数的值以及是否包含身份证明参数:
URI 的格式取决于您正在使用的云对象存储服务,有关详细信息,请参见云对象存储 URI 格式。 |
|
提供导出格式选项的 JSON 字符串。 支持的选项为:
|
|
使用此参数可以指定 SELECT warehouse_id, quantity FROM inventories 当 例如: SELECT JSON_OBJECT(* RETURNING CLOB) from(SELECT warehouse_id, quantity FROM inventories) |
|
使用此参数以 |
使用说明:
-
如果需要,您提供的
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 (参数) | 说明 |
---|---|
|
用于访问云对象存储的身份证明的名称。 |
|
对象或文件 URI。URI 的格式取决于您使用的云对象存储服务,有关详细信息,请参见云对象存储 URI 格式。 |
|
数据库中目录的名称。 英尺 1 |
|
指定要创建的文件的名称。如果未指定文件名,则从 |
startoffset |
过程开始读取的偏移量(以字节为单位)。 |
endoffset |
以字节为单位的偏移量,直到过程停止读取为止。 |
|
指定用于存储对象的压缩。将 |
脚注 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 (参数) | 说明 |
---|---|
|
数据库中目录的名称。 |
使用说明
-
要对 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
。
范例
这是一个流水线函数,为每个文件返回一行。例如,使用以下查询可使用此函数:
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
LIST_OBJECTS 函数
此函数列出对象存储上指定位置中的对象。结果包括对象名称以及有关对象的其他元数据,例如大小、校验和、创建时间戳和上次修改时间戳。
语法
DBMS_CLOUD.LIST_OBJECTS
(
credential_name IN VARCHAR2,
location_uri IN VARCHAR2)
RETURN TABLE;
参数
Parameter (参数) | 说明 |
---|---|
|
用于访问云对象存储的身份证明的名称。 |
location_uri |
对象或文件 URI。URI 的格式取决于您使用的云对象存储服务,有关详细信息,请参见云对象存储 URI 格式。 |
使用说明
-
根据对象存储的功能,
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 (参数) | 说明 |
---|---|
|
用于访问源云对象存储的身份证明的名称。 如果未提供 |
|
指定指向源对象存储存储桶或文件夹位置的 URI。 此参数是必需的。 URI 的格式取决于云对象存储服务。有关更多信息,请参见 Cloud Object Storage URI Formats 。 |
|
指定需要将文件移动到的目标对象存储存储桶或文件夹的 URI。 此参数是必需的。 URI 的格式取决于云对象存储服务。有关更多信息,请参见 Cloud Object Storage URI Formats 。 |
|
用于访问目标云对象存储位置的身份证明的名称。 如果未提供 |
范例
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 (参数) | 说明 |
---|---|
|
用于访问云对象存储的身份证明的名称。 |
|
对象或文件 URI。URI 的格式取决于您使用的云对象存储服务,有关详细信息,请参见云对象存储 URI 格式。 |
|
Autonomous Database 上目录的名称。 英尺 1 |
|
指定要从 Autonomous Database 复制到云对象存储的 |
|
指定目录中文件的名称。 |
|
指定用于存储对象的压缩。 默认值: |
脚注 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 (参数) | 说明 |
---|---|
|
目标表的名称。在运行 |
|
目标表所在的方案的名称。默认值为 NULL,表示目标表与运行该过程的用户处于相同的方案中。 |
|
新文件可能会对方案进行更改。支持的更新包括:新列、删除的列。对现有列的更新,例如数据类型更改会引发错误。 默认值: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 (参数) | 说明 |
---|---|
|
外部表的名称。 |
|
使用此参数以 |
|
如果已定义,则仅验证特定分区。如果未指定,则按顺序读取所有分区,直到达到 |
|
如果已定义,则仅验证特定的子分区。如果未指定,则从所有外部分区或子分区依次读取,直到达到 |
|
外部表所在的方案的名称。默认值为 NULL,表示外部表与运行该过程的用户位于相同的方案中。 |
|
要扫描的行数。默认值为 NULL,表示将扫描源文件中的所有行。 |
|
仅供内部使用。请勿使用此参数。 |
|
确定在拒绝行时验证是否应停止。默认值为 |
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 (参数) | 说明 |
---|---|
|
外部表的名称。 |
|
使用此参数以 |
|
外部表所在的方案的名称。默认值为 NULL,表示外部表与运行该过程的用户位于相同的方案中。 |
|
要扫描的行数。默认值为 NULL,表示将扫描源文件中的所有行。 |
|
确定在拒绝行时验证是否应停止。默认值为 如果外部表引用了 Avro、ORC 或 Parquet 文件,则验证将在第一个被拒绝的行停止。 当外部表将 |
使用说明
-
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 (参数) | 说明 |
---|---|
|
外部表的名称。 |
|
使用此参数以 |
|
如果已定义,则仅验证特定分区。如果未指定,则从所有外部分区依次读取,直到达到 |
|
如果已定义,则仅验证特定的子分区。如果未指定,则从所有外部分区或子分区依次读取,直到达到 |
|
外部表所在的方案的名称。默认值为 NULL,表示外部表与运行该过程的用户位于相同的方案中。 |
|
要扫描的行数。默认值为 NULL,表示将扫描源文件中的所有行。 |
|
仅供内部使用。请勿使用此参数。 |
|
确定在拒绝行时验证是否应停止。默认值为 |