Connecteur Python API¶

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,))

Copy

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 paire de clés et rotation de paires de clés.
private_key_file		Spécifie le chemin d’accès au fichier de clé privée pour l’utilisateur spécifié. Voir Utilisation de l’authentification par paire de clés et rotation de paires de clés.
private_key_file_pwd		Spécifie la phrase secrète qui déchiffre le fichier de clé privée pour l’utilisateur spécifié. Voir Utilisation de l’authentification par paire de clés et rotation de 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%AppDataLocalSnowflakeCachesocsp_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, AD FS, 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.
socket_timeout		Délai d’expiration en secondes pour les requêtes de lecture et de connexion au niveau du socket. Pour plus d’informations, consultez Gestion des délais d’expiration de connexion.
backoff_policy		Nom de la fonction génératrice qui définit le temps d’attente entre les tentatives. Pour plus d’informations, consultez Gestion des politiques d’interruption de connexion pour les tentatives.

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 sur l’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.

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()

Copy

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])

Copy

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)

Copy

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();

Copy

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¶

expired¶

Vérifie si le jeton maître de la connexion a expiré.

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.

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

Copy

utilisez l’appel suivant :

cursor.execute(
    "PUT file://this_directory_path/is_ignored/myfile.csv @mystage",
    file_stream=<io_object>)

Copy

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 (?, ?)"

Copy

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)

Copy

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 un DataFrame Pandas.

Paramètres:

Aucun.

Renvoie:

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

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 DataFrame Pandas.

• 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()

# ...

Copy

fetch_pandas_batches()¶

But:

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

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 cadres de données Pandas, consultez la documentation DataFrame Pandas.

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 DataFrame Pandas.

• 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)

# ...

Copy

__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 :

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 :

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.

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.

Attributs¶

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.

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.

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.

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 (success, num_chunks, num_rows, output) où :

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

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

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

• output 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 « customers » (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')

Copy

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.)

Note

Veuillez noter que lorsque les noms de colonnes dans les DataFrame pandas ne contiennent que des lettres minuscules, vous devez entourer les noms de colonnes de guillemets doubles, sinon le connecteur lève une ProgrammingError.

La bibliothèque snowflake-sqlalchemy ne met pas entre guillemets les noms de colonnes en minuscules lors de la création d’une table, tandis que pd_writer met en guillemets les noms de colonnes par défaut. Le problème vient du fait que la commande COPY INTO s’attend à ce que les noms de colonnes soient mis entre guillemets.

Des améliorations seront apportées à la bibliothèque snowflake-sqlalchemy.

Par exemple :

import pandas as pd
from snowflake.connector.pandas_tools import pd_writer

sf_connector_version_df = pd.DataFrame([('snowflake-connector-python', '1.0')], columns=['NAME', 'NEWEST_VERSION'])

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

# When the column names consist of only lower case letters, quote the column names
sf_connector_version_df = pd.DataFrame([('snowflake-connector-python', '1.0')], columns=['"name"', '"newest_version"'])
sf_connector_version_df.to_sql('driver_versions', engine, index=False, method=pd_writer)

Copy

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)

Copy

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 :

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 :