Mappage des types de données entre SQL et les langages de traitement

Dans ce chapitre :

Une procédure stockée ou une fonction définie par l’utilisateur que vous écrivez est appelée depuis SQL, et reçoit et renvoie donc des valeurs dans des types de données SQL. Toutefois, son gestionnaire sous-jacent utilisera les types de données du langage du gestionnaire, comme Java, Python ou Scala. Au moment de l’exécution, Snowflake effectue une conversion entre les types SQL et les types de gestionnaire pour les arguments et les valeurs de retour.

Notez que Snowflake effectue également ces conversions dans les cas suivants :

  • Lors de la construction dynamique d’une instruction SQL utilisant une valeur dans une variable du gestionnaire.

  • Lors de la liaison de la valeur d’une variable du gestionnaire à une instruction préparée.

Cette rubrique décrit les mappages valides entre les données et les types SQL et ceux des langages de gestionnaire pris en charge. Utilisez ce contenu pour choisir les types de données lors de l’écriture d’un gestionnaire.

Pour plus d’informations sur les types de données SQL de Snowflake , voir Résumé des types de données.

Mappages de type de données SQL-Java

Le tableau ci-dessous montre les mappages de types entre SQL et Java. Ces mappages s’appliquent généralement à la fois aux arguments transmis à la procédure ou à la fonction et aux valeurs renvoyées. Il existe toutefois quelques exceptions, qui sont énumérées dans les notes de bas de page.

Notez que certains types de données SQL (par exemple, NUMBER) sont compatibles avec plusieurs types de données Java (par exemple, int, long, etc.). Dans ces cas, vous pouvez utiliser n’importe quel type de données Java ayant une capacité suffisante pour contenir les valeurs réelles qui seront transmises. Si vous transmettez une valeur SQL à un type de données Java incompatible (ou vice versa), Snowflake émet une erreur.

Type SQL

Type Java

Remarques

ARRAY

String[]

Formate les éléments du tableau sous forme de chaînes de caractères.

ARRAY

String

Formate le tableau comme une chaîne JSON (par exemple [1, "foo", null]).

BINARY

byte[]

BINARY

String

Encode la chaîne binaire en hexadécimal. [4]

BINARY

InputStream

Expose la valeur BINARY comme une séquence d’octets.

BOOLEAN

boolean

Ne peut être nul.

BOOLEAN

Boolean

BOOLEAN

String

[4]

DATE

java.sql.Date

DATE

String

Formate la date sous la forme YYYY-MM-DD. [4]

FLOAT

double

Ne peut être nul.

FLOAT

Double

FLOAT

float

Ne peut être nul. Peut entraîner une perte de précision.

FLOAT

Float

Peut entraîner une perte de précision.

FLOAT

String

Peut entraîner une perte de précision (la conversion float-> chaîne est avec perte).

GEOGRAPHY

String

Formate la géographie comme GeoJSON .

GEOGRAPHY

Geography

[5]

NUMBER

short

Ne peut être nul. Doit se situer dans l’intervalle des valeurs courtes (pas de partie fractionnaire et la partie entière ne peut pas dépasser les valeurs courtes max/min).

NUMBER

Short

Doit se situer dans l’intervalle des valeurs courtes (pas de partie fractionnaire, et la partie entière ne peut pas dépasser les valeurs courtes max/min).

NUMBER

int

Ne peut être nul. Doit être compris dans l’intervalle des int (pas de partie fractionnaire, et la partie entière ne peut pas dépasser les valeurs int max/min).

NUMBER

Integer

Doit être compris dans l’intervalle des int (pas de partie fractionnaire, et la partie entière ne peut pas dépasser les valeurs int max/min).

NUMBER

long

Ne peut être nul. Doit être compris dans l’intervalle des valeurs longues (pas de partie fractionnaire, et la partie entière ne peut pas dépasser les valeurs longues max/min).

NUMBER

Long

Doit être compris dans l’intervalle des valeurs longues (pas de partie fractionnaire, et la partie entière ne peut pas dépasser les valeurs longues max/min).

NUMBER

java.math.BigDecimal

NUMBER

java.math.BigInteger

Doit être compris dans l’intervalle de BigInteger (pas de partie fractionnaire).

NUMBER

String

OBJECT

Map<Chaîne , chaîne>

Les clés de la carte sont les clés de l’objet, et les valeurs sont formatées comme des chaînes de caractères.

OBJECT

String

Formate l’objet sous la forme d’une chaîne JSON (par exemple {"x": 3, "y": true}).

TIME

java.sql.Time

[3]

TIME

String

Formate l’heure sous la forme HH:MI:SS.SSSSSSSSS où la partie en fraction de secondes dépend de la précision de l’heure. [3]

TIMESTAMP_LTZ

java.sql.Timestamp

Doit être compris dans l’intervalle de java.sql.Timestamp. [3]

TIMESTAMP_LTZ

String

Le format de sortie est DY, DD MON YYYY HH24:MI:SS TZHTZM. [1] , [3] , [4]

TIMESTAMP_NTZ

java.sql.Timestamp

Doit être compris dans l’intervalle de java.sql.Timestamp. Traite le temps de type durée chronométrée comme un décalage par rapport à l’époque Unix (imposant un fuseau horaire UTC, en fait). [3]

TIMESTAMP_NTZ

String

Traite le temps de type durée chronométrée comme un décalage par rapport à l’époque Unix (imposant un fuseau horaire UTC, en fait). Le format de sortie est DY, DD MON YYYY HH:MI:SS. [2] , [3] , [4]

TIMESTAMP_TZ

java.sql.Timestamp

Doit être compris dans l’intervalle de java.sql.Timestamp. [3]

TIMESTAMP_TZ

String

Le format de sortie est DY, DD MON YYYY HH24:MI:SS TZHTZM. [1] , [3] , [4]

VARCHAR

String

VARIANT

Variante

Le type de données Variant est une classe du paquet Snowpark. Pour plus d’information, voir Types de paquets Snowpark pris en charge pour les fonctions définies par l’utilisateur. Pour un exemple, voir Transmission d’une valeur VARIANT à une UDF Java en ligne.

Tableaux

Les UDFs Java peuvent recevoir des tableaux de l’un des types de données Java suivants :

Type de données

Remarques

String

boolean

L’ARRAY Snowflake ne doit contenir que des éléments BOOLEAN, et ne doit pas contenir de valeurs NULL.

double

float

L’ARRAY Snowflake doit contenir l’une des valeurs suivantes et ne doit pas contenir de valeurs NULL.

int

long

short

L’ARRAY Snowflake ne doit contenir que des éléments à point fixe avec une échelle de 0, et ne doit pas contenir de valeurs NULL.

Valeurs NULL

Snowflake prend en charge deux valeurs NULL distinctes : SQL NULL et JSON null de VARIANT. (Pour des informations sur les données VARIANT NULL Snowflake, voir Valeurs NULL.)

Java prend en charge une seule valeur null, qui ne concerne que les types de données non primitifs.

Un argument SQL NULL dans un gestionnaire Java se traduit par la valeur null Java, mais seulement pour les types de données Java qui prennent en charge null.

Une valeur Java null renvoyée est reconvertie au format SQL NULL.

Valeurs et fuseaux horaires TIMESTAMP_LTZ

Une UDF Java est largement isolée de l’environnement dans lequel elle est appelée. Cependant, le fuseau horaire est hérité de l’environnement d’appel. Si la session de l’appelant a défini un fuseau horaire par défaut avant d’appeler l’UDF Java , alors l’UDF Java a le même fuseau horaire par défaut. L’UDF Java utilise les mêmes données de la base de données des fuseaux horaires IANA que la base native TIMEZONE Snowflake SQL (c’est-à-dire les données de la version 2021a de la base de données des fuseaux horaires).

Types de paquets Snowpark pris en charge pour les fonctions définies par l’utilisateur

Dans une fonction définie par l’utilisateur, vous pouvez utiliser un sous-ensemble spécifique de types inclus dans le paquet Java Snowpark Snowflake. Bien que ces types soient conçus pour être utilisés dans du code Snowpark, certains sont également pris en charge pour être utilisés dans des UDFs pour la commodité qu’ils peuvent apporter. (Pour en savoir plus sur Snowpark, voir la documentation Snowpark.)

Note

La bibliothèque Snowpark est indispensable pour les procédures stockées écrites en Java, Python et Scala. Par conséquent, vous pouvez y utiliser les types Snowpark sans restriction.

Les types Snowpark figurant dans le tableau suivant sont pris en charge dans le code UDF. Vous ne devez pas utiliser d’autres types Snowpark dans le code UDF, ils n’y sont pas pris en charge.

Type Snowpark

Version Snowpark requise

Description

Geography

1.2.0 ou supérieure

Représente le type GEOGRAPHY de Snowflake. Pour un exemple qui utilise le type de données Geography, voir Transmission d’une valeur GEOGRAPHY à une UDF Java en ligne.

Variante

1.4.0 et supérieure

Représente les données VARIANT Snowflake. Pour un exemple qui utilise le type de données Variant, voir Transmission d’une valeur VARIANT à une UDF Java en ligne.

Spécification du paquet Snowpark en tant que dépendance

Lorsque vous développez du code UDF qui utilise le paquet Snowpark, vous devez configurer votre environnement de développement de manière à pouvoir compiler et exécuter du code avec des dépendances Snowpark. Pour en savoir plus, voir Configuration d’autres environnements de développement pour Snowpark Java.

Lorsque vous déployez une UDF en exécutant l’instruction CREATE FUNCTION vous pouvez spécifier le paquet Snowpark en tant que dépendance sans charger le fichier JAR vers une zone de préparation (la bibliothèque est déjà dans Snowflake). Pour ce faire, spécifiez le nom et la version du paquet dans la clause PACKAGES. Pour un exemple de syntaxe, voir Transmission d’une valeur GEOGRAPHY à une UDF Java en ligne.

Mappages de type de données SQL-JavaScript

Le tableau suivant indique les types de données SQL Snowflake et les types de données JavaScript correspondants :

Type de données SQL

Type de données JavaScript

Remarques

ARRAY

JSON

BOOLEAN

boolean

DATE

date

GEOGRAPHY, GEOMETRY

JSON

REAL, FLOAT, FLOAT8, FLOAT4, DOUBLE, DOUBLE PRECISION

number

TIME

string

TIMESTAMP, TIMESTAMP_LTZ, TIMESTAMP_NTZ, TIMESTAMP_TZ

date ou SfDate

Lorsqu’un horodatage est transmis en tant qu’argument à une procédure stockée, l’horodatage est converti en objet JavaScript date. Dans d’autres situations (par exemple, lors de la récupération de ResultSet), un horodatage est converti en un objet SfDate. Pour plus de détails sur le type de données SfDate, qui n’est pas un type de données standard JavaScript, reportez-vous à la section API de procédures stockées JavaScript.

VARCHAR, CHAR, CHARACTER, STRING, TEXT

string

VARIANT

JSON

Remarques

Tous les types de données SQL de Snowflake ont un type de données JavaScript correspondant. Par exemple, JavaScript ne prend pas directement en charge les types de données INTEGER ou NUMBER. Dans ces cas, vous devez convertir le type de données SQL en un type de données alternatif approprié. Par exemple, vous pouvez convertir un SQL INTEGER en SQL FLOAT, qui peut ensuite être converti en une valeur JavaScript de type de données number.

Le tableau ci-dessous indique les conversions appropriées pour les types de données SQL incompatibles :

Type de données SQL incompatible

Type de données SQL incompatible

BINARY

Uint8Array

INTEGER

FLOAT

NUMBER, NUMERIC, DECIMAL

FLOAT

OBJECT

Uint8Array

Lors du renvoi de valeurs

Si l’instruction return dans JavaScript renvoie un type de données différent du type de retour déclaré de la procédure stockée, la valeur JavaScript est, si possible, convertie en type de données SQL. Par exemple, si un nombre est renvoyé, mais que la procédure stockée est déclarée comme renvoyant une chaîne, le nombre est converti en chaîne au sein de JavaScript, puis copié dans la chaîne renvoyée dans l’instruction SQL. (Gardez à l’esprit que les erreurs de programmation JavaScript, comme le retour du type de données incorrect, peuvent être masquées par ce comportement.)

Si aucune conversion valide pour la conversion n’existe, une erreur se produit.

Lors de la liaison de valeurs

Lorsque vous liez des variables JavaScript à des instructions SQL, Snowflake convertit les types de données JavaScript en types de données SQL. Vous pouvez lier des variables des types de données JavaScript suivants :

  • nombre

  • chaîne

  • SfDate

    Pour plus de détails sur le type de données SfDate, qui n’est pas un type de données standard JavaScript, reportez-vous à la section API de procédures stockées JavaScript.

Pour plus d’informations sur la liaison, avec quelques exemples, voir Variables de liaison.

Vous pouvez également trouver les sujets suivants utiles :

Mappages des types de données SQL-Python

Le tableau ci-dessous montre les mappages de types entre SQL et Python. Ces mappages s’appliquent généralement à la fois aux arguments transmis au gestionnaire Python et aux valeurs renvoyées.

Type SQL

Type Python

Remarques

ARRAY

list

Lorsqu’un type de données Python est converti en ARRAY, s’il y a des données décimales Python intégrées, celles-ci seront converties en chaîne dans le ARRAY.

BINARY

bytes

BOOLEAN

bool

DATE

datetime.date

FLOAT

float

Les opérations en virgule flottante peuvent présenter de petites erreurs d’arrondi, qui peuvent s’accumuler, notamment lorsque les fonctions d’agrégation traitent un grand nombre de lignes. Les erreurs d’arrondi peuvent varier à chaque exécution de la requête si les lignes sont traitées dans un ordre différent. Pour plus d’informations, voir Types de données numériques : Flottant.

GEOGRAPHY, GEOMETRY

dict

Formate la géographie sous forme de GeoJSON, puis la convertit en un dict Python.

NUMBER

int ou decimal.Decimal

Si l’échelle du type NUMBER est 0, le type Python int est utilisé. Sinon, le type decimal.Decimal est utilisé.

OBJECT

dict

Lorsqu’un type de données Python est converti en OBJECT, s’il y a des données décimales Python intégrées, celles-ci seront converties en chaîne dans le OBJECT.

TIME

datetime.time

Bien que Snowflake puisse stocker des valeurs temporelles avec une précision de l’ordre de la nanoseconde, le type datetime.time n’offre qu’une précision de l’ordre de la milliseconde. La conversion entre les types de données Snowflake et Python peut réduire la précision effective à des millisecondes.

TIMESTAMP_LTZ

datetime.datetime

Utilisez le fuseau horaire local pour convertir l’heure interne UTC en heure locale « naïve ». Requiert le type de retour datetime « naïf ».

TIMESTAMP_NTZ

datetime.datetime

Convertissez directement en datetime « naïf ». Requiert le type de retour datetime « naïf ».

TIMESTAMP_TZ

datetime.datetime

Convertissez en datetime « sensible » avec des informations sur le fuseau horaire. Requiert le type de retour datetime « sensible ».

VARCHAR

str

VARIANT

dict, list, int, float, str, ou bool

Chaque ligne de variante est convertie dynamiquement en un type Python pour les arguments et vice versa pour les valeurs de retour. Les types suivants sont convertis en chaînes plutôt qu’en types Python natifs : décimal, binaire, date, heure, timestamp_ltz, timestamp_ntz, timestamp_tz. Lorsqu’un type de données Python est converti en VARIANT, s’il y a des données décimales Python intégrées, celles-ci seront converties en chaîne dans le VARIANT.

Mappages de type de données SQL-Scala

Snowflake prend en charge les types de données Scala suivants en plus des types Java répertoriés dans Mappages de type de données SQL-Java :

Type de données SQL

Type Scala

Remarques

ARRAY

Array[String]

BINARY

Array[Byte]

BOOLEAN

Boolean ou Option[Boolean]

DOUBLE

Double ou Option[Double]

FLOAT

Float ou Option[Float]

NUMBER

Les types suivants sont pris en charge :

  • Int ou Option[Int]

  • Long ou Option[Long]

OBJECT

Map[String, String]

VARCHAR

String

VARIANT

String

Formate la valeur en fonction du type qui est représenté. Variante null est formatée comme la chaîne « null ».

Pour DATE et TIMESTAMP, utilisez les types Java répertoriés dans Mappages de type de données SQL-Java.