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. des éléments FLOAT . des éléments à point fixe (avec une échelle quelconque).
`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.