Python-Konnektor-API

Der Snowflake-Konnektor für Python implementiert die Spezifikation der Python Database API v2.0 (PEP-249). Unter diesem Thema werden die Standard-API und die Snowflake-spezifischen Erweiterungen behandelt.

Unter diesem Thema:

Modul: snowflake.connector

Das Hauptmodul ist snowflake.connector, das ein Connection-Objekt erstellt und Error-Klassen bereitstellt.

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

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

Name Ihres Kontos (bereitgestellt von Snowflake). Weitere Details dazu finden Sie unter Nutzungshinweise (unter diesem Thema).

user

Ja

Anmeldename des Benutzers.

password

Ja

Kennwort für den Benutzer.

region

Veraltet – Geben Sie die Region stattdessen als Teil des account-Parameters an. 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.

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

Standardmäßig False. Stellen Sie dies auf True ein, um die Sitzung auf unbestimmte Zeit aktiv zu halten, auch wenn es keine Aktivität des Benutzers gibt. Stellen Sie sicher, dass Sie die close-Methode aufrufen, um den Thread ordnungsgemäß zu beenden, da sonst der Prozess hängen bleiben kann.

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%\AppData\Local\Snowflake\Caches\ocsp_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 to authenticate using your web browser and Okta, ADFS, or any other SAML 2.0-compliant identity provider (IdP) that has been defined for your account.

  • https://<Ihr_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.

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.

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)

  • Der Parameter gibt das Snowflake-Konto an, zu dem Sie eine Verbindung herstellen. Diese Angabe ist erforderlich.

  • Fügen Sie nicht den Snowflake-Domänennamen (snowflakecomputing.com) als Teil des Parameters ein. Snowflake hängt den Domänennamen automatisch an Ihren Kontonamen an, um die angeforderte Verbindung herzustellen.

  • Ihr vollständiger Kontoname kann möglicherweise zusätzliche Segmente enthalten, die die Region und die Cloudplattform angeben, wo Ihr Konto gehostet wird.

    Beispiele für Kontonamen nach Region

    Wenn Ihr Kontoname beispielsweise xy12345 ist:

    Cloudplattform/Region

    Vollständiger Kontoname

    AWS

    US West (Oregon)

    xy12345

    US East (Ohio)

    xy12345.us-east-2.aws

    US East (N. Virginia)

    xy12345.us-east-1

    US East (Commercial Gov - N. Virginia)

    xy12345.us-east-1-gov.aws

    Canada (Central)

    xy12345.ca-central-1.aws

    EU (Irland)

    xy12345.eu-west-1

    EU (Frankfurt)

    xy12345.eu-central-1

    Asia Pacific (Tokio)

    xy12345.ap-northeast-1.aws

    Asia Pacific (Mumbai)

    xy12345.ap-south-1.aws

    Asia Pacific (Singapur)

    xy12345.ap-southeast-1

    Asia Pacific (Sydney)

    xy12345.ap-southeast-2

    GCP

    US Central1 (Iowa)

    xy12345.us-central1.gcp

    Europe West2 (London)

    xy12345.europe-west2.gcp

    Europe West4 (Niederlande)

    xy12345.europe-west4.gcp

    Azure

    West US 2 (Washington)

    xy12345.west-us-2.azure

    East US 2 (Virginia)

    xy12345.east-us-2.azure

    US Gov Virginia

    xy12345.us-gov-virginia.azure

    Canada Central (Toronto)

    xy12345.canada-central.azure

    West Europe (Niederlande)

    xy12345.west-europe.azure

    Switzerland North (Zürich)

    xy12345.switzerland-north.azure

    Southeast Asia (Singapur)

    xy12345.southeast-asia.azure

    Australia East (New South Wales)

    xy12345.australia-east.azure

    Wichtig

    Wenn eine der folgenden Bedingungen zutrifft, unterscheidet sich Ihr Kontoname von der oben beschriebenen Struktur:

    • Wenn Ihre Snowflake Edition VPS ist, wenden Sie sich an den Snowflake-Support, um Details zu Ihrem Kontonamen zu erhalten.

    • Wenn für Ihr Konto AWS PrivateLink aktiviert ist, muss der Kontoname ein zusätzliches privatelink-Segment enthalten. Weitere Details dazu finden Sie unter AWS PrivateLink & Snowflake.

Objekt: Connection

Ein Connection-Objekt enthält die Verbindungs- und Sitzungsinformationen, um die Datenbankverbindung aktiv zu halten. Wenn die Verbindung getrennt wird oder die Sitzung abläuft, schlagen alle nachfolgenden Operationen fehl.

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

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)

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

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.

Attribute

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.

Objekt: Cursor

Ein Cursor-Objekt stellt einen Datenbankcursor für Ausführungs- und Abrufoperationen dar. Jeder Cursor hat seine eigenen Attribute, description und rowcount, sodass die Cursors isoliert sind.

Methoden

close()
Zweck

Schließt das Cursorobjekt.

execute(operation[, parameters])
Zweck

Bereitet eine Datenbankoperation vor und führt diese aus (z. B. Abfrage oder Befehl).

Parameter

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

parameters: Die optionalen Parameter können als Liste oder Wörterbuch bereitgestellt werden und werden in der Operation an Variablen gebunden. Weitere Informationen zum Binden finden Sie unter Binden von Daten. Weitere Informationen darüber, welche Python-Datentypen welchen SQL-Datentypen zugeordnet sind, finden Sie unter Datentyp-Zuordnungen für qmark- und numeric-Bindungen.

Rückgabewerte

Gibt die Referenz eines Cursor-Objekts zurück.

executemany(operation, seq_of_parameters)
Zweck

Bereitet eine Datenbankoperation vor und führt sie für alle in seq_of_parameters gefundenen Parametersequenzen aus.

Parameter

operation

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

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

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.

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 ein DataFrame zurück, das 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()

# ...
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 abgerufen werden müssen.

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

# ...
__iter__()

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

Attribute

description

Nur-Lese-Attribut, das eine Folge von 7 Werten zurückgibt:

Wert

Beschreibung

name

Spaltenname.

type_code

Interner Typcode.

display_size

(Nicht verwendet. Wie „internal_size“.)

internal_size

Interne Datengröße.

precision

Genauigkeit der numerischen Daten.

scale

Skala für numerische Daten.

null_ok

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

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

Das Cursor.description-Attribut gibt die Spaltenmetadaten zurück. type_code präsentiert den Spaltendatentyp und verwendet die folgende Zuordnung, um die Zeichenfolgendarstellung zu erhalten:

type_code

Zeichenfolgendarstellung

Datentyp

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

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:

Python-Datentyp

Datentyp in Snowflake

int

NUMBER(38, 0)

long

NUMBER(38, 0)

decimal

NUMBER(38, <Skalierung>)

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

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.

Objekt: Exception

In PEP-249 sind die Ausnahmen definiert, die der Snowflake-Konnektor für Python im Falle von Fehlern oder Warnungen auslösen kann. Die Anwendung muss korrekt reagieren und entscheiden, ob die Codeausführung fortgesetzt oder abgebrochen wird.

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.

Modul: snowflake.connector.pandas_tools

Das Modul snowflake.connector.pandas_tools bietet Funktionen für die Arbeit mit der Pandas-Datenanalysebibliothek.

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.

Rückgabewerte

Gibt ein Tupel von (Erfolg, Anzahl_der_Blöcke, Anzahl_der_Zeilen, Ausgabe) zurück, wobei:

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

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

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

  • Ausgabe 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')
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, ü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.)

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)

Unterstützung von Datums- und Zeitstempel

Snowflake unterstützt mehrere DATE- und TIMESTAMP-Datentypen, und der Snowflake-Konnektor ermöglicht das Binden von nativen datetime- und date-Objekten für Aktualisierungs- und Abrufoperationen.

Abrufen von Daten

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

Snowflake-Datentypen

Python-Datentyp

Verhalten

TIMESTAMP_TZ

datetime mit tzinfo

Ruft Daten ab, einschließlich Zeitzonenoffset, und übersetzt sie in ein datetime-mit-tzinfo-Objekt.

TIMESTAMP_LTZ, TIMESTAMP

datetime mit tzinfo

Ruft Daten ab, übersetzt sie in ein datetime-Objekt und hängt tzinfo basierend auf dem Sitzungsparameter TIMESTAMP_TYPE_MAPPING an.

TIMESTAMP_NTZ

datetime

Ruft Daten ab und übersetzt sie in ein datetime-Objekt. Dem Objekt sind keine Zeitzoneninformationen zugeordnet.

DATE

date

Ruft Daten ab und übersetzt sie in ein date-Objekt. Dem Objekt sind keine Zeitzoneninformationen zugeordnet.

Bemerkung

tzinfo ist ein auf der UTC-Abweichung basierendes Zeitzonenobjekt ohne IANA-Zeitzonennamen. Die Zeitzonennamen stimmen möglicherweise nicht überein, aber gleichwertige, abweichungsbasierte Zeitzonenobjekte gelten als identisch.

Aktualisieren von Daten

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

Python-Datentyp

Snowflake-Datentypen

Verhalten

datetime

TIMESTAMP_TZ, TIMESTAMP_LTZ, TIMESTAMP_NTZ, DATE

Konvertiert ein datetime-Objekt in eine Zeichenfolge im Format YYYY-MM-DD HH24:MI:SS.FF TZH:TZM und aktualisiert diese. Wenn kein Zeitzonenoffset angegeben ist, hat die Zeichenfolge das Format YYYY-MM-DD HH24:MI:SS.FF. Der Benutzer ist dafür verantwortlich, tzinfo für das datetime-Objekt einzustellen.

struct_time

TIMESTAMP_TZ, TIMESTAMP_LTZ, TIMESTAMP_NTZ, DATE

Konvertiert ein struct_time-Objekt in eine Zeichenfolge im Format YYYY-MM-DD HH24:MI:SS.FF TZH:TZM und aktualisiert diese. Die Zeitzoneninformationen werden über time.timezone abgerufen, was die UTC-Zeitzonenoffset beinhaltet. Der Benutzer ist dafür verantwortlich, die Umgebungsvariable TZ für time.timezone festzulegen.

date

TIMESTAMP_TZ, TIMESTAMP_LTZ, TIMESTAMP_NTZ, DATE

Konvertiert ein Datumsobjekt in eine Zeichenfolge im Format YYYY-MM-DD. Es wird keine Zeitzone berücksichtigt.

time

TIMESTAMP_TZ, TIMESTAMP_LTZ, TIMESTAMP_NTZ, DATE

Wandelt ein Zeitobjekt in eine Zeichenfolge im Format HH24:MI:SS.FF um. Es wird keine Zeitzone berücksichtigt.

timedelta

TIMESTAMP_TZ, TIMESTAMP_LTZ, TIMESTAMP_NTZ, DATE

Konvertiert ein Timedelta-Objekt in eine Zeichenfolge im Format HH24:MI:SS.FF. Es wird keine Zeitzone berücksichtigt.