Zuordnung von Datentypen zwischen SQL und Handler-Sprachen¶
Unter diesem Thema:
Eine von Ihnen geschriebene gespeicherte Prozedur oder benutzerdefinierte Funktion wird über SQL aufgerufen, sodass Werte in SQL-Datentypen empfangen und zurückgegeben werden. Der zugrunde liegende Handler verwendet jedoch Datentypen aus der Sprache des Handlers, z. B. Java, Python oder Scala. Zur Laufzeit konvertiert Snowflake Argument- und Rückgabewerte zwischen den SQL-Typen und den Handler-Typen.
Beachten Sie, dass Snowflake diese Konvertierungen auch in den folgenden Fällen vornimmt:
Beim dynamischen Erstellen einer SQL-Anweisung, die einen Wert in einer Handler-Variable verwendet.
Beim Binden des Werts einer Handler-Variablen an eine vorbereitete Anweisung.
Unter diesem Thema werden gültige Zuordnungen zwischen SQL-Datentypen und denen der unterstützten Handler-Sprachen beschrieben. Verwenden Sie diesen Inhalt, um beim Schreiben eines Handlers Datentypen auszuwählen.
Weitere Informationen zu Snowflake SQL-Datentypen finden Sie unter Zusammenfassung der Datentypen.
Zuordnung von Datentypen zwischen SQL und Java¶
Die folgende Tabelle zeigt die Typzuordnungen zwischen SQL und Java. Diese Zuordnungen gelten im Allgemeinen sowohl für die Argumente, die an die Prozedur oder Funktion übergeben werden, als auch für die Werte, die zurückgegeben werden. Es gibt jedoch einige Ausnahmen, die in Fußnoten ausgeführt werden.
Beachten Sie, dass einige SQL-Datentypen (z. B. NUMBER) mit mehreren Java-Datentypen kompatibel sind (z. B. int
, long
). In diesen Fällen können Sie einen beliebigen Java-Datentyp verwenden, der genügend Kapazität hat, um die tatsächlich zu übergebenden Werte aufzunehmen. Wenn Sie einen SQL-Wert an einen inkompatiblen Java-Datentyp übergeben (oder umgekehrt), gibt Snowflake einen Fehler aus.
SQL-Typ |
Java-Typ |
Anmerkungen |
---|---|---|
ARRAY |
|
Formatiert die Elemente des Arrays als Zeichenfolgen. |
ARRAY |
|
Formatiert das Array als JSON-Zeichenfolge (z. B. |
BINARY |
|
|
BINARY |
|
Kodiert die binäre Zeichenfolge in hexadezimale Form. [4] |
BINARY |
|
Gibt den BINARY-Wert als eine Sequenz von Bytes aus. |
BOOLEAN |
|
Darf nicht null sein. |
BOOLEAN |
|
|
BOOLEAN |
|
|
DATE |
|
|
DATE |
|
Formatiert das Datum als |
FLOAT |
|
Darf nicht null sein. |
FLOAT |
|
|
FLOAT |
|
Darf nicht null sein. Kann zu Genauigkeitsverlust führen. |
FLOAT |
|
Kann zu Genauigkeitsverlust führen. |
FLOAT |
|
Kann zu Genauigkeitsverlust führen (float -> string-Konvertierung ist verlustbehaftet). |
GEOGRAPHY |
|
Formatiert das Geography-Element als GeoJSON. |
GEOGRAPHY |
||
NUMBER |
|
Darf nicht null sein. Muss in den Bereich von short passen (ohne Bruchteil, und ganzzahliger Teil darf die max/min-Werte von short nicht überschreiten). |
NUMBER |
|
Muss in den Bereich von short passen (ohne Bruchteil, und ganzzahliger Teil darf die max/min-Werte von short nicht überschreiten). |
NUMBER |
|
Darf nicht null sein. Muss in den Bereich von int passen (ohne Bruchteil, und ganzzahliger Teil darf die max/min-Werte von int nicht überschreiten). |
NUMBER |
|
Muss in den Bereich von int passen (ohne Bruchteil, und ganzzahliger Teil darf die max/min-Werte von int nicht überschreiten). |
NUMBER |
|
Darf nicht null sein. Muss in den Bereich von long passen (ohne Bruchteil, und ganzzahliger Teil darf die max/min-Werte von long nicht überschreiten). |
NUMBER |
|
Muss in den Bereich von long passen (ohne Bruchteil, und ganzzahliger Teil darf die max/min-Werte von long nicht überschreiten). |
NUMBER |
|
|
NUMBER |
|
Muss in den Bereich von BigInteger passen (ohne Bruchteil). |
NUMBER |
|
|
OBJECT |
|
Die Schlüssel der Zuordnung (Map) sind die Schlüssel des Objekts, und die Werte sind als Zeichenfolgen formatiert. |
OBJECT |
|
Formatiert das Objekt als JSON-Zeichenfolge (z. B. |
TIME |
|
|
TIME |
|
Formatiert die Uhrzeit als |
TIMESTAMP_LTZ |
|
Muss in den Bereich von java.sql.Timestamp passen. [3] |
TIMESTAMP_LTZ |
|
Das Ausgabeformat ist |
TIMESTAMP_NTZ |
|
Muss in den Bereich von java.sql.Timestamp passen. Behandelt die Gesamtbetrachtungszeit (Wall Clock Time) als Versatz von der Unix-Epoche (erzwingt effektiv eine UTC-Zeitzone). [3] |
TIMESTAMP_NTZ |
|
Behandelt die Gesamtbetrachtungszeit (Wall Clock Time) als Versatz von der Unix-Epoche (erzwingt effektiv eine UTC-Zeitzone). Das Ausgabeformat ist |
TIMESTAMP_TZ |
|
Muss in den Bereich von java.sql.Timestamp passen. [3] |
TIMESTAMP_TZ |
|
Das Ausgabeformat ist |
VARCHAR |
|
|
VARIANT |
Der Datentyp Variant ist eine Klasse im Snowpark-Paket. Weitere Informationen dazu finden Sie unter Unterstützte Snowpark-Pakettypen für benutzerdefinierte Funktionen. Ein Beispiel dazu finden Sie unter Übergeben eines VARIANT-Werts an eine Inline-Java-UDF. |
Arrays¶
Java-UDFs können Arrays von jedem der folgenden Java-Datentypen erhalten:
Datentyp |
Anmerkungen |
---|---|
|
|
|
Das Snowflake-ARRAY darf nur BOOLEAN-Elemente enthalten und darf keine NULL-Werte enthalten. |
|
Das Snowflake-ARRAY darf nur Elemente eines der folgenden Typen enthalten und darf keine NULL-Werte enthalten. |
|
Das Snowflake-ARRAY darf nur Festkomma-Elemente mit einer Dezimalstellenzahl von 0 enthalten und darf keine NULL-Werte enthalten. |
NULL-Werte¶
Snowflake unterstützt zwei verschiedene NULL-Werte: SQL NULL
und VARIANT JSON null
. (Weitere Informationen zu Snowflake VARIANT NULL finden Sie unter NULL-Werte.)
Java unterstützt einen null
-Wert, der nur für nicht primitive Datentypen gilt.
Ein SQL-NULL
-Argument für einen Java-Handler wird in den Java-null
-Wert umgewandelt, aber nur für Java-Datentypen, die null
unterstützen.
Ein zurückgegebener Java null
-Wert wird in SQL NULL
zurückübersetzt.
TIMESTAMP_LTZ-Werte und Zeitzonen¶
Ein Java-UDF ist weitgehend isoliert von der Umgebung, in der sie aufgerufen wird. Die Zeitzone wird jedoch von der aufrufenden Umgebung geerbt. Wenn die Sitzung des Aufrufers vor dem Aufruf der Java-UDF eine Standardzeitzone eingestellt hat, dann hat die Java-UDF die gleiche Standardzeitzone. Die Java-UDF verwendet dieselben Daten der IANA-Zeitzonendatenbank, die auch von der nativen TIMEZONE-Funktion in Snowflake SQL verwendet wird (d. h. Daten aus Release 2021a der Zeitzonendatenbank).
Unterstützte Snowpark-Pakettypen für benutzerdefinierte Funktionen¶
In einer benutzerdefinierten Funktion können Sie eine bestimmte Teilmenge von Typen verwenden, die im Snowpark-Java-Paket von Snowflake enthalten sind. Obwohl diese Typen für die Verwendung im Snowpark-Code gedacht sind, können einige davon auch in UDFs verwendet werden, da sie großen praktischen Wert haben. (Weitere Informationen zu Snowpark finden Sie in der Snowpark-Dokumentation).
Bemerkung
Die Snowpark-Bibliothek ist eine Voraussetzung für gespeicherte Prozeduren, die in Java, Python oder Scala geschrieben wurden. Daher können Sie die Snowpark-Typen dort ohne Einschränkungen nutzen.
Die in der folgenden Tabelle aufgeführten Snowpark-Typen werden im UDF-Code unterstützt. Sie können keine anderen Snowpark-Typen in UDF-Code verwenden, da diese dort nicht unterstützt werden.
Snowpark-Typ |
Erforderliche Snowpark-Version |
Beschreibung |
---|---|---|
1.2.0 oder höher |
Repräsentiert den GEOGRAPHY-Typ von Snowflake. Ein Beispiel für die Verwendung des Datentyps |
|
1.4.0 oder höher |
Stellt Snowflake-VARIANT-Daten dar. Ein Beispiel für die Verwendung des Datentyps |
Angeben des Snowpark-Pakets als Abhängigkeit¶
Wenn Sie UDF-Code entwickeln, der das Snowpark-Paket verwendet, müssen Sie Ihre Entwicklungsumgebung so einrichten, dass Sie Code mit Snowpark-Abhängigkeiten kompilieren und ausführen können. Weitere Informationen dazu finden Sie unter Einrichten anderer Entwicklungsumgebungen für Snowpark Java.
Bei der Bereitstellung einer UDF durch Ausführen der CREATE FUNCTION-Anweisung können Sie das Snowpark-Paket als Abhängigkeit angeben, ohne die JAR-Datei in einen Stagingbereich hochladen zu müssen (die Bibliothek ist bereits in Snowflake enthalten). Dazu geben Sie in der PACKAGES
-Klausel den Paketnamen und die Version an. Ein Syntaxbeispiel finden Sie unter Übergeben eines GEOGRAPHY-Werts an eine Inline-Java-UDF.
Zuordnung von Datentypen zwischen SQL und JavaScript¶
Die folgende Tabelle enthält die Snowflake SQL-Datentypen sowie die entsprechenden JavaScript-Datentypen:
SQL-Datentyp |
JavaScript-Datentyp |
Anmerkungen |
---|---|---|
ARRAY |
|
|
BOOLEAN |
|
|
DATE |
|
|
GEOGRAPHY, GEOMETRY |
|
|
REAL, FLOAT, FLOAT8, FLOAT4, DOUBLE, DOUBLE PRECISION |
|
|
TIME |
|
|
TIMESTAMP, TIMESTAMP_LTZ, TIMESTAMP_NTZ, TIMESTAMP_TZ |
|
Wenn ein Zeitstempel als Argument an eine gespeicherte Prozedur übergeben wird, wird dieser Zeitstempel in ein JavaScript- |
VARCHAR, CHAR, CHARACTER, STRING, TEXT |
|
|
VARIANT |
|
Anmerkungen¶
Nicht alle Snowflake SQL-Datentypen haben einen entsprechenden JavaScript-Datentyp. Beispielsweise unterstützt JavaScript die Datentypen INTEGER oder NUMBER nicht direkt. In diesen Fällen sollten Sie den SQL-Datentyp in einen geeigneten alternativen Datentyp konvertieren. Beispielsweise können Sie einen SQL INTEGER- in einen SQL FLOAT-Wert konvertieren, der sich dann in einen JavaScript-Wert vom Datentyp number
konvertieren lässt.
In der folgenden Tabelle werden entsprechende Konvertierungen für die inkompatiblen SQL-Datentypen angezeigt:
Inkompatibler SQL-Datentyp |
Kompatibler SQL-Datentyp |
---|---|
BINARY |
Uint8Array |
INTEGER |
FLOAT |
NUMBER, NUMERIC, DECIMAL |
FLOAT |
OBJECT |
Uint8Array |
Bei der Rückgabe von Werten¶
Wenn die return
-Anweisung in JavaScript einen Datentyp zurückgibt, der sich vom deklarierten Rückgabetyp der gespeicherten Prozedur unterscheidet, wird der JavaScript-Wert nach Möglichkeit in den Datentyp SQL umgewandelt. Wenn beispielsweise eine Zahl zurückgegeben wird, in der gespeicherten Prozedur jedoch eine Zeichenfolge als Rückgabewert deklariert ist, wird die Zahl innerhalb von JavaScript in eine Zeichenfolge konvertiert und dann in die in der SQL-Anweisung zurückgegebene Zeichenfolge kopiert. (Beachten Sie, dass bestimmte JavaScript-Programmierfehler, z. B. das Zurückgeben des falschen Typs, durch dieses Verhalten verborgen werden können.)
Wenn keine gültige Umwandlung für die Konvertierung vorhanden ist, tritt ein Fehler auf.
Beim Binden von Werten¶
Wenn Sie JavaScript-Variablen an SQL-Anweisungen binden, führt Snowflake eine Konvertierung von JavaScript-Datentypen in SQL-Datentypen durch. Sie können Variablen der folgenden JavaScript-Datentypen binden:
number
string
SfDate
Weitere Informationen zum Datentyp
SfDate
, der kein standardmäßiger JavaScript-Datentyp ist, finden Sie unter API für gespeicherte Prozeduren in JavaScript.
Weitere Informationen zum Binden, einschließlich einiger Beispiele, finden Sie unter Binden von Variablen.
Möglicherweise sind auch folgende Themen hilfreich:
Zuordnung von Datentypen zwischen SQL und Python¶
Die folgende Tabelle zeigt die Typzuordnungen zwischen SQL und Python. Diese Zuordnungen gelten im Allgemeinen sowohl für die Argumente, die an den Python-Handler übergeben werden, als auch für die Werte, die von diesem zurückgegeben werden.
SQL-Typ |
Python-Typ |
Anmerkungen |
---|---|---|
ARRAY |
|
Wenn ein Python-Datentyp in einen ARRAY-Wert konvertiert wird und eingebettete Python-Dezimaldaten vorliegen, werden die eingebetteten Python-Dezimalwerte im ARRAY-Wert in String-Werte (Zeichenfolgen) konvertiert. |
BINARY |
|
|
BOOLEAN |
|
|
DATE |
|
|
FLOAT |
|
Bei Gleitkommaoperationen können kleine Rundungsfehler auftreten, die sich summieren, insbesondere wenn Aggregationsfunktionen eine große Anzahl von Zeilen verarbeiten. Rundungsfehler können bei jeder Ausführung der Abfrage variieren, wenn die Zeilen in einer anderen Reihenfolge verarbeitet werden (z. B. bei unterschiedlicher Partitionierung in einem verteilten System). Weitere Informationen dazu finden Sie unter Numerische Datentypen: Gleitkomma. |
GEOGRAPHY, GEOMETRY |
|
Formatiert den Geography-Typ als GeoJSON und wandelt ihn dann in den Python-Typ dict um. |
NUMBER |
|
Wenn die Dezimalstellenzahl des NUMBER-Typs 0 ist, wird der Python-Typ int verwendet. Andernfalls wird der Typ decimal.Decimal verwendet. |
OBJECT |
|
Wenn ein Python-Datentyp in einen OBJECT-Wert konvertiert wird und eingebettete Python-Dezimaldaten vorliegen, werden die eingebetteten Python-Dezimalwerte im OBJECT-Wert in String-Werte (Zeichenfolgen) konvertiert. |
TIME |
|
Obwohl Snowflake Zeitwerte mit Nanosekundengenauigkeit speichern kann, bietet der Python-Typ datetime.time nur eine Genauigkeit im Millisekundenbereich. Die Konvertierung zwischen Snowflake- und Python-Datentypen kann die effektive Genauigkeit auf Millisekunden reduzieren. |
TIMESTAMP_LTZ |
|
Verwenden Sie die lokale Zeitzone, um die interne UTC-Zeit in die lokale „naive“ datetime-Zeit umzuwandeln. Erfordert „naive“ datetime als Rückgabetyp. |
TIMESTAMP_NTZ |
|
Direkte Konvertierung in „naive“ datetime. Erfordert „naive“ datetime als Rückgabetyp. |
TIMESTAMP_TZ |
|
Konvertierung in „aware“ datetime mit Zeitzoneninformation. Erfordert „aware“ datetime als Rückgabetyp. |
VARCHAR |
|
|
VARIANT |
|
Jede Variant-Zeile wird für Argumente dynamisch in einen Python-Typ konvertiert und umgekehrt für Rückgabewerte. Die folgenden Typen werden in Zeichenfolgen und nicht in native Python-Typen konvertiert: decimal, binary, date, time, timestamp_ltz, timestamp_ntz, timestamp_tz. Wenn ein Python-Datentyp in einen VARIANT-Wert konvertiert wird und eingebettete Python-Dezimaldaten vorliegen, werden die eingebetteten Python-Dezimalwerte im VARIANT-Wert in String-Werte (Zeichenfolgen) konvertiert. |
Zuordnung von Datentypen zwischen SQL und Scala¶
Snowflake unterstützt die folgenden Scala-Datentypen zusätzlich zu den unter Zuordnung von Datentypen zwischen SQL und Java aufgeführten Java-Typen:
SQL-Datentyp |
Scala-Typ |
Anmerkungen |
---|---|---|
ARRAY |
|
|
BINARY |
|
|
BOOLEAN |
|
|
DOUBLE |
|
|
FLOAT |
|
|
NUMBER |
Die folgenden Typen werden unterstützt:
|
|
OBJECT |
|
|
VARCHAR |
|
|
VARIANT |
|
Formatiert den Wert abhängig vom Typ, der dargestellt wird. Variante null wird als die Zeichenfolge „null“ formatiert. |
Für DATE und TIMESTAMP sind die unter Zuordnung von Datentypen zwischen SQL und Java aufgeführten Java-Typen zu verwenden.