DBMS_CLOUD_PIPELINE 程序包

DBMS_CLOUD_PIPELINE 软件包允许您创建数据管道以在云中加载和导出数据。此程序包支持将对象存储中的文件连续增量数据加载到数据库中。DBMS_CLOUD_PIPELINE 还支持根据时间戳列连续增量导出表数据或从数据库到对象存储的查询结果。

Prerequisites

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

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

您的组管理员必须使用 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_PIPELINE 子程序摘要

此表汇总了 DBMS_CLOUD_PIPELINE 软件包中包含的子程序。

子程序 说明

CREATE_PIPELINE 过程

创建新数据管道。

DROP_PIPELINE 过程

删除现有数据管道。

RESET_PIPELINE 过程

重置数据管道的跟踪状态。使用重置管道从数据加载或导出的初始状态重新启动管道。(可选)重置管道可以清除数据库或对象存储中的数据,具体取决于管道的类型。

RUN_PIPELINE_ONCE 过程

在当前前台会话中按需运行管道,而不是执行调度的作业。

SET_ATTRIBUTE 过程

设置管道属性。有两个重载过程,一个用于设置单个属性,另一个用于使用属性名称/值对的 JSON 文档设置多个属性

START_PIPELINE 过程

启动数据管道。启动管道时,管道操作将根据管道属性中配置的“间隔”在调度的作业中连续运行。

STOP_PIPELINE 过程

停止数据管道。停止管道时,不会为该管道安排将来作业。

CREATE_PIPELINE 过程

该过程将创建新数据管道。

语法

DBMS_CLOUD_PIPELINE.CREATE_PIPELINE(
      pipeline_name        IN   VARCHAR2,
      pipeline_type        IN   VARCHAR2,
      attributes           IN   CLOB        DEFAULT NULL,
      description          IN   VARCHAR2    DEFAULT NULL
);

参数

Parameter (参数) 说明

pipeline_name

指定管道的名称。管道名称必须遵循 Oracle SQL 标识符的命名规则。有关详细信息,请参阅 Oracle Database Database PL/SQL Language ReferenceOracle Database 23ai Database PL/SQL Language Reference 中的 Identifiers

此参数是必需的。

pipeline_type

指定管道类型。

有效值:LOADEXPORT

此参数是必需的。

attributes

JSON 格式的管道属性。

默认值:NULL

有关更多信息,请参见DBMS_CLOUD_PIPELINE Attributes

description

管道的说明。

默认值:NULL

DROP_PIPELINE 过程

该过程将删除现有数据管道。如果某个管道已启动,则必须先停止该管道,然后才能将其删除。

语法

DBMS_CLOUD_PIPELINE.DROP_PIPELINE(
       pipeline_name        IN   VARCHAR2,
       force                IN   BOOLEAN DEFAULT FALSE
 );

参数

Parameter (参数) 说明

pipeline_name

指定管道名称。

此参数是必需的。

force

强制删除管道,即使它处于已启动状态也是如此。

有效值:TRUEFALSE

默认值:FALSE

使用说明

  • 要删除处于已启动状态的管道,请将 force 参数设置为 TRUE

RESET_PIPELINE 过程

重置数据管道的跟踪状态。使用重置管道从数据加载或导出的初始状态重新启动管道。(可选)重置管道可以清除数据库或对象存储中的数据,具体取决于管道的类型。要重置数据管道,数据管道必须处于停止状态。

语法

DBMS_CLOUD_PIPELINE.RESET_PIPELINE(
       pipeline_name        IN   VARCHAR2,
       purge_data           IN   BOOLEAN DEFAULT FALSE
 );

参数

Parameter (参数) 说明

pipeline_name

指定管道的名称。

此参数是必需的。

purge_data

清除数据适用于加载管道或导出管道:

  • 对于加载管道,当 TRUE 时,截断数据库表中的数据。

  • 对于导出管道,当 TRUE 时,删除对象存储位置中的文件。

有效值:TRUEFALSE

默认值:FALSE

使用说明

  • 要重置数据管道,数据管道必须处于停止状态。有关更多信息,请参见STOP_PIPELINE Procedure

  • 对于加载管道,重置管道将清除管道正在加载的文件的记录。重置加载管道后调用 START_PIPELINERUN_PIPELINE_ONCE 时,管道会重复数据加载并包括对象存储位置中存在的所有文件。

    purge_data 设置为 TRUE 时,DBMS_CLOUD_PIPELINE.RESET_PIPELINE 将执行以下操作:

    • 截断使用 table_name 属性指定的管道数据库表中的数据。

    • 删除管道的状态表,以及管道的错误文件表和错误表(如果存在)。

  • 对于导出管道,重置管道将清除数据库表中上次跟踪的数据。重置导出管道后调用 START_PIPELINERUN_PIPELINE_ONCE 时,管道将重复从表或查询导出数据。

    purge_data 设置为 TRUE 时,DBMS_CLOUD_PIPELINE.RESET_PIPELINE 将删除使用 location 属性指定的对象存储位置中的现有文件。

RUN_PIPELINE_ONCE 过程

此过程在当前前台会话中按需运行管道,而不是在调度的作业中运行。在将管道作为连续作业启动之前,使用 DBMS_CLOUD_PIPELINE.RUN_PIPELINE_ONCE 测试管道。

语法

DBMS_CLOUD_PIPELINE.RUN_PIPELINE_ONCE(
       pipeline_name  IN  VARCHAR2
);

参数

Parameter (参数) 说明

pipeline_name

指定要运行的管道名称。

此参数是必需的。

使用说明

  • 对管道执行测试运行后,可以使用 DBMS_CLOUD_PIPELINE.RESET_PIPELINE 重置管道状态。这允许您在计划作业中启动管道之前重置管道状态。

  • 如果管道处于已启动状态,则它无法在前台会话中运行。

SET_ATTRIBUTE 过程

此过程设置管道属性。有两个重载过程,一个用于设置单个属性,另一个用于使用属性名称/值对的 JSON 文档设置多个属性。

语法

PROCEDURE DBMS_CLOUD_PIPELINE.SET_ATTRIBUTE(
      pipeline_name        IN   VARCHAR2,
      attribute_name       IN   VARCHAR2,
      attribute_value      IN   CLOB
);
 
PROCEDURE DBMS_CLOUD_PIPELINE.SET_ATTRIBUTE(
      pipeline_name        IN   VARCHAR2,
      attributes           IN   CLOB
);

参数

Parameter (参数) 说明

pipeline_name

指定管道的名称以设置属性。

此参数是必需的。

attribute_name

指定要设置的属性的属性名。

有关更多信息,请参见DBMS_CLOUD_PIPELINE Attributes

attribute_value

指定管道属性的值。

有关更多信息,请参见DBMS_CLOUD_PIPELINE Attributes

attributes

指定包含属性名称和值的 JSON 文档。

有关更多信息,请参见DBMS_CLOUD_PIPELINE Attributes

使用说明

  • 使用 DBMS_CLOUD_PIPELINE.SET_ATTRIBUTE 使用 attributes 参数设置多个属性时,将删除所有现有属性并使用 JSON 文档中的指定属性进行覆盖。

START_PIPELINE 过程

该过程将启动数据管道。启动管道时,管道操作会根据使用管道属性配置的 interval 在调度的作业中连续运行。

语法

DBMS_CLOUD_PIPELINE.START_PIPELINE(
      pipeline_name        IN   VARCHAR2,
      start_date           IN   TIMESTAMP WITH TIME ZONE DEFAULT NULL
);

参数

Parameter (参数) 说明

pipeline_name

指定管道的名称。

此参数是必需的。

start_date

指定管道作业的开始日期。

默认值:NULL

使用说明

  • 默认情况下,管道作业在管道启动后立即开始。要稍后启动管道作业,请使用 start_date 参数指定有效的日期或时间戳。

  • 有关管道 interval 和其他管道属性的信息,请参阅 DBMS_CLOUD_PIPELINE 属性

STOP_PIPELINE 过程

该过程将停止数据管道。停止管道时,不会为该管道安排将来作业。

语法

DBMS_CLOUD_PIPELINE.STOP_PIPELINE(
      pipeline_name        IN   VARCHAR2,
      force                IN   BOOLEAN  DEFAULTFALSE
);

参数

Parameter (参数) 说明

pipeline_name

指定管道的名称。

此参数是必需的。

force

如果强制参数传递为 TRUE,则它将终止管道的任何正在运行的作业。

有效值:TRUE, FALSE

默认值:FALSE

DBMS_CLOUD_PIPELINE 属性

属性有助于控制和配置数据管道的行为。

属性

注意:

管道类型列中所示,根据管道类型 LOADEXPORT,管道支持一组不同的属性。
属性名称 说明 管道类型 管道启动后可修改
credential_name

用于访问源云对象存储的身份证明的名称。

默认值:NULL

如果未提供 credential_name,则将 credential_name 设置为 NULL

LOAD, EXPORT
field_list

标识源文件中的字段及其数据类型。此参数的语法与常规 Oracle 外部表中的 field_list 子句相同。有关详细信息,请参阅 Oracle Database 19c UtilitiesOracle Database 23ai Utilities 中的 field_list

默认值:NULL

默认值指定字段及其数据类型由 table_name 属性中指定的表中的列确定。

LOAD
format

描述管道类型格式的选项。

导出管道不支持数据泵 format

此属性对于 LOADEXPORT 管道都是必需的。

LOAD, EXPORT
interval

调度的管道作业的连续执行之间的时间间隔(以分钟为单位)。

默认值:15 分钟

LOAD, EXPORT
key_column

指定 tablequery 中的时间戳或日期列,用于连续将较新数据导出到对象存储。上次执行时间戳或日期由导出管道跟踪,并与 key_column 中的值进行比较,以确定要导出到对象存储的新数据。

默认值:NULL

如果没有为导出管道指定 key_column,则 tablequery 的全部内容将上载到每个管道作业执行中的对象存储。

EXPORT
location

指定指向对象存储位置的 URI。

URI 的格式取决于云对象存储服务。有关更多信息,请参见 Cloud Object Storage URI Formats

此属性对于 LOADEXPORT 管道都是必需的。

LOAD, EXPORT
priority

指定一个字符串值,用于确定为管道执行的并行操作数。

  • 在加载管道中,它确定并行加载的文件数。

  • 在导出管道中,它确定从数据库提取数据的并行度。

优先级较高的操作会消耗更多数据库资源并更快完成。

有效值包括:

  • HIGH:确定使用数据库的 ECPU 计数处理的并行文件数(如果数据库使用 OCPU,则为 OCPU 计数
  • MEDIUM:使用中型服务的并发限制确定同时进程的数量。默认值为 4。
  • LOW:按序列顺序运行管道作业。

默认值:MEDIUM

最大并发文件操作数限制为 64。

LOAD, EXPORT
query

指定 SELECT 语句,以便仅导出所需的数据。该查询确定作为文本文件( CSV、JSON、Parquet 或 XML )或转储文件导出的文件的内容。

例如:

SELECT warehouse_id, quantity FROM inventories

默认值:NULL

对于导出管道,必须提供 table_namequery

EXPORT
table_name

指定用于加载或导出数据的目标表的名称。

对于加载管道,必须提供 table_name

对于导出管道,必须提供 table_namequery

LOAD, EXPORT
table_owner

目标表所在的用于加载或导出数据的方案的名称。

默认值:NULL

使用 NULL 值时,目标表与运行该过程的用户处于同一方案中。

LOAD, EXPORT