Entrée et sortie binaires¶

Snowflake accepte trois formats binaires ou schĂ©mas d’encodage : hex, base64 et UTF-8.

Présentation des formats binaires pris en charge¶

Cette section décrit les formats binaires pris en charge.

hex (par défaut)¶

Le format « hex Â» se rĂ©fĂšre au systĂšme hexadĂ©cimal, ou base 16. Dans ce format, chaque octet est reprĂ©sentĂ© par deux caractĂšres (chiffres de 0 Ă  9 et lettres de A Ă  F). Lors de l’utilisation du format hexadĂ©cimal pour effectuer la conversion :

From

À

Remarques

Binaire

ChaĂźne

hex utilise des lettres majuscules.

ChaĂźne

Binaire

hex est insensible Ă  la casse.

hex est le format binaire par défaut.

base64¶

Le format « base64 Â» encode les donnĂ©es binaires (ou les donnĂ©es de chaĂźne) sous forme de caractĂšres ASCII imprimables (lettres, chiffres et signes de ponctuation ou opĂ©rateurs mathĂ©matiques). (Le schĂ©ma d’encodage en base64 est dĂ©fini dans RFC 4648.)

Les donnĂ©es encodĂ©es en Base64 prĂ©sentent les avantages suivants :

  • Les donnĂ©es encodĂ©es en base64 Ă©tant du texte ASCII pur, elles peuvent ĂȘtre stockĂ©es dans des systĂšmes prenant en charge les donnĂ©es de type ASCII mais pas les donnĂ©es BINARY. Par exemple, les donnĂ©es binaires reprĂ©sentant de la musique (Ă©chantillons numĂ©riques) ou les donnĂ©es UTF reprĂ©sentant des caractĂšres en mandarin peuvent ĂȘtre codĂ©es sous forme de texte ASCII et stockĂ©es dans des systĂšmes ne prenant en charge que les caractĂšres ASCII.

  • Comme les donnĂ©es encodĂ©es en base64 ne contiennent pas de caractĂšres de contrĂŽle (par exemple, des caractĂšres de fin de transmission, des caractĂšres de tabulation), les donnĂ©es encodĂ©es en base64 peuvent ĂȘtre transmises et reçues sans risque que les caractĂšres de contrĂŽle puissent ĂȘtre interprĂ©tĂ©s comme des commandes plutĂŽt que des donnĂ©es. Les donnĂ©es encodĂ©es en Base64 sont compatibles avec les modems plus anciens et les autres Ă©quipements de tĂ©lĂ©communication qui transmettent et reçoivent des donnĂ©es un caractĂšre Ă  la fois (sans en-tĂȘtes de paquets ni protocoles indiquant quelles parties d’un paquet sont des donnĂ©es et quelles parties sont des informations de contrĂŽle ou d’en-tĂȘte).

Les donnĂ©es encodĂ©es en Base64 prĂ©sentent les inconvĂ©nients suivants :

  • La conversion des donnĂ©es entre les reprĂ©sentations binaires et imprimables ASCII consomme des ressources de calcul.

  • Les donnĂ©es encodĂ©es en Base64 nĂ©cessitent environ 1/3 d’espace de stockage de plus que les donnĂ©es d’origine.

Les sections suivantes fournissent des dĂ©tails techniques sur l’encodage base64.

DĂ©tails de l’encodage base64¶

Chaque groupe de trois octets de 8 bits (un total de 24 bits) de donnĂ©es binaires est rĂ©organisĂ© en quatre groupes de 6 bits chacun (toujours 24 bits). Chacune des 64 combinaisons possibles de 6 bits est reprĂ©sentĂ©e par l’un des 64 caractĂšres ASCII imprimables suivants :

  • Lettres majuscules (A - Z)

  • Lettres minuscules (a - z)

  • Chiffres dĂ©cimaux (0 - 9)

  • +

  • /

De plus, le caractĂšre = est utilisĂ© pour le remplissage si la longueur de l’entrĂ©e n’est pas un multiple exact de 3.

Comme les donnĂ©es encodĂ©es en base64 ne contiennent pas de caractĂšres d’espacement (espaces, sauts de lignes, etc.), les donnĂ©es encodĂ©es en base64 peuvent ĂȘtre mĂ©langĂ©es avec des espaces si vous le souhaitez. Par exemple, si l’émetteur ou le rĂ©cepteur a une longueur de ligne maximale limitĂ©e, les donnĂ©es encodĂ©es en base64 peuvent ĂȘtre fractionnĂ©es en lignes individuelles en ajoutant des caractĂšres de nouvelle ligne sans corrompre les donnĂ©es. Lors de l’utilisation de base64 pour effectuer la conversion :

From

À

Remarques

Binaire

ChaĂźne

Base64 n’insùre pas d’espace ni de saut de ligne.

ChaĂźne

Binaire

Base64 ignore tous les espaces blancs et les sauts de ligne.

UTF-8¶

Le format UTF-8 fait référence au codage des caractÚres UTF-8 pour Unicode.

UTF-8 est utilisĂ© pour les codages binaires Ă  texte. UTF-8 ne peut pas ĂȘtre utilisĂ© pour les codages binaires Ă  texte, car toutes les valeurs BINARY possibles ne peuvent pas ĂȘtre converties en chaĂźnes UTF-8 valides.

Ce format est pratique pour effectuer une conversion simple entre un format binaire et une chaĂźne, pour rĂ©interprĂ©ter les donnĂ©es sous-jacentes comme l’un ou l’autre type plutĂŽt que d’encoder et dĂ©coder rĂ©ellement.

ParamÚtres de session pour les valeurs binaires¶

Il existe deux paramĂštres de session qui dĂ©terminent comment les valeurs binaires sont transmises Ă  l’intĂ©rieur et Ă  l’extĂ©rieur de Snowflake :

  • BINARY_INPUT_FORMAT : SpĂ©cifie le format de l’entrĂ©e VARCHAR des fonctions qui font la conversion de VARCHAR vers BINARY. Ce paramĂštre est utilisĂ© pour :

    • Effectuer la conversion en BINARY dans la version Ă  un argument de TO_BINARY.

    • Charger des donnĂ©es dans Snowflake (si aucune option de format de fichier n’est spĂ©cifiĂ©e ; voir ci-dessous pour plus de dĂ©tails).

    Le paramĂštre peut ĂȘtre rĂ©glĂ© sur HEX, BASE64 ou UTF-8 (ou UTF8). Les valeurs des paramĂštres sont insensibles Ă  la casse. La valeur par dĂ©faut est HEX.

  • BINARY_OUTPUT_FORMAT : SpĂ©cifie le format de la sortie VARCHAR des fonctions qui font la conversion de BINARY en VARCHAR. Ce paramĂštre est utilisĂ© pour :

    • Effectuer la conversion en VARCHAR dans la version Ă  un argument de TO_CHAR , TO_VARCHAR.

    • DĂ©charger des donnĂ©es depuis Snowflake (si aucune option de format de fichier n’est spĂ©cifiĂ©e ; voir ci-dessous pour plus de dĂ©tails).

    • Affichage de donnĂ©es binaires dans un format lisible par l’homme (par exemple, dans l’interface Web de Snowflake), alors qu’aucune conversion binaire-varchar n’a Ă©tĂ© appelĂ©e de façon explicite.

    Le paramĂštre peut ĂȘtre rĂ©glĂ© sur HEX ou BASE64. Les valeurs des paramĂštres sont insensibles Ă  la casse. La valeur par dĂ©faut est HEX.

    Note

    Comme la conversion du format binaire Ă  la chaĂźne peut Ă©chouer avec le format UTF-8, BINARY_OUTPUT_FORMAT ne peut pas ĂȘtre rĂ©glĂ© sur UTF-8. Pour utiliser UTF-8 pour la conversion dans ce cas de figure, utilisez la version Ă  deux arguments de TO_CHAR , TO_VARCHAR.

Les paramĂštres peuvent ĂȘtre dĂ©finis aux niveaux du compte, de l’utilisateur et de la session. ExĂ©cutez la commande SHOW PARAMETERS pour afficher les paramĂštres actuels qui s’appliquent Ă  toutes les opĂ©rations de la session en cours.

Option de format de fichier pour charger/décharger des valeurs binaires¶

En plus des paramĂštres de session binaires d’entrĂ©e et de sortie, Snowflake offre l’option de format de fichier BINARY_FORMAT, qui peut ĂȘtre utilisĂ©e pour contrĂŽler explicitement le formatage binaire lors du chargement ou du dĂ©chargement des donnĂ©es dans les tables Snowflake.

Cette option peut ĂȘtre rĂ©glĂ©e sur HEX, BASE64 ou UTF-8 (les valeurs sont insensibles Ă  la casse). L’option concerne Ă  la fois le chargement et le dĂ©chargement des donnĂ©es et, comme les autres options de format de fichier, peut ĂȘtre spĂ©cifiĂ©e de plusieurs façons :

  • Dans un format de fichier nommĂ©, qui peut ensuite ĂȘtre rĂ©fĂ©rencĂ© dans une zone de prĂ©paration nommĂ©e ou directement dans une commande COPY.

  • Dans une zone de prĂ©paration nommĂ©e, qui peut ensuite ĂȘtre rĂ©fĂ©rencĂ©e directement dans une commande COPY.

  • Directement dans une commande COPY.

Chargement des données¶

Lorsqu’il est utilisĂ© pour le chargement des donnĂ©es, BINARY_FORMAT spĂ©cifie le format de valeurs binaires dans vos fichiers de donnĂ©es mis en zone de prĂ©paration. Cette option annule toute valeur dĂ©finie pour le paramĂštre BINARY_INPUT_FORMAT dans la session (voir ParamĂštres de session pour les valeurs binaires).

Si l’option est rĂ©glĂ©e sur HEX ou BASE64, le chargement des donnĂ©es peut Ă©chouer lorsque les chaĂźnes du fichier de donnĂ©es mis en zone de prĂ©paration ne sont pas valides par rapport au format hex ou base64. Dans ce cas, Snowflake retourne une erreur et exĂ©cute l’action spĂ©cifiĂ©e pour l’option de copie ON_ERROR.

Déchargement des données¶

Lorsqu’elle est utilisĂ©e dans le dĂ©chargement de donnĂ©es, l’option BINARY_FORMAT spĂ©cifie le format appliquĂ© aux valeurs binaires dĂ©chargĂ©es dans les fichiers situĂ©s dans la zone de prĂ©paration spĂ©cifiĂ©e. Cette option annule toute valeur dĂ©finie pour le paramĂštre BINARY_OUTPUT_FORMAT dans la session (voir ParamĂštres de session pour les valeurs binaires).

Si l’option est rĂ©glĂ©e sur UTF-8, le dĂ©chargement des donnĂ©es Ă©choue lorsque l’une des valeurs binaires de la table contient des donnĂ©es UTF-8 non valides. Dans ce cas, Snowflake renvoie une erreur.

Exemple d’entrĂ©e/de sortie¶

Les entrĂ©es/sorties BINARY peuvent ĂȘtre dĂ©routantes car « ce que vous voyez n’est pas nĂ©cessairement ce que vous obtenez Â».

Prenons l’exemple suivant :

CREATE OR REPLACE TABLE binary_table (v VARCHAR, b BINARY);

INSERT INTO binary_table (v, b)
  SELECT 'AB', TO_BINARY('AB');

SELECT v, b FROM binary_table;
Copy
+----+----+
| V  | B  |
|----+----|
| AB | AB |
+----+----+

Les sorties de la colonne v (VARCHAR) et de la colonne b semblent identiques. Pourtant, la valeur de la colonne b a Ă©tĂ© convertie en binaire. Pourquoi la valeur de la colonne b reste-t-elle inchangĂ©e ?

La rĂ©ponse est que l’argument de TO_BINARY est traitĂ© comme une sĂ©quence de chiffres hexadĂ©cimaux (mĂȘme s’il se trouve entre guillemets et ressemble donc Ă  une chaĂźne). Les deux caractĂšres que vous voyez sont en fait interprĂ©tĂ©s comme une paire de chiffres hexadĂ©cimaux reprĂ©sentant un octet de donnĂ©es binaires, et non deux octets de donnĂ©es de chaĂźne. (Cela n’aurait pas fonctionnĂ© si notre « chaĂźne Â» d’entrĂ©e contenait des caractĂšres autres que des chiffres hexadĂ©cimaux ; le rĂ©sultat aurait Ă©tĂ© un message d’erreur similaire Ă  "String '...' isn't a legal hex-encoded string".)

De plus, lorsque des donnĂ©es BINARY sont affichĂ©es, elles sont affichĂ©es par dĂ©faut sous la forme d’une sĂ©quence de chiffres hexadĂ©cimaux. Ainsi, les donnĂ©es sont entrĂ©es sous forme de chiffres hexadĂ©cimaux (pas une chaĂźne) et sont affichĂ©es sous forme de chiffres hexadĂ©cimaux, de sorte qu’elles semblent inchangĂ©es.

En fait, si l’objectif Ă©tait de stocker la chaĂźne Ă  deux caractĂšres AB, le code Ă©tait incorrect. Le code appropriĂ© utiliserait la fonction HEX_ENCODE pour convertir la chaĂźne en une sĂ©quence de chiffres hexadĂ©cimaux (ou utiliserait une autre fonction « encoder Â» pour effectuer la conversion dans un autre format, tel que base64) avant de stocker les donnĂ©es. Voici des exemples.

Exemple de format hexadĂ©cimal (« HEX Â»)¶

Pour entrer des donnĂ©es BINARY, vous pouvez les encoder sous la forme d’une chaĂźne de caractĂšres hexadĂ©cimaux, comme indiquĂ© dans l’exemple suivant.

Commencez par crĂ©er une table avec une colonne BINARY :

CREATE OR REPLACE TABLE demo_binary_hex (b BINARY);
Copy

Si vous essayez d’insĂ©rer une chaĂźne « ordinaire Â» en utilisant la fonction TO_BINARY pour essayer de la convertir en une valeur BINARY valide, elle Ă©choue :

INSERT INTO demo_binary_hex (b) SELECT TO_BINARY('HELP', 'HEX');
Copy

Voici le message d’erreur :

100115 (22000): The following string is not a legal hex-encoded value: 'HELP'

Cette fois, convertissez explicitement l’entrĂ©e en une chaĂźne de chiffres hexadĂ©cimaux avant de l’insĂ©rer (cela rĂ©ussira) :

INSERT INTO demo_binary_hex (b) SELECT TO_BINARY(HEX_ENCODE('HELP'), 'HEX');
Copy

Maintenant, rĂ©cupĂ©rez les donnĂ©es :

SELECT TO_VARCHAR(b), HEX_DECODE_STRING(TO_VARCHAR(b)) FROM demo_binary_hex;
Copy
+---------------+----------------------------------+
| TO_VARCHAR(B) | HEX_DECODE_STRING(TO_VARCHAR(B)) |
|---------------+----------------------------------|
| 48454C50      | HELP                             |
+---------------+----------------------------------+

Comme vous pouvez le constater, la sortie est affichĂ©e par dĂ©faut en hexadĂ©cimal. Pour rĂ©cupĂ©rer la chaĂźne d’origine, utiliser la fonction HEX_DECODE_STRING (le complĂ©ment de la fonction HEX_ENCODE qui Ă©tait utilisĂ©e prĂ©cĂ©demment pour encoder la chaĂźne).

La requĂȘte suivante montre plus en dĂ©tail ce qui se passe en interne :

SELECT 'HELP',
       HEX_ENCODE('HELP'),
       b,
       HEX_DECODE_STRING(HEX_ENCODE('HELP')),
       TO_VARCHAR(b),
       HEX_DECODE_STRING(TO_VARCHAR(b))
  FROM demo_binary_hex;
Copy
+--------+--------------------+----------+---------------------------------------+---------------+----------------------------------+
| 'HELP' | HEX_ENCODE('HELP') | B        | HEX_DECODE_STRING(HEX_ENCODE('HELP')) | TO_VARCHAR(B) | HEX_DECODE_STRING(TO_VARCHAR(B)) |
|--------+--------------------+----------+---------------------------------------+---------------+----------------------------------|
| HELP   | 48454C50           | 48454C50 | HELP                                  | 48454C50      | HELP                             |
+--------+--------------------+----------+---------------------------------------+---------------+----------------------------------+

Exemple de format BASE64¶

Avant de lire cette section, voir Exemple de format hexadĂ©cimal (« HEX Â»). Les concepts de base sont similaires et Exemple de format hexadĂ©cimal (« HEX Â») les explique plus en dĂ©tail.

Commencez par crĂ©er une table avec une colonne BINARY :

CREATE OR REPLACE TABLE demo_binary_base64 (b BINARY);
Copy

InsĂ©rer une ligne :

INSERT INTO demo_binary_base64 (b) SELECT TO_BINARY(BASE64_ENCODE('HELP'), 'BASE64');
Copy

RĂ©cupĂ©rer cette ligne :

SELECT 'HELP',
       BASE64_ENCODE('HELP'),
       BASE64_DECODE_STRING(BASE64_ENCODE('HELP')),
       TO_VARCHAR(b, 'BASE64'),
       BASE64_DECODE_STRING(TO_VARCHAR(b, 'BASE64'))
 FROM demo_binary_base64;
Copy
+--------+-----------------------+---------------------------------------------+-------------------------+-----------------------------------------------+
| 'HELP' | BASE64_ENCODE('HELP') | BASE64_DECODE_STRING(BASE64_ENCODE('HELP')) | TO_VARCHAR(B, 'BASE64') | BASE64_DECODE_STRING(TO_VARCHAR(B, 'BASE64')) |
|--------+-----------------------+---------------------------------------------+-------------------------+-----------------------------------------------|
| HELP   | SEVMUA==              | HELP                                        | SEVMUA==                | HELP                                          |
+--------+-----------------------+---------------------------------------------+-------------------------+-----------------------------------------------+

Exemple de format UTF-8¶

Commencez par crĂ©er une table avec une colonne BINARY :

CREATE OR REPLACE TABLE demo_binary_utf8 (b BINARY);
Copy

InsĂ©rer une ligne :

INSERT INTO demo_binary_utf8 (b) SELECT TO_BINARY('HELP', 'UTF-8');
Copy

RĂ©cupĂ©rer cette ligne :

SELECT 'HELP',
       TO_VARCHAR(b, 'UTF-8')
  FROM demo_binary_utf8;
Copy
+--------+------------------------+
| 'HELP' | TO_VARCHAR(B, 'UTF-8') |
|--------+------------------------|
| HELP   | HELP                   |
+--------+------------------------+