DBMS_CLOUD Opções de Formato do Pacote

O argumento de formato em DBMS_CLOUD especifica o formato de arquivos de origem.

As duas maneiras de especificar o argumento de formato são:

format => '{"format_option" : “format_value” }'  

E:

format => json_object('format_option' value 'format_value'))

Exemplos de:

format => json_object('type' VALUE 'CSV')

Para especificar várias opções de formato, separe os valores com uma vírgula (",").

Por exemplo:

format => json_object('ignoremissingcolumns' value 'true', 'removequotes' value 'true', 
                           'dateformat' value 'YYYY-MM-DD-HH24-MI-SS', 'blankasnull' value 'true', 'logretention' value 7)

Observação:

Para opções de formato Avro, ORC ou Parquet, consulte DBMS_CLOUD Opções de Formato do Pacote para Avro, ORC ou Parquet.

Conforme observado na coluna Opção de Formato, um conjunto limitado de opções de formato é válido com DBMS_CLOUD.COPY_COLLECTION ou com DBMS_CLOUD.COPY_DATA quando format type é JSON.

Opção de Formato Descrição Sintaxe

blankasnull

Quando definido como true, carrega campos que consistem em espaços como nulos.

blankasnull : true

Valor padrão: False

characterset

Válido com format JSON e COPY_DATA

Especifica o conjunto de caracteres dos arquivos de origem

characterset: string

Valor padrão: Conjunto de caracteres do banco de dados

columnpath

Só use com format JSON e COPY_DATA

Array de expressões de caminho JSON que correspondem aos campos que precisam ser extraídos dos registros JSON. Cada uma das expressões de caminho JSON no array deve seguir as regras descritas em Expressões de Caminho SQL/JSON no Oracle Database 19c JSON Developer's Guide ou Oracle Database 23ai JSON Developer's Guide.

Só use com formato JSON e DBMS_CLOUD.COPY_DATA.

Array JSON de expressões de caminho json expressas em formato de string. Por exemplo: valor 'columnpath' '["$.WEATHER_STATION_ID", "$.WEATHER_STATION_NAME"]'

compression

Opção válida com dados JSON

Especifica o tipo de compactação do arquivo de origem.

O formato de arquivamento ZIP não é suportado.

A especificação do valor auto verifica os tipos de compactação: gzip, zlib, std, bzip2.

compression: auto|gzip|zlib|bzip2

Valor padrão: O valor nulo significa sem compactação.

conversionerrors

Se uma linha for rejeitada por causa de erros de conversão do tipo de dados, as colunas relacionadas serão armazenadas como nulas ou a linha será rejeitada.

conversionerrors : reject_record | store_null

Valor padrão: reject_record

dateformat

Especifica o formato de data no arquivo de origem. A opção de formato AUTO pesquisa os seguintes formatos:

J 
MM-DD-YYYYBC 
MM-DD-YYYY 
YYYYMMDD HHMISS 
YYMMDD HHMISS 
YYYY.DDD 
YYYY-MM-DD

dateformat : string

Valor padrão: Formato de data do banco de dados

delimiter

Especifica o delimitador de campo.

Para usar um caractere especial como delimitador, especifique o valor HEX do código ASCII do caractere. Veja este exemplo que especifica o caractere TAB como delimitador:

format => json_object('delimiter' value 'X''9''')

delimiter : caractere

Valor padrão | (caractere de barra vertical)

detectfieldorder

Especifica que os campos nos arquivos de dados externos estão em uma ordem diferente das colunas na tabela. Detecte a ordem dos campos usando a primeira linha de cada arquivo de dados externo e mapeie-a para as colunas da tabela. Os nomes de campo nos arquivos de dados externos são comparados de maneira que não faz distinção entre maiúsculas e minúsculas com os nomes das colunas da tabela.

Esta opção de formato é aplicável aos seguintes procedimentos:

  • DBMS_CLOUD.COPY_DATA

  • DBMS_CLOUD.CREATE_EXTERNAL_TABLE

  • DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE

  • DBMS_CLOUD.CREATE_HYBRID_PART_TABLE

Restrições para detectfieldorder:

  • Os nomes de campo no arquivo de dados devem aparecer na primeira linha de registro e não devem conter espaços em branco entre os nomes de campo.

  • O delimitador de campo no registro de nomes de campo deve ser igual ao delimitador de campo para os dados no arquivo.

  • Nomes de campos cotados não são suportados. Os nomes dos campos nos arquivos de dados são comparados, sem distinção entre maiúsculas e minúsculas, com os nomes das colunas da tabela externa.

  • Os delimitadores de campo incorporados não são permitidos nos nomes de campo.

  • O número de colunas na tabela deve corresponder ao número de campos nos arquivos de dados.

  • Essa opção de formato não é aplicável aos formatos Bigdata ou Oracle Data Pump, pois esses formatos têm informações precisas de metadados de coluna no formato de arquivo binário.

    Os formatos de texto, CSV, JSON, Parquet ou XML podem se beneficiar dessa detecção automática de ordem de campo quando a primeira linha contiver os nomes dos campos.

Consulte FIELD NAMES em Oracle Database 19c Utilities ou Oracle Database 23ai Utilities e a descrição de ALL FILES para obter mais informações.

detectfieldorder: true

Valor padrão: false

enablelogs

A opção de formato enablelogs é usada com os seguintes procedimentos DBMS_CLOUD:

  • COPY_DATA

  • COPY_COLLECTION

  • EXPORT_DATA

enablelogs especifica um valor booliano. Quando definido como TRUE, os logs são gerados. Quando definido como FALSE, os logs não são gerados.

Por exemplo:

format => JSON_OBJECT('enablelogs' value FALSE)

enablelogs: false

Valor padrão: true

encryption

A opção de formato encryption especifica as opções de criptografia e decriptografia para exportar e importar dados de/para o Armazenamento de Objetos.

Use encryption para especificar os seguintes parâmetros para criptografar e decriptografar:

  • user_defined_function: Especifica uma função totalmente qualificada definida pelo usuário para decriptografar ou criptografar o BLOB especificado (objeto binário grande). Ele retorna um BLOB criptografado ou descriptografado. user_defined_function é mutuamente exclusivo com outros parâmetros para encryption.

    Por exemplo, ADMIN.DECRYPTION_CALLBACK.

  • type: Especifica o algoritmo de criptografia DBMS_CRYPTO a ser decriptografado ou criptografado.

    type aceita valores no formato Algoritmos de Cifragem de Bloco + Modificadores de Encadeamento de Cifragem de Bloco + Modificadores de Preenchimento de Cifragem de Bloco.

    Os Algoritmos de Cifragem de Bloco Suportados são:

    • DBMS_CRYPTO.ENCRYPT_AES256

    Os Modificadores de Encadeamento de Cifragem de Bloco Suportados são:

    • DBMS_CRYPTO.CHAIN_CBC

    • DBMS_CRYPTO.CHAIN_CFB

    • DBMS_CRYPTO.CHAIN_ECB

    • DBMS_CRYPTO.CHAIN_OFB

    Os Modificadores de Preenchimento de Cifragem de Bloco Suportados são:

    • DBMS_CRYPTO.PAD_PKCS5

    • DBMS_CRYPTO.PAD_NONE

    • DBMS_CRYPTO.PAD_ZERO

    • DBMS_CRYPTO.PAD_ORCL

  • credential_name: Especifica a credencial usada para armazenar a chave de criptografia.

Os valores de Modificadores de Encadeamento de Cifragem de Bloco e Modificadores de Preenchimento de Cifragem de Bloco assumem como padrão DBMS_CRYPTO.CHAIN_CBC e DBMS_CRYPTO.PAD_PKCS5, se você não especificar valores para esses parâmetros.

A opção de formato encryption é usada com os seguintes procedimentos DBMS_CLOUD:
  • Usado para passar parâmetros a serem descriptografados para estes procedimentos:

    • DBMS_CLOUD.COPY_DATA

    • DBMS_CLOUD.CREATE_EXTERNAL_TABLE

    • DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE

    • DBMS_CLOUD.CREATE_HYBRID_PART_TABLE

      Para DBMS_CLOUD.CREATE_HYBRID_PART_TABLE, essa opção só é aplicável aos arquivos do Object Storage.

    • DBMS_CLOUD.COPY_COLLECTION

  • Usado para transmitir parâmetros a serem criptografados para este procedimento:

    • DBMS_CLOUD.EXPORT_DATA

Por exemplo:

format => JSON_OBJECT('encryption' value json_object ('type' value DBMS_CRYPTO.ENCRYPT_AES256 + DBMS_CRYPTO.CHAIN_CBC + DBMS_CRYPTO.PAD_PKCS5, 'credential_name' value 'ENCRYPTION_CRED'))
encryption:value

Em que value é uma string JSON que fornece parâmetros adicionais para criptografia:

type: valor

Especifica o tipo de criptografia.

credential_name: value

Especifica a credencial usada para armazenar a chave de criptografia.

user_defined_function: value

Especifica uma função totalmente qualificada definida pelo usuário para decriptografar ou criptografar o BLOB especificado (objeto binário grande).

endquote

Os dados podem ser colocados entre dois delimitadores, especificados com quote e endquote. Os caracteres quote e endquote são removidos durante o carregamento quando especificados.

Por exemplo:

format => JSON_OBJECT(‘quote’ value ‘(’, ‘endquote’ value ‘)’)

endquote:character

Valor padrão: Nulo, o que significa que não há endquote.

escape

O caractere "\" é usado como o caractere de escape quando especificado.

escape : true

Valor padrão: false

ignoreblanklines

Opção válida com dados JSON

As linhas em branco são ignoradas quando definidas como verdadeiras.

ignoreblanklines : true

Valor padrão: False

ignoremissingcolumns

Se houver mais colunas no field_list do que nos arquivos de origem, as colunas extras serão armazenadas como nulas.

ignoremissingcolumns : true

Valor padrão False

jsonpath

Usar somente com COPY_COLLECTION

Caminho JSON para identificar o documento a ser carregado.

Esta opção só é válida para dados de coleção JSON com DBMS_CLOUD.COPY_COLLECTION.

jsonpath: string

Valor padrão: Nulo

keyassignment

Usar somente com COPY_COLLECTION

Especifica se uma nova coleção é criada como uma coleção compatível com mongo ou como uma coleção SODA.

Quando o valor é definido como embedded_oid, uma nova coleção é criada como uma coleção compatível com mongo.

Por padrão, esse parâmetro não está definido, o que significa que uma nova coleção é criada como uma coleção SODA.

keyassignment: embedded_oid

Padrão: keyassignment não está definido

keypath

Usar somente com COPY_COLLECTION

Especifica um atributo nos dados a serem carregados como o valor '_id'.

Se keypath for especificado, você também deverá especificar o valor keyassignment como embedded_oid.

Defina o valor como um caminho, por exemplo, '$.mykey', para selecionar o valor do caminho como valor '_id'.

Esse parâmetro é opcional e só é válido para carregamento em coleções compatíveis com mongo.

Se não for especificado, o Oracle gerará um ID de sistema exclusivo de 12 bytes e o preencherá como o atributo '_id', se um atributo '_id' ainda não estiver presente nos dados que estão sendo carregados.

keypath: string

Padrão: keypath não está definido.

Quando keypath é definido, o valor padrão da string é NULL.

language

Especifica o nome de um idioma (por exemplo, FRENCH), cujas informações de configuração regional podem ser derivadas.

language: string

Valor padrão: Nulo

Consulte Locale Data no Oracle Database 19c Database Globalization Support Guide ou Oracle Database 23ai Database Globalization Support Guide para obter uma listagem de idiomas suportados pelo sistema Oracle.

logdir

Especifica um valor de string que determina o nome do objeto de diretório em que os arquivos logfile_table ou badfile_table são salvos.

Por padrão, logdir não faz distinção entre maiúsculas e minúsculas, mas é reservado quando o valor especificado está entre aspas duplas.

Por exemplo:

format => JSON_OBJECT ('logdir' value 'test_log')

A opção de formato logdir especificada no exemplo acima salva os arquivos logfile_table ou badfile_table no objeto de diretório TEST_LOG.

format => JSON_OBJECT ('logdir' value '"test_log"')

A opção de formato logdir especificada no exemplo acima salva os arquivos logfile_table ou badfile_table no objeto de diretório test_log.

logdir: string

Valor padrão: DATA_PUMP_DIR

logprefix

Especifica um valor de string que determina o prefixo dos arquivos logfile_table e badfile_table.

O formato do nome da tabela de log é: logprefix$operation_id

Por padrão, o logprefix está em letras maiúsculas, mas é reservado quando o valor especificado está entre aspas duplas.

Por exemplo:

format => JSON_OBJECT ('logprefix' value 'TEST')

Os arquivos de log usam o prefixo TEST, como: TEST$2_LOG e TEST$2_BAD.

logprefix: string

Valor padrão: COPY

logretention

Especifica uma duração de inteiro positiva, em dias, para a qual os arquivos logfile_table e badfile_table são retidos.

Valores válidos: 0 a 99999

Por exemplo:

format => JSON_OBJECT ('logretention' value 7)

logretention: número

Valor padrão: 2

maxdocsize

Esta opção só é válida com dados JSON

Tamanho máximo de documentos JSON.

maxdocsize: número

Valor padrão: 1 Megabyte

Valor máximo permitido: 2 Gigabytes

numericcharacters

Especifica os caracteres a serem usados como separador de grupo e caractere decimal.

decimal_character: O decimal separa a parte inteira de um número da parte decimal.

group_separator: O separador de grupo separa grupos de números inteiros (ou seja, milhares, milhões, bilhões etc.).

numericcharacters: 'decimal_character group_separator'

Valor padrão: ".,"

Consulte o NLS_NUMERIC_CHARACTERS Oracle Database 19c Database Globalization Support Guide Oracle Database 23ai Database Globalization Support Guide para obter mais informações.

numberformat

Especifica o modelo de formato de número. Os modelos de formato numérico fazem com que o número seja arredondado para o número especificado de dígitos significativos. Um modelo de formato de número é composto de um ou mais elementos de formato de número.

É usado em combinação com numericcharacters.

numberformat: number_format_model

Valor padrão: é derivado da definição do parâmetro NLS_TERRITORY

Consulte Modelos de Formato de Número em Referência de Linguagem SQL 19c do Oracle Database ou Referência de Linguagem SQL do Oracle Database 23ai para obter mais informações.

partition_columns

A opção de formato partition_columns é usada com DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE para especificar os nomes de coluna e os tipos de dados de colunas de partição quando as colunas de partição são derivadas do caminho do arquivo, dependendo do tipo de arquivo de dados, estruturado ou não estruturado:

  • Quando DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE inclui o parâmetro column_list e o arquivo de dados não é estruturado, como com arquivos de texto CSV, partition_columns não inclui o tipo de dados. Por exemplo, use um formato como o seguinte para esse tipo de especificação partition_columns:

    '"partition_columns":["state","zipcode"]'

    O tipo de dados não é obrigatório porque ele está especificado no parâmetro column_list DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE.

  • Quando o DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE não inclui o parâmetro column_list e os arquivos de dados são estruturados, como arquivos Avro, ORC ou Parquet, a opção partition_columns inclui o tipo de dados. Veja o seguinte exemplo que mostra uma especificação partition_columns:

    '"partition_columns":[
                   {"name":"country", "type":"varchar2(10)"},
                   {"name":"year", "type":"number"},
                   {"name":"month", "type":"varchar2(10)"}]'

Se os arquivos de dados não forem estruturados e a subcláusula type for especificada com partition_columns, a subcláusula type será ignorada.

Para nomes de objeto que não se baseiam no formato hive, a ordem das colunas especificadas de partition_columns deve corresponder à ordem em que aparecem no nome do objeto em file_uri_list.

 

quote

Especifica o caractere de aspas para os campos, os caracteres quote são removidos durante o carregamento quando especificado.

quote: character

Valor padrão: Nulo significa que não há aspas

recorddelimiter

Opção válida com dados JSON

Especifica o delimitador de registro.

Por padrão, DBMS_CLOUD tenta localizar automaticamente o caractere de nova linha correto como delimitador. Ele primeiro pesquisa o arquivo para o caractere de nova linha do Windows "\r\n". Se encontrar o caractere de nova linha do Windows, ele será usado como delimitador de registro para todos os arquivos do procedimento. Se um caractere de nova linha do Windows não for encontrado, ele procurará o caractere de nova linha do UNIX/Linux "\n" e, se encontrar um, usará "\n" como delimitador de registro para todos os arquivos no procedimento.

Especifique esse argumento explicitamente se quiser substituir o comportamento padrão, por exemplo:

format => json_object('recorddelimiter' VALUE '''\r\n''')

Para indicar que não há delimitador de registro, você pode especificar um recorddelimiter que não ocorra no arquivo de entrada. Por exemplo, para indicar que não há delimitador, especifique o caractere de controle 0x01 (SOH) como valor para recorddelimiter e defina o valor recorddelimiter como "0x''01''" (esse caractere não ocorre no texto JSON). Por exemplo:

format => '{"recorddelimiter" : "0x''01''"}'

O recorddelimiter é definido uma vez por chamada de procedimento. Se você estiver usando o valor padrão, detected newline, todos os arquivos usarão o mesmo delimitador de registro, se um for detectado.

recorddelimiter: caractere

Valor padrão: nova linha detectada

regexuri

A opção de formato regexuri é usada com os seguintes procedimentos DBMS_CLOUD:

  • COPY_COLLECTION

  • COPY_DATA

  • CREATE_EXTERNAL_TABLE

  • CREATE_EXTERNAL_PART_TABLE

  • CREATE_HYBRID_PART_TABLE

Quando o valor de regexuri for definido como TRUE, você poderá usar curingas, bem como expressões regulares nos nomes de arquivo nos URIs de arquivo de origem da Nuvem.

Os caracteres "*" e "?" são considerados caracteres curinga quando o parâmetro regexuri é definido como FALSE. Quando o parâmetro regexuri é definido como TRUE, os caracteres "*" e "?" fazem parte do padrão de expressão regular especificado.

Padrões de expressão regular só são suportados para o nome do arquivo ou caminho da subpasta em seus URIs e a correspondência de padrões é idêntica à executada pela função REGEXP_LIKE. Padrões de expressão regular não são suportados para nomes de diretórios.

Para tabelas externas, essa opção só é suportada com as tabelas criadas em um arquivo no Object Storage.

Por exemplo:

format => JSON_OBJECT('regexuri' value TRUE)

Consulte REGEXP_LIKE Condition em Oracle Database 19c SQL Language Reference ou Oracle Database 23ai SQL Language Reference para obter mais informações sobre a condição REGEXP_LIKE.

regexuri: True

Valor padrão: False

rejectlimit

A operação resultará em erro após o número especificado de linhas ser rejeitado.

rejectlimit: número

Valor padrão: 0

removequotes

Remove todas as aspas que estão ao redor de qualquer campo no arquivo de origem.

removequotes: true

Valor padrão: False

skipheaders

Especifica quantas linhas devem ser ignoradas do início do arquivo.

skipheaders: número

Valor padrão: 0 se não for especificado; 1 se for especificado sem um valor

territory

Especifica um nome de território para determinar melhor as características dos dados de entrada.

territory: string

Valor padrão: Nulo

Consulte Locale Data no Oracle Database 19c Database Globalization Support Guide ou Oracle Database 23ai Database Globalization Support Guide para obter uma listagem de idiomas suportados pelo sistema Oracle.

timestampformat

Especifica o formato de timestamp no arquivo de origem. A opção de formato AUTO pesquisa os seguintes formatos:

YYYY-MM-DD HH:MI:SS.FF 
YYYY-MM-DD HH:MI:SS.FF3
YYYY-MM-DD HH24:MI:SS.FF3
MM/DD/YYYY HH:MI:SS.FF3

timestampformat : string

Valor padrão: Formado de timestamp do banco de dados

A string pode conter caracteres curinga, como "$".

timestampltzformat

Especifica o timestamp com o formato de fuso horário local no arquivo de origem. A opção de formato AUTO pesquisa os seguintes formatos:

DD Mon YYYY HH:MI:SS.FF TZR 
MM/DD/YYYY HH:MI:SS.FF TZR 
YYYY-MM-DD HH:MI:SS+/-TZR 
YYYY-MM-DD HH:MI:SS.FF3 
DD.MM.YYYY HH:MI:SS TZR

timestampltzformat : string

Valor padrão: Formato de timestamp do banco de dados com fuso horário local

timestamptzformat

Especifica o timestamp com o formato de fuso horário no arquivo de origem. A opção de formato AUTO pesquisa os seguintes formatos:

DD Mon YYYY HH:MI:SS.FF TZR 
MM/DD/YYYY HH:MI:SS.FF TZR 
YYYY-MM-DD HH:MI:SS+/-TZR 
YYYY-MM-DD HH:MI:SS.FF3 
DD.MM.YYYY HH:MI:SS TZR

timestamptzformat: string

Valor padrão: Formato de timestamp do banco de dados com fuso horário

trimspaces

Especifica como os espaços à esquerda e à direita dos campos são cortados.

Consulte a descrição de trim_spec em Oracle Database 19c Utilities ou Oracle Database 23ai Utilities.

trimspaces: rtrim| ltrim| notrim| lrtrim| ldrtrim

Valor padrão: notrim

truncatecol

Se os dados do arquivo forem muito longos para um campo, essa opção truncará o valor do campo em vez de rejeitar a linha.

truncatecol:true

Valor padrão: False

type

Especifica o tipo de arquivo de origem.

Consulte a descrição de CSV em Oracle Database 19c Utilities ou Oracle Database 23ai Utilities.

Se type for datapump, a única outra opção de formato válida será rejectlimit.

Se type for datapump, os únicos Armazenamentos de Objetos suportados serão o Oracle Cloud Infrastructure Object Storage e o Oracle Cloud Infrastructure Object Storage Classic.

Consulte DBMS_CLOUD Opções de Formato do Pacote para Avro, ORC ou Parquet para obter os valores type avro, orc ou parquet.

Para dados JSON com DBMS_CLOUD.COPY_COLLECTION, type tem dois valores válidos: json (padrão) e ejson. Para DBMS_CLOUD.COPY_COLLECTION, esses dois valores especificam que a entrada são dados JSON. O valor ejson faz com que objetos estendidos nos dados de entrada JSON textuais sejam convertidos em valores JSON escalares na coleção JSON binária nativa. O valor json não executa essa transformação e todos os objetos nos dados de entrada são convertidos no formato JSON binário.

Para dados JSON com DBMS_CLOUD.COPY_DATA, type tem um valor válido: json. Esse valor especifica que a entrada são dados JSON.

type: csv|csv with embedded|csv without embedded |avro||datapump|orc|parquet

Observação:

Nem todos os procedimentos DBMS_CLOUD suportam todos esses tipos.

csv é o mesmo que csv without embedded.

Valor padrão: Nulo

Para dados JSON, há dois valores type válidos para uso com DBMS_CLOUD.COPY_COLLECTION: json|ejson Nesse caso, o valor padrão é json. Para dados JSON com DBMS_CLOUD.COPY_DATA, somente json é válido.

unpackarrays

Usar somente com COPY_COLLECTION

Quando definido como true, se um documento carregado for um array, o conteúdo do array será carregado como documentos, e não como array propriamente. Isso só se aplica ao array de nível superior.

Quando definido como true, todo o array é inserido como documento único.

Esta opção só é válida para dados de coleção JSON com DBMS_CLOUD.COPY_COLLECTION.

unpackarrays: true

Valor padrão: False