Connecteur Python API

Le connecteur Snowflake pour Python implémente la spécification Python Database API v2.0 (PEP-249). Ce chapitre traite de l’API standard et des extensions spécifiques à Snowflake.

Dans ce chapitre :

Module : snowflake.connector

Le module principal est snowflake.connector qui crée un objet Connection et fournit des classes Error.

Constantes

apilevel

Constante de chaîne indiquant le niveau API pris en charge. Le connecteur prend en charge API "2.0".

threadsafety

Constante entière indiquant le niveau de sécurité de « thread safety » pris en charge par l’interface. Le connecteur Snowflake pour Python prend en charge le niveau 2, qui indique que les threads peuvent partager le module et les connexions.

paramstyle

Constante de chaîne indiquant le type de formatage de marqueur de paramètre attendu par l’interface. Le connecteur prend en charge le type "pyformat" par défaut, qui s’applique aux codes de format étendus Python (par exemple ...WHERE name=%s ou ...WHERE name=%(name)s). Connection.connect peut remplacer paramstyle pour changer les formats de variables de liaison en "qmark" ou "numeric", où les variables sont ? ou :N, respectivement.

Par exemple :

format: .execute("... WHERE my_column = %s", (value,))
pyformat: .execute("... WHERE my_column = %(name)s", {"name": value})
qmark: .execute("... WHERE my_column = ?", (value,))
numeric: .execute("... WHERE my_column = :1", (value,))

Note

La variable de liaison se produit du côté client si paramstyle est "pyformat" ou "format", et du côté serveur si "qmark" ou "numeric". Actuellement, il n’y a pas de différence significative entre ces options en termes de performances ou de fonctionnalités, car le connecteur ne prend pas en charge la compilation de texte SQL suivi d’exécutions multiples. Au lieu de cela, les options "qmark" et "numeric" s’alignent sur la compatibilité du texte de requête des autres pilotes (à savoir JDBC, ODBC, Pilote Go Snowflake), qui prennent en charge les liaisons côté serveur avec le format de variable ? ou :N.

Fonctions

connect(parameters...)
But

Constructeur pour créer une connexion à la base de données. Renvoie un objet Connection.

Par défaut, le mode « autocommit » est activé (c’est-à-dire que si la connexion est fermée, toutes les modifications sont validées). Si vous avez besoin d’une transaction, utilisez la commande BEGIN pour démarrer la transaction, et COMMIT ou ROLLBACK pour valider ou annuler toute modification.

Paramètres

Les paramètres d’entrée valides sont :

Paramètre

Obligatoire

Description

account

Oui

Nom de votre compte (fourni par Snowflake). Pour plus de détails, voir Notes sur l’utilisation (dans ce chapitre).

user

Oui

Nom de connexion de l’utilisateur.

password

Oui

Mot de passe de l’utilisateur.

region

Obsolète Veuillez spécifier la région dans les paramètres du account. Cette description du paramètre concerne uniquement la rétrocompatibilité.

host

N’est plus utilisé Nom d’hôte. Utilisé en interne uniquement (n’a donc pas besoin d’être défini).

port

N’est plus utilisé Numéro de port (443 par défaut). Utilisé en interne uniquement (n’a donc pas besoin d’être défini).

database

Nom de la base de données par défaut à utiliser. Après la connexion, vous pouvez utiliser USE DATABASE pour modifier la base de données.

schema

Nom du schéma par défaut à utiliser pour la base de données. Après la connexion, vous pouvez utiliser USE SCHEMA pour modifier le schéma.

role

Nom du rôle par défaut à utiliser. Après la connexion, vous pouvez utiliser USE ROLE pour modifier le rôle.

warehouse

Nom de l’entrepôt par défaut à utiliser. Après vous être connecté, vous pouvez utiliser USE WAREHOUSE pour modifier l’entrepôt.

passcode_in_password

False par défaut. Définissez cette valeur si True si le code d’accès MFA (authentification multi-facteurs) est intégré dans le mot de passe de connexion.

passcode

Le code d’accès fourni par Duo lorsque vous utilisez MFA (Authentification multi-facteurs) pour vous connecter.

autocommit

None par défaut, qui honore le paramètre Snowflake AUTOCOMMIT. Définissez la valeur sur True ou False pour activer ou désactiver le mode de validation automatique dans la session.

client_prefetch_threads

Nombre de threads utilisés pour télécharger les jeux de résultats (4 par défaut). L’augmentation de la valeur améliore les performances d’extraction mais nécessite davantage de mémoire.

client_session_keep_alive

False par défaut. Définissez cette valeur sur True pour que la session reste active indéfiniment, même s’il n’y a aucune activité de l’utilisateur. Assurez-vous d’appeler la méthode close pour terminer correctement le thread ou le processus risque de se bloquer.

login_timeout

Délai d’attente en secondes pour la connexion. Par défaut, 60 secondes. La demande de connexion abandonne après le délai d’attente si la réponse HTTP est « success ».

network_timeout

Délai d’attente en secondes pour toutes les autres opérations. Par défaut, aucun/infini. Une requête générale abandonne après le délai d’attente si la réponse HTTP n’est pas « success ».

ocsp_response_cache_filename

URI du fichier de cache de réponse OCSP. Par défaut, le fichier de cache de réponse OCSP est créé dans le répertoire du cache :

  • Linux : ~/.cache/snowflake/ocsp_response_cache

  • macOS: ~/Library/Caches/Snowflake/ocsp_response_cache

  • Windows : %USERPROFILE%\AppData\Local\Snowflake\Caches\ocsp_response_cache

Pour localiser le fichier dans un autre répertoire, indiquez le chemin d’accès et le nom du fichier dans le champ URI (par ex. file:///tmp/my_ocsp_response_cache.txt).

authenticator

Authentificateur pour Snowflake :

  • snowflake (par défaut) pour utiliser l’authentificateur interne Snowflake.

  • externalbrowser to authenticate using your web browser and Okta, ADFS, or any other SAML 2.0-compliant identity provider (IdP) that has been defined for your account.

  • https://<votre_nom_compte_okta>.okta.com (c.-à-d. le point de terminaison d’URL pour Okta) pour s’authentifier via Okta natif.

  • oauth pour s’authentifier à l’aide de OAuth. Vous devez également spécifier le paramètre token et définir sa valeur sur le jeton d’accès OAuth.

Si la valeur n’est pas snowflake, les paramètres d’utilisateur et de mot de passe doivent être vos identifiants de connexion pour le IdP.

validate_default_parameters

False par défaut. Si True, alors :

  • Produire une exception si l’une des bases de données, l’un des schémas ou l’un des entrepôts spécifiés n’existe pas.

  • Afficher un avertissement à stderr si un nom d’argument non valide ou une valeur d’argument du mauvais type de données est transmis.

paramstyle

pyformat par défaut pour la liaison côté client. Spécifiez qmark ou numeric pour modifier le format des variables de liaison pour la liaison côté serveur.

timezone

None par défaut, qui honore le paramètre Snowflake TIMEZONE. Définissez un fuseau horaire valide (par exemple, America/Los_Angeles) pour définir le fuseau horaire de la session.

Attributs

Error, Warning, ...

Toutes les classes d’exception définies par la norme de l’API de base de données Python. Le connecteur Snowflake pour Python fournit les attributs msg, errno, sqlstate, sfqid et raw_msg.

Notes d’utilisation pour le paramètre account (pour la méthode connect)

  • Le paramètre spécifie le compte Snowflake auquel vous vous connectez et est obligatoire.

  • Ne pas inclure le nom de domaine Snowflake (snowflakecomputing.com) dans le paramètre. Snowflake ajoute automatiquement le nom de domaine à votre nom de compte pour créer la connexion requise.

  • Votre nom de compte complet peut inclure des segments supplémentaires identifiant la région et la plate-forme Cloud où votre compte est hébergé.

    Exemples de noms de compte par région

    Si votre nom de compte est xy12345 :

    Plate-forme Cloud/Région

    Nom de compte complet

    AWS

    US Ouest (Oregon)

    xy12345

    US Est (Ohio)

    xy12345.us-east-2.aws

    US Est (Virginie du Nord)

    xy12345.us-east-1

    US Est (Gouvernement commercial - Virginie du Nord)

    xy12345.us-east-1-gov.aws

    Canada (Centre)

    xy12345.ca-central-1.aws

    EU (Irlande)

    xy12345.eu-west-1

    EU (Francfort)

    xy12345.eu-central-1

    Asie-Pacifique (Tokyo)

    xy12345.ap-northeast-1.aws

    Asie Pacifique (Mumbai)

    xy12345.ap-south-1.aws

    Asie-Pacifique (Singapour)

    xy12345.ap-southeast-1

    Asie-Pacifique (Sydney)

    xy12345.ap-southeast-2

    GCP

    US Central1 (Iowa)

    xy12345.us-central1.gcp

    Europe Ouest2 (Londres)

    xy12345.europe-west2.gcp

    Europe Ouest4 (Pays-Bas)

    xy12345.europe-west4.gcp

    Azure

    Ouest US 2 (Washington)

    xy12345.west-us-2.azure

    Est US 2 (Virginie)

    xy12345.east-us-2.azure

    US Gov Virginia

    xy12345.us-gov-virginia.azure

    Canada Central (Toronto)

    xy12345.canada-central.azure

    Europe de l’Ouest (Pays-Bas)

    xy12345.west-europe.azure

    Suisse Nord (Zurich)

    xy12345.switzerland-north.azure

    Asie du Sud-Est (Singapour)

    xy12345.southeast-asia.azure

    Australie Est (Nouvelle-Galles du Sud)

    xy12345.australia-east.azure

    Important

    Si l’une des conditions suivantes est remplie, le nom de votre compte est différent de la structure décrite dans cet exemple :

    • Si votre édition Snowflake est VPS, contactez le support Snowflake pour obtenir des détails sur le nom de votre compte.

    • Si AWS PrivateLink est activé pour votre compte, le nom de votre compte nécessite un segment privatelink supplémentaire. Pour plus de détails, voir AWS PrivateLink et Snowflake.

Objet : Connection

Un objet Connection contient les informations de connexion et de session visant à garder la connexion de base de données active. S’il est fermé ou si la session expire, toutes les opérations suivantes échoueront.

Méthodes

autocommit(True|False)
But

Active ou désactive le mode de validation automatique. Par défaut, la validation automatique est activée (True).

close()
But

Ferme la connexion. Si une transaction est encore ouverte lorsque la connexion est fermée, les modifications sont annulées.

La fermeture de la connexion supprime explicitement la session active du serveur. Sinon, la session active continue jusqu’à ce qu’elle soit finalement purgée du serveur, limitant ainsi le nombre de requêtes simultanées.

Par exemple :

# context manager ensures the connection is closed
with snowflake.connector.connect(...) as con:
    con.cursor().execute(...)

# try & finally to ensure the connection is closed.
con = snowflake.connector.connect(...)
try:
    con.cursor().execute(...)
finally:
    con.close()
commit()
But

Si la validation automatique est désactivée, valide la transaction en cours. Si la validation automatique est activée, cette méthode est ignorée.

rollback()
But

Si la validation automatique est désactivée, la transaction en cours est annulée. Si la validation automatique est activée, cette méthode est ignorée.

cursor()
But

Constructeur pour créer un objet Cursor. Les valeurs de retour des appels fetch*() sont une seule séquence ou une liste de séquences.

cursor(snowflake.connector.DictCursor)
But

Constructeur pour créer un objet DictCursor. Les valeurs de retour des appels fetch*() sont un dict unique ou une liste d’objets dict. Ceci est utile pour récupérer les valeurs par nom de colonne à partir des résultats.

execute_string(sql_text, remove_comments=False, return_cursors=True)
But

Exécutez une ou plusieurs instructions SQL passées sous forme de chaînes. Si remove_comments est défini sur True, les commentaires sont supprimés de la requête. Si return_cursors est défini sur True, cette méthode retourne une séquence d’objets Cursor dans l’ordre d’exécution.

Exemple

Cet exemple montre l’exécution de plusieurs commandes dans une seule chaîne, puis l’utilisation de la séquence de curseurs qui est retournée :

cursor_list = connection1.execute_string(
    "SELECT * FROM testtable WHERE col1 LIKE 'T%';"
    "SELECT * FROM testtable WHERE col2 LIKE 'A%';"
    )

for cursor in cursor_list:
   for row in cursor:
      print(row[0], row[1])

Note

Les méthodes telles que execute_string() qui permettent de multiples instructions SQL dans une seule chaîne sont vulnérables aux attaques par injection SQL. Évitez d’utiliser la concaténation de chaînes, ou des fonctions telles que la fonction format() de Python pour composer dynamiquement une instruction SQL en combinant SQL avec des données d’utilisateur, à moins que vous n’ayez validé les données d’utilisateur. L’exemple ci-dessous illustre le problème :

# "Binding" data via the format() function (UNSAFE EXAMPLE)
value1_from_user = "'ok3'); DELETE FROM testtable WHERE col1 = 'ok1'; select pi("
sql_cmd = "insert into testtable(col1) values('ok1'); "                  \
          "insert into testtable(col1) values('ok2'); "                  \
          "insert into testtable(col1) values({col1});".format(col1=value1_from_user)
# Show what SQL Injection can do to a composed statement.
print(sql_cmd)

connection1.execute_string(sql_cmd)

L’instruction à composition dynamique ressemble à la suivante (de nouvelles lignes ont été ajoutées pour faciliter la lecture) :

insert into testtable(col1) values('ok1');
insert into testtable(col1) values('ok2');
insert into testtable(col1) values('ok3');
DELETE FROM testtable WHERE col1 = 'ok1';
select pi();

Si vous combinez des instructions SQL avec des chaînes entrées par des utilisateurs non fiables, alors il est plus sûr de lier des données à une instruction que de composer une chaîne. La méthode execute_string() ne prend pas de paramètres de liaison. Pour lier des paramètres, utilisez Cursor.execute() ou Cursor.executemany().

execute_stream(sql_stream, remove_comments=False)
But

Exécutez une ou plusieurs instructions SQL passées comme objet de flux. Si remove_comments est défini sur True, les commentaires sont supprimés de la requête. Ce générateur produit chaque objet Cursor au fur et à mesure que les instructions SQL s’exécutent.

Attributs

messages

L’objet de liste comprenant des séquences (classe d’exception, valeur d’exception) pour tous les messages reçus depuis la base de données sous-jacente pour cette connexion.

La liste est automatiquement effacée par n’importe quel appel de méthode.

errorhandler

Attribut de lecture/d’écriture faisant référence à un gestionnaire d’erreur à appeler en cas de condition d’erreur.

Ce gestionnaire doit être un appelable Python acceptant les arguments suivants :

errorhandler(connection, cursor, errorclass, errorvalue)

Error, Warning, ...

Toutes les classes d’exception définies par la norme de l’API de base de données Python.

Objet : Cursor

Un objet Cursor représente un curseur de base de données pour exécuter et récupérer des opérations. Chaque curseur a ses propres attributs, description et rowcount, de sorte que les curseurs sont isolés.

Méthodes

close()
But

Ferme l’objet de curseur.

execute(operation[, parameters])
But

Prépare et exécute une opération de base de données (c.-à-d. une requête ou une commande).

Paramètres

opération : une chaîne contenant l’instruction SQL à exécuter.

paramètres : les paramètres facultatifs peuvent être fournis sous forme de liste ou de dictionnaire et seront liés à des variables dans l’opération. Pour plus d’informations sur les paramètres de liaison, voir Données de liaison. Pour plus d’informations sur les types de données Python mappés aux types de données SQL, voir Mappages de type de donnée pour les liaisons qmark et numeric.

Renvoie

Renvoie la référence d’un objet Cursor.

executemany(operation, seq_of_parameters)
But

Prépare une opération de base de données et l’exécute selon toutes les séquences de paramètres ou les mappages trouvés dans seq_of_parameters.

Paramètres

operation

L’opération est une chaîne contenant le code à exécuter. La chaîne doit contenir un ou plusieurs caractères de remplacement (comme des points d’interrogation) pour Données de liaison.

Par exemple :

"insert into testy (v1, v2) values (?, ?)"

seq_of_parameters

Il doit s’agir d’une séquence (liste ou tuple) de listes ou de tuples. Voir l’exemple de code ci-dessous pour les séquences d’exemple.

Renvoie

Renvoie la référence d’un objet Cursor.

Exemple
stmt1 = "create table testy (V1 varchar, V2 varchar)"
cs.execute(stmt1)

# A list of lists
sequence_of_parameters1 = [ ['Smith', 'Ann'], ['Jones', 'Ed'] ]
# A tuple of tuples
sequence_of_parameters2 = ( ('Cho', 'Kim'), ('Cooper', 'Pat') )

stmt2 = "insert into testy (v1, v2) values (?, ?)"
cs.executemany(stmt2, sequence_of_parameters1)
cs.executemany(stmt2, sequence_of_parameters2)

En interne, plusieurs méthodes execute sont appelées et le jeu de résultats du dernier appel execute sera conservé.

Note

La méthode executemany ne peut être utilisée que pour exécuter une seule instruction SQL paramétrée et lui passer plusieurs valeurs de liaison.

L’exécution de plusieurs instructions SQL séparées par un point-virgule dans un appel execute n’est pas prise en charge. À la place, émettez un appel execute distinct pour chaque instruction.

fetchone()
But

Récupère la prochaine ligne d’un ensemble de résultats de requête et renvoie une séquence/un dict unique ou None lorsqu’aucune donnée n’est disponible.

fetchmany([size=cursor.arraysize])
But

Récupère les prochaines lignes d’un ensemble de résultats de requête et renvoie une liste de séquences/de dicts. Une séquence vide est retournée lorsqu’il n’y a plus de lignes disponibles.

fetchall()
But

Récupère toutes les lignes d’un ensemble de résultats de requête, ou celles restantes, et renvoie une liste de séquences/de dicts.

fetch_pandas_all()
But

Cette méthode récupère toutes les lignes d’un curseur et les charge dans Pandas DataFrame.

Paramètres

Aucune.

Renvoie

Renvoie un DataFrame contenant toutes les lignes de l’ensemble de résultats. Pour plus d’informations sur les trames de données Pandas, consultez la documentation Pandas DataFrame.

S’il n’y a pas de lignes, cela renvoie Aucun.

Notes sur l’utilisation
  • Cette méthode n’est pas un remplacement complet de la méthode read_sql() de Pandas ; cette méthode consiste à fournir un moyen rapide de récupérer des données à partir d’une requête SELECT et de stocker les données dans un Pandas DataFrame.

  • Actuellement, cette méthode ne fonctionne que pour les instructions SELECT.

Exemples
ctx = snowflake.connector.connect(
          host=host,
          user=user,
          password=password,
          account=account,
          warehouse=warehouse,
          database=database,
          schema=schema,
          protocol='https',
          port=port)

# Create a cursor object.
cur = ctx.cursor()

# Execute a statement that will generate a result set.
sql = "select * from t"
cur.execute(sql)

# Fetch the result set from the cursor and deliver it as the Pandas DataFrame.
df = cur.fetch_pandas_all()

# ...
fetch_pandas_batches()
But

Cette méthode récupère un sous-ensemble des lignes dans un curseur et les délivre à un Pandas DataFrame.

Paramètres

Aucune.

Renvoie

Renvoie un DataFrame contenant un sous-ensemble des lignes de l’ensemble de résultats. Pour plus d’informations sur les trames de données Pandas, consultez la documentation Pandas DataFrame.

Renvoie None s’il n’y a plus de lignes à récupérer.

Notes sur l’utilisation
  • Selon le nombre de lignes dans le jeu de résultats, ainsi que le nombre de lignes spécifiées dans l’appel de méthode, la méthode peut avoir besoin d’être appelée plus d’une fois, ou elle peut renvoyer toutes les lignes dans un seul lot si elles correspondent toutes.

  • Cette méthode n’est pas un remplacement complet de la méthode read_sql() de Pandas ; cette méthode consiste à fournir un moyen rapide de récupérer des données à partir d’une requête SELECT et de stocker les données dans un Pandas DataFrame.

  • Actuellement, cette méthode ne fonctionne que pour les instructions SELECT.

Exemples
ctx = snowflake.connector.connect(
          host=host,
          user=user,
          password=password,
          account=account,
          warehouse=warehouse,
          database=database,
          schema=schema,
          protocol='https',
          port=port)

# Create a cursor object.
cur = ctx.cursor()

# Execute a statement that will generate a result set.
sql = "select * from t"
cur.execute(sql)

# Fetch the result set from the cursor and deliver it as the Pandas DataFrame.
for df in cur.fetch_pandas_batches():
    my_dataframe_processing_function(df)

# ...
__iter__()

Se retourne pour rendre les curseurs compatibles avec le protocole d’itération.

Attributs

description

Attribut en lecture seule qui retourne une séquence de 7 valeurs :

Valeur

Description

name

Nom de colonne.

type_code

Code de type interne.

display_size

(Non utilisé. Identique à internal_size.)

internal_size

Taille des données internes.

precision

Précision des données numériques.

scale

Échelle pour les données numériques.

null_ok

True si des valeurs NULL sont autorisées pour la colonne ou False.

rowcount

Attribut en lecture seule qui retourne le nombre de lignes dans le dernier execute produit. La valeur est -1, ou None si aucun execute n’est exécuté.

sfqid

Attribut en lecture seule qui renvoie l’ID de requête Snowflake dans le dernier execute exécuté.

arraysize

Attribut de lecture/d’écriture indiquant le nombre de lignes à récupérer à un certain moment avec fetchmany(). Par défaut, 1 signifie récupérer une seule ligne à la fois.

connection

Attribut en lecture seule qui renvoie une référence à l’objet Connection sur lequel le curseur a été créé.

messages

Objet de liste qui inclut les séquences (classe d’exception, valeur d’exception) pour tous les messages qu’il a reçus de la base de données sous-jacente pour le curseur.

La liste est effacée automatiquement par n’importe quel appel de méthode à l’exception des appels fetch*().

errorhandler

Attribut de lecture/d’écriture faisant référence à un gestionnaire d’erreur à appeler en cas de condition d’erreur.

Ce gestionnaire doit être un appelable Python acceptant les arguments suivants :

errorhandler(connection, cursor, errorclass, errorvalue)

Codes de type

Cursor.description retourne les métadonnées de la colonne. type_code représente le type de données de la colonne, et utilise la carte suivante pour obtenir la représentation de la chaîne :

type_code

Représentation de chaîne

Type de données

0

FIXED

NUMBER/INT

1

REAL

REAL

2

TEXT

VARCHAR/STRING

3

DATE

DATE

4

TIMESTAMP

TIMESTAMP

5

VARIANT

VARIANT

6

TIMESTAMP_LTZ

TIMESTAMP_LTZ

7

TIMESTAMP_TZ

TIMESTAMP_TZ

8

TIMESTAMP_NTZ

TIMESTAMP_TZ

9

OBJECT

OBJECT

10

ARRAY

ARRAY

11

BINARY

BINARY

12

TIME

TIME

13

BOOLEAN

BOOLEAN

Mappages de type de donnée pour les liaisons qmark et numeric

Si paramstyle est "qmark" ou "numeric", les mappages suivants par défaut de Python vers le type de données Snowflake sont utilisés :

Type de données Python

Type de données dans Snowflake

int

NUMBER(38, 0)

long

NUMBER(38, 0)

decimal

NUMBER(38, <échelle>)

float

REAL

str

TEXT

unicode

TEXT

bytes

BINARY

bytearray

BINARY

bool

BOOLEAN

date

DATE

time

TIME

timedelta

TIME

datetime

TIMESTAMP_NTZ

struct_time

TIMESTAMP_NTZ

Si vous devez mapper un autre type Snowflake (p. ex. datetime à TIMESTAMP_LTZ), spécifiez le type de données Snowflake dans un tuple composé du type de données Snowflake suivi de la valeur. Voir Liaison de datetime avec TIMESTAMP pour des exemples.

Objet : Exception

PEP-249 définit les exceptions que le connecteur Snowflake pour Python peut faire en cas d’erreur ou d’avertissement. L’application doit les traiter correctement et décider de continuer ou d’arrêter l’exécution du code.

Méthodes

Aucune méthode n’est disponible pour les objets Exception.

Attributs

errno

Code d’erreur DB Snowflake.

msg

Message d’erreur incluant le code d’erreur, le code d’état SQL et l’ID de requête.

raw_msg

Message d’erreur. Aucun code d’erreur, de code d’état SQL ou d’ID de requête n’est inclus.

sqlstate

Code d’état SQL conforme à ANSI

sfqid

ID de requête Snowflake.

Module : snowflake.connector.pandas_tools

Le module snowflake.connector.pandas_tools fournit des fonctions pour travailler avec la bibliothèque d’analyse de données Pandas.

Fonctions

write_pandas(parameters...)
But

Écrit un DataFrame Pandas dans une table dans une base de données Snowflake.

Pour écrire les données dans la table, la fonction enregistre les données dans des fichiers Parquet, utilise la commande PUT pour télécharger ces fichiers dans une zone de préparation temporaire et utilise la commande COPY INTO <table> pour copier les données des fichiers dans la table. Vous pouvez utiliser certains des paramètres de fonction pour contrôler la façon dont les instructions PUT et COPY INTO <table> sont exécutées.

Paramètres

Les paramètres d’entrée valides sont :

Paramètre

Obligatoire

Description

conn

Oui

objet Connection contenant la connexion à la base de données Snowflake.

df

Oui

objet pandas.DataFrame contenant les données à copier dans la table.

table_name

Oui

Nom de la table dans laquelle les données doivent être copiées.

database

Nom de la base de données contenant la table. Par défaut, la fonction écrit dans la base de données actuellement utilisée dans la session. Remarque : si vous spécifiez ce paramètre, vous devez également spécifier le paramètre schema.

schema

Nom du schéma contenant la table. Par défaut, la fonction écrit dans la table du schéma actuellement utilisé dans la session.

chunk_size

Nombre d’éléments à insérer simultanément. Par défaut, la fonction insère tous les éléments à la fois dans un seul bloc.

compression

L’algorithme de compression à utiliser pour les fichiers Parquet. Vous pouvez spécifier "gzip" pour une meilleure compression ou "snappy" pour une compression plus rapide. Par défaut, la fonction utilise "gzip".

on_error

Spécifie comment les erreurs doivent être gérées. Définissez ce paramètre sur l’une des valeurs de chaîne documentées dans ON_ERROR l’option de copie. Par défaut, la fonction utilise "ABORT_STATEMENT".

parallel

Nombre de threads à utiliser lors du téléchargement des fichiers Parquet vers la zone de préparation temporaire. Pour le nombre par défaut de threads utilisés et les instructions sur comment choisir le nombre de threads, voir le paramètre parallèle de la commande PUT.

Renvoie

Renvoie un tuple de (réussite, nombre_blocs, nombre_lignes, sortie) où :

  • réussite est True si la fonction a correctement écrit les données dans la table.

  • nombre_blocs est le nombre de blocs de données que la fonction a copiés.

  • nombre_lignes est le nombre de lignes insérées par la fonction.

  • sortie est la sortie de la commande COPY INTO <table>.

Exemple

L’exemple suivant écrit les données d’un DataFrame Pandas dans la table nommée “clients”.

import pandas
from snowflake.connector.pandas_tools import write_pandas

# Create the connection to the Snowflake database.
cnx = snowflake.connector.connect(...)

# Create a DataFrame containing data about customers
df = pandas.DataFrame([('Mark', 10), ('Luke', 20)], columns=['name', 'balance'])

# Write the data from the DataFrame to the table named "customers".
success, nchunks, nrows, _ = write_pandas(cnx, df, 'customers')
pd_writer(parameters...)
But

pd_writer est une méthode d’insertion permettant d’insérer des données dans une base de données Snowflake.

Lorsque vous appelez pandas.DataFrame.to_sql, transférez method=pd_writer pour indiquer que vous voulez utiliser pd_writer comme méthode d’insertion de données. (Vous n’avez pas besoin d’appeler pd_writer à partir de votre propre code. La méthode to_sql appelle pd_writer et fournit les paramètres d’entrée nécessaires.)

La fonction pd_writer utilise la fonction write_pandas pour écrire les données du DataFrame dans la base de données Snowflake.

Paramètres

Les paramètres d’entrée valides sont :

Paramètre

Obligatoire

Description

table

Oui

objet pandas.io.sql.SQLTable pour la table.

conn

Oui

objet sqlalchemy.engine.Engine ou sqlalchemy.engine.Connection utilisé pour se connecter à la base de données Snowflake.

keys

Oui

Noms des colonnes de la table pour les données à insérer.

data_iter

Oui

Itérateur pour les lignes contenant les données à insérer.

Exemple

L’exemple suivant transmet method=pd_writer à la méthode pandas.DataFrame.to_sql, qui à son tour appelle la fonction pd_writer pour écrire les données du DataFrame Pandas dans une base de données Snowflake.

import pandas
from snowflake.connector.pandas_tools import pd_writer

# Create a DataFrame containing data about customers
df = pandas.DataFrame([('Mark', 10), ('Luke', 20)], columns=['name', 'balance'])

# Specify that the to_sql method should use the pd_writer function
# to write the data from the DataFrame to the table named "customers"
# in the Snowflake database.
df.to_sql('customers', engine, index=False, method=pd_writer)

Prise en charge de l’horodatage et de la date

Snowflake prend en charge plusieurs types de données DATE et TIMESTAMP. Le connecteur Snowflake permet de lier des objets natifs datetime et date pour les opérations de mise à jour et de récupération.

Récupération de données

Lors de la récupération des données de date et d’heure, les types de données Snowflake sont convertis en types de données Python :

Types de données Snowflake

Type de données Python

Comportement

TIMESTAMP_TZ

datetime avec tzinfo

Récupère les données, y compris le décalage de fuseau horaire, et les traduit en datetime avec l’objet tzinfo.

TIMESTAMP_LTZ, TIMESTAMP

datetime avec tzinfo

Récupère les données, les traduit en un objet datetime, et attache tzinfo en fonction du paramètre de session TIMESTAMP_TYPE_MAPPING.

TIMESTAMP_NTZ

datetime

Récupère les données et les traduit en objet datetime. Aucune information de fuseau horaire n’est attachée à l’objet.

DATE

date

Récupère les données et les traduit en objet date. Aucune information de fuseau horaire n’est attachée à l’objet.

Note

tzinfo est un objet de fuseau horaire UTC basé sur le décalage et non sur les noms de fuseau horaire IANA . Les noms de fuseau horaire peuvent ne pas correspondre, mais les objets de fuseau horaire équivalents basés sur le décalage sont considérés comme identiques.

Mise à jour des données

Lors de la mise à jour des données de date et d’heure, les types de données Python sont convertis en types de données Snowflake :

Type de données Python

Types de données Snowflake

Comportement

datetime

TIMESTAMP_TZ, TIMESTAMP_LTZ, TIMESTAMP_NTZ, DATE

Convertit un objet « datetime » en une chaîne au format YYYY-MM-DD HH24:MI:SS.FF TZH:TZM et la met à jour. Si aucun décalage de fuseau horaire n’est fourni, la chaîne sera au format YYYY-MM-DD HH24:MI:SS.FF. L’utilisateur est responsable du réglage de tzinfo pour l’objet datetime.

struct_time

TIMESTAMP_TZ, TIMESTAMP_LTZ, TIMESTAMP_NTZ, DATE

Convertit un objet « struct_time » en une chaîne au format YYYY-MM-DD HH24:MI:SS.FF TZH:TZM et la met à jour. Les informations de fuseau horaire sont extraites de time.timezone qui inclut le décalage de fuseau horaire de UTC. L’utilisateur est responsable du paramétrage de la variable d’environnement TZ pour time.timezone.

date

TIMESTAMP_TZ, TIMESTAMP_LTZ, TIMESTAMP_NTZ, DATE

Convertit un objet « date » en une chaîne au format YYYY-MM-DD. Aucun fuseau horaire n’est pris en compte.

time

TIMESTAMP_TZ, TIMESTAMP_LTZ, TIMESTAMP_NTZ, DATE

Convertit un objet « time » en une chaîne au format HH24:MI:SS.FF. Aucun fuseau horaire n’est pris en compte.

timedelta

TIMESTAMP_TZ, TIMESTAMP_LTZ, TIMESTAMP_NTZ, DATE

Convertit un objet « timedelta » en une chaîne au format HH24:MI:SS.FF. Aucun fuseau horaire n’est pris en compte.