Carregar Dados de Arquivos na Nuvem

O pacote DBMS_CLOUD do PL/SQL fornece suporte ao carregamento de dados de arquivos na nuvem para tabelas criadas no Autonomous AI Database on Dedicated Exadata Infrastructure.

Você pode carregar dados de diferentes formatos usando os seguintes procedimentos PL/SQL fornecidos por DBMS_CLOUD:

Antes de carregar os dados dos arquivos, verifique se:

O pacote DBMS_CLOUD suporta carregamento de arquivos nos seguintes serviços da nuvem: Oracle Cloud Infrastructure Object Storage, Oracle Cloud Infrastructure Object Storage Classic, Azure Blob Storage e Amazon S3.

Criar Credenciais

Saiba como armazenar a sua credencial do Cloud Object Storage usando o procedimento DBMS_CLOUD.CREATE_CREDENTIAL.

Execute o procedimento DBMS_CLOUD.CREATE_CREDENTIAL usando qualquer ferramenta de banco de dados, como SQL*Plus, SQL Developer ou Database Actions (ferramenta SQL Developer baseada na web). Por exemplo:

BEGIN
  DBMS_CLOUD.CREATE_CREDENTIAL(
    credential_name => 'DEF_CRED_NAME',
    username => 'adb_user@oracle.com',
    password => 'password'
  );
END;
/

Os valores fornecidos para username e password dependem do serviço de Cloud Object Storage que você está usando:

Esta operação armazena as credenciais no banco de dados em um formato criptografado. Você pode usar qualquer nome para o nome da credencial. Observe que essa etapa só é necessária uma vez, a menos que suas credenciais do armazenamento de objetos sejam alteradas. Depois de armazenar as credenciais, você poderá usar o mesmo nome de credencial para todos os carregamentos de dados.

Carregar Dados de Arquivos de Texto

Saiba como carregar dados de arquivos de texto na nuvem para seu Autonomous AI Database usando o procedimento DBMS_CLOUD.COPY_DATA.

O arquivo de origem neste exemplo, channels.txt, tem os seguintes dados:

S,Direct Sales,Direct
T,Tele Sales,Direct
C,Catalog,Indirect
I,Internet,Indirect
P,Partners,Others

  1. Armazene sua credencial do Cloud Object Storage usando o procedimento DBMS_CREDENTIAL.CREATE_CREDENTIAL. Consulte Criar Credenciais para mais detalhes.</span>

  2. Crie a tabela que conterá os dados. Por exemplo:

     CREATE TABLE CHANNELS
   (channel_id CHAR(1),
     channel_desc VARCHAR2(20),
     channel_class VARCHAR2(20)
   );
 /

  3. Carregue dados na tabela usando o procedimento DBMS_CLOUD.COPY_DATA. Por exemplo:

     BEGIN
  DBMS_CLOUD.COPY_DATA(
    table_name =>'CHANNELS',
    credential_name =>'DEF_CRED_NAME',
    file_uri_list =>'https://swiftobjectstorage.us-phoenix-1.oraclecloud.com/v1/idthydc0kinr/mybucket/channels.txt',
    format => json_object('delimiter' value ',')
  );
 END;
 /

    Os parâmetros são:

    • table_name: é o nome da tabela de destino.

    • credential_name: é o nome da credencial criada na etapa anterior.

    • file_uri_list: é uma lista delimitada por vírgulas dos arquivos de origem que você deseja carregar.

      Neste exemplo, file_uri_list é um URI Swift do Oracle Cloud Infrastructure que especifica o arquivo channels.txt no bucket mybucket na região us-phoenix-1. (idthydc0kinr é o namespace dp armazenamento de objetos no qual o bucket reside.) Para obter informações sobre os formatos de URI suportados, consulte Formatos de URI do Cloud Object Storage.

    • format: define as opções especificadas para descrever o formato do arquivo de origem. Para obter informações sobre as opções de formato que você pode especificar, consulte Parâmetro de Formato.

Carregar um Arquivo JSON de Documentos Delimitados em uma Coleta

Saiba como carregar um arquivo JSON de documentos delimitados em uma coleção no seu Autonomous AI Database usando o procedimento DBMS_CLOUD.COPY_DATA.

Este exemplo carrega valores de JSON de um arquivo delimitado pela linha e usa o arquivo JSON myCollection.json. Cada valor, cada linha, é carregado em uma coleção no seu Autonomous AI Database como um único documento.

Veja a seguir o exemplo desse arquivo. Ele tem três linhas, com um objeto por linha. Cada um desses objetos é carregado como um documento JSON separado.

{ "name" : "apple", "count": 20 }
{ "name" : "orange", "count": 42 }
{ "name" : "pear", "count": 10 }

Procedimento

  1. Armazene sua credencial do Cloud Object Storage usando o procedimento DBMS_CLOUD.CREATE_CREDENTIAL. Consulte Criar Credenciais para obter mais detalhes.

  2. Carregue dados em uma coleção usando o procedimento DBMS_CLOUD.COPY_DATA. Por exemplo:

     BEGIN 
   DBMS_CLOUD.COPY_COLLECTION(
     collection_name =>'fruit',
     credential_name =>'DEF_CRED_NAME',
     file_uri_list =>'https://objectstorage.us-ashburn-1.oraclecloud.com/n/namespace-string/b/fruit_bucket/o/myCollection.json',
     format => json_object('recorddelimiter' value '''\n''')
   );
 END;
 /

    Os parâmetros são:

    • collection_name: é o nome da coleção de destino.

    • credential_name: é o nome da credencial criada na etapa anterior.

    • file_uri_list: é uma lista delimitada por vírgulas dos arquivos de origem que você deseja carregar.

      Neste exemplo, file_uri_list é um URI Swift do Oracle Cloud Infrastructure que especifica o arquivo myCollection.json no bucket mybucket na região us-phoenix-1. Para obter informações sobre os formatos de URI suportados, consulte Formatos de URI do Cloud Object Storage.

    • format: define as opções especificadas para descrever o formato do arquivo de origem. As opções de formato characterset, compression, ignoreblanklines, jsonpath, maxdocsize, recorddelimiter, rejectlimit, unpackarray são suportadas para carregar dados JSON. Qualquer outro formato especificado resultará em um erro. Para obter informações sobre as opções de formato que você pode especificar, consulte Parâmetro de Formato.

Carregar um Array de Documentos JSON para uma Coleção

Saiba como carregar uma matriz de documentos JSON em uma coleção no Autonomous AI Database usando o procedimento DBMS_CLOUD.COPY_COLLECTION.

Este exemplo usa o arquivo JSON fruit_array.json. O seguinte mostra o conteúdo do arquivo fruit_array.json:

[{"name" : "apple", "count": 20 },
 {"name" : "orange", "count": 42 },
 {"name" : "pear", "count": 10 }]

Procedimento

  1. Armazene sua credencial do Cloud Object Storage usando o procedimento DBMS_CLOUD.CREATE_CREDENTIAL. Consulte Criar Credenciais para obter mais detalhes.

  2. Carregue dados em uma coleção usando o procedimento DBMS_CLOUD.COPY_DATA. Por exemplo:

     BEGIN 
   DBMS_CLOUD.COPY_COLLECTION(    
     collection_name => 'fruits',    
     credential_name => 'DEF_CRED_NAME',    
     file_uri_list => 'https://objectstorage.us-ashburn-1.oraclecloud.com/n/namespace-string/b/json/o/fruit_array.json',
     format => '{"recorddelimiter" : "0x''01''", "unpackarrays" : "TRUE", "maxdocsize" : "10240000"}'
   );
 END;
 /

    Neste exemplo, você carrega um único valor JSON que ocupa o arquivo inteiro. Portanto, não há necessidade de especificar um delimitador de registro. Para indicar que não há delimitador de registro, você pode usar um caractere que não ocorra no arquivo de entrada. Por exemplo, você pode usar o valor "0x''01''" porque esse caractere não ocorre diretamente no texto JSON.

    Quando o parâmetro unpackarrays do valor de formato é definido como TRUE, o array de documentos é carregado como documentos individuais, e não como um array inteiro. No entanto, a descompactação de elementos do array é limitada a um único nível. Se houver arrays aninhados nos documentos, esses arrays não serão descompactados.

    Os parâmetros são:

    • collection_name: é o nome da coleção de destino.

    • credential_name: é o nome da credencial criada na etapa anterior.

    • file_uri_list: é uma lista delimitada por vírgulas dos arquivos de origem que você deseja carregar.

      Neste exemplo, file_uri_list é um URI Swift do Oracle Cloud Infrastructure que especifica o arquivo myCollection.json no bucket mybucket na região us-phoenix-1. Para obter informações sobre os formatos de URI suportados, consulte Formatos de URI do Cloud Object Storage.

    • format: define as opções especificadas para descrever o formato do arquivo de origem. As opções de formato characterset, compression, ignoreblanklines, jsonpath, maxdocsize, recorddelimiter, rejectlimit, unpackarray são suportadas para carregar dados JSON. Qualquer outro formato especificado resultará em um erro. Para obter informações sobre as opções de formato que você pode especificar, consulte Parâmetro de Formato.

    O carregamento de fruit_array.json com DBMS_CLOUD.COPY_COLLECTION usando a opção de formato unpackarrays faz o procedimento reconhecer valores do array na origem. Portanto, em vez de carregar os dados como um único documento, como seria por padrão, os dados são carregados na coleção fruits com cada valor no array como um único documento.

Copiar Dados JSON em uma Tabela Existente

Use DBMS_CLOUD.COPY_DATA para carregar dados JSON na nuvem em uma tabela.

O arquivo de origem neste exemplo é um arquivo de dados JSON.

Procedimento

  1. Armazene suas credenciais do armazenamento de objetos usando o procedimento DBMS_CLOUD.CREATE_CREDENTIAL. Por exemplo:

     SET DEFINE OFF
 BEGIN
   DBMS_CLOUD.CREATE_CREDENTIAL(
     credential_name => 'DEF_CRED_NAME',
     username => 'adb_user@example.com',
     password => 'password'
   );
 END;
 /

    Esta operação armazena as credenciais no banco de dados em um formato criptografado. Você pode usar qualquer nome para o nome da credencial. Observe que essa etapa só é necessária uma vez, a menos que suas credenciais do armazenamento de objetos sejam alteradas. Depois de armazenar as credenciais, você poderá usar o mesmo nome de credencial para todos os carregamentos de dados.

    Para obter informações detalhadas sobre os parâmetros, consulte Procedimento CREATE_CREDENTIAL.

  2. Carregue dados JSON em uma tabela existente usando o procedimento DBMS_CLOUD.COPY_DATA.

    Por exemplo:

     CREATE TABLE WEATHER2
     (WEATHER_STATION_ID VARCHAR2(20),
      WEATHER_STATION_NAME VARCHAR2(50));
 /

 BEGIN
   DBMS_CLOUD.COPY_DATA(
       table_name      => 'WEATHER2',
       credential_name => 'DEF_CRED_NAME',
       file_uri_list   => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/jsonfiles*',
       format          =>  JSON_OBJECT('type' value 'json', 'columnpath' value '["$.WEATHER_STATION_ID",
           "$.WEATHER_STATION_NAME"]')
     );
 END;
 /

    Os parâmetros são:

    • table_name: é o nome da tabela de destino.

    • credential_name: é o nome da credencial criada na etapa anterior.

    • file_uri_list: é uma lista delimitada por vírgulas dos arquivos de origem que você deseja carregar. Você pode usar curingas nos nomes de arquivo em seus URIs. O caractere "*" pode ser usado como curinga para vários caracteres; o caractere "?" pode ser usado como curinga para um único caractere.

    • format: para DBMS_CLOUD.COPY_DATA com dados JSON, a type é json. Especifique outros valores de formato para definir as opções para descrever o formato do arquivo de origem JSON. Consulte Opções de Formato de Pacote DBMS_CLOUD para obter mais informações.

    Neste exemplo, namespace-string é o namespace do Oracle Cloud Infrastructure Object Storage e bucketname é o nome do bucket. Consulte Noções Básicas de Namespaces do serviço Object Storage para obter mais informações.

    Para obter informações detalhadas sobre os parâmetros, consulte Procedimento COBY_DATA.

Monitorar e Solucionar Problemas de Carga de Dados

Todas as operações de carregamento de dados feitas usando o pacote DBMS_CLOUD PL/SQL estão registradas nas tabelas dba_load_operations e user_load_operations:

Consulte estas tabelas para ver informações sobre carregamentos de dados em andamento e concluídos. Por exemplo, o uso de uma instrução SELECT com um predicado de cláusula WHERE na coluna TYPE mostra operações de carga com o tipo COPY:

SELECT table_name, owner_name, type, status, start_time, update_time, logfile_table, badfile_table
  FROM user_load_operations WHERE type = 'COPY';
TABLE_NAME OWNER_NAME  TYPE   STATUS     START_TIME                            UPDATE_TIME                          LOGFILE_TABLE   BADFILE_TABLE
---------- ----------- ------- ---------- ---------------------- --------------------- --------------- ------------- ------------- -------------
CHANNELS   SH          COPY   COMPLETED  04-MAR-21 07.38.30.522711000 AM GMT    04-MAR-21 07.38.30.522711000 AM GMT  COPY$1_LOG     COPY$1_BAD

A coluna LOGFILE_TABLE mostra o nome da tabela que você pode consultar para verificar o log de uma operação de carregamento. Por exemplo, a consulta a seguir mostra o log da operação de carregamento:

select * from COPY$21_LOG;

A coluna BADFILE_TABLE mostra o nome da tabela que você pode consultar para verificar as linhas que apresentaram erros durante o carregamento. Por exemplo, a consulta a seguir mostra os registros rejeitados para a operação de carregamento:

select * from COPY$21_BAD;

Dependendo dos erros mostrados no log e das linhas mostradas na tabela BADFILE_TABLE especificada, você pode corrigir o erro especificando as opções corretas de formato em DBMS_CLOUD.COPY_DATA.

Observação: As tabelas LOGFILE_TABLE e BADFILE_TABLE são armazenadas durante dois dias para cada operação e, em seguida, são removidas automaticamente.

dbmscloud-para-objetos-e-arquivos.md#GUID-CEC0CA63-B77F-4D64-B70F-1E8476AE3ED6

Consulte Procedimento DELETE_ALL_OPERATIONS para saber como limpar a tabela user_load_operations.

Objetos JSON Textuais que Representam Valores Escalares Estendidos

Os dados JSON binários nativos (formato OSON) estendem a linguagem JSON adicionando tipos escalares, como data, que correspondem a tipos SQL e não fazem parte do padrão JSON. O Oracle Database também suporta o uso de objetos JSON textuais que representam valores escalares JSON, incluindo esses valores não padrão.

Quando você cria dados JSON binários nativos com base em dados JSON textuais que contêm esses objetos estendidos, eles podem, opcionalmente, ser substituídos por valores escalares JSON correspondentes (binários nativos).

Um exemplo de objeto estendido é {"$numberDecimal":31}. Representa um valor escalar JSON do tipo não padrão número decimal e, quando interpretado como tal, é substituído por um número decimal no formato binário nativo.

Por exemplo, quando você usa o construtor de tipo de dados JSON, JSON, se você usar a palavra-chave EXTENDED, os objetos estendidos reconhecidos na entrada textual serão substituídos pelos valores escalares correspondentes no resultado JSON binário nativo. Se você não incluir a palavra-chave EXTENDED, essa substituição não ocorrerá; os objetos JSON estendidos textuais serão simplesmente convertidos no estado em que se encontram em objetos JSON no formato binário nativo.

Na direção oposta, quando você usa a função SQL/JSON json_serialize para serializar dados JSON binários como dados JSON textuais (VARCHAR2, CLOB ou BLOB), pode usar a palavra-chave EXTENDED para substituir valores escalares JSON (binários nativos) por objetos JSON textuais estendidos correspondentes.

Observação: Se o banco de dados usado for um Oracle Autonomous AI Database, você poderá usar o procedimento PL/SQL DBMS_CLOUD.copy_collection para criar uma coleção de documentos JSON com base em um arquivo de dados JSON, como o produzido por bancos de dados NoSQL comuns, incluindo o Oracle NoSQL Database.

Se você usar ejson como o valor do parâmetro type do procedimento, os objetos JSON estendidos reconhecidos no arquivo de entrada serão substituídos pelos valores escalares correspondentes na coleção JSON binária nativa resultante. Na outra direção, você pode usar a função json_serialize com a palavra-chave EXTENDED para substituir valores escalares por objetos JSON estendidos nos dados JSON textuais resultantes.

Estes são os dois principais casos de uso para objetos estendidos:

Para fins de troca, você pode ingerir dados JSON de um arquivo produzido por bancos de dados NoSQL comuns, incluindo o Oracle NoSQL Database, convertendo objetos estendidos em escalares JSON binários nativos. Na outra direção, você pode exportar dados JSON binários nativos como dados textuais, substituindo valores JSON escalares específicos da Oracle por objetos JSON estendidos textuais correspondentes.

Dica: Como exemplo de inspeção, considere um objeto como {"dob" : "2000-01-02T00:00:00"} como resultado da serialização de dados JSON nativos. "2000-01-02T00:00:00" é o resultado da serialização de um valor binário nativo do tipo data ou o valor binário nativo é apenas uma string? Usar json_serialize com a palavra-chave EXTENDED permite que você saiba.

O mapeamento de campos de objeto estendido para tipos JSON escalares é, em geral, muitos para um: mais de um tipo de objeto JSON estendido pode ser mapeado para um determinado valor escalar. Por exemplo, os objetos JSON estendidos {"$numberDecimal":"31"} e {"$numberLong:"31"} são traduzidos como o valor 31 do número do tipo escalar de idioma JSON, e o método de item type() retorna "number" para cada um desses escalares JSON.

O método de item type() reporta o tipo escalar de idioma JSON de seu valor de destino (como uma string JSON). Alguns valores escalares são distinguíveis internamente, mesmo quando têm o mesmo tipo escalar. Isso geralmente permite que a função json_serialize (com a palavra-chave EXTENDED) reconstrua o objeto JSON estendido original. Esses valores escalares são diferenciados internamente usando diferentes tipos de SQL para implementá-los ou marcando-os com o tipo de objeto JSON estendido do qual foram derivados.

Quando o json_serialize reconstrói o objeto JSON estendido original, o resultado nem sempre é textualmente idêntico ao original, mas é sempre semanticamente equivalente. Por exemplo, {"$numberDecimal":"31"} e {"$numberDecimal":31} são semanticamente equivalentes, mesmo que os valores do campo sejam diferentes no tipo (string e número). Eles são traduzidos para o mesmo valor interno e cada um é marcado como derivado de um objeto estendido $numberDecimal (mesma tag). Mas quando serializado, o resultado para ambos é {"$numberDecimal":31}. A Oracle sempre usa o tipo mais diretamente relevante para o valor de campo, que nesse caso é o valor de idioma JSON 31, do número de tipo escalar.

A tabela a seguir apresenta correspondências entre os vários tipos usados. Ele mapeia entre (1) tipos de objetos estendidos usados como entrada, (2) tipos reportados pelo método de item type(), (3) tipos de SQL usados internamente, (4) tipos de linguagem JSON padrão usados como saída pela função json_serialize e (5) tipos de saída de objetos estendidos por json_serialize quando a palavra-chave EXTENDED é especificada.

Tipo de Objeto Estendido (Entrada) Tipo Escalar JSON do Oracle (Reportado por type()) Tipo Escalar SQL Tipo Escalar JSON Padrão (Saída) Tipo de Objeto Estendido (Saída)
$numberDouble com um valor JSON, uma string que representa o número ou uma destas strings: "Infinity", "-Infinity", "Inf", "-Inf", "Nan"(Consulte a Nota de Rodapé 1) duplo BINARY_DOUBLE number $numberDouble com um valor JSON ou uma destas strings: "Inf", "-Inf", "Nan"(Consulte a Nota de Rodapé 2)
$numberFloat com valor igual ao de $numberDouble flutuante BINARY_FLOAT number $numberFloat com valor igual ao de $numberDouble
$numberDecimal com valor igual ao de $numberDouble number NUMBER number $numberDecimal com valor igual ao de $numberDouble
$numberInt com um valor inteiro de 32 bits assinado ou uma string que representa o número number NUMBER number $numberInt com valor igual ao de $numberDouble
$numberLong com um valor JSON ou uma string que representa o número number NUMBER number $numberLong com valor igual ao de $numberDouble

$binary com o valor um destes:

  • uma string com 64 caracteres de base
  • Um objeto com os campos base64 e subType, cujos valores são uma string de 64 caracteres base e o número 0 (binário arbitrário) ou 4 (UUID), respectivamente

Quando o valor é uma string de caracteres base-64, o objeto estendido também pode ter o campo $subtype com o valor 0 ou 4, expresso como um inteiro de um byte (0-255) ou uma string hexadecimal de 2 caracteres. representando esse inteiro

binário BLOB ou RAW

string

A conversão é equivalente ao uso da função SQL rawtohex.

Uma das seguintes opções se aplica:
  • $binary com valor de uma string com 64 caracteres de base
  • $rawid com valor de uma string de 32 caracteres hexadecimais, se a entrada tiver um valor subType de 4 (UUID)
$oid com valor de uma string de 24 caracteres hexadecimais binário RAW(12)

string

A conversão é equivalente ao uso da função SQL rawtohex.

$rawid com valor de uma string de 24 caracteres hexadecimais
$rawhex com valor de uma string com um número par de caracteres hexadecimais binário RAW

string

A conversão é equivalente ao uso da função SQL rawtohex.

$binary com valor de uma string de 64 caracteres base, preenchida à direita com = caracteres
$rawid com valor de uma string de 24 ou 32 caracteres hexadecimais binário RAW

string

A conversão é equivalente ao uso da função SQL rawtohex.

$rawid
$oracleDate com valor e uma string de data ISO 8601 data DATE string $oracleDate com valor e uma string de data ISO 8601
$oracleTimestamp com valor e string de timestamp ISO 8601 timestamp TIMESTAMP string $oracleTimestamp com valor e string de timestamp ISO 8601
$oracleTimestampTZ com valor uma string de timestamp ISO 8601 com um deslocamento de fuso horário numérico ou com Z timestamp com fuso horário TIMESTAMP WITH TIME ZONE string $oracleTimestampTZ com valor uma string de timestamp ISO 8601 com deslocamento de fuso horário numérico ou com Z

$date com o valor um dos seguintes:

  • Contagem de milissegundos inteiros desde 1º de janeiro de 1990
  • Uma string de timestamp ISO 8601
  • Um objeto com o campo numberLong com um valor inteiro em milissegundos desde 1º de janeiro de 1990
timestamp com fuso horário TIMESTAMP WITH TIME ZONE string $oracleTimestampTZ com valor uma string de timestamp ISO 8601 com deslocamento de fuso horário numérico ou com Z
$intervalDaySecond com valor e uma string de intervalo ISO 8601 conforme especificado para a função SQL to_dsinterval diassegundoIntervalo INTERVAL DAY TO SECOND string $intervalDaySecond com valor e uma string de intervalo ISO 8601 conforme especificado para a função SQL to_dsinterval
$intervalYearMonth com valor e uma string de intervalo ISO 8601 conforme especificado para a função SQL to_yminterval mêsanoIntervalo INTERVAL YEAR TO MONTH string $intervalYearMonth com valor e uma string de intervalo ISO 8601 conforme especificado para a função SQL to_yminterval

Dois campos:

  • Campo $vector com valor de um array cujos elementos são números ou as strings "Nan", "Inf" e "-Inf" (representando valores não-número e infinitos).

  • Campo $vectorElementType com valor de string "float32" ou "float64". Estes correspondem aos números IEEE de 32 bits e IEEE de 64 bits, respectivamente.

vetor VECTOR matriz de números

Dois campos:

  • Campo $vector com valor de um array cujos elementos são números ou as strings "Nan", "Inf" e "-Inf" (representando valores não-número e infinitos).

  • Campo $vectorElementType com valor de string "float32" ou "float64".

Nota de rodapé 1 Os valores de string são interpretados sem distinção entre maiúsculas e minúsculas. Por exemplo, "NAN" "nan" e "nAn" são aceitos e equivalentes e, da mesma forma, "INF", "inFinity" e "iNf". Números infinitamente grandes ("Infinity" ou "Inf") e pequenos ("-Infinity" ou "-Inf") são aceitos com a palavra completa ou a abreviação.

Nota de rodapé 2 Na saída, apenas esses valores de string são usados. Nenhuma variante completa de Infinity ou letra maiúscula.

Conteúdo Relacionado