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 remplacerparamstyle
pour changer les formats de variables de liaison en"qmark"
ou"numeric"
, où les variables sont?
ou:N
, respectivement.Par exemple :
format: .execute("... WHERE my_column = %s", (value,)) pyformat: .execute("... WHERE my_column = %(name)s", {"name": value}) qmark: .execute("... WHERE my_column = ?", (value,)) numeric: .execute("... WHERE my_column = :1", (value,))
Note
La variable de liaison se produit du côté client si
paramstyle
est"pyformat"
ou"format"
, et du côté serveur si"qmark"
ou"numeric"
. Actuellement, il n’y a pas de différence significative entre ces options en termes de performances ou de fonctionnalités, car le connecteur ne prend pas en charge la compilation de texte SQL suivi d’exécutions multiples. Au lieu de cela, les options"qmark"
et"numeric"
s’alignent sur la compatibilité du texte de requête des autres pilotes (à savoir JDBC, ODBC, Pilote Go Snowflake), qui prennent en charge les liaisons côté serveur avec le format de variable?
ou:N
.
Fonctions¶
-
connect
(parameters...)¶ - But
Constructeur pour créer une connexion à la base de données. Renvoie un objet
Connection
.Par défaut, le mode « autocommit » est activé (c’est-à-dire que si la connexion est fermée, toutes les modifications sont validées). Si vous avez besoin d’une transaction, utilisez la commande BEGIN pour démarrer la transaction, et COMMIT ou ROLLBACK pour valider ou annuler toute modification.
- Paramètres
Les paramètres d’entrée valides sont :
Paramètre
Obligatoire
Description
account
Oui
Nom de votre compte (fourni par Snowflake). Pour plus de détails, voir Notes sur l’utilisation (dans ce chapitre).
user
Oui
Nom de connexion de l’utilisateur.
password
Oui
Mot de passe de l’utilisateur.
region
Obsolète Veuillez spécifier la région dans les paramètres du
account
. Cette description du paramètre concerne uniquement la rétrocompatibilité.host
N’est plus utilisé Nom d’hôte. Utilisé en interne uniquement (n’a donc pas besoin d’être défini).
port
N’est plus utilisé Numéro de port (
443
par défaut). Utilisé en interne uniquement (n’a donc pas besoin d’être défini).database
Nom de la base de données par défaut à utiliser. Après la connexion, vous pouvez utiliser USE DATABASE pour modifier la base de données.
schema
Nom du schéma par défaut à utiliser pour la base de données. Après la connexion, vous pouvez utiliser USE SCHEMA pour modifier le schéma.
role
Nom du rôle par défaut à utiliser. Après la connexion, vous pouvez utiliser USE ROLE pour modifier le rôle.
warehouse
Nom de l’entrepôt par défaut à utiliser. Après vous être connecté, vous pouvez utiliser USE WAREHOUSE pour modifier l’entrepôt.
passcode_in_password
False
par défaut. Définissez cette valeur siTrue
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 surTrue
ouFalse
pour activer ou désactiver le mode de validation automatique dans la session.client_prefetch_threads
Nombre de threads utilisés pour télécharger les jeux de résultats (
4
par défaut). L’augmentation de la valeur améliore les performances d’extraction mais nécessite davantage de mémoire.client_session_keep_alive
False
par défaut. Définissez cette valeur surTrue
pour que la session reste active indéfiniment, même s’il n’y a aucune activité de l’utilisateur. Assurez-vous d’appeler la méthodeclose
pour terminer correctement le thread ou le processus risque de se bloquer.login_timeout
Délai d’attente en secondes pour la connexion. Par défaut, 60 secondes. La demande de connexion abandonne après le délai d’attente si la réponse HTTP est « success ».
network_timeout
Délai d’attente en secondes pour toutes les autres opérations. Par défaut, aucun/infini. Une requête générale abandonne après le délai d’attente si la réponse HTTP n’est pas « success ».
ocsp_response_cache_filename
URI du fichier de cache de réponse OCSP. Par défaut, le fichier de cache de réponse OCSP est créé dans le répertoire du cache :
Linux :
~/.cache/snowflake/ocsp_response_cache
macOS:
~/Library/Caches/Snowflake/ocsp_response_cache
Windows :
%USERPROFILE%\AppData\Local\Snowflake\Caches\ocsp_response_cache
Pour localiser le fichier dans un autre répertoire, indiquez le chemin d’accès et le nom du fichier dans le champ URI (par ex.
file:///tmp/my_ocsp_response_cache.txt
).authenticator
Authentificateur pour Snowflake :
snowflake
(par défaut) pour utiliser l’authentificateur interne Snowflake.
externalbrowser
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ètretoken
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. SiTrue
, 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écifiezqmark
ounumeric
pour modifier le format des variables de liaison pour la liaison côté serveur.timezone
None
par défaut, qui honore le paramètre Snowflake TIMEZONE. Définissez un fuseau horaire valide (par exemple,America/Los_Angeles
) pour définir le fuseau horaire de la session.
Attributs¶
-
Error, Warning, ...
Toutes les classes d’exception définies par la norme de l’API de base de données Python. Le connecteur Snowflake pour Python fournit les attributs
msg
,errno
,sqlstate
,sfqid
etraw_msg
.
Notes d’utilisation pour le paramètre account
(pour la méthode connect
)¶
Le paramètre spécifie le compte Snowflake auquel vous vous connectez et est obligatoire.
Ne pas inclure le nom de domaine Snowflake (
snowflakecomputing.com
) dans le paramètre. Snowflake ajoute automatiquement le nom de domaine à votre nom de compte pour créer la connexion requise.Votre nom de compte complet peut inclure des segments supplémentaires identifiant la région et la plate-forme Cloud où votre compte est hébergé.
Exemples de noms de compte par région
Si votre nom de compte est
xy12345
:Plate-forme Cloud/Région
Nom de compte complet
AWS
US Ouest (Oregon)xy12345
US Est (Ohio)xy12345.us-east-2.aws
US Est (Virginie du Nord)xy12345.us-east-1
US Est (Gouvernement commercial - Virginie du Nord)xy12345.us-east-1-gov.aws
Canada (Centre)xy12345.ca-central-1.aws
Europe (Londres)xy12345.eu-west-2.aws
EU (Irlande)xy12345.eu-west-1
EU (Francfort)xy12345.eu-central-1
Asie-Pacifique (Tokyo)xy12345.ap-northeast-1.aws
Asie Pacifique (Mumbai)xy12345.ap-south-1.aws
Asie-Pacifique (Singapour)xy12345.ap-southeast-1
Asie-Pacifique (Sydney)xy12345.ap-southeast-2
GCP
US Central1 (Iowa)xy12345.us-central1.gcp
Europe Ouest2 (Londres)xy12345.europe-west2.gcp
Europe Ouest4 (Pays-Bas)xy12345.europe-west4.gcp
Azure
Ouest US 2 (Washington)xy12345.west-us-2.azure
Est US 2 (Virginie)xy12345.east-us-2.azure
US Gov Virginiaxy12345.us-gov-virginia.azure
Canada Central (Toronto)xy12345.canada-central.azure
Europe de l’Ouest (Pays-Bas)xy12345.west-europe.azure
Suisse Nord (Zurich)xy12345.switzerland-north.azure
Asie du Sud-Est (Singapour)xy12345.southeast-asia.azure
Australie Est (Nouvelle-Galles du Sud)xy12345.australia-east.azure
Important
Si l’une des conditions suivantes est remplie, le nom de votre compte complet est différent de la structure décrite dans les exemples ci-dessus :
Si votre édition Snowflake est VPS, contactez le support Snowflake pour obtenir des détails sur le nom de votre compte.
Si AWS PrivateLink ou Azure Private Link est activé pour votre compte, votre nom de compte nécessite un segment
privatelink
au lieu du segment de la région. Pour plus de détails, voir :
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 appelsfetch*()
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 appelsfetch*()
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 surTrue
, les commentaires sont supprimés de la requête. Sireturn_cursors
est défini surTrue
, cette méthode retourne une séquence d’objetsCursor
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 fonctionformat()
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, utilisezCursor.execute()
ouCursor.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 surTrue
, les commentaires sont supprimés de la requête. Ce générateur produit chaque objetCursor
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
-
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éthodeexecute()
).- 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
-
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
-
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
Attributs¶
-
messages
¶ L’objet de liste comprenant des séquences (classe d’exception, valeur d’exception) pour tous les messages reçus depuis la base de données sous-jacente pour cette connexion.
La liste est automatiquement effacée par n’importe quel appel de méthode.
-
errorhandler
¶ Attribut de lecture/d’écriture faisant référence à un gestionnaire d’erreur à appeler en cas de condition d’erreur.
Ce gestionnaire doit être un appelable Python acceptant les arguments suivants :
errorhandler(connection, cursor, errorclass, errorvalue)
-
Error, Warning, ...
Toutes les classes d’exception définies par la norme de l’API de base de données Python.
Objet : Cursor
¶
Un objet Cursor
représente un curseur de base de données pour exécuter et récupérer des opérations. Chaque curseur a ses propres attributs, description
et rowcount
, de sorte que les curseurs sont isolés.
Méthodes¶
-
close
() - But
Ferme l’objet de curseur.
-
execute
(command[, parameters])¶ - 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
Les paramètres facultatifs peuvent être fournis sous forme de liste ou de dictionnaire et seront liés à des variables dans la commande. Pour plus d’informations sur les paramètres de liaison, voir Données de liaison. Pour plus d’informations sur les types de données Python mappés aux types de données SQL , voir Mappages de type de donnée pour les liaisons qmark et numeric.
- Renvoie
Renvoie la référence d’un objet
Cursor
.
-
executemany
(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
.- 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
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 appelexecute
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 appelexecute
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
-
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
Aucune.
- Renvoie
Renvoie un DataFrame contenant toutes les lignes de l’ensemble de résultats. Pour plus d’informations sur les trames de données Pandas, consultez la documentation Pandas DataFrame.
S’il n’y a pas de lignes, cela renvoie Aucun.
- Notes sur l’utilisation
Cette méthode n’est pas un remplacement complet de la méthode read_sql() de Pandas ; cette méthode consiste à fournir un moyen rapide de récupérer des données à partir d’une requête SELECT et de stocker les données dans un Pandas DataFrame.
Actuellement, cette méthode ne fonctionne que pour les instructions SELECT.
- Exemples
ctx = snowflake.connector.connect( host=host, user=user, password=password, account=account, warehouse=warehouse, database=database, schema=schema, protocol='https', port=port) # Create a cursor object. cur = ctx.cursor() # Execute a statement that will generate a result set. sql = "select * from t" cur.execute(sql) # Fetch the result set from the cursor and deliver it as the Pandas DataFrame. df = cur.fetch_pandas_all() # ...
-
fetch_pandas_batches
()¶ - But
Cette méthode récupère un sous-ensemble des lignes dans un curseur et les délivre à un Pandas DataFrame.
- Paramètres
Aucune.
- Renvoie
Renvoie un DataFrame contenant un sous-ensemble des lignes de l’ensemble de résultats. Pour plus d’informations sur les trames de données Pandas, consultez la documentation Pandas DataFrame.
Renvoie None s’il n’y a plus de lignes à récupérer.
- Notes sur l’utilisation
Selon le nombre de lignes dans le jeu de résultats, ainsi que le nombre de lignes spécifiées dans l’appel de méthode, la méthode peut avoir besoin d’être appelée plus d’une fois, ou elle peut renvoyer toutes les lignes dans un seul lot si elles correspondent toutes.
Cette méthode n’est pas un remplacement complet de la méthode read_sql() de Pandas ; cette méthode consiste à fournir un moyen rapide de récupérer des données à partir d’une requête SELECT et de stocker les données dans un Pandas DataFrame.
Actuellement, cette méthode ne fonctionne que pour les instructions SELECT.
- Exemples
ctx = snowflake.connector.connect( host=host, user=user, password=password, account=account, warehouse=warehouse, database=database, schema=schema, protocol='https', port=port) # Create a cursor object. cur = ctx.cursor() # Execute a statement that will generate a result set. sql = "select * from t" cur.execute(sql) # Fetch the result set from the cursor and deliver it as the Pandas DataFrame. for df in cur.fetch_pandas_batches(): my_dataframe_processing_function(df) # ...
-
__iter__
()¶ Se retourne pour rendre les curseurs compatibles avec le protocole d’itération.
Attributs¶
-
description
¶ Attribut en lecture seule qui retourne une séquence de 7 valeurs :
Valeur
Description
name
Nom de colonne.
type_code
Code de type interne.
display_size
(Non utilisé. Identique à internal_size.)
internal_size
Taille des données internes.
precision
Précision des données numériques.
scale
Échelle pour les données numériques.
null_ok
True
si des valeurs NULL sont autorisées pour la colonne ouFalse
.
-
rowcount
¶ Attribut en lecture seule qui retourne le nombre de lignes dans le dernier
execute
produit. La valeur est-1
ouNone
si aucunexecute
n’est exécuté.
-
sfqid
¶ Attribut en lecture seule qui renvoie l’ID de requête Snowflake dans le dernier
execute
ouexecute_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¶
Cursor.description
retourne les métadonnées de la colonne. type_code
représente le type de données de la colonne, et utilise la carte suivante pour obtenir la représentation de la chaîne :
type_code |
Représentation de chaîne |
Type de données |
---|---|---|
0 |
FIXED |
NUMBER/INT |
1 |
REAL |
REAL |
2 |
TEXT |
VARCHAR/STRING |
3 |
DATE |
DATE |
4 |
TIMESTAMP |
TIMESTAMP |
5 |
VARIANT |
VARIANT |
6 |
TIMESTAMP_LTZ |
TIMESTAMP_LTZ |
7 |
TIMESTAMP_TZ |
TIMESTAMP_TZ |
8 |
TIMESTAMP_NTZ |
TIMESTAMP_TZ |
9 |
OBJECT |
OBJECT |
10 |
ARRAY |
ARRAY |
11 |
BINARY |
BINARY |
12 |
TIME |
TIME |
13 |
BOOLEAN |
BOOLEAN |
Mappages de type de donnée pour les liaisons qmark
et numeric
¶
Si paramstyle
est "qmark"
ou "numeric"
, les mappages suivants par défaut de Python vers le type de données Snowflake sont utilisés :
Type de données Python |
Type de données dans Snowflake |
---|---|
|
NUMBER(38, 0) |
|
NUMBER(38, 0) |
|
NUMBER(38, <échelle>) |
|
REAL |
|
TEXT |
|
TEXT |
|
BINARY |
|
BINARY |
|
BOOLEAN |
|
DATE |
|
TIME |
|
TIME |
|
TIMESTAMP_NTZ |
|
TIMESTAMP_NTZ |
Si vous devez mapper un autre type Snowflake (p. ex. datetime
à TIMESTAMP_LTZ
), spécifiez le type de données Snowflake dans un tuple composé du type de données Snowflake suivi de la valeur. Voir Liaison de datetime avec TIMESTAMP pour des exemples.
Objet : Exception
¶
PEP-249 définit les exceptions que le connecteur Snowflake pour Python peut faire en cas d’erreur ou d’avertissement. L’application doit les traiter correctement et décider de continuer ou d’arrêter l’exécution du code.
Méthodes¶
Aucune méthode n’est disponible pour les objets Exception
.
Attributs¶
-
errno
¶ Code d’erreur DB Snowflake.
-
msg
¶ Message d’erreur incluant le code d’erreur, le code d’état SQL et l’ID de requête.
-
raw_msg
¶ Message d’erreur. Aucun code d’erreur, de code d’état SQL ou d’ID de requête n’est inclus.
-
sqlstate
¶ Code d’état SQL conforme à ANSI
-
sfqid
ID de requête Snowflake.
Module : snowflake.connector.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
etCOPY 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
estTrue
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 commandeCOPY 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érezmethod=pd_writer
pour indiquer que vous voulez utiliserpd_writer
comme méthode d’insertion de données. (Vous n’avez pas besoin d’appelerpd_writer
à partir de votre propre code. La méthodeto_sql
appellepd_writer
et fournit les paramètres d’entrée nécessaires.)La fonction
pd_writer
utilise la fonctionwrite_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
ousqlalchemy.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éthodepandas.DataFrame.to_sql
, qui à son tour appelle la fonctionpd_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 |
Récupère les données, y compris le décalage de fuseau horaire, et les traduit en |
|
TIMESTAMP_LTZ, TIMESTAMP |
Récupère les données, les traduit en un objet |
|
TIMESTAMP_NTZ |
Récupère les données et les traduit en objet |
|
DATE |
Récupère les données et les traduit en 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 |
struct_time |
TIMESTAMP_TZ, TIMESTAMP_LTZ, TIMESTAMP_NTZ, DATE |
Convertit un objet « struct_time » en une chaîne au format |
date |
TIMESTAMP_TZ, TIMESTAMP_LTZ, TIMESTAMP_NTZ, DATE |
Convertit un objet « date » en une chaîne au format |
time |
TIMESTAMP_TZ, TIMESTAMP_LTZ, TIMESTAMP_NTZ, DATE |
Convertit un objet « time » en une chaîne au format |
timedelta |
TIMESTAMP_TZ, TIMESTAMP_LTZ, TIMESTAMP_NTZ, DATE |
Convertit un objet « timedelta » en une chaîne au format |