Operaciones masivas para archivos en la nube

Acerca de las Operaciones de Archivos en Bloque

Las operaciones de archivo en bloque de DBMS_CLOUD soportan la descarga y carga de archivos en Autonomous Database, incluido el soporte para copiar, mover y suprimir archivos en almacenes de objetos en la nube, ya sea dentro del mismo proveedor del almacén de objetos o entre proveedores del almacén de objetos.

Las operaciones de archivos en bloque soportan el paralelismo y proporcionan un rendimiento óptimo para cargar, descargar, copiar y mover archivos. El paralelismo para operaciones de archivos en bloque se maneja especificando una prioridad para una operación. Las prioridades apoyadas son:

HIGH: utilice el recuento de recursos informáticos de CPU de la instancia de Autonomous Database para determinar el número de archivos paralelos procesados.
MEDIUM: utilice el límite de simultaneidad para el servicio Medium para determinar el paralelismo.
LOW: procesa los archivos en orden serie (sin simultaneidad).

La ejecución de operaciones masivas con mayor prioridad utiliza más recursos de base de datos y las operaciones se completan más rápido cuando el paralelismo puede acelerar la operación. Una prioridad más baja consume menos recursos de base de datos y las operaciones tardan más en completarse cuando el paralelismo puede acelerar la operación. Cuando las operaciones masivas implican un número pequeño de archivos que contienen pocos datos, la especificación de una prioridad más alta puede no cambiar el rendimiento.

Para aumentar el paralelismo de las operaciones de archivos en bloque, utilice la prioridad HIGH y aumente el número de CPU asignadas a la instancia de Autonomous Database. El máximo de operaciones de archivos simultáneos admitidas está limitado a 64 para operaciones de archivos masivos.

La prioridad predeterminada es MEDIUM, que especifica que las operaciones de archivos masivos utilizan el límite de simultaneidad definido para el grupo de consumidores MEDIUM.

Consulte DBMS_CLOUD para la gestión de archivos en bloque para obtener detalles sobre el uso del parámetro format para especificar priority con operaciones de archivos en bloque.

En los subprogramas DBMS_CLOUD que se describen a continuación, credential_name, source_credential_name o target_credential_name pueden ser NULL para el URI de cubo público, autenticado previamente o firmado previamente.

Copia masiva de archivos en el almacenamiento de objetos en la nube

Utilice el procedimiento DBMS_CLOUD.BULK_COPY para copiar en bloque archivos de un cubo o carpeta del almacén de objetos a otro cubo o carpeta.

Cree un objeto de credencial para acceder a la ubicación de origen.

El nombre de credencial de origen, como se especifica con el parámetro source_credential_name, también se utiliza por defecto como credencial para la ubicación de destino.

Consulte CREATE_CREDENTIAL para obtener más información.
Cuando el origen y el destino están en distintos almacenes de objetos o tienen cuentas diferentes con el mismo proveedor de nube, cree una credencial para acceder a la ubicación de destino e incluya el parámetro target_credential_name.
Ejecute el procedimiento DBMS_CLOUD.BULK_COPY para copiar archivos en paralelo de un cubo o carpeta del almacén de objetos a otro cubo o carpeta que puede ser entre proveedor, cuentas y cubos en la nube. Para ejecutar el procedimiento, debe estar conectado como administrador o tener el privilegio EXECUTE en DBMS_CLOUD.
```
BEGIN 
DBMS_CLOUD.BULK_COPY (
      source_credential_name => 'OCI_CRED',
      source_location_uri    => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname1/o',
      target_location_uri    => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname2/o',
      format                 => JSON_OBJECT ('logretention' value 7, 'logprefix' value 'BULKOP')
);
END;
/
```
En este ejemplo, se copian en bloque archivos de un cubo de Oracle Cloud Infrastructure Object Storage a otro.

Consulte BULK_COPY Procedimiento para obtener más información.

Consulte DBMS_CLOUD Formatos de URI de almacenamiento de objetos en la nube de archivos del paquete para obtener más información.

Por ejemplo, utilice DBMS_CLOUD.BULK_COPY para copiar archivos de Amazon S3 en Oracle Cloud Infrastructure Object Storage.

BEGIN
DBMS_CLOUD.BULK_COPY(      
      source_credential_name  => 'AWS_CRED',
      source_location_uri     => 'https://bucketname.s3-us-west-2.amazonaws.com/',
      target_credential_name  => 'OCI_CRED',
      target_location_uri     => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname2/o',
      format                  =>  JSON_OBJECT ('logretention' value 7, 'logprefix' value 'BULKOP')
);
END;
/

Traslado masivo de archivos a través de Cloud Object Storage

Utilice el procedimiento DBMS_CLOUD.BULK_MOVE para mover archivos de forma masiva de una ubicación de Cloud Object Storage a otra.

El primer paso para mover archivos es copiarlos en la ubicación de destino. Después de que los archivos se copian correctamente, se suprimen de la ubicación de origen.

Los archivos se cambian de nombre en lugar de copiarse si el almacén de objetos permite las operaciones de cambio de nombre entre las ubicaciones de origen y destino.

Cree un objeto de credencial para acceder a la ubicación de origen.

El nombre de credencial de origen, como se especifica con el parámetro source_credential_name, también se utiliza por defecto como credencial para la ubicación de destino.

Consulte CREATE_CREDENTIAL para obtener más información.
Cuando el origen y el destino están en distintos almacenes de objetos o tienen cuentas diferentes con el mismo proveedor de nube, cree una credencial para acceder a la ubicación de destino e incluya el parámetro target_credential_name.
Ejecute el procedimiento DBMS_CLOUD.BULK_MOVE para mover archivos de forma masiva de una ubicación de Cloud Object Storage a otra. Para ejecutar el procedimiento, debe estar conectado como administrador o tener el privilegio EXECUTE en DBMS_CLOUD.
```
BEGIN 
DBMS_CLOUD.BULK_MOVE (    
     source_credential_name => 'OCI_CRED',
     source_location_uri    => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname1/o',
     target_location_uri    => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname2/o',
     format                 => JSON_OBJECT ('logretention' value 7, 'logprefix' value 'BULKMOVE')
);
END;
/
```
En este ejemplo, se mueven en bloque archivos de una ubicación de Oracle Cloud Infrastructure Object Storage a otra.

Consulte procedimiento BULK_MOVE para obtener más información.

Consulte DBMS_CLOUD Formatos de URI de almacenamiento de objetos en la nube de archivos del paquete para obtener más información.

Por ejemplo, utilice DBMS_CLOUD.BULK_MOVE para mover archivos de Amazon S3 a Oracle Cloud Infrastructure Object Storage.

BEGIN
DBMS_CLOUD.BULK_MOVE(      
      source_credential_name  => 'AWS_CRED',
      source_location_uri     => 'https://bucketname.s3-us-west-2.amazonaws.com/',
      target_credential_name  => 'OCI_CRED',
      target_location_uri     => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname2/o',
      format                  =>  JSON_OBJECT ('logretention' value 7, 'logprefix' value 'BULKOP')
);
END;
/

Descarga masiva de archivos desde Cloud Object Storage

Utilice el procedimiento DBMS_CLOUD.BULK_DOWNLOAD para descargar en bloque archivos de la ubicación del almacén de objetos en la nube al objeto de directorio en una instancia de Autonomous Database.

Cree una credencial para acceder a Cloud Object Storage.

El nombre de credencial se especifica con el parámetro credential_name.

Consulte CREATE_CREDENTIAL para obtener más información.
Ejecute el procedimiento DBMS_CLOUD.BULK_DOWNLOAD para descargar archivos en un directorio de Autonomous Database desde Cloud Object Storage. Para ejecutar el procedimiento, debe estar conectado como administrador o tener el privilegio EXECUTE en DBMS_CLOUD.
```
BEGIN
DBMS_CLOUD.BULK_DOWNLOAD (
     credential_name => 'OCI_CRED',
     location_uri    => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o',
     directory_name  => 'BULK_TEST',
     format          => JSON_OBJECT ('logretention' value 7, 'logprefix' value 'BULKOP')
 );
END;
/
```
En este ejemplo se descargan en bloque archivos del URI de ubicación del almacén de objetos de Oracle Cloud Infrastructure en el objeto de directorio de una instancia de Autonomous Database.

Note:
Para escribir los archivos en el objeto de directorio de destino, debe tener el privilegio WRITE en el objeto de directorio.

Consulte procedimiento BULK_DOWNLOAD para obtener más información.

Consulte DBMS_CLOUD Formatos de URI de almacenamiento de objetos en la nube de archivos del paquete para obtener más información.

Carga masiva de archivos en Cloud Object Storage

Utilice el procedimiento DBMS_CLOUD.BULK_UPLOAD para cargar archivos de forma masiva desde un objeto de directorio en la base de datos a una ubicación del almacén de objetos en la nube.

Cree una credencial para acceder a Cloud Object Storage.

El nombre de credencial se especifica con el parámetro credential_name.

Consulte CREATE_CREDENTIAL para obtener más información.
Ejecute el procedimiento DBMS_CLOUD.BULK_UPLOAD para copiar archivos en Cloud Object Storage desde un directorio de base de datos en la instancia de Autonomous Database. Para ejecutar el procedimiento, debe estar conectado como administrador o tener el privilegio EXECUTE en DBMS_CLOUD.
```
BEGIN
DBMS_CLOUD.BULK_UPLOAD (    
     credential_name => 'OCI_CRED',
     location_uri    => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o',
     directory_name  => 'BULK_TEST',
     format          => JSON_OBJECT ('logretention' value 5, 'logprefix' value 'BULKUPLOAD')
 );
END;
/
```
En este ejemplo se cargan archivos en bloque desde un objeto de directorio, como se especifica con el parámetro directory_name en el URI de ubicación del almacén de objetos de Oracle Cloud Infrastructure.

Note:
Para leer los archivos de origen en el objeto de directorio, debe tener el privilegio READ en el objeto de directorio.

Consulte procedimiento BULK_UPLOAD para obtener más información.

Supresión masiva de archivos de Cloud Object Storage

Utilice el procedimiento DBMS_CLOUD.BULK_DELETE para suprimir en bloque archivos de Cloud Object Storage.

Cree una credencial para acceder a Cloud Object Storage.

El nombre de credencial se especifica con el parámetro credential_name.

credential_name puede ser NULL para el URI de cubo público, autenticado previamente o firmado previamente.

Consulte CREATE_CREDENTIAL para obtener más información.
Ejecute el procedimiento DBMS_CLOUD.BULK_DELETE para suprimir archivos del almacén de objetos en la nube. Para ejecutar el procedimiento, debe estar conectado como administrador o tener el privilegio EXECUTE en DBMS_CLOUD.
```
BEGIN
DBMS_CLOUD.BULK_DELETE (    
     credential_name => 'OCI_CRED',
     location_uri    => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o',
     format          => JSON_OBJECT ('logretention' value 5, 'logprefix' value 'BULKDEL')
);
END;
/
```
En este ejemplo se suprimen en bloque archivos del almacén de objetos de Oracle Cloud Infrastructure.

Consulte el procedimiento BULK_DELETE para obtener más información.

Consulte DBMS_CLOUD Formatos de URI de almacenamiento de objetos en la nube de archivos del paquete para obtener más información.

Supervisión y solución de problemas de cargas de archivos masivas

Todas las operaciones de carga de datos DBMS_CLOUD se registran en las vistas dba_load_operations y user_load_operations.

Puede utilizar las siguientes vistas para supervisar y solucionar problemas de cargas de archivos masivas:

dba_load_operations: muestra todas las operaciones de carga.
user_load_operations: muestra las operaciones de carga del esquema.

Consulte estas vistas para ver información sobre las operaciones de archivos masivos en curso y finalizadas. Por ejemplo, la siguiente sentencia SELECT con un predicado de cláusula WHERE en TYPE, se muestran las operaciones DOWNLOAD:


SELECT owner_name, type, status, start_time, update_time, status_table, rows_loaded 
   FROM user_load_operations WHERE type = 'DOWNLOAD';

OWNER_NAME TYPE     STATUS    START_TIME               UPDATE_TIME              STATUS_TABLE ROWS_LOADED 
---------- -------- --------- ------------------------ ------------------------ ------------ ----------- 
"ADMIN"    DOWNLOAD COMPLETED 2022-10-17T20:42:19.498Z 2022-10-17T20:42:21.054Z DWN$2_STATUS           4 
"ADMIN"    DOWNLOAD FAILED    2022-10-17T20:40:54.348Z 2022-10-17T20:40:55.679Z DWN$1_STATUS

La columna STATUS_TABLE muestra el nombre de la tabla que puede consultar para consultar la información de registro detallada de la operación de descarga masiva. Por ejemplo:

DESCRIBE DWN$2_STATUS
Name          Null?    Type                        
------------- -------- --------------------------- 
ID            NOT NULL NUMBER                      
NAME                   VARCHAR2(4000)              
BYTES                  NUMBER                      
CHECKSUM               VARCHAR2(128)               
LAST_MODIFIED          TIMESTAMP(6) WITH TIME ZONE 
STATUS                 VARCHAR2(30)                
ERROR_CODE             NUMBER                      
ERROR_MESSAGE          VARCHAR2(4000)              
START_TIME             TIMESTAMP(6) WITH TIME ZONE 
END_TIME               TIMESTAMP(6) WITH TIME ZONE 
SID                    NUMBER                      
SERIAL#                NUMBER                      
ROWS_LOADED            NUMBER                      

SELECT id, name, bytes, status, error_message, start_time, end_time FROM DWN$2_STATUS;
ID NAME       BYTES STATUS    ERROR_MESSAGE START_TIME               END_TIME                 
-- ---------- ----- --------- ------------- ------------------------ ------------------------ 
 1 trees.txt     58 COMPLETED               2022-10-17T20:42:19.998Z 2022-10-17T20:42:20.421Z 
 2 trees1.txt    58 COMPLETED               2022-10-17T20:42:20.425Z 2022-10-17T20:42:20.533Z 
 3 trees2.txt    58 COMPLETED               2022-10-17T20:42:20.535Z 2022-10-17T20:42:20.894Z 
 4 trees3.txt    58 COMPLETED               2022-10-17T20:42:20.896Z 2022-10-17T20:42:21.043Z

La tabla de estado muestra cada nombre de archivo y su estado para la operación en bloque.

El número de error y el mensaje relevantes se registran en la tabla de estado si falla una operación en un archivo específico.

Para las operaciones finalizadas, el tiempo necesario para cada operación se puede calcular con las horas informadas START_TIME y END_TIME.

La columna STATUS de la operación de archivo puede tener uno de los siguientes valores:

Estado del Archivo	Descripción
`COMPLETED`	La operación de archivo se ha realizado correctamente.
`FAILED`	Fallo en la operación de archivo. Se puede intentar un reintento dos veces.
`PENDING`	La operación de archivo aún no se ha iniciado.
`RUNNING`	La operación de archivo está actualmente en curso.
`SKIPPED`	Se ha saltado la operación de archivo.

Si alguna operación de archivo falla después de dos reintentos, la operación en bloque se marca como fallida y se genera un error. Por ejemplo:

ORA-20003: Operation failed, please query table DOWNLOAD$2_STATUS for error details

Al utilizar una operación de archivo masivo DBMS_CLOUD, hay opciones de parámetro format que controlan las tablas de estado:

logretention: especifica un valor entero que determina la duración en días que se retiene la tabla de estado. El valor por defecto es de 2 días.

logprefix: especifica un valor de cadena que determina el prefijo de nombre de la tabla de estado de operación en bloque.

Cada operación en bloque tiene su propio valor por defecto para la opción logprefix:

Procedimiento	Valor por defecto para `logprefix`
`DBMS_CLOUD.BULK_COPY`	`COPYOBJ`
`DBMS_CLOUD.BULK_DELETE`	`DELETE`
`DBMS_CLOUD.BULK_DOWNLOAD`	`DOWNLOAD`
`DBMS_CLOUD.BULK_MOVE`	`MOVE`
`DBMS_CLOUD.BULK_UPLOAD`	`UPLOAD`

Consulte Procedimiento DELETE_ALL_OPERATIONS para obtener información sobre cómo borrar la tabla user_load_operations.