En quoi le variant est-il différent des chaînes JSON ?

info

Aperçu

Cette fonctionnalité est en aperçu public.

Cet article décrit les changements de comportement et les différences de syntaxe et de sémantique lors de l'utilisation du type de données variant. Cet article suppose que vous êtes familiarisé avec le traitement des données de chaîne JSON sur Databricks. Pour les utilisateurs novices de Databricks, vous devriez utiliser la variante plutôt que les chaînes JSON chaque fois que vous stockez des données semi-structurées qui nécessitent de la flexibilité pour un schéma changeant ou inconnu. Voir Modéliser les données semi-structurées.

Dans Databricks Runtime 15.3 et versions ultérieures, vous pouvez utiliser le type de données variant pour encoder et interroger des données semi-structurées. Databricks recommande le type de données variant en remplacement du stockage de données semi-structurées à l'aide de chaînes JSON. Les performances de lecture et d'écriture améliorées pour le type de données variant lui permettent de remplacer les types complexes natifs de Spark tels que les structures et les tableaux dans certains cas d'utilisation.

Comment interroger les données de variantes ?

Les données variantes utilisent les mêmes opérateurs pour query les champs, les sous-champs et les éléments de tableau.

Pour interroger un champ, utilisez :. Par exemple, column_name:field_name.

Pour interroger un sous-champ, utilisez .. Par exemple, column_name:field_name.subfield_name.

Pour query un élément de tableau, utilisez [n] où n est la valeur d'index entier de l'élément. Par exemple, pour interroger la première valeur d'un tableau, column_name:array_name[0].

Les différences suivantes pourraient compromettre les query existantes lors de la mise à niveau des chaînes JSON vers la variante :

• Tous les éléments de chemin de variante sont mis en correspondance de manière sensible à la casse. Les chaînes JSON ne sont pas sensibles à la casse. Cela signifie que pour une variante, column_name:FIELD_NAME et column_name:field_name recherchent différents champs dans les données stockées.
• La syntaxe [*] n'est pas prise en charge pour identifier ou décompresser tous les éléments dans un tableau.
• Le variant encode les valeurs NULL différemment des chaînes JSON. Voir Règles nulles de variante.
• Les colonnes Variant ont des limitations pour certaines Opérations. Consulter Limitations.

Convertir des chaînes JSON vers et depuis variant

Dans Databricks Runtime 15,3 et versions ultérieures, la fonction to_json dispose de fonctionnalités supplémentaires pour convertir les types VARIANT en chaînes JSON. Les options sont ignorées lors de la conversion de VARIANT en chaîne JSON. Consulter to_json.

La fonction parse_json (SQL ou Python) transforme une chaîne JSON en type VARIANT. Bien que parse_json(json_string_column) soit l'inverse logique de to_json(variant_column), les règles de conversion suivantes expliquent pourquoi il ne s'agit pas de l'inverse exact :

• Les espaces ne sont pas parfaitement conservés.
• L'ordre des clés est arbitraire.
• Les zéros de fin dans les nombres peuvent être tronqués.

SQL

SQL

SELECT parse_json('{"key": 1, "data": [2, 3, "str"]}');

Python

Python

spark.range(1).select(parse_json(lit('{"key": 1, "data": [2, 3, "str"]}'))).display()

La fonction parse_json renvoie une erreur si la chaîne JSON est mal formée, dépasse la limite de taille de la variante ou est invalide. Utilisez la fonction try_parse_json (SQL ou Python) pour renvoyer NULL lorsqu'une erreur d'analyse se produit.

SQL

SQL

SELECT try_parse_json('{"a" : invalid, "b" : 2}');

Python

Python

spark.range(1).select(try_parse_json(lit('{"a" : invalid, "b" : 2}'))).display()

Quelles sont les fonctions SQL pour travailler avec les variantes ?

Les fonctions SQL Apache Spark disponibles dans Databricks Runtime 15,3 et versions ultérieures fournissent des méthodes pour interagir avec les données de variante. Le tableau suivant comprend la nouvelle fonction, la fonction de chaîne JSON correspondante et des notes sur les différences de comportement.

Les variantes gèrent le transtypage et les NULLdifféremment des chaînes JSON. Consultez les règles de transtypage de variante et les règles de nullité de variante.

remarque

Pour utiliser ces fonctions avec les DataFrames PySpark, importez-les depuis pyspark.sql.functions.

Fonction Variante	Fonction de chaîne JSON	Notes
variant_get	cast et get_json_object	Prend une expression, un chemin et un type. Suit toutes les règles pour les chemins de variantes, le transtypage et les nulls.
try_variant_get	try_cast et get_json_object	Prend une expression, un chemin et un type. Suit toutes les règles pour les chemins de variantes, le transtypage et les nulls.
is_variant_null	est nul	Vérifie si l'expression stocke un VARIANT NULL encodé. Utilisez is null pour vérifier si l'expression d'entrée est NULL.
schéma de variante	schéma JSON	Lorsque l'on détermine le schéma pour un ARRAY<elementType>, le elementType peut être inféré comme VARIANT si des types conflictuels sont trouvés dans les données.
schema_of_variant_agg	schema_of_json_agg	Lorsqu'aucun type commun minimal n'est identifié, le type est dérivé comme VARIANT.
variant_explode	exploser	Génère pos, key et value colonnes. Lors de l’expansion d’un tableau, la clé de sortie est toujours null.
variant_explode_outer	explode_outer	Génère pos, key et value colonnes. Lors de l’expansion d’un tableau, la clé de sortie est toujours null.

Fonction Variante	Fonction de chaîne JSON	Notes
variant_get	cast et get_json_object	Prend une expression, un chemin et un type. Suit toutes les règles pour les chemins de variantes, le transtypage et les nulls.
try_variant_get	try_cast et get_json_object	Prend une expression, un chemin et un type. Suit toutes les règles pour les chemins de variantes, le transtypage et les nulls.
is_variant_null	est nul	Vérifie si l'expression stocke un VARIANT NULL encodé. Utilisez is null pour vérifier si l'expression d'entrée est NULL.
schéma de variante	schéma JSON	Lorsque l'on détermine le schéma pour un ARRAY<elementType>, le elementType peut être inféré comme VARIANT si des types conflictuels sont trouvés dans les données.
schema_of_variant_agg	schema_of_json_agg	Lorsqu'aucun type commun minimal n'est identifié, le type est dérivé comme VARIANT.
variant_explode	exploser	Génère pos, key et value colonnes. Lors de l’expansion d’un tableau, la clé de sortie est toujours null.
variant_explode_outer	explode_outer	Génère pos, key et value colonnes. Lors de l’expansion d’un tableau, la clé de sortie est toujours null.