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	Votre identificateur de compte. L’identificateur du compte ne comprend pas le suffixe `snowflakecomputing.com`. . . Pour plus de détails et d’exemples, voir Notes sur l’utilisation (dans cette rubrique).
`user`	Oui	Nom de connexion de l’utilisateur.
`password`	Oui	Mot de passe de l’utilisateur.
`region`		Obsolète 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 multifactorielle) pour vous connecter.
`private_key`		La clé privée utilisée pour l’authentification. Pour plus d’informations, voir Utilisation de l’authentification par paires de clés et rotation des paires de clés.
`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`		Définissez cette valeur sur `True` pour que la session reste active indéfiniment. Lors de la définition de `True`, assurez-vous d’appeler la méthode `close` pour terminer correctement le thread ou le processus risque de se bloquer.
		La valeur par défaut dépend de la version du connecteur que vous utilisez :
		Version 2.4.6 et ultérieure : `None` par défaut. . Lorsque la valeur est `None`, le paramètre de session CLIENT_SESSION_KEEP_ALIVE est prioritaire. . . Pour remplacer le paramètre de session, passez `True` ou `False` pour cet argument.
		Version 2.4.5 et antérieure : `False` par défaut. . Lorsque la valeur est `False` (soit en spécifiant explicitement la valeur, soit en omettant l’argument), le paramètre de session CLIENT_SESSION_KEEP_ALIVE est prioritaire. . . Le passage de `client_session_keey_alive=False` à la méthode `connect` ne remplace pas la valeur `TRUE` du paramètre de session `CLIENT_SESSION_KEEP_ALIVE`.
`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` pour vous authentifier en utilisant votre navigateur Web et Okta, ADFS, ou tout autre fournisseur d’identité conforme à SAML 2.0 (IdP) qui a été défini pour votre compte.
		`https://<nom_compte_okta>.okta.com` (c.-à-d. le point de terminaison d’URL pour votre compte Okta) pour s’authentifier via Okta natif.
		`oauth` pour vous 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.
		`username_password_mfa` pour s’authentifier avec la mise en cache du jeton MFA. Pour plus de détails, voir Utilisation de la mise en cache des jetons MFA pour réduire le nombre d’invites lors de l’authentification — Facultatif.
		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.
`arrow_number_to_decimal`		`False` par défaut, ce qui signifie que les valeurs des colonnes NUMBER sont renvoyées sous forme de nombres à virgule flottante en double précision (`float64`). . . Définissez cette valeur sur `True` pour que les valeurs des colonnes DECIMAL soient retournées sous forme de nombres décimaux (`decimal.Decimal`) lors de l’appel des méthodes `fetch_pandas_all()` et `fetch_pandas_batches()`. . . Ce paramètre a été introduit dans la version 2.4.3 du connecteur Snowflake pour Python.

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`)¶

Pour le paramètre requis account, spécifiez votre identificateur de compte.

Notez que l’identificateur du compte ne comprend pas le nom de domaine snowflakecomputing.com. Snowflake l’ajoute automatiquement lors de la création de la connexion.

L’exemple suivant utilise un identificateur de compte qui spécifie le myaccount dans l’organisation myorganization :

ctx = snowflake.connector.connect(
    user='<user_name>',
    password='<password>',
    account='myorganization-myaccount',
    ... )

L’exemple suivant utilise le localisateur de compte xy12345 comme identifiant de compte :

ctx = snowflake.connector.connect(
    user='<user_name>',
    password='<password>',
    account='xy12345',
    ... )

Notez que cet exemple utilise un compte dans la région AWS US Ouest (Oregon). Si le compte se trouve dans une autre région ou s’il utilise un autre fournisseur Cloud, vous devez spécifier des segments supplémentaires après le localisateur de compte.

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.

get_query_status(query_id)¶

But: Renvoie le statut d’une requête.
Paramètres: query_id

ID de la requête. Voir Récupération des ID de requête Snowflake.
Renvoie: Renvoie l’objet QueryStatus qui représente le statut de la requête.
Exemple: Voir Vérification du statut d’une requête.

get_query_status_throw_if_error(query_id)¶

But: Renvoie le statut d’une requête. Si la requête aboutit à une erreur, cette méthode génère un ProgrammingError (comme le ferait la méthode execute() ).
Paramètres: query_id

ID de la requête. Voir Récupération des ID de requête Snowflake.
Renvoie: Renvoie l’objet QueryStatus qui représente le statut de la requête.
Exemple: Voir Vérification du statut d’une requête.

is_still_running(query_status)¶

But: Renvoie True si le statut de la requête indique que la requête n’est pas encore terminée ou est toujours en cours.
Paramètres: query_status

L’objet QueryStatus qui représente le statut de la requête. Pour obtenir cet objet pour une requête, voir Vérification du statut d’une requête.
Exemple: Voir Vérification du statut d’une requête.

is_an_error(query_status)¶

But: Renvoie True si le statut de la requête indique que la requête a abouti à une erreur.
Paramètres: query_status

L’objet QueryStatus qui représente le statut de la requête. Pour obtenir cet objet pour une requête, voir Vérification du statut d’une requête.
Exemple: Voir Vérification du statut d’une requête.

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.

describe(command [, parameters][, timeout][, file_stream])¶

But

Renvoie des métadonnées sur le jeu de résultats sans exécuter une commande de base de données. Cela renvoie les mêmes métadonnées que celles disponibles dans l’attribut description après l’exécution d’une requête.

Cette méthode a été introduite dans la version 2.4.6 du connecteur Snowflake pour Python.

Paramètres

Voir les paramètres de la méthode execute().

Renvoie

Renvoie une liste d’objets ResultMetadata qui décrivent les colonnes dans le jeu de résultats.

Exemple

Voir Récupération de métadonnées de colonne.

execute(command [, parameters][, timeout][, file_stream])¶

But

Prépare et exécute une commande de base de données.

Paramètres

command

Une chaîne contenant l’instruction SQL à exécuter.

parameters

(Facultatif) Si vous avez utilisé des paramètres pour lier des données dans l’instruction SQL, définissez ce paramètre comme la liste ou le dictionnaire des variables qui doivent être liées à ces paramètres.

Pour plus d’informations sur le mappage des types de données Python pour les variables aux types de données SQL des colonnes correspondantes, voir Mappages de type de donnée pour les liaisons qmark et numeric.

timeout

(Facultatif) Nombre de secondes à attendre pour que la requête se termine. Si la requête n’est pas terminée au bout de ce temps, elle doit être interrompue.

file_stream

(Facultatif) Lors de l’exécution d’une commande PUT, vous pouvez utiliser ce paramètre pour télécharger un objet de type fichier en mémoire (par exemple, l’objet E/S renvoyé par la fonction Python open()), plutôt qu’un fichier sur le système de fichiers. Définissez ce paramètre sur cet objet d’E/S.

Lorsque vous spécifiez l’URI pour le fichier de données dans la commande PUT :

Vous pouvez utiliser n’importe quel chemin de répertoire. Le chemin de répertoire que vous spécifiez dans l’URI est ignoré.

Pour le nom de fichier, indiquez le nom du fichier qui doit être créé sur la zone de préparation.

Par exemple, pour télécharger un fichier depuis un flux de fichiers vers un fichier nommé :
@mystage/myfile.csv
utilisez l’appel suivant :
cursor.execute(
    "PUT file://this_directory_path/is_ignored/myfile.csv @mystage",
    file_stream=<io_object>)

Renvoie

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

executemany(command, seq_of_parameters)¶

But

Prépare une commande de base de données et l’exécute selon toutes les séquences de paramètres trouvées dans seq_of_parameters. Vous pouvez utiliser cette méthode pour effectuer une opération d’insertion par lots.

Paramètres

command

La commande est une chaîne contenant le code à exécuter. La chaîne doit contenir un ou plusieurs espaces réservés (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

# This example uses qmark (question mark) binding, so
# you must configure the connector to use this binding style.
from snowflake import connector
connector.paramstyle='qmark'

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.

execute_async(...)¶

But: Prépare et soumet une commande de base de données pour une exécution asynchrone. Voir Exécution d’une requête asynchrone.
Paramètres: Cette méthode utilise les mêmes paramètres que la méthode execute() .
Renvoie: Renvoie la référence d’un objet Cursor.
Exemple: Voir Exemples de requêtes asynchrones.

fetch_arrow_all()¶

But

Cette méthode récupère toutes les lignes d’un curseur et les charge dans une table PyArrow.

Paramètres

Aucun.

Renvoie

Renvoie une table PyArrow contenant toutes les lignes du jeu de résultats.

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

Exemple

Voir Distribution de charges de travail qui récupèrent des résultats avec le connecteur Snowflake pour Python.

fetch_arrow_batches()¶

But

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

Paramètres

Aucun.

Renvoie

Renvoie une table PyArrow contenant un sous-ensemble des lignes du jeu de résultats.

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

Exemple

Voir Distribution de charges de travail qui récupèrent des résultats avec le connecteur Snowflake pour Python.

get_result_batches()¶

But: Renvoie une liste d’objets ResultBatch que vous pouvez utiliser pour extraire un sous-ensemble de lignes du jeu de résultats.
Paramètres: Aucun.
Renvoie: Renvoie une liste d’objets ResultBatch ou None si l’exécution de la requête n’est pas terminée.
Exemple: Voir Distribution de charges de travail qui récupèrent des résultats avec le connecteur Snowflake pour Python.

get_results_from_sfqid(query_id)¶

But: Récupère les résultats d’une requête asynchrone ou d’une requête synchrone précédemment soumise.
Paramètres: query_id

ID de la requête. Voir Récupération des ID de requête Snowflake.
Exemple: Voir Utilisation de l’ID de requête pour récupérer les résultats d’une requête.

fetchone()¶

But: Récupère la prochaine ligne d’un jeu 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

Aucun.

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

Aucun.

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 Aucun 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 renvoie des métadonnées sur les colonnes du jeu de résultats.

Cet attribut est défini après avoir appelé la méthode execute() pour exécuter la requête. (Dans la version 2.4.6 ou ultérieure, vous pouvez récupérer ces métadonnées sans exécuter la requête en appelant la méthode describe()).

Cet attribut a l’une des valeurs suivantes :

Versions 2.4.5 et antérieures : cet attribut est défini sur une liste de tuples.
Versions 2.4.6 et ultérieures : cet attribut est défini sur une liste d’objets ResultMetadata.

Chaque tuple ou objet ResultMetadata contient les métadonnées qui décrivent une colonne dans le jeu de résultats. Vous pouvez accéder aux métadonnées par index ou, dans les versions 2.4.6 et ultérieures, par attribut d’objet ResultMetadata :

Indice de valeur	Attribut ResultMetadata	Description
`0`	`name`	Nom de colonne.
`1`	`type_code`	Code de type interne.
`2`	`display_size`	(Non utilisé. Identique à internal_size.)
`3`	`internal_size`	Taille des données internes.
`4`	`precision`	Précision des données numériques.
`5`	`scale`	Échelle pour les données numériques.
`6`	`is_nullable`	`True` si des valeurs NULL sont autorisées pour la colonne ou `False`.

Pour des exemples d’obtention de cet attribut, voir Récupération de métadonnées de colonne.

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 ou execute_async 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¶

Dans l’objet Cursor, l’attribut description et la méthode describe() fournissent une liste de tuples (ou, dans les versions 2.4.6 et ultérieures, d’objets ResultMetadata) qui décrivent les colonnes dans le jeu de résultats.

Dans un tuple, la valeur au niveau de l’indice 1 (l’attribut type_code dans l’objet ResultMetadata) représente le type de données de la colonne. Le connecteur Snowflake pour Python utilise la carte suivante pour obtenir la représentation de la chaîne, en fonction du code de type :

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.

Objet `ResultBatch`¶

Un objet ResultBatch encapsule une fonction qui récupère un sous-ensemble de lignes d’un jeu de résultats. Pour répartir le travail de récupération des résultats entre plusieurs employés ou nœuds, vous pouvez appeler la méthode obtenir_lot_résultats() dans l’objet Curseur pour récupérer une liste d’objets ResultBatch et distribuer ces objets à différents employés ou nœuds pour traitement.

Attributs¶

rowcount¶

Attribut en lecture seule qui retourne le nombre de lignes dans le lot de résultats.

compressed_size¶

Attribut en lecture seule qui renvoie la taille des données (une fois compressées) dans le lot de résultats.

uncompressed_size¶

Attribut en lecture seule qui renvoie la taille des données (non compressées) dans le lot de résultats.

Méthodes¶

to_arrow()¶

But

Cette méthode renvoie une table PyArrow contenant les lignes de l’objet ResultBatch.

Paramètres

Aucun.

Renvoie

Renvoie une table PyArrow contenant les lignes de l’objet ResultBatch.

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

to_pandas()¶

But

Cette méthode renvoie un DataFrame Pandas contenant les lignes de l’objet ResultBatch.

Paramètres

Aucun.

Renvoie

Retourne un DataFrame Pandas contenant les lignes de l’objet ResultBatch.

S’il n’y a pas de lignes, cela renvoie un DataFrame Pandas vide.

Objet : `ResultMetadata`¶

Un objet ResultMetadata représente les métadonnées d’une colonne dans le jeu de résultats. Une liste de ces objets est renvoyée par l’attribut description et la méthode describe de l’objet Cursor.

Cet objet a été introduit dans la version 2.4.6 du connecteur Snowflake pour Python.

Méthodes¶

Aucun.

Attributs¶

name¶: Nom de la 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.

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

Module : `snowflake.connector.constants`¶

Le module snowflake.connector.constants définit les constantes utilisées dans l” API.

Enums¶

class QueryStatus¶

Représente le statut d’une requête asynchrone. Cette énumération a les constantes suivantes :

Constante Enum	Description
RUNNING	La requête est toujours en cours d’exécution.
ABORTING	La requête est en cours d’annulation côté serveur.
SUCCESS	La requête s’est terminée avec succès.
FAILED_WITH_ERROR	La requête s’est terminée avec une erreur.
QUEUED	La requête est mise en file d’attente pour exécution (c’est-à-dire qu’elle n’est pas encore exécutée), généralement parce qu’elle attend des ressources.
DISCONNECTED	La connexion de la session est interrompue. L’état de la requête basculera bientôt sur « FAILED_WITH_ERROR ».
RESUMING_WAREHOUSE	L’entrepôt démarre et la requête n’est pas encore en cours d’exécution.
BLOCKED	L’instruction attend un verrou détenu par une autre instruction.
NO_DATA	Les données sur l’instruction ne sont pas encore disponibles, généralement parce que l’instruction n’est pas encore exécutée.

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.
`quote_identifiers`		Si `False`, empêche le connecteur d” entrer des guillemets doubles autour des identificateurs avant d’envoyer les identificateurs au serveur. Par défaut, le connecteur place des guillemets doubles autour des identificateurs.

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 (voir la documentation de Pandas), 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.

Connecteur Python API¶

Module : snowflake.connector¶

Constantes¶

Fonctions¶

Attributs¶

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

Objet : Connection¶

Méthodes¶

Attributs¶

Objet : Cursor¶

Méthodes¶

Attributs¶

Codes de type¶

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

Objet : Exception¶

Méthodes¶

Attributs¶

Objet ResultBatch¶

Attributs¶

rowcount¶

compressed_size¶

uncompressed_size¶

Méthodes¶

Objet : ResultMetadata¶

Méthodes¶

Attributs¶

Module : snowflake.connector.constants¶

Enums¶

Module : snowflake.connector.pandas_tools¶

Fonctions¶

Prise en charge de l’horodatage et de la date¶

Récupération de données¶

Mise à jour des données¶

Module : `snowflake.connector`¶

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

Objet : `Connection`¶

Objet : `Cursor`¶

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

Objet : `Exception`¶

Objet `ResultBatch`¶

Objet : `ResultMetadata`¶

Module : `snowflake.connector.constants`¶

Module : `snowflake.connector.pandas_tools`¶