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

String[]

Formatiert die Elemente des Arrays als Zeichenfolgen.

ARRAY

String

Formatiert das Array als JSON-Zeichenfolge (z. B. [1, "foo", null]).

BINARY

byte[]

BINARY

String

Kodiert die binäre Zeichenfolge in hexadezimale Form. 4

BINARY

InputStream

Gibt den BINARY-Wert als eine Sequenz von Bytes aus.

BOOLEAN

boolean

Darf nicht null sein.

BOOLEAN

Boolean

BOOLEAN

String

4

DATE

java.sql.Date

DATE

String

Formatiert das Datum als YYYY-MM-DD. 4

FLOAT

double

Darf nicht null sein.

FLOAT

Double

FLOAT

float

Darf nicht null sein. Kann zu Genauigkeitsverlust führen.

FLOAT

Float

Kann zu Genauigkeitsverlust führen.

FLOAT

String

Kann zu Genauigkeitsverlust führen (float -> string-Konvertierung ist verlustbehaftet).

GEOGRAPHY

String

Formatiert das Geography-Element als GeoJSON.

GEOGRAPHY

Geography

5

NUMBER

short

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

Short

Muss in den Bereich von short passen (ohne Bruchteil, und ganzzahliger Teil darf die max/min-Werte von short nicht überschreiten).

NUMBER

int

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

Integer

Muss in den Bereich von int passen (ohne Bruchteil, und ganzzahliger Teil darf die max/min-Werte von int nicht überschreiten).

NUMBER

long

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

Long

Muss in den Bereich von long passen (ohne Bruchteil, und ganzzahliger Teil darf die max/min-Werte von long nicht überschreiten).

NUMBER

java.math.BigDecimal

NUMBER

java.math.BigInteger

Muss in den Bereich von BigInteger passen (ohne Bruchteil).

NUMBER

String

OBJECT

Map<Zeichenfolge, Zeichenfolge>

Die Schlüssel der Zuordnung (Map) sind die Schlüssel des Objekts, und die Werte sind als Zeichenfolgen formatiert.

OBJECT

String

Formatiert das Objekt als JSON-Zeichenfolge (z. B. {"x": 3, "y": true}).

TIME

java.sql.Time

3

TIME

String

Formatiert die Uhrzeit als HH:MI:SS.SSSSSSSSS, wobei der Sekundenbruchteil von der Genauigkeit der Uhrzeit abhängt. 3

TIMESTAMP_LTZ

java.sql.Timestamp

Muss in den Bereich von java.sql.Timestamp passen. 3

TIMESTAMP_LTZ

String

Das Ausgabeformat ist DY, DD MON YYYY HH24:MI:SS TZHTZM. 1, 3, 4

TIMESTAMP_NTZ

java.sql.Timestamp

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

String

Behandelt die Gesamtbetrachtungszeit (Wall Clock Time) als Versatz von der Unix-Epoche (erzwingt effektiv eine UTC-Zeitzone). Das Ausgabeformat ist DY, DD MON YYYY HH:MI:SS. 2, 3, 4

TIMESTAMP_TZ

java.sql.Timestamp

Muss in den Bereich von java.sql.Timestamp passen. 3

TIMESTAMP_TZ

String

Das Ausgabeformat ist DY, DD MON YYYY HH24:MI:SS TZHTZM. 1, 3, 4

VARCHAR

String

VARIANT

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.
1(1,2)

Das Format stimmt mit dem Internet (RFC)-Zeitstempelformat DY, DD MON YYYY HH24:MI:SS TZHTZM überein, wie unter Zeitstempelformate beschrieben. Wenn ein Zeitzonenversatz (die TZHTZM-Komponente) vorhanden ist, handelt es sich in der Regel um Ziffern (z. B. steht -0700 für 7 Stunden hinter UTC). Wenn der Zeitzonenversatz Z (für „Zulu“) anstelle von Ziffern angegeben wird, ist das gleichbedeutend mit „+0000“ (UTC).

2

Das Format stimmt mit dem Internet (RFC)-Zeitstempelformat DY, DD MON YYYY HH24:MI:SS überein, wie unter Zeitstempelformate beschrieben. Wenn auf die Zeichenfolge ein Leerzeichen und Z (für „Zulu“) folgt, wird der Versatz explizit mit „0000“ (UTC) angegeben.

3(1,2,3,4,5,6,7,8)

Obwohl Snowflake Zeitwerte mit Nanosekundengenauigkeit speichern kann, bietet die java.sql.time-Bibliothek nur Millisekundengenauigkeit. Die Konvertierung zwischen Snowflake- und Java-Datentypen kann die effektive Genauigkeit auf Millisekunden reduzieren.

4(1,2,3,4,5,6)

Diese Typzuordnung wird bei der Konvertierung von SQL-Argumenten nach Java unterstützt, aber nicht bei der Konvertierung von Java-Rückgabetypen in SQL-Typen.

5

Java verfügt nicht über einen eigenen Datentyp für geographische Daten. Der Geography-Datentyp, auf den hier Bezug genommen wird, ist eine Klasse im Snowpark-Paket. Weitere Informationen dazu finden Sie unter Unterstützte Snowpark-Pakettypen für benutzerdefinierte Funktionen.

Arrays

Java-UDFs können Arrays von jedem der folgenden Java-Datentypen erhalten:

Datentyp

Anmerkungen

String

boolean

Das Snowflake-ARRAY darf nur BOOLEAN-Elemente enthalten und darf keine NULL-Werte enthalten.

double

float

Das Snowflake-ARRAY darf nur Elemente eines der folgenden Typen enthalten und darf keine NULL-Werte enthalten.

int

long

short

Das Snowflake-ARRAY darf nur Festkomma-Elemente mit einer Skalierung 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

Geography

1.2.0 oder höher

Repräsentiert den GEOGRAPHY-Typ von Snowflake. Ein Beispiel für die Verwendung des Datentyps Geography finden Sie unter Übergeben eines GEOGRAPHY-Werts an eine Inline-Java-UDF.

Variant

1.4.0 oder höher

Stellt Snowflake-VARIANT-Daten dar. Ein Beispiel für die Verwendung des Datentyps Variant finden Sie unter Übergeben eines VARIANT-Werts an eine Inline-Java-UDF.

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

JSON

BOOLEAN

boolean

DATE

date

REAL, FLOAT, FLOAT8, FLOAT4, DOUBLE, DOUBLE PRECISION

number

TIME

string

TIMESTAMP, TIMESTAMP_LTZ, TIMESTAMP_NTZ, TIMESTAMP_TZ

date oder SfDate

Wenn ein Zeitstempel als Argument an eine gespeicherte Prozedur übergeben wird, wird dieser Zeitstempel in ein JavaScript-date-Objekt konvertiert. In anderen Fällen (z. B. beim Abrufen von ResultSet) wird ein Zeitstempel in ein SfDate-Objekt konvertiert. Weitere Informationen zum Datentyp SfDate, der kein standardmäßiger JavaScript-Datentyp ist, finden Sie unter API für gespeicherte Prozeduren in JavaScript.

VARCHAR, CHAR, CHARACTER, STRING, TEXT

string

VARIANT

JSON

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:

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

list

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

bytes

BOOLEAN

bool

DATE

datetime.date

FLOAT

float

Bei Gleitkommaoperationen können kleine Rundungsfehler auftreten, die sich summieren, insbesondere wenn Aggregatfunktionen 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

dict

Formatiert den Geography-Typ in GeoJSON und wandelt ihn dann in Python-Typ dict um.

NUMBER

int oder decimal.Decimal

Wenn die Skalierung des NUMBER-Typs 0 ist, wird der Python-Typ int verwendet. Andernfalls wird der Typ decimal.Decimal verwendet.

OBJECT

dict

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

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

datetime.datetime

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

datetime.datetime

Direkte Konvertierung in „naive“ datetime. Erfordert „naive“ datetime als Rückgabetyp.

TIMESTAMP_TZ

datetime.datetime

Konvertierung in „aware“ datetime mit Zeitzoneninformation. Erfordert „aware“ datetime als Rückgabetyp.

VARCHAR

str

VARIANT

dict, list, int, float, str oder bool

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

Array[String]

BINARY

Array[Byte]

BOOLEAN

Boolean oder Option[Boolean]

DOUBLE

Double oder Option[Double]

FLOAT

Float oder Option[Float]

NUMBER

Die folgenden Typen werden unterstützt:

  • Int oder Option[Int]

  • Long oder Option[Long]

OBJECT

Map[String, String]

VARCHAR

String

VARIANT

String

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.

Sprache: Deutsch