Paquete DBMS_CLOUD_PIPELINE

El paquete DBMS_CLOUD_PIPELINE permite crear pipelines de datos para cargar y exportar datos en la nube. Este paquete soporta la carga de datos incremental continua de archivos en el almacén de objetos en la base de datos. DBMS_CLOUD_PIPELINE también soporta la exportación incremental continua de datos de tabla o resultados de consulta de la base de datos al almacén de objetos según una columna de registro de hora.

Temas relacionados

Requisitos

Como desarrollador, puede utilizar procedimientos DBMS_CLOUD con instancias de Autonomous Database desplegadas en Oracle Public Cloud, Multicloud o Exadata Cloud@Customer.

En función de la opción de despliegue, se deben cumplir los siguientes requisitos para utilizar los procedimientos DBMS_CLOUD con los proveedores de servicios Amazon S3, Azure Blob Storage y Google Cloud Storage.

El administrador del conjunto debe haber configurado una conectividad saliente mediante un gateway de NAT, como se describe a continuación:
  • Cree un gateway de NAT en la red virtual en la nube (VCN) en la que residan los recursos de Autonomous Database siguiendo las instrucciones de Creación de un gateway de NAT de la Documentación de Oracle Cloud Infrastructure.
  • Después de crear el gateway de NAT, agregue una regla de ruta y una regla de seguridad de salida a cada subred (en la VCN) en la que residan los recursos de Autonomous Database para que estos recursos puedan utilizar el gateway para obtener una clave pública de la instancia de Azure AD:
    1. Vaya a la página Detalles de subred de la subred.
    2. En el separador Información de Subred, haga clic en el nombre de la Tabla de Direcciones de la subred para mostrar su página Detalles de Tabla de Direcciones.
    3. En la tabla de Reglas de ruta existentes, compruebe si ya hay una regla con las siguientes características:
      • Destino: 0.0.0.0/0
      • Tipo de destino: gateway de NAT
      • Destino: nombre del gateway de NAT que acaba de crear en la VCN

      Si dicha regla no existe, haga clic en Agregar reglas de ruta y agregue una regla de ruta con estas características.

    4. Vuelva a la página Detalles de subred de la subred.
    5. En la tabla Listas de seguridad de la subred, haga clic en el nombre de la lista de seguridad de la subred para mostrar su página Detalles de lista de seguridad.
    6. En el menú lateral, en Recursos, haga clic en Reglas de salida.
    7. En la tabla de Reglas de salida existentes, compruebe si ya hay una regla con las siguientes características:
      • Tipo de destino: CIDR
      • Destino: 0.0.0.0/0
      • Protocolo IP: TCP
      • Rango de puertos de origen: 443
      • Rango de puertos de destino: todos

      Si dicha regla no existe, haga clic en Agregar Reglas de Salida y agregue una regla de salida con estas características.

La configuración del proxy HTTP en el entorno debe permitir que la base de datos acceda al proveedor de servicios en la nube.

El administrador del conjunto define esta configuración al crear la infraestructura de Exadata Cloud@Customer, como se describe en Uso de la consola para aprovisionar Exadata Database Service on Cloud@Customer.

Note:

La configuración de red, incluido el proxy HTTP, solo se puede editar hasta que la infraestructura de Exadata tenga el estado Necesita activación. Una vez activada, no puede editar esa configuración.

La configuración de un proxy HTTP para una infraestructura de Exadata ya aprovisionada necesita una solicitud de servicio (SR) en My Oracle Support. Consulte Creación de una solicitud de servicio en My Oracle Support para obtener más información.

Resumen de subprogramas DBMS_CLOUD_PIPELINE

En esta tabla, se resumen los subprogramas incluidos en el paquete DBMS_CLOUD_PIPELINE.

Subprograma Descripción

Procedimiento CREATE_PIPELINE

Crea un nuevo pipeline de datos.

Procedimiento DROP_PIPELINE

Borra un pipeline de datos existente.

Procedimiento RESET_PIPELINE

Restablece el estado de seguimiento de un pipeline de datos. Utilice el pipeline de restablecimiento para reiniciar el pipeline desde el estado inicial de carga o exportación de datos. Si lo desea, el pipeline de restablecimiento puede depurar datos en la base de datos o en el almacén de objetos, según el tipo de pipeline.

Procedimiento RUN_PIPELINE_ONCE

Realiza una ejecución bajo demanda del pipeline en la sesión en primer plano actual, en lugar de un trabajo programado.

Procedimiento SET_ATTRIBUTE

Define atributos de pipeline. Hay dos procedimientos sobrecargados, uno para definir un solo atributo y otro para definir varios atributos mediante un documento JSON de pares de nombre/valor de atributo

Procedimiento START_PIPELINE

Inicia el pipeline de datos. Cuando se inicia un pipeline, la operación de pipeline se ejecutará continuamente en un trabajo programado según el "intervalo" configurado en los atributos de pipeline.

Procedimiento STOP_PIPELINE

Para el pipeline de datos. Cuando se para un pipeline, no se programan trabajos futuros para el pipeline.

Procedimiento CREATE_PIPELINE

El procedimiento crea un nuevo pipeline de datos.

Sintaxis

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

Parámetros

parámetro Descripción

pipeline_name

Especifica un nombre para el pipeline. El nombre del pipeline debe seguir las reglas de nomenclatura de los identificadores SQL de Oracle. Consulte Identificadores en Referencia de lenguaje PL/SQL de Oracle Database Database o Referencia de lenguaje PL/SQL de Oracle Database 23ai Database para obtener más información.

Este parámetro es obligatorio.

pipeline_type

Especifica el tipo de pipeline.

Valores válidos: LOAD, EXPORT

Este parámetro es obligatorio.

attributes

Atributos de pipeline en formato JSON.

Valor por defecto: NULL

Consulte DBMS_CLOUD_PIPELINE Attributes para obtener más información.

description

Descripción del pipeline.

Valor por defecto: NULL

Procedimiento DROP_PIPELINE

El procedimiento borra un pipeline de datos existente. Si se ha iniciado un pipeline, se debe parar para poder borrarlo.

Sintaxis

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

Parámetros

parámetro Descripción

pipeline_name

Especifica un nombre de pipeline.

Este parámetro es obligatorio.

force

Borrar de forma forzada un pipeline, incluso si está en estado iniciado.

Valores válidos: TRUE, FALSE

Valor por defecto: FALSE

Notas de uso

  • Para borrar un pipeline que está en estado iniciado, defina el parámetro force en TRUE.

Procedimiento RESET_PIPELINE

Restablece el estado de seguimiento de un pipeline de datos. Utilice el pipeline de restablecimiento para reiniciar el pipeline desde el estado inicial de carga o exportación de datos. Si lo desea, el pipeline de restablecimiento puede depurar datos en la base de datos o en el almacén de objetos, según el tipo de pipeline. Un pipeline de datos debe estar en estado parado para restablecerlo.

Sintaxis

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

Parámetros

parámetro Descripción

pipeline_name

Especifica un nombre para el pipeline.

Este parámetro es obligatorio.

purge_data

Los datos de depuración se aplican a un pipeline de carga o a un pipeline de exportación:

  • Para un pipeline de carga, cuando TRUE, trunque los datos en la tabla de base de datos.

  • Para un pipeline de exportación, cuando TRUE, suprima los archivos de la ubicación del almacén de objetos.

Valores válidos: TRUE, FALSE

Valor por defecto: FALSE

Notas de uso

  • Un pipeline de datos debe estar en estado parado para restablecerlo. Consulte STOP_PIPELINE Procedimiento para obtener más información.

  • Para un pipeline de carga, al restablecer el pipeline se borra el registro de los archivos que está cargando el pipeline. Cuando llama a START_PIPELINE o a RUN_PIPELINE_ONCE después de restablecer un pipeline de carga, el pipeline repite la carga de datos e incluye todos los archivos presentes en la ubicación del almacén de objetos.

    Cuando purge_data se define en TRUE, DBMS_CLOUD_PIPELINE.RESET_PIPELINE hace lo siguiente:

    • Trunca los datos de la tabla de base de datos del pipeline que especifique con el atributo table_name.

    • Borra la tabla de estado del pipeline, la tabla de archivos y la tabla de errores incorrectos del pipeline (si existen).

  • Para un pipeline de exportación, al restablecer el pipeline se borran los últimos datos con seguimiento de la tabla de la base de datos. Cuando llama a START_PIPELINE o a RUN_PIPELINE_ONCE después de restablecer un pipeline de exportación, el pipeline repite la exportación de datos de la tabla o consulta.

    Cuando purge_data se define en TRUE, DBMS_CLOUD_PIPELINE.RESET_PIPELINE suprime los archivos existentes en la ubicación del almacén de objetos especificada con el atributo location.

Procedimiento RUN_PIPELINE_ONCE

Este procedimiento realiza una ejecución bajo demanda del pipeline en la sesión en primer plano actual, en lugar de una ejecución en un trabajo programado. Utilice DBMS_CLOUD_PIPELINE.RUN_PIPELINE_ONCE para probar un pipeline antes de iniciar el pipeline como un trabajo continuo.

Sintaxis

DBMS_CLOUD_PIPELINE.RUN_PIPELINE_ONCE(
       pipeline_name  IN  VARCHAR2
);

Parámetros

parámetro Descripción

pipeline_name

Especifica un nombre para la ejecución del pipeline.

Este parámetro es obligatorio.

Notas de uso

  • Después de realizar una ejecución de prueba de un pipeline, puede restablecer el estado del pipeline mediante DBMS_CLOUD_PIPELINE.RESET_PIPELINE. Esto le permite restablecer el estado del pipeline antes de iniciar el pipeline en un trabajo programado.

  • Si un pipeline está en estado iniciado, no se puede ejecutar en la sesión de primer plano.

Procedimiento SET_ATTRIBUTE

Este procedimiento define atributos de pipeline. Hay dos procedimientos sobrecargados, uno para definir un solo atributo y otro para definir varios atributos mediante un documento JSON de pares de nombre/valor de atributo.

Sintaxis

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
);

Parámetros

parámetro Descripción

pipeline_name

Especifica un nombre para que el pipeline defina atributos.

Este parámetro es obligatorio.

attribute_name

Especifica el nombre de atributo para el atributo que se va a definir.

Consulte DBMS_CLOUD_PIPELINE Attributes para obtener más información.

attribute_value

Especifica el valor para el atributo de pipeline que se va a definir.

Consulte DBMS_CLOUD_PIPELINE Attributes para obtener más información.

attributes

Especifica un documento JSON que contiene nombres y valores de atributos.

Consulte DBMS_CLOUD_PIPELINE Attributes para obtener más información.

Notas de uso

  • Al utilizar DBMS_CLOUD_PIPELINE.SET_ATTRIBUTE para definir varios atributos con el parámetro attributes, todos los atributos existentes se suprimen y sobrescriben con los atributos especificados del documento JSON.

Procedimiento START_PIPELINE

El procedimiento inicia el pipeline de datos. Cuando se inicia un pipeline, la operación de pipeline se ejecuta continuamente en un trabajo programado según interval configurado con los atributos de pipeline.

Sintaxis

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

Parámetros

parámetro Descripción

pipeline_name

Especifica un nombre para el pipeline.

Este parámetro es obligatorio.

start_date

Especifica la fecha de inicio del trabajo de pipeline.

Valor por defecto: NULL

Notas de uso

  • Por defecto, un trabajo de pipeline comienza inmediatamente, tan pronto como se inicia el pipeline. Para iniciar un trabajo de pipeline más tarde, especifique una fecha o un registro de hora válidos mediante el parámetro start_date.

  • Consulte Atributos de DBMS_CLOUD_PIPELINE para obtener información sobre el pipeline interval y otros atributos de pipeline.

Procedimiento STOP_PIPELINE

El procedimiento para el pipeline de datos. Cuando se para un pipeline, no se programan trabajos futuros para el pipeline.

Sintaxis

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

Parámetros

parámetro Descripción

pipeline_name

Especifica un nombre para el pipeline.

Este parámetro es obligatorio.

force

Si se transfiere el parámetro force como TRUE, terminará cualquier trabajo en ejecución para el pipeline.

Valores válidos: TRUE, FALSE

Valor por defecto: FALSE

Atributos DBMS_CLOUD_PIPELINE

Los atributos ayudan a controlar y configurar el comportamiento de un pipeline de datos.

Atributos

Note:

Como se indica en la columna Tipo de pipeline, según el tipo de pipeline LOAD o EXPORT, un pipeline soporta un juego diferente de atributos.
Nombre del atributo Descripción Tipo de pipeline Modificable después de que se inicie el pipeline
credential_name

Nombre de la credencial para acceder a Cloud Object Storage de origen.

Valor por defecto: NULL.

Si no proporciona credential_name, credential_name se define en NULL.

LOAD, EXPORT Sí
field_list

Identifica los campos en los archivos de origen y sus tipos de datos. La sintaxis de este argumento es la misma que la cláusula field_list de las tablas externas normales de Oracle. Para obtener más información, consulte field_list en Oracle Database 19c Utilities o Oracle Database 23ai Utilities.

Valor por defecto: NULL

El valor por defecto especifica los campos y sus tipos de dato vienen determinados por las columnas de la tabla especificada en el atributo table_name.

LOAD Sí
format

Opciones que describen el formato del tipo de pipeline.

El pump de datos format no está soportado para un pipeline de exportación.

Este atributo es obligatorio para los pipelines LOAD y EXPORT.

LOAD, EXPORT Sí
interval

Intervalo de tiempo en minutos entre ejecuciones consecutivas del trabajo de pipeline programado.

Valor predeterminado: 15 minutos

 LOAD, EXPORT Sí
key_column

Una columna de fecha o registro de hora en table o query especificados para exportar datos más recientes continuamente al almacén de objetos. El pipeline de exportación realiza un seguimiento de la fecha o el registro de hora de la última ejecución y se compara con el valor de key_column para identificar nuevos datos para exportarlos al almacén de objetos.

Valor por defecto: NULL

Si no se especifica key_column para un pipeline de exportación, todo el contenido de table o query se carga en el almacén de objetos en cada ejecución de trabajo de pipeline.

EXPORT N.º
location

Este parámetro especifica el URI o los directorios del archivo de origen y los archivos de origen. Puede utilizar comodines en los nombres de archivo.

Este parámetro es obligatorio.

URI de archivo de origen en la nube

Puede especificar un URI de archivo de origen para el cubo o la subcarpeta. Puede utilizar comodines para especificar subcarpetas o patrones de nombre de archivo. Se puede usar el carácter "*" como comodín para varios caracteres y el carácter "?" se puede utilizar como comodín para un solo carácter.

Ejemplo de uso de comodines:

location_uri => 'https://objectstorage.my$region.oraclecloud.com/n/namespace-string/b/bucketname/o/year=????/month=??/*.csv

El formato de los URI depende del servicio Cloud Object Storage que utilice; para obtener información, consulte Formatos de URI en la nube de almacenamiento de objetos.

Directorio

Puede especificar un directorio y un nombre de archivo. El formato para especificar un directorio es 'MY_DIR:filename.ext'. Por defecto, el nombre de directorio MY_DIR es un objeto de base de datos y no distingue entre mayúsculas y minúsculas. El Nombre del Archivo es sensible a mayúsculas/minúsculas.

Solo puede utilizar comodines para especificar nombres de archivo en un directorio. Se puede usar el carácter "*" como comodín para varios caracteres y el carácter "?" se puede utilizar como comodín para un solo carácter.

Por ejemplo: 'MY_DIR:*" o 'MY_DIR:test?'

Utilice comillas dobles para especificar un nombre de directorio sensible a mayúsculas/minúsculas.

Por ejemplo: '"my_dir1":*, "my_dir2":Test?'

Para incluir un carácter de comillas, utilice dos comillas.

Por ejemplo: 'MY_DIR:''filename.ext'. Especifica que el nombre de archivo empieza por una comilla (').

   
priority

Especifica un valor de cadena que determina el número de operaciones paralelas realizadas para el pipeline.

  • En un pipeline de carga, determina el número de archivos cargados en paralelo.

  • En un pipeline de exportación, determina el grado de paralelismo para recuperar datos de la base de datos.

Una operación con mayor prioridad consume más recursos de base de datos y se completa antes.

Éstos son los valores válidos:

  • HIGH: determina el número de archivos paralelos manejados mediante el recuento de ECPU de la base de datos (recuento de OCPU si la base de datos utiliza OCPU).
  • MEDIUM: determina el número de procesos simultáneos mediante el límite de simultaneidad para el servicio Medium. El valor por defecto es 4.
  • LOW: ejecute el trabajo de pipeline en orden de serie.

Valor por defecto: MEDIUM

El número máximo de operaciones de archivos simultáneas está limitado a 64.

 LOAD, EXPORT Sí
query

Especifica una sentencia SELECT para que solo se exporten los datos necesarios. La consulta determina el contenido de los archivos que exporta como archivos de texto (CSV, JSON, Parquet o XML) o archivos de volcado.

Por ejemplo:

SELECT warehouse_id, quantity FROM inventories

Valor por defecto: NULL

Para un pipeline de exportación, table_name o query es obligatorio.

EXPORT N.º
table_name

Especifica el nombre de la tabla de destino para cargar o exportar datos.

Para un pipeline de carga, table_name es obligatorio.

Para un pipeline de exportación, table_name o query es obligatorio.

LOAD, EXPORT N.º
table_owner

Nombre del esquema en el que reside la tabla de destino para cargar o exportar datos.

Valor por defecto: NULL

Con un valor NULL, la tabla de destino está en el mismo esquema que el usuario que ejecuta el procedimiento.

LOAD, EXPORT N.º