Documentação do Oracle Cloud Infrastructure

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 aos 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}. Ele 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 substituidos 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 são simplesmente convertidos como estão para objetos JSON no formato binário nativo.

Por outro lado, ao usar a função SQL/JSON json_serialize para serializar dados JSON binários como dados JSON textuais (VARCHAR2, CLOB ou BLOB), você pode usar a palavra-chave EXTENDED para substituir valores escalares JSON (binários nativos) pelos correspondentes objetos JSON textuais estendidos.

Observação

Se o banco de dados que você usa for um Oracle Autonomous 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 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. Por outro lado, 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 de objetos estendidos:

  • Intercâmbio (importação/exportação):

    • Consuma dados JSON existentes (em algum lugar) que contenham objetos estendidos.

    • Serialize dados JSON binários nativos como dados JSON textuais com objetos estendidos, para uso fora do banco de dados.

  • Inspeção de dados JSON binários nativos: consulte o que você tem examinando objetos estendidos correspondentes.

Para fins de intercâmbio, 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. Por outro lado, você pode exportar dados JSON binários nativos como dados textuais, substituindo valores JSON escalares específicos da Oracle pelos correspondentes objetos JSON textuais estendidos.

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? O uso de 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 convertidos com o valor 31 do número do tipo escalar da linguagem 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 da linguagem 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 distinguidos internamente usando diferentes tipos SQL para implementá-los ou marcando-os com o tipo de objeto JSON estendido do qual são derivados.

Quando json_serialize reconstrui 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 de campo sejam diferentes em tipo (string e número). Eles são convertidos no mesmo valor interno e cada um é marcado como derivado de um objeto estendido $numberDecimal (mesma tag). Mas quando serializado, o resultado de ambos é {"$numberDecimal":31}. A Oracle sempre usa o tipo mais diretamente relevante para o valor do campo que, nesse caso, é o valor 31 da linguagem JSON, do número do tipo escalar.

A Tabela 3-1 apresenta correspondências entre os vários tipos usados. Ela é mapeada entre (1) tipos de objetos estendidos usados como entrada, (2) tipos reportados pelo método de item type(), (3) tipos 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.

Tabela 3-1 Relações de Tipo de Objeto JSON Expandido

Tipo de objeto estendido (entrada) Tipo Escalar JSON Oracle (Reportado por type()) Tipo Escalar SQL Tipo Escalar JSON Padrão (Saída) Tipo de Objeto Estendido (Saída)
$numberDouble com o valor sendo um número JSON, uma string que representa o número ou uma destas strings: "Infinity", "-Infinity", "Inf", "-Inf", "Nan"Retroativo 1 duplo BINARY_DOUBLE

número

 $numberDouble com o valor sendo um número JSON ou uma destas strings: "Inf", "-Inf", "Nan"Rodapé 2
$numberFloat com valor igual a $numberDouble float BINARY_FLOAT

número

 $numberFloat com valor igual a $numberDouble
$numberDecimal com valor igual a $numberDouble número NUMBER

número

 $numberDecimal com valor igual a $numberDouble
$numberInt com o valor sendo um inteiro de 32 bits assinado ou uma string que representa o número número NUMBER

número

 $numberInt com valor igual a $numberDouble
$numberLong com o valor sendo um número JSON ou uma string que representa o número número NUMBER

número

 $numberLong com valor igual a $numberDouble

$binary com o valor sendo um destes:

  • uma string de caracteres base-64
  • Um objeto com os campos base64 e subType, cujos valores são uma string de caracteres base-64 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 número inteiro de um byte (0 a 255) ou uma string hexadecimal de 2 caracteres que representa esse número 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 o valor sendo uma string de caracteres base-64
  • $rawid com o valor sendo uma string de 32 caracteres hexadecimais, se a entrada tiver um valor subType igual a 4 (UUID)
$oid com o valor sendo uma string de 24 caracteres sextavados binário RAW(12)

string

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

$rawid com o valor sendo uma string de 24 caracteres sextavados
$rawhex com valor sendo uma string com um número par de caracteres hexa binário RAW

string

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

$binary com o valor sendo uma string de caracteres base-64, preenchida à direita com caracteres =
$rawid com o valor sendo 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 o valor sendo uma string de data ISO 8601 data DATE

string

 $oracleDate com o valor sendo uma string de data ISO 8601
$oracleTimestamp com o valor sendo uma string de timestamp ISO 8601 timestamp TIMESTAMP

string

 $oracleTimestamp com o valor sendo uma string de timestamp ISO 8601
$oracleTimestampTZ com o valor sendo 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 o valor sendo uma string de timestamp ISO 8601 com um deslocamento de fuso horário numérico ou com Z

$date com o valor sendo um dos seguintes:

  • Uma contagem total de milissegundos desde 1o de janeiro de 1990
  • Uma string de timestamp ISO 8601
  • Um objeto com o campo numberLong com o valor sendo uma contagem de milissegundos de números inteiros desde 1o de janeiro de 1990
timestamp com fuso horário TIMESTAMP WITH TIME ZONE

string

 $oracleTimestampTZ com o valor sendo uma string de timestamp ISO 8601 com um deslocamento de fuso horário numérico ou com Z
$intervalDaySecond com o valor sendo uma string de intervalo ISO 8601, conforme especificado para a função SQL to_dsinterval daysecondInterval INTERVAL DAY TO SECOND

string

 $intervalDaySecond com o valor sendo uma string de intervalo ISO 8601, conforme especificado para a função SQL to_dsinterval
$intervalYearMonth com o valor sendo uma string de intervalo ISO 8601, conforme especificado para a função SQL to_yminterval yearmonthInterval INTERVAL YEAR TO MONTH

string

 $intervalYearMonth com o valor sendo uma string de intervalo ISO 8601, conforme especificado para a função SQL to_yminterval

Dois campos:

  • Campo $vector com o valor de um array cujos elementos são números ou as strings "Nan", "Inf" e "-Inf" (representando não um número e valores 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

array de números

Dois campos:

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

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

Observação 1: os valores das strings são interpretados sem maiúsculas de minúsculas. Por exemplo, "NAN" "nan" e "nAn" são aceitos e equivalentes; 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.

Observação 2 Na saída, somente esses valores de string são usados - sem variantes da palavra completa Infinity ou de maiúsculas/minúsculas.