Documentation sur Oracle Cloud Infrastructure

Objets JSON textuels représentant des valeurs scalaires étendues

Les données JSON binaires natives (format OSON) étendent le langage JSON en ajoutant des types scalaires, tels que la date, qui correspondent à des types SQL et ne font pas partie de la norme JSON. Oracle Database prend également en charge l'utilisation d'objets JSON textuels qui représentent des valeurs scalaires JSON, y compris ces valeurs non standard.

Lorsque vous créez des données JSON binaires natives à partir de données JSON textuelles qui contiennent de tels objets étendus, elles peuvent éventuellement être remplacées avec les valeurs scalaires JSON correspondantes (binaire natif).

Un exemple d'objet étendu est {"$numberDecimal":31}. Il représente une valeur scalaire JSON du type non standard nombre décimal et, lorsqu'il est interprété comme tel, il est remplacé par un nombre décimal au format binaire natif.

Par exemple, lorsque vous utilisez le constructeur de type de données JSON, JSON, si vous utilisez le mot clé EXTENDED, les objets étendus reconnus dans l'entrée textuelle sont remplacés par des valeurs scalaires correspondantes dans le résultat JSON binaire natif. Si vous n'incluez pas le mot clé EXTENDED, aucun remplacement de ce type ne se produit; les objets JSON étendus textuels sont simplement convertis tels quels en objets JSON dans le format binaire natif.

Dans la direction opposée, lorsque vous utilisez la fonction SQL/JSON json_serialize pour sérialiser les données JSON binaires en tant que données JSON textuelles (VARCHAR2, CLOB ou BLOB), vous pouvez utiliser le mot clé EXTENDED pour remplacer les valeurs scalaires JSON (binaire natif) par les objets JSON étendus textuels correspondants.

Note

Si la base de données que vous utilisez est une base de données Oracle Autonomous Database, vous pouvez utiliser la procédure PL/SQL DBMS_CLOUD.copy_collection pour créer une collection de documents JSON à partir d'un fichier de données JSON tel que celui produit par les bases de données NoSQL communes, y compris Oracle NoSQL Database.

Si vous utilisez ejson comme valeur du paramètre type de la procédure, les objets JSON étendus reconnus dans le fichier d'entrée sont remplacés par des valeurs scalaires correspondantes dans la collection JSON binaire native résultante. Dans l'autre sens, vous pouvez utiliser la fonction json_serialize avec le mot clé EXTENDED pour remplacer les valeurs scalaires par des objets JSON étendus dans les données JSON textuelles résultantes.

Voici les deux principaux cas d'utilisation des objets étendus :

  • Échange (importation/exportation) :

    • Ingérer des données JSON existantes (de quelque part) qui contiennent des objets étendus.

    • Sérialiser les données JSON binaires natives en tant que données JSON textuelles avec des objets étendus, pour une utilisation en dehors de la base de données.

  • Inspection des données JSON binaires natives : Voyez ce que vous avez en examinant les objets étendus correspondants.

Aux fins d'échange, vous pouvez ingérer des données JSON à partir d'un fichier produit par des bases de données NoSQL communes, notamment Oracle NoSQL Database, en convertissant les objets étendus en scalaires JSON binaires natifs. Dans l'autre sens, vous pouvez exporter des données JSON binaires natives en tant que données textuelles, en remplaçant les valeurs JSON scalaires propres à Oracle par les objets JSON étendus textuels correspondants.

Conseil :

À titre d'exemple d'inspection, considérez un objet tel que {"dob" : "2000-01-02T00:00:00"} comme le résultat de la sérialisation des données JSON natives. "2000-01-02T00:00:00" est-il le résultat de la sérialisation d'une valeur binaire native de type date, ou la valeur binaire native n'est-elle qu'une chaîne? L'utilisation de json_serialize avec le mot clé EXTENDED vous le permet.

Le mappage des champs d'objet étendu aux types JSON scalaires est, en général, plusieurs à un : plus d'un type d'objet JSON étendu peut être mappé à une valeur scalaire donnée. Par exemple, les objets JSON étendus {"$numberDecimal":"31"} et {"$numberLong:"31"} sont tous deux traduits par la valeur 31 du numéro de type scalaire JSON et la méthode d'élément type() retourne "number" pour chacun de ces scalaires JSON.

La méthode d'élément type() indique le type scalaire JSON de sa valeur cible (en tant que chaîne JSON). Certaines valeurs scalaires se distinguent en interne, même lorsqu'elles ont le même type scalaire. Cela permet généralement à la fonction json_serialize (avec le mot clé EXTENDED) de reconstruire l'objet JSON étendu d'origine. Ces valeurs scalaires sont distinguées à l'interne en utilisant des types SQL différents pour les mettre en oeuvre ou en les marquant avec le type d'objet JSON étendu à partir duquel elles ont été dérivées.

Lorsque json_serialize reconstruit l'objet JSON étendu initial, le résultat n'est pas toujours textuellement identique à l'original, mais il est toujours sémantiquement équivalent. Par exemple, {"$numberDecimal":"31"} et {"$numberDecimal":31} sont sémantiquement équivalents, même si les valeurs de champ diffèrent par leur type (chaîne et nombre). Ils sont traduits dans la même valeur interne et chacun est marqué comme étant dérivé d'un objet étendu $numberDecimal (même balise). Mais lorsqu'il est sérialisé, le résultat pour les deux est {"$numberDecimal":31}. Oracle utilise toujours le type le plus directement pertinent pour la valeur du champ, qui dans ce cas est la valeur de langue JSON 31, de type scalaire.

Le tableau 3-1 présente les correspondances entre les différents types utilisés. Il mappe entre (1) les types d'objets étendus utilisés en entrée, (2) les types signalés par la méthode d'élément type(), (3) les types SQL utilisés en interne, (4) les types de langue JSON standard utilisés en sortie par la fonction json_serialize et (5) les types d'objets étendus émis par json_serialize lorsque le mot clé EXTENDED est spécifié.

Tableau 3-1 : Relations étendues de type d'objet JSON

Type d'objet étendu (entrée) Type de scalaire Oracle JSON (déclaré par type()) Type scalaire SQL Type de scalaire JSON standard (sortie) Type d'objet étendu (sortie)
$numberDouble avec une valeur de numéro JSON, une chaîne représentant le nombre ou l'une de ces chaînes : "Infinity", "-Infinity", "Inf", "-Inf", "Nan"Foot 1 double BINARY_DOUBLE

nombre

 $numberDouble avec une valeur de numéro JSON ou l'une des chaînes suivantes : "Inf", "-Inf", "Nan"Foot 2
$numberFloat avec la même valeur que pour $numberDouble float BINARY_FLOAT

nombre

 $numberFloat avec la même valeur que pour $numberDouble
$numberDecimal avec la même valeur que pour $numberDouble nombre NUMBER

nombre

 $numberDecimal avec la même valeur que pour $numberDouble
$numberInt avec une valeur entière signée de 32 bits ou une chaîne représentant le nombre nombre NUMBER

nombre

 $numberInt avec la même valeur que pour $numberDouble
$numberLong avec une valeur de nombre JSON ou une chaîne représentant le nombre nombre NUMBER

nombre

 $numberLong avec la même valeur que pour $numberDouble

$binary avec l'une des valeurs suivantes :

  • une chaîne de caractères base-64
  • Objet avec les champs base64 et subType, dont les valeurs sont une chaîne de caractères base-64 et le nombre 0 (binaire arbitraire) ou 4 (UUID), respectivement

Lorsque la valeur est une chaîne de caractères base-64, l'objet étendu peut également avoir le champ $subtype avec la valeur 0 ou 4, exprimé sous la forme d'un entier d'un octet (0-255) ou d'une chaîne hexadécimale de 2 caractères. représentant un tel entier

binaire BLOB ou RAW

chaîne

La conversion équivaut à l'utilisation de la fonction SQL rawtohex.

Un des éléments suivants :
  • $binary avec valeur une chaîne de caractères de base-64
  • $rawid avec une chaîne de 32 caractères hexadécimaux, si l'entrée avait une valeur subType de 4 (UUID)
$oid avec une valeur de 24 caractères hexadécimaux binaire RAW(12)

chaîne

La conversion équivaut à l'utilisation de la fonction SQL rawtohex.

$rawid avec une valeur de 24 caractères hexadécimaux
$rawhex avec la valeur une chaîne avec un nombre pair de caractères hexadécimaux binaire RAW

chaîne

La conversion équivaut à l'utilisation de la fonction SQL rawtohex.

$binary avec valeur une chaîne de caractères base-64, avec remplissage à droite de = caractères
$rawid avec une valeur de chaîne de 24 ou 32 caractères hexadécimaux binaire RAW

chaîne

La conversion équivaut à l'utilisation de la fonction SQL rawtohex.

$rawid
$oracleDate avec une valeur de chaîne de date ISO 8601 date DATE

chaîne

 $oracleDate avec une valeur de chaîne de date ISO 8601
$oracleTimestamp avec une valeur de chaîne d'horodatage ISO 8601 estampille TIMESTAMP

chaîne

 $oracleTimestamp avec une valeur de chaîne d'horodatage ISO 8601
$oracleTimestampTZ avec la valeur une chaîne d'horodatage ISO 8601 avec un décalage de fuseau horaire numérique ou avec Z horodatage avec fuseau horaire TIMESTAMP WITH TIME ZONE

chaîne

 $oracleTimestampTZ avec la valeur une chaîne d'horodatage ISO 8601 avec un décalage de fuseau horaire numérique ou avec Z

$date avec la valeur l'un des suivants :

  • Un nombre entier de millisecondes depuis le 1er janvier 1990
  • Une chaîne d'horodatage ISO 8601
  • Objet avec le champ numberLong dont la valeur est un nombre entier de millisecondes depuis le 1er janvier 1990
horodatage avec fuseau horaire TIMESTAMP WITH TIME ZONE

chaîne

 $oracleTimestampTZ avec la valeur une chaîne d'horodatage ISO 8601 avec un décalage de fuseau horaire numérique ou avec Z
$intervalDaySecond avec une valeur d'intervalle ISO 8601 comme spécifié pour la fonction SQL to_dsinterval daysecondInterval INTERVAL DAY TO SECOND

chaîne

 $intervalDaySecond avec une valeur d'intervalle ISO 8601 comme spécifié pour la fonction SQL to_dsinterval
$intervalYearMonth avec une valeur d'intervalle ISO 8601 comme spécifié pour la fonction SQL to_yminterval yearmonthInterval INTERVAL YEAR TO MONTH

chaîne

 $intervalYearMonth avec une valeur d'intervalle ISO 8601 comme spécifié pour la fonction SQL to_yminterval

Deux champs :

  • Champ $vector avec la valeur d'un tableau dont les éléments sont des nombres ou les chaînes "Nan", "Inf" et "-Inf" (représentant des valeurs non numériques et infinies).

  • Champ $vectorElementType avec la valeur de chaîne "float32" ou "float64". Ceux-ci correspondent respectivement aux nombres IEEE 32 bits et IEEE 64 bits.

vecteur VECTOR

tableau de nombres

Deux champs :

  • Champ $vector avec la valeur d'un tableau dont les éléments sont des nombres ou les chaînes "Nan", "Inf" et "-Inf" (représentant des valeurs non numériques et infinies).

  • Champ $vectorElementType avec la valeur de chaîne "float32" ou "float64".

Note de bas de page 1 Les valeurs de chaîne sont interprétées de manière non sensible à la casse. Par exemple, "NAN" "nan" et "nAn" sont acceptés et équivalents, de même que "INF", "inFinity" et "iNf". Les nombres infiniment grands ("Infinity" ou "Inf") et petits ("-Infinity" ou "-Inf") sont acceptés avec le mot complet ou l'abréviation.

Note de bas de page 2 Sur la sortie, seules ces valeurs de chaîne sont utilisées — aucune variante de mot complet Infinity ou de lettre-case.