Python-Konnektor-API¶

Konstanten¶

apilevel¶

Zeichenfolgenkonstante, die die unterstützte API-Ebene angibt. Der Konnektor unterstützt API "2.0".

threadsafety¶

Ganzzahlkonstante, die den von der Schnittstelle unterstützten Threadsicherheitslevel angibt. Der Snowflake-Konnektor für Python unterstützt Level 2, d. h. Threads können das Modul und die Verbindungen gemeinsam nutzen.

paramstyle¶

Zeichenfolgenkonstante, die den Typ der von der Schnittstelle erwarteten Formatierung der Parametermarker angibt. Der Konnektor unterstützt standardmäßig den Typ "pyformat", der für erweiterte Python-Formatcodes gilt (z. B. ...WHERE name=%s oder ...WHERE name=%(name)s). Connection.connect kann paramstyle überschreiben, um die Bindungsvariablenformate in "qmark" oder "numeric" zu ändern, wobei die Variablen ? bzw. :N sind.

Beispiel:

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

Bemerkung

Die Bindungsvariable tritt auf Clientseite auf, wenn paramstyle den Wert "pyformat" oder "format" und auf Serverseite den Wert "qmark" oder "numeric" hat. Derzeit gibt es keinen signifikanten Unterschied zwischen diesen Optionen in Bezug auf Leistung oder Funktionsumfang, da der Konnektor das Kompilieren und anschließende mehrfache Ausführen von SQL-Text nicht unterstützt. Stattdessen richten sich die Optionen "qmark" und "numeric" nach der Abfragetextkompatibilität anderer Treiber (z. B. JDBC, ODBC, Go-Snowflake-Treiber), die serverseitige Bindungen mit dem variablen Format ? oder :N unterstützen.

Funktionen¶

connect(parameters...)¶

Zweck:

Konstruktor zum Erstellen einer Verbindung zur Datenbank. Gibt ein Connection-Objekt zurück.

Standardmäßig ist der Autocommit-Modus aktiviert (d. h. wenn die Verbindung geschlossen wird, werden alle Änderungen committet). Wenn Sie eine Transaktion benötigen, verwenden Sie den Befehl BEGIN, um die Transaktion zu starten, und COMMIT oder ROLLBACK, um Änderungen zu committen oder zurückzusetzen.

Parameter:

Die gültigen Eingabeparameter sind:

Parameter	Erforderlich	Beschreibung
account	Ja	Ihr Kontobezeichner. Der Kontobezeichner enthält nicht das Suffix snowflakecomputing.com. . . Weitere Details und Beispiele dazu finden siehe unter Nutzungshinweise (unter diesem Thema).
user	Ja	Anmeldename des Benutzers.
password	Ja	Kennwort für den Benutzer.
region		Veraltet Diese Beschreibung des Parameters dient nur der Abwärtskompatibilität.
host		Nicht mehr verwendet – Hostname. Nur intern verwendet (d. h. Parameter muss nicht eingestellt werden).
port		Nicht mehr verwendet – Portnummer (standardmäßig 443). Nur intern verwendet (d. h. Parameter muss nicht eingestellt werden).
database		Name der zu verwendenden Standarddatenbank. Nach der Anmeldung können Sie mit USE DATABASE die Datenbank ändern.
schema		Name des Standardschemas, das für die Datenbank verwendet werden soll. Nach der Anmeldung können Sie mit USE SCHEMA das Schema ändern.
role		Name der Standardrolle, die verwendet werden soll. Nach der Anmeldung können Sie mit USE ROLE die Rolle ändern.
warehouse		Name des zu verwendenden Standard-Warehouse. Nach der Anmeldung können Sie mit USE WAREHOUSE das Warehouse ändern.
passcode_in_password		Standardmäßig False. Stellen Sie dies auf True ein, wenn die MFA-Kennung (mehrstufige Authentifizierung) in das Anmeldekennwort eingebettet ist.
passcode		Kennung, die von Duo bei der Verwendung von MFA (mehrstufige Authentifizierung) für die Anmeldung bereitgestellt wird.
private_key		Der private Schlüssel, der für die Authentifizierung verwendet wird. Weitere Informationen dazu finden Sie unter Verwenden von Schlüsselpaar-Authentifizierung und Schlüsselpaar-Rotation.
private_key_file		Gibt den Pfad zur Datei des privaten Schlüssels für den angegebenen Benutzer an. Siehe Verwenden von Schlüsselpaar-Authentifizierung und Schlüsselpaar-Rotation.
private_key_file_pwd		Gibt die Passphrase zum Entschlüsseln der Datei des privaten Schlüssels für den angegebenen Benutzer an. Siehe Verwenden von Schlüsselpaar-Authentifizierung und Schlüsselpaar-Rotation.
autocommit		Standardmäßig None, wodurch der Snowflake-Parameter AUTOCOMMIT berücksichtigt wird. Stellen Sie dies auf True oder False ein, um den Autocommit-Modus in der Sitzung zu aktivieren bzw. zu deaktivieren.
client_prefetch_threads		Anzahl der Threads, die zum Herunterladen der Resultset verwendet werden (standardmäßig 4). Das Erhöhen des Werts verbessert die Abrufleistung, erfordert jedoch mehr Speicher.
client_session_keep_alive		Um die Sitzung auf unbestimmte Zeit aktiv zu halten (auch wenn es keine Aktivitäten des Benutzers gibt), legen Sie den Wert auf True ein. Wenn dieser Wert auf True eingestellt ist, rufen Sie die close-Methode auf, um den Thread ordnungsgemäß zu beenden, da sonst der Prozess hängen bleiben kann.
		Der Standardwert hängt von der Version des Konnektors ab, den Sie verwenden:
		Version 2.4.6 und später: Standardmäßig None. . Wenn der Wert None ist, hat der Sitzungsparameter CLIENT_SESSION_KEEP_ALIVE Vorrang. . . Um den Sitzungsparameter außer Kraft zu setzen, geben Sie True oder False für dieses Argument ein.
		Version 2.4.5 und früher: Standardmäßig False. . Wenn der Wert False ist (entweder durch explizite Angabe des Wertes oder durch Weglassen des Arguments), hat der Sitzungsparameter CLIENT_SESSION_KEEP_ALIVE Vorrang. . . Durch Übergabe von client_session_keey_alive=False an die connect-Methode wird der TRUE-Wert im Sitzungsparameter CLIENT_SESSION_KEEP_ALIVE nicht außer Kraft gesetzt.
login_timeout		Timeout für Anmeldung in Sekunden. Standardmäßig 60 Sekunden. Die Anmeldeanforderung gibt nach Ablauf des Timeouts auf, wenn die HTTP-Antwort „success“ ist.
network_timeout		Timeout für alle anderen Operationen in Sekunden. Standardmäßig „none“ oder „infinite“. Eine allgemeine Anforderung gibt nach Ablauf des Timeout auf, wenn die HTTP-Antwort nicht „success“ ist.
ocsp_response_cache_filename		URI für die OCSP-Antwort-Cachedatei. Standardmäßig wird die OCSP-Antwort-Cachedatei im Cacheverzeichnis erstellt:
		Linux: ~/.cache/snowflake/ocsp_response_cache
		macOS: ~/Library/Caches/Snowflake/ocsp_response_cache
		Windows: %USERPROFILE%AppDataLocalSnowflakeCachesocsp_response_cache
		Um die Datei in einem anderen Verzeichnis zu lokalisieren, geben Sie in der URI Pfad und Dateinamen an (z. B. file:///tmp/my_ocsp_response_cache.txt).
authenticator		Authentifikator für Snowflake:
		snowflake (Standard), um den internen Snowflake-Authentifikator zu verwenden.
		externalbrowser, um sich mit Ihrem Webbrowser und Okta, AD FS oder einem anderen SAML 2.0-kompatiblen Identitätsanbieter (IdP) zu authentifizieren, der für Ihr Konto definiert wurde.
		https://<Okta-Kontoname>.okta.com (d. h. der URL-Endpunkt für Okta) zur Authentifizierung durch natives Okta.
		oauth zum Authentifizieren mit OAuth. Sie müssen auch den Parameter token angeben und seinen Wert auf das OAuth-Zugriffstoken setzen.
		username_password_mfa zum Authentifizieren mit MFA-Tokencaching. Weitere Details dazu finden Sie unter Verwenden von MFA-Tokencaching zur Minimierung der Anzahl von Eingabeaufforderungen bei der Authentifizierung – Optional.
		Wenn der Wert nicht snowflake ist, müssen für die Benutzer- und Kennwortparameter Ihre IdP-Anmeldeinformationen verwendet werden.
validate_default_parameters		Standardmäßig False. Wenn True, dann:
		Wenn Datenbank, Schema oder Warehouse nicht vorhanden ist, wird eine Ausnahme ausgelöst.
		Wenn ein ungültiger Argumentname oder ein Argumentwert des falschen Datentyps übergeben wird, dann wird eine Warnung an stderr gedruckt.
paramstyle		Standardmäßig pyformat für die clientseitige Bindung. Geben Sie qmark oder numeric an, um die Formate der Bindungsvariablen für die serverseitige Bindung zu ändern.
timezone		Standardmäßig None, wodurch der Snowflake-Parameter TIMEZONE berücksichtigt wird. Wird auf eine gültige Zeitzone (z. B. America/Los_Angeles) eingestellt, um die Sitzungszeitzone anzugeben.
arrow_number_to_decimal		Standardmäßig False, was bedeutet, dass NUMBER-Spaltenwerte als Gleitkommazahlen mit doppelter Genauigkeit (float64) zurückgegeben werden. . . Setzen Sie dies auf True, um DECIMAL-Spaltenwerte als Dezimalzahlen (decimal.Decimal) zurückzugeben, wenn Sie die Methoden fetch_pandas_all() und fetch_pandas_batches() aufrufen. . . Dieser Parameter wurde in Version 2.4.3 des Snowflake-Konnektors für Python eingeführt.
socket_timeout		Timeout in Sekunden für Lese- und Verbindungsanforderungen auf Socket-Ebene. Weitere Informationen dazu finden Sie unter Verwalten von Verbindungstimeouts.
backoff_policy		Name der Generatorfunktion, die festlegt, wie lange zwischen den Wiederholungsversuchen gewartet werden soll. Weitere Informationen dazu finden Sie unter Verwalten von Verbindungs-Backoff-Richtlinien für Wiederholungsversuche.

Attribute¶

Error, Warning, ...

Alle Ausnahmeklassen, die durch den Python-Datenbank-API-Standard definiert sind. Der Snowflake-Konnektor für Python stellt die Attribute msg, errno, sqlstate, sfqid und raw_msg bereit.

Nutzungshinweise für die Verwendung des account-Parameters (für die connect-Methode)¶

Geben Sie für den erforderlichen Parameter account Ihren Kontobezeichner an.

Beachten Sie, dass der Kontobezeichner nicht den snowflakecomputing.com-Domänennamen enthält. Snowflake hängt diesen automatisch beim Erstellen der Verbindung an.

Im folgenden Beispiel wird ein Kontobezeichner (Kontoname) verwendet, der das Konto myaccount der Organisation myorganization angibt:

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

Im folgenden Beispiel wird der Konto-Locator xy12345 als Kontobezeichner verwendet:

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

Beachten Sie, dass in diesem Beispiel ein Konto in der Region AWS US West (Oregon) verwendet wird. Wenn sich das Konto in einer anderen Region befindet oder wenn das Konto einen anderen Cloudanbieter verwendet, müssen Sie nach dem Konto-Locator zusätzliche Segmente angeben.

Methoden¶

autocommit(True|False)¶

Zweck:

Aktiviert oder deaktiviert den Autocommit-Modus. Standardmäßig ist Autocommit aktiviert (True).

close()¶

Zweck:

Schließt die Verbindung. Wenn eine Transaktion beim Schließen der Verbindung noch geöffnet ist, werden die Änderungen rückgängig gemacht.

Wenn die Verbindung explizit geschlossen wird, wird die aktive Sitzung vom Server entfernt. Andernfalls wird die aktive Sitzung fortgesetzt, bis sie schließlich endgültig vom Server entfernt wird, wodurch die Anzahl der gleichzeitigen Abfragen begrenzt wird.

Beispiel:

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

Zweck:

Wenn Autocommit deaktiviert ist, wird die aktuelle Transaktion committet. Wenn Autocommit aktiviert ist, wird diese Methode ignoriert.

rollback()¶

Zweck:

Wenn Autocommit deaktiviert ist, erfolgt ein Rollback der aktuellen Transaktion. Wenn Autocommit aktiviert ist, wird diese Methode ignoriert.

cursor()¶

Zweck:

Konstruktor zum Erstellen eines Cursor-Objekts. Die Rückgabewerte von fetch*()-Aufrufen sind eine einzelne Sequenz oder eine Liste von Sequenzen.

cursor(snowflake.connector.DictCursor)

Zweck:

Konstruktor zum Erstellen eines DictCursor-Objekts. Die Rückgabewerte von fetch*()-Aufrufen sind ein einzelnes dict-Objekt oder eine Liste von dict-Objekten. Dies ist nützlich, um Werte nach Spaltennamen aus den Ergebnissen abzurufen.

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

Zweck:

Führt eine oder mehrere SQL-Anweisungen aus, die als Zeichenfolgen übergeben werden. Wenn remove_comments auf True gesetzt ist, werden Kommentare aus der Abfrage entfernt. Wenn return_cursors auf True gesetzt ist, gibt diese Methode eine Sequenz von Cursor-Objekten in der Reihenfolge der Ausführung zurück.

Beispiel:

Im folgenden Beispiel wird die Ausführung mehrerer Befehle in einer einzigen Zeichenfolge und die Verwendung der zurückgegebenen Sequenz von Cursors gezeigt:

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

Bemerkung

Methoden wie execute_string(), die mehrere SQL-Anweisungen in einer einzigen Zeichenfolge zulassen, sind anfällig für Angriffe durch Einschleusung von SQL-Befehlen. Vermeiden Sie bei der dynamischen Erstellung von SQL-Anweisungen für die Kombination von SQL mit Benutzerdaten die Verwendung der Zeichenfolgenverkettungen oder von Funktionen wie die Python-Funktion format(), es sei denn, Sie haben die Benutzerdaten validiert. Im Beispiel unten wird das Problem veranschaulicht:

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

Die dynamisch zusammengesetzte Anweisung sieht wie folgt aus (zur besseren Lesbarkeit wurden neue Zeilen hinzugefügt):

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

Wenn Sie SQL-Anweisungen mit Zeichenfolgen kombinieren, die von nicht vertrauenswürdigen Benutzern eingegeben wurden, ist es sicherer, Daten an eine Anweisung zu binden statt eine Zeichenfolge zu erstellen. Die Methode execute_string() übernimmt keine Bindungsparameter, verwenden Sie daher zum Binden von Parametern Cursor.execute() oder Cursor.executemany().

execute_stream(sql_stream, remove_comments=False)¶

Zweck:

Führt eine oder mehrere SQL-Anweisungen aus, die als Streamobjekt übergeben werden. Wenn remove_comments auf True gesetzt ist, werden Kommentare aus der Abfrage entfernt. Dieser Generator liefert jedes Cursor-Objekt als Ausführung von SQL-Anweisungen.

get_query_status(query_id)¶

Zweck:

Gibt den Status einer Abfrage zurück.

Parameter:

query_id

Die ID der Abfrage. Siehe Abrufen der Snowflake-Abfrage-ID.

Rückgabewerte:

Gibt das Objekt QueryStatus zurück, das den Status der Abfrage repräsentiert.

Beispiel:

Siehe Überprüfen des Status einer Abfrage.

get_query_status_throw_if_error(query_id)¶

Zweck:

Gibt den Status einer Abfrage zurück. Wenn die Abfrage zu einem Fehler führt, löst diese Methode einen ProgrammingError aus (wie die Methode execute()).

Parameter:

query_id

Die ID der Abfrage. Siehe Abrufen der Snowflake-Abfrage-ID.

Rückgabewerte:

Gibt das Objekt QueryStatus zurück, das den Status der Abfrage repräsentiert.

Beispiel:

Siehe Überprüfen des Status einer Abfrage.

is_still_running(query_status)¶

Zweck:

Gibt True zurück, wenn der Abfragestatus anzeigt, dass die Abfrage noch nicht abgeschlossen oder noch in Bearbeitung ist.

Parameter:

query_status

Das Objekt QueryStatus, das den Status der Abfrage repräsentiert. Um dieses Objekt für eine Abfrage zu erhalten, siehe Überprüfen des Status einer Abfrage.

Beispiel:

Siehe Überprüfen des Status einer Abfrage.

is_an_error(query_status)¶

Zweck:

Gibt True zurück, wenn der Abfragestatus anzeigt, dass die Abfrage zu einem Fehler geführt hat.

Parameter:

query_status

Das Objekt QueryStatus, das den Status der Abfrage repräsentiert. Um dieses Objekt für eine Abfrage zu erhalten, siehe Überprüfen des Status einer Abfrage.

Beispiel:

Siehe Überprüfen des Status einer Abfrage.

Attribute¶

expired¶

Verfolgt, ob das Master-Token der Verbindung abgelaufen ist.

messages¶

Das Listenobjekt einschließlich der Sequenzen (Ausnahmeklasse, Ausnahmewert) für alle Meldungen, die von der zugrunde liegenden Datenbank für diese Verbindung empfangen werden.

Die Liste wird bei jedem Methodenaufruf automatisch gelöscht.

errorhandler¶

Lese-/Schreibattribut, das einen Fehlerhandler referenziert, der aufgerufen wird, wenn eine Fehlerbedingung erfüllt ist.

Der Handler muss eine aufrufbare Python-Methode sein, die die folgenden Argumente akzeptiert:

errorhandler(connection, cursor, errorclass, errorvalue)

Error, Warning, ...

Alle Ausnahmeklassen, die durch den Python-Datenbank-API-Standard definiert sind.

Methoden¶

close()

Zweck:

Schließt das Cursorobjekt.

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

Zweck:

Gibt Metadaten über das Resultset zurück, ohne dass ein Datenbankbefehl ausgeführt wird. Dies gibt die gleichen Metadaten zurück, die nach der Ausführung einer Abfrage im Attribut description verfügbar sind.

Diese Methode wurde in Version 2.4.6 des Snowflake-Konnektors für Python eingeführt.

Parameter:

Siehe Parameter für die Methode execute().

Rückgabewerte:

Gibt eine Liste von ResultMetadata-Objekten zurück, die die Spalten im Resultset beschreiben.

Beispiel:

Siehe Abrufen von Spaltenmetadaten.

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

Zweck:

Bereitet einen Datenbankbefehl vor und führt diesen aus.

Parameter:

command

Eine Zeichenfolge, die die auszuführende SQL-Anweisung enthält.

parameters

(Optional) Wenn Sie in der SQL-Anweisung Parameter für das Binden von Daten verwendet haben, setzen Sie dies auf die Liste oder das Wörterbuch der Variablen, die an diese Parameter gebunden werden sollen.

Weitere Informationen zum Zuordnen der Python-Datentypen der Variablen zu SQL-Datentypen der zugehörigen Spalten finden Sie unter Datentyp-Zuordnungen für qmark- und numeric-Bindungen.

timeout

(Optional) Anzahl der Sekunden, die auf den Abschluss der Abfrage gewartet werden soll. Wenn die Abfrage nach Ablauf dieser Zeit nicht abgeschlossen ist, sollte die Abfrage abgebrochen werden.

file_stream

(Optional) Bei der Ausführung eines PUT-Befehls können Sie diesen Parameter verwenden, um statt einer Datei im Dateisystem ein dateiähnliches Objekt im Arbeitsspeicher (z. B. das von der Python-Funktion open() zurückgegebene E/A-Objekt) hochzuladen. Setzen Sie diesen Parameter auf dieses E/A-Objekt.

Bei Angabe der URI für die Datendatei im PUT-Befehl:

• Sie können einen beliebigen Verzeichnispfad verwenden. Der Verzeichnispfad, den Sie in der URI angeben, wird ignoriert.

• Geben Sie für den Dateinamen den Namen der Datei an, die im Stagingbereich erstellt werden soll.

Laden Sie zum Beispiel eine Datei aus einem Dateistream in eine Datei mit folgendem Namen hoch:

@mystage/myfile.csv

Copy

verwenden Sie den folgenden Aufruf:

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

Copy

Rückgabewerte:

Gibt die Referenz eines Cursor-Objekts zurück.

executemany(command, seq_of_parameters)¶

Zweck:

Bereitet einen Datenbankbefehl vor und führt diesen für alle in seq_of_parameters gefundenen Parametersequenzen aus. Sie können diese Methode verwenden, um eine Batch-Einfügeoperation auszuführen.

Parameter:

command

Der Befehl ist eine Zeichenfolge, die den auszuführenden Code enthält. Die Zeichenfolge sollte einen oder mehrere Platzhalter (z. B. Fragezeichen) für Binden von Daten enthalten.

Beispiel:

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

Copy

seq_of_parameters

Dies sollte eine Sequenz (Liste oder Tupel) von Listen oder Tupeln sein. Der unten stehende Beispielcode zeigt mögliche Sequenzen.

Rückgabewerte:

Gibt die Referenz eines Cursor-Objekts zurück.

Beispiel:

# 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

Intern werden mehrere execute-Methoden aufgerufen, und das Resultset des letzten execute-Anrufs bleibt erhalten.

Bemerkung

Die executemany-Methode kann nur zur Ausführung einzelner parametrisierter SQL-Anweisung und zur Übergabe mehrerer Bindungswerte verwendet werden.

Das Ausführen mehrerer, durch Semikolon getrennter SQL-Anweisungen innerhalb eines execute-Aufrufs wird nicht unterstützt. Geben Sie stattdessen für jede Anweisung einen separaten execute-Aufruf aus.

execute_async(...)¶

Zweck:

Bereitet einen Datenbankbefehl für die asynchrone Ausführung vor und übermittelt den Befehl. Siehe Ausführen einer asynchronen Abfrage.

Parameter:

Diese Methode verwendet die gleichen Parameter wie die Methode execute().

Rückgabewerte:

Gibt die Referenz eines Cursor-Objekts zurück.

Beispiel:

Siehe Beispiele für asynchrone Abfragen.

fetch_arrow_all()¶

Zweck:

Diese Methode ruft alle Zeilen in einem Cursor ab und lädt sie in eine PyArrow-Tabelle.

Parameter:

Keine.

Rückgabewerte:

Gibt eine PyArrow-Tabelle zurück, die alle Zeilen aus dem Resultset enthält.

Wenn keine Zeilen vorhanden sind, wird „None“ zurückgegeben.

Beispiel:

Siehe Verteilen von Workloads, die Ergebnisse mit dem Snowflake-Konnektor für Python abrufen.

fetch_arrow_batches()¶

Zweck:

Diese Methode ruft eine Teilmenge der Zeilen in einem Cursor ab und liefert sie an eine PyArrow-Tabelle.

Parameter:

Keine.

Rückgabewerte:

Gibt eine PyArrow-Tabelle zurück, die eine Teilmenge der Zeilen aus dem Resultset enthält.

Gibt „None“ zurück, wenn keine Zeilen mehr zum Abrufen vorhanden sind.

Beispiel:

Siehe Verteilen von Workloads, die Ergebnisse mit dem Snowflake-Konnektor für Python abrufen.

get_result_batches()¶

Zweck:

Gibt eine Liste von ResultBatch-Objekten zurück, die Sie verwenden können, um eine Teilmenge von Zeilen aus dem Resultset abzurufen.

Parameter:

Keine.

Rückgabewerte:

Gibt eine Liste von ResultBatch-Objekten zurück oder None, wenn die Ausführung der Abfrage nicht abgeschlossen wurde.

Beispiel:

Siehe Verteilen von Workloads, die Ergebnisse mit dem Snowflake-Konnektor für Python abrufen.

get_results_from_sfqid(query_id)¶

Zweck:

Ruft die Ergebnisse einer asynchronen Abfrage oder einer zuvor übermittelten synchronen Abfrage ab.

Parameter:

query_id

Die ID der Abfrage. Siehe Abrufen der Snowflake-Abfrage-ID.

Beispiel:

Siehe Verwenden der Abfrage-ID zum Abrufen von Abfrageergebnissen.

fetchone()¶

Zweck:

Ruft die nächste Zeile aus dem Resultset einer Abfrage ab und gibt eine einzelne Sequenz/dict zurück oder None, wenn keine weiteren Daten verfügbar sind.

fetchmany([size=cursor.arraysize])¶

Zweck:

Ruft die nächsten Zeilen aus dem Resultset einer Abfrage ab und gibt eine Liste von Sequenzen/dict zurück. Eine leere Sequenz wird zurückgegeben, wenn keine Zeilen mehr verfügbar sind.

fetchall()¶

Zweck:

Ruft alle oder die restlichen Zeilen aus dem Resultset einer Abfrage ab und gibt eine Liste von Sequenzen/dict zurück.

fetch_pandas_all()¶

Zweck:

Diese Methode ruft alle Zeilen in einem Cursor ab und lädt sie in einen pandas-DataFrame.

Parameter:

Keine.

Rückgabewerte:

Gibt einen DataFrame zurück, der alle Zeilen aus dem Resultset enthält. Weitere Informationen zu pandas-DataFrames finden Sie in der pandas-DataFrame-Dokumentation.

Wenn keine Zeilen vorhanden sind, wird „None“ zurückgegeben.

Nutzungshinweise:

• Diese Methode ist kein vollständiger Ersatz für die pandas-Methode read_sql(). Diese Methode bietet eine schnelle Möglichkeit, Daten aus einer SELECT-Abfrage abzurufen und die Daten in einem pandas-DataFrame zu speichern.

• Derzeit funktioniert diese Methode nur für SELECT-Anweisungen.

Beispiele:

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

Zweck:

Diese Methode ruft eine Teilmenge der Zeilen in einem Cursor ab und liefert sie an einen pandas-DataFrame.

Parameter:

Keine.

Rückgabewerte:

Gibt einen DataFrame zurück, der eine Teilmenge der Zeilen aus dem Resultset enthält. Weitere Informationen zu pandas-DataFrames finden Sie in der pandas-DataFrame-Dokumentation.

Gibt „None“ zurück, wenn keine Zeilen mehr zum Abrufen vorhanden sind.

Nutzungshinweise:

• Abhängig von der Anzahl der Zeilen im Resultset sowie der Anzahl der im Methodenaufruf angegebenen Zeilen muss die Methode möglicherweise mehrmals aufgerufen werden, oder es werden möglicherweise alle Zeilen in einem einzigen Batch zurückgegeben, wenn sie alle passen.

• Diese Methode ist kein vollständiger Ersatz für die pandas-Methode read_sql(). Diese Methode bietet eine schnelle Möglichkeit, Daten aus einer SELECT-Abfrage abzurufen und die Daten in einem pandas-DataFrame zu speichern.

• Derzeit funktioniert diese Methode nur für SELECT-Anweisungen.

Beispiele:

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

Gibt sich selbst zurück, um für Kompatibilität der Cursors mit dem Iterationsprotokoll zu sorgen.

Attribute¶

description¶

Schreibgeschütztes Attribut, das Metadaten über die Spalten im Resultset zurückgibt.

Dieses Attribut wird festgelegt, nachdem Sie die Methode execute() zur Ausführung der Abfrage aufgerufen haben. (Ab Version 2.4.6 können Sie diese Metadaten abrufen, ohne die Abfrage auszuführen, indem Sie die Methode describe() aufrufen.)

Dieses Attribut wird auf einen der folgenden Werte gesetzt:

• Versionen 2.4.5 und früher: Dieses Attribut wird auf eine Liste von Tupeln gesetzt.

• Versionen 2.4.6 und später: Dieses Attribut wird auf eine Liste von ResultMetadata-Objekten gesetzt.

Jedes Tupel- oder ResultMetadata-Objekt enthält die Metadaten, die eine Spalte im Resultset beschreiben. Sie können auf die Metadaten über den Index oder ab Version 2.4.6 auch über das Objektattribut ResultMetadata zugreifen:

Index des Wertes	ResultMetadata-Attribut	Beschreibung
0	name	Spaltenname.
1	type_code	Interner Typcode.
2	display_size	(Nicht verwendet. Wie „internal_size“.)
3	internal_size	Interne Datengröße.
4	precision	Genauigkeit der numerischen Daten.
5	scale	Dezimalstellenzahl der numerischen Daten.
6	is_nullable	True, wenn NULL-Werte für die Spalte erlaubt sind, ansonsten False.

Beispiele für das Abrufen dieses Attributs finden Sie unter Abrufen von Spaltenmetadaten.

rowcount¶

Nur-Lese-Attribut, das die Anzahl der Zeilen des zuletzt erstellten execute zurückgibt. Der Wert ist -1 oder None, wenn kein execute ausgeführt wird.

sfqid¶

Nur-Lese-Attribut, das die Snowflake-Abfrage-ID im zuletzt ausgeführten execute- oder execute_async-Befehl zurückgibt.

arraysize¶

Lese-/Schreibattribut, das die Anzahl der auf einmal mit fetchmany() abzurufenden Zeilen angibt. Es hat standardmäßig den Wert 1, was bedeutet, dass jeweils eine einzelne Zeile abgerufen wird.

connection¶

Nur-Lese-Attribut, das eine Referenz auf das Objekt Connection zurückgibt, auf dem der Cursor erstellt wurde.

messages

Listenobjekt, das die Sequenzen (Ausnahmeklasse, Ausnahmewert) für alle Meldungen enthält, die es von der zugrunde liegenden Datenbank für den Cursor erhalten hat.

Die Liste wird automatisch bei jedem Methodenaufruf mit Ausnahme von fetch*()-Aufrufen gelöscht.

errorhandler

Lese-/Schreibattribut, das einen Fehlerhandler referenziert, der aufgerufen wird, wenn eine Fehlerbedingung erfüllt ist.

Der Handler muss eine aufrufbare Python-Methode sein, die die folgenden Argumente akzeptiert:

errorhandler(connection, cursor, errorclass, errorvalue)

Typcodes¶

Im Cursor-Objekt liefern das Attribut description und die Methode describe() eine Liste von Tupeln (oder ab Version 2.4.6 auch ResultMetadata-Objekten), die die Spalten im Resultset beschreiben.

In einem Tupel repräsentiert der Wert bei Index 1 (das Attribut Typcode im Objekt ResultMetadata) den Datentyp der Spalte. Der Snowflake-Konnektor für Python verwendet die folgende Zuordnung, um die Zeichenfolgenrepräsentation basierend auf dem Typcode zu erhalten:

Datentyp-Zuordnungen für qmark- und numeric-Bindungen¶

Wenn paramstyle entweder "qmark" oder "numeric" ist, werden die folgenden Standardzuordnungen von Python- zu Snowflake-Datentypen verwendet:

Wenn die Zuordnung zu einem anderen Snowflake-Typ (z. B. datetime zu TIMESTAMP_LTZ) erfolgen soll, geben Sie den Snowflake-Datentyp in einem Tupel an, das aus dem Snowflake-Datentyp und dem Wert besteht. Entsprechende Beispiele finden Sie unter Binden von datetime an TIMESTAMP.

Methoden¶

Für Exception-Objekte sind keine Methoden verfügbar.

Attribute¶

errno¶

Snowflake-DB-Fehlercode.

msg¶

Fehlermeldung mit Fehlercode, SQL-Zustandscode und Abfrage-ID.

raw_msg¶

Fehlermeldung. Enthält weder Fehlercode, noch SQL-Zustandscode oder Abfrage-ID.

sqlstate¶

ANSI-kompatibler SQL-Zustandscode

sfqid

Snowflake-Abfrage-ID.

Attribute¶

Methoden¶

to_arrow()¶

Zweck:

Diese Methode gibt eine PyArrow-Tabelle zurück, die die Zeilen des ResultBatch-Objekts enthält.

Parameter:

Keine.

Rückgabewerte:

Gibt eine PyArrow-Tabelle zurück, die die Zeilen aus dem ResultBatch-Objekt enthält.

Wenn keine Zeilen vorhanden sind, wird „None“ zurückgegeben.

to_pandas()¶

Zweck:

Diese Methode gibt einen pandas-DataFrame zurück, der die Zeilen des ResultBatch-Objekts enthält.

Parameter:

Keine.

Rückgabewerte:

Gibt einen pandas-DataFrame zurück, der die Zeilen aus dem ResultBatch-Objekt enthält.

Wenn keine Zeilen vorhanden sind, wird ein leerer pandas-DataFrame zurückgegeben.

Methoden¶

Keine.

Attribute¶

name¶

Name der Spalte

type_code¶

Interner Typcode.

display_size¶

Nicht verwendet. Wie „internal_size“.

internal_size¶

Interne Datengröße.

precision¶

Genauigkeit der numerischen Daten.

scale¶

Dezimalstellenzahl der numerischen Daten.

is_nullable¶

True, wenn NULL-Werte für die Spalte erlaubt sind, ansonsten False.

Enumerationen¶

class QueryStatus¶

Repräsentiert den Status einer asynchronen Abfrage. Diese Enumeration hat die folgenden Konstanten:

Enumerationskonstante	Beschreibung
RUNNING	Die Abfrage wird noch ausgeführt.
ABORTING	Die Abfrage wird auf Serverseite gerade abgebrochen.
SUCCESS	Die Abfrage wurde erfolgreich abgeschlossen.
FAILED_WITH_ERROR	Die Abfrage wurde erfolglos beendet.
QUEUED	Die Abfrage wartet in Warteschlange auf Ausführung, normalerweise weil sie auf Ressourcen wartet.
DISCONNECTED	Die Verbindung der Sitzung ist unterbrochen. Der Status der Abfrage wird bald in „FAILED_WITH_ERROR“ geändert.
RESUMING_WAREHOUSE	Das Warehouse wird gestartet, und die Abfrage wird noch nicht ausgeführt.
BLOCKED	Die Anweisung wartet auf eine Sperre, die von einer anderen Anweisung gehalten wird.
NO_DATA	Daten zur Anweisung sind noch nicht verfügbar, normalerweise, weil die Ausführung der Anweisung noch nicht begonnen hat.

Funktionen¶

write_pandas(parameters...)¶

Zweck:

Schreibt einen pandas-DataFrame in die Tabelle einer Snowflake-Datenbank.

Zum Schreiben der Daten in die Tabelle speichert die Funktion die Daten in Parquet-Dateien, lädt diese Dateien mit dem Befehl PUT in einen temporären Stagingbereich hoch und kopiert die Daten mit dem Befehl COPY INTO <Tabelle> aus den Dateien in die Tabelle. Mithilfe bestimmter Funktionsparameter können Sie steuern, wie die Anweisungen PUT und COPY INTO <Tabelle> ausgeführt werden.

Parameter:

Die gültigen Eingabeparameter sind:

Parameter	Erforderlich	Beschreibung
conn	Ja	Connection-Objekt, das die Verbindungsinformationen zur Snowflake-Datenbank enthält.
df	Ja	pandas.DataFrame-Objekt, das die Daten enthält, die in die Tabelle kopiert werden sollen.
table_name	Ja	Name der Tabelle, in die die Daten kopiert werden sollen.
database		Name der Datenbank, die die Tabelle enthält. Standardmäßig schreibt die Funktion Daten in die Datenbank, die in der aktuellen Sitzung verwendet wird. Hinweis: Wenn Sie diesen Parameter angeben, müssen Sie auch den Parameter schema angeben.
schema		Name des Schemas, das die Tabelle enthält. Standardmäßig schreibt die Funktion Daten in die Tabelle des Schemas, das in der aktuellen Sitzung verwendet wird.
chunk_size		Anzahl der Elemente, die gleichzeitig eingefügt werden sollen. Standardmäßig fügt die Funktion alle Elemente gleichzeitig in einen Block ein.
compression		Der für die Parquet-Dateien zu verwendende Komprimierungsalgorithmus. Sie können entweder "gzip" für eine bessere Komprimierung oder "snappy" für eine schnellere Komprimierung angeben. Standardmäßig verwendet die Funktion "gzip".
on_error		Gibt an, wie Fehler behandelt werden sollen. Setzen Sie den Parameter auf einen der Zeichenfolgenwerte, die in der ON_ERROR-Kopieroption dokumentiert sind. Standardmäßig verwendet die Funktion "ABORT_STATEMENT".
parallel		Anzahl der Threads, die beim Hochladen der Parquet-Dateien in den temporären Stagingbereich verwendet werden sollen. Weitere Informationen zur Standardanzahl der verwendeten Threads und zu den Richtlinien für die Auswahl der Threadanzahl finden Sie unter den Parallelitätsparametern des PUT-Befehls.
quote_identifiers		Wenn False, wird verhindert, dass der Konnektor doppelte Anführungszeichen um Bezeichner herum ausgibt, bevor die Bezeichner an den Server gesendet werden. Standardmäßig setzt der Konnektor doppelte Anführungszeichen um Bezeichner.

Rückgabewerte:

Gibt ein Tupel von (success, num_chunks, num_rows, output) zurück, wobei:

• success ist True, wenn die Funktion die Daten erfolgreich in die Tabelle geschrieben hat.

• num_chunks ist die Anzahl der Datenblöcke, die die Funktion kopiert hat.

• num_rows ist die Anzahl der Zeilen, die von der Funktion eingefügt wurden.

• output ist die Ausgabe des Befehls COPY INTO <Tabelle>.

Beispiel:

Im folgenden Beispiel werden die Daten von einem pandas-DataFrame in die Tabelle „customers“ geschrieben.

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

Zweck:

pd_writer ist eine Einfügemethode zum Einfügen von Daten in eine Snowflake-Datenbank.

Wenn Sie pandas.DataFrame.to_sql aufrufen (siehe pandas-Dokumentation), übergeben Sie method=pd_writer, um anzugeben, dass Sie pd_writer als Methode zum Einfügen von Daten verwenden möchten. (Sie müssen pd_writer nicht über Ihren eigenen Code aufrufen. Die Methode to_sql ruft pd_writer auf und übergibt die erforderlichen Eingabeparameter.)

Bemerkung

Beachten Sie, dass Sie die Spaltennamen in doppelten Anführungszeichen einschließen müssen, wenn die Spaltennamen im Pandas-DataFrame nur Kleinbuchstaben enthalten; andernfalls löst der Konnektor einen ProgrammingError aus.

Die Bibliothek snowflake-sqlalchemy schließt beim Erstellen einer Tabelle Spaltennamen in Kleinbuchstaben nicht in Anführungszeichen ein, während pd_writer Spaltennamen standardmäßig in Anführungszeichen setzt. Das Problem tritt auf, weil der COPY INTO-Befehl erwartet, dass Spaltennamen in Anführungszeichen gesetzt werden.

An der Bibliothek snowflake-sqlalchemy sind Verbesserungen geplant.

Beispiel:

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

Die Funktion pd_writer verwendet die Funktion write_pandas(), um die Daten aus dem DataFrame in die Snowflake-Datenbank zu schreiben.

Parameter:

Die gültigen Eingabeparameter sind:

Parameter	Erforderlich	Beschreibung
table	Ja	pandas.io.sql.SQLTable-Objekt für die Tabelle.
conn	Ja	sqlalchemy.engine.Engine- oder sqlalchemy.engine.Connection-Objekt, das die Verbindungsinformationen zur Snowflake-Datenbank enthält.
keys	Ja	Namen der Tabellenspalten für die einzufügenden Daten.
data_iter	Ja	Iterator für die Zeilen mit den einzufügenden Daten.

Beispiel:

Im folgenden Beispiel wird method=pd_writer an die Methode pandas.DataFrame.to_sql übergeben, die wiederum die Funktion pd_writer aufruft, um die Daten aus dem pandas-DataFrame in eine Snowflake-Datenbank zu schreiben.

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

Abrufen von Daten¶

Beim Abrufen von Datums- und Uhrzeitdaten werden die Snowflake-Datentypen in Python-Datentypen umgewandelt:

Aktualisieren von Daten¶

Beim Aktualisieren von Datums- und Uhrzeitdaten werden die Python-Datentypen in Snowflake-Datentypen umgewandelt: