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

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',
    ... )
Copy

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

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

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

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

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.

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

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 :

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

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.