Operações em Lote para Arquivos na Nuvem

O pacote PL/SQL DBMS_CLOUD oferece suporte à execução paralela para atividades de upload, download, cópia e transferência de arquivos em massa, o que agiliza a experiência do usuário e oferece desempenho ideal para operações de arquivos em massa.

O pacote DBMS_CLOUD suporta o carregamento e o descarregamento de arquivos nos seguintes serviços de nuvem:

Oracle Cloud Infrastructure Object Storage
Armazenamento de Blob do Azure
Amazon S3
Armazenamento do Google Cloud

Consulte Formatos de URI do Arquivo de Pacote DBMS_CLOUD para obter mais informações.

Sobre Operações de Arquivo em Massa

As operações de arquivo em massa do DBMS_CLOUD suportam o download e o 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. 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 para o serviço Médio para determinar o paralelismo.
LOW: Processar arquivos em ordem serial (sem simultaneidade).

A execução de operações em massa com prioridade mais alta usa mais recursos de banco de dados e as operações são concluídas com mais rapidez quando o paralelismo pode acelerar a operação. Uma prioridade mais baixa consome menos recursos de banco de dados e as operações demoram mais para serem concluídas quando o paralelismo pode acelerar a operação. Quando operações em massa envolvem pequenos números de arquivos que contêm poucos dados, especificar 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, o credential_name, o source_credential_name ou o target_credential_name podem ser NULL para URI de bucket público, Pré-autenticado ou Pré-assinado.

Cópia em Massa de Arquivos 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 mais informações.
Quando a origem e o destino estiverem em Áreas de Armazenamento de Objetos distintas 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 pode ser entre provedor de nuvem, contas e buckets. 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_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 arquivos em massa de um bucket do Oracle Cloud Infrastructure Object Storage para outro.

Consulte Procedimento BULK_COPY para obter mais informações.

Consulte Formatos de URI do Database Cloud Object Storage do Arquivo de Pacote DBMS_CLOUD 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 no Cloud Object Storage

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

A primeira etapa na movimentação de 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 Object Store permitir a renomeação de operações entre os locais de origem e de 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 mais informações.
Quando a origem e o destino estiverem em Áreas de Armazenamento de Objetos distintas 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 estar conectado 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 move arquivos em massa de um local do Oracle Cloud Infrastructure Object Storage para outro.

Consulte Procedimento BULK_MOVE para obter mais informações.

Consulte Formatos de URI do Database Cloud Object Storage do Arquivo de Pacote DBMS_CLOUD 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 de Arquivos em Massa 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 seu Cloud Object Storage.

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

Consulte CREATE_CREDENTIAL para 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 do 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 do diretório de destino, você deve ter o privilégio WRITE no objeto do diretório.

Consulte Procedimento BULK_DOWNLOAD para obter mais informações.

Consulte Formatos de URI do Database Cloud Object Storage do Arquivo de Pacote DBMS_CLOUD para obter mais informações.

Fazer Upload de Arquivos em Massa 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 seu Cloud Object Storage.

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

Consulte CREATE_CREDENTIAL para 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 de local do Oracle Cloud Infrastructure Object Store.

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 Procedimento BULK_UPLOAD para obter mais informações.

Excluir Arquivos em Massa 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 seu 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 ou Pré-autenticado ou Pré-assinado.

Consulte CREATE_CREDENTIAL para mais informações.
Execute o procedimento DBMS_CLOUD.BULK_DELETE para excluir arquivos do Cloud Object Store. 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_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 Oracle Cloud Infrastructure Object Store.

Consulte Procedimento BULK_DELETE para mais informações.

Consulte Formatos de URI do Database Cloud Object Storage do Arquivo de Pacote DBMS_CLOUD para obter mais informações.

Monitorar e Solucionar Problemas de Carregamentos 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 views para monitorar e solucionar problemas de carregamentos 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 views para ver informações sobre operações de arquivos em massa em andamento e concluídas. Por exemplo, a seguinte instrução SELECT com um predicado de cláusula WHERE na 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 de log detalhadas 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 relevante e a mensagem são gravados 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 START_TIME e END_TIME relatados.

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 de arquivo. Uma nova tentativa pode ser feita duas vezes.
`PENDING`	A operação de arquivo ainda não foi iniciada.
`RUNNING`	A operação de arquivos está em andamento no momento.
`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 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 as tabelas de status:

logretention: Especifica um valor inteiro que determina a duração em dias da retenção da tabela de status. 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 massa 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 saber como limpar a tabela user_load_operations.

Conteúdo Relacionado

DBMS_CLOUD para Gerenciamento de Arquivos em Massa