Operações em Lote para Arquivos na Nuvem

Sobre operações de arquivo em massa

As operações de arquivo em massa DBMS_CLOUD suportam download e upload de arquivos no Autonomous AI Database, incluindo suporte para copiar, mover e excluir arquivos nos Cloud Object Stores, dentro do mesmo provedor de Armazenamento de Objetos ou entre provedores de Armazenamento de Objetos.

As operações de arquivo em massa suportam paralelismo e fornecem desempenho ideal para upload, download, cópia e movimentação de arquivos. O paralelismo para operações de arquivo em massa é tratado especificando uma prioridade para uma operação. As prioridades apoiadas são:

HIGH: Use a contagem de computação de CPU da instância do Autonomous AI Database para determinar o número de arquivos paralelos processados.
MEDIUM: Use o limite de simultaneidade do serviço Medium para determinar o paralelismo.
LOW: Processa arquivos em ordem serial (sem simultaneidade).

A execução de operações em massa com prioridade mais alta usa mais recursos e operações de banco de dados completos mais rapidamente quando o paralelismo pode acelerar a operação. Uma prioridade mais baixa consome menos recursos de banco de dados e as operações levam mais tempo para serem concluídas quando o paralelismo pode acelerar a operação. Quando operações em massa envolvem um pequeno número de arquivos que contêm poucos dados, a especificação de prioridade mais alta pode não alterar o desempenho.

Para aumentar o paralelismo para operações de arquivos em massa, use a prioridade HIGH e aumente o número de CPUs designadas à sua instância do Autonomous AI Database. O máximo de operações de arquivo simultâneas suportadas é limitado a 64 para operações de arquivo em massa.

A prioridade padrão é MEDIUM, que especifica que as operações de arquivo em massa usam o limite de simultaneidade definido para o grupo de consumidores MEDIUM.

Consulte DBMS_CLOUD para Gerenciamento de Arquivos em Massa para obter detalhes sobre como usar o parâmetro format para especificar o priority com operações de arquivo em massa.

Nos subprogramas DBMS_CLOUD discutidos abaixo, credential_name, source_credential_name ou target_credential_name podem ser NULL para URI de bucket público, Pré-autenticado ou Pré-assinado.

Copiar Arquivos em Massa no Cloud Object Storage

Use o procedimento DBMS_CLOUD.BULK_COPY para copiar em massa arquivos de um bucket ou pasta do Object Store para outro bucket ou pasta.

Crie um objeto de credencial para acessar o local de origem.

Por padrão, o nome da credencial de origem, conforme especificado com o parâmetro source_credential_name, também é usado como a credencial do local de destino.

Consulte CREATE_CREDENTIAL para obter mais informações.
Quando a origem e o destino estiverem em Armazenamentos de Objetos distintos ou tiverem contas diferentes com o mesmo provedor de nuvem, crie uma credencial para acessar o local de destino e inclua o parâmetro target_credential_name.
Execute o procedimento DBMS_CLOUD.BULK_COPY para copiar arquivos em paralelo de um bucket ou pasta do Object Store para outro bucket ou pasta que possa estar entre provedor de nuvem, contas e buckets. Para executar o procedimento, você deve fazer log-in como usuário ADMIN ou ter o privilégio EXECUTE em 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;
/
```
Este exemplo copia em massa arquivos de um bucket do Oracle Cloud Infrastructure Object Storage para outro.

Consulte BULK_COPY Procedimento para obter mais informações.

Consulte DBMS_CLOUD Formatos de URI do Serviço File Cloud Object Storage para obter mais informações.

Por exemplo, use DBMS_CLOUD.BULK_COPY para copiar arquivos do Amazon S3 para o 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;
/

Mover Arquivos em Massa pelo Cloud Object Storage

Use o procedimento DBMS_CLOUD.BULK_MOVE para mover arquivos em massa de um local do Cloud Object Storage para outro.

O primeiro passo para mover arquivos é copiá-los para o local de destino. Depois que os arquivos forem copiados com sucesso, eles serão excluídos do local de origem.

Os arquivos serão renomeados em vez de copiados se o Armazenamento de Objetos permitir a renomeação de operações entre locais de origem e destino.

Crie um objeto de credencial para acessar o local de origem.

Por padrão, o nome da credencial de origem, conforme especificado com o parâmetro source_credential_name, também é usado como a credencial do local de destino.

Consulte CREATE_CREDENTIAL para obter mais informações.
Quando a origem e o destino estiverem em Armazenamentos de Objetos distintos ou tiverem contas diferentes com o mesmo provedor de nuvem, crie uma credencial para acessar o local de destino e inclua o parâmetro target_credential_name.
Execute o procedimento DBMS_CLOUD.BULK_MOVE para mover arquivos em massa de um local do Cloud Object Storage para outro. Para executar o procedimento, você deve fazer log-in como usuário ADMIN ou ter o privilégio EXECUTE em 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;
/
```
Este exemplo em massa move arquivos de um local do Oracle Cloud Infrastructure Object Storage para outro.

Consulte BULK_MOVE Procedimento para obter mais informações.

Consulte DBMS_CLOUD Formatos de URI do Serviço File Cloud Object Storage para obter mais informações.

Por exemplo, use DBMS_CLOUD.BULK_MOVE para mover arquivos do Amazon S3 para o 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;
/

Download em Massa de Arquivos do Cloud Object Storage

Use o procedimento DBMS_CLOUD.BULK_DOWNLOAD para fazer download em massa de arquivos do local do Cloud Object Store para o objeto de diretório em um Autonomous AI Database.

Crie uma credencial para acessar o Cloud Object Storage.

O nome da credencial é especificado com o parâmetro credential_name.

Consulte CREATE_CREDENTIAL para obter mais informações.
Execute o procedimento DBMS_CLOUD.BULK_DOWNLOAD para fazer download de arquivos em um diretório do Autonomous AI Database no Cloud Object Storage. Para executar o procedimento, você deve estar conectado como usuário ADMIN ou ter o privilégio EXECUTE em 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;
/
```
Este exemplo faz download de arquivos em massa do URI de local do Oracle Cloud Infrastructure Object Store para o objeto de diretório em um Autonomous AI Database.

Observação:
Para gravar os arquivos no objeto de diretório de destino, você deve ter o privilégio WRITE no objeto de diretório.

Consulte BULK_DOWNLOAD Procedimento para obter mais informações.

Consulte DBMS_CLOUD Formatos de URI do Serviço File Cloud Object Storage para obter mais informações.

Upload em Massa de Arquivos para o Cloud Object Storage

Use o procedimento DBMS_CLOUD.BULK_UPLOAD para fazer upload em massa de arquivos de um objeto de diretório no banco de dados para um local do Cloud Object Store.

Crie uma credencial para acessar o Cloud Object Storage.

O nome da credencial é especificado com o parâmetro credential_name.

Consulte CREATE_CREDENTIAL para obter mais informações.
Execute o procedimento DBMS_CLOUD.BULK_UPLOAD para copiar arquivos para o Cloud Object Storage de um diretório de banco de dados na sua instância do Autonomous AI Database. Para executar o procedimento, você deve estar conectado como usuário ADMIN ou ter o privilégio EXECUTE em 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;
/
```
Este exemplo faz upload em massa de arquivos de um objeto de diretório, conforme especificado com o parâmetro directory_name para o URI do local do Armazenamento de Objetos do Oracle Cloud Infrastructure.

Observação:
Para ler os arquivos de origem no objeto de diretório, você deve ter o privilégio READ no objeto de diretório.

Consulte BULK_UPLOAD Procedimento para obter mais informações.

Exclusão em Massa de Arquivos do Cloud Object Storage

Use o procedimento DBMS_CLOUD.BULK_DELETE para excluir arquivos em massa do Cloud Object Storage.

Crie uma credencial para acessar o Cloud Object Storage.

O nome da credencial é especificado com o parâmetro credential_name.

O credential_name pode ser NULL para URI de bucket público, Pré-autenticado ou Pré-assinado.

Consulte CREATE_CREDENTIAL para obter mais informações.
Execute o procedimento DBMS_CLOUD.BULK_DELETE para excluir arquivos do Armazenamento de Objetos na Nuvem. Para executar o procedimento, você deve fazer log-in como usuário ADMIN ou ter o privilégio EXECUTE em 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;
/
```
Este exemplo exclui em massa arquivos do Armazenamento de Objetos do Oracle Cloud Infrastructure.

Consulte BULK_DELETE Procedimento para obter mais informações.

Consulte DBMS_CLOUD Formatos de URI do Serviço File Cloud Object Storage para obter mais informações.

Monitorar e Solucionar Problemas de Cargas de Arquivos em Massa

Todas as operações de carregamento de dados DBMS_CLOUD são registradas nas views dba_load_operations e user_load_operations.

Você pode usar as seguintes exibições para monitorar e solucionar problemas de cargas de arquivos em massa:

dba_load_operations: mostra todas as operações de carga.
user_load_operations: mostra as operações de carga no seu esquema.

Consulte essas exibições para ver informações sobre operações de arquivo em massa em andamento e concluídas. Por exemplo, a seguinte instrução SELECT com um predicado de cláusula WHERE em TYPE mostra operações 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

A coluna STATUS_TABLE mostra o nome da tabela que você pode consultar para verificar informações detalhadas de log da operação de download em massa. Por exemplo:

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

A tabela de status mostra cada nome de arquivo e seu status para a operação em massa.

O número de erro e a mensagem relevantes serão registrados na tabela de status se uma operação em um arquivo específico falhar.

Para operações concluídas, o tempo necessário para cada operação pode ser calculado usando o tempo reportado START_TIME e END_TIME.

A coluna STATUS da operação de arquivo pode ter um dos seguintes valores:

Status do Arquivo	Descrição
`COMPLETED`	Operação de arquivo concluída com sucesso.
`FAILED`	Falha na operação do arquivo. Uma nova tentativa pode ser feita duas vezes.
`PENDING`	A operação do arquivo ainda não foi iniciada.
`RUNNING`	A operação de arquivo está em andamento atualmente.
`SKIPPED`	Operação de arquivo ignorada.

Se qualquer operação de arquivo falhar após duas tentativas de repetição, a operação em massa será marcada como com falha e um erro será gerado. Por exemplo:

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

Quando você usa uma operação de arquivo em massa DBMS_CLOUD, há opções de parâmetro format que controlam tabelas de status:

logretention: Especifica um valor inteiro que determina a duração em dias em que a tabela de status é retida. O valor padrão é 2 dias.

logprefix: Especifica um valor de string que determina o prefixo de nome da tabela de status da operação em massa.

Cada operação em lote tem seu próprio valor padrão para a opção logprefix:

Procedimento	Valor Padrão 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 Procedimento DELETE_ALL_OPERATIONS para obter informações sobre como limpar a tabela user_load_operations.