API-Unterstützung für JDBC-Treiber¶

Methoden¶

Snowflake-spezifisches Verhalten¶

Keine.

Zusätzliche Methoden¶

getQueryID()¶

Zweck:

Diese Methode gibt die Snowflake-Abfrage-ID der zuletzt ausgeführten Abfrage von CallableStatement zurück. Wenn mit der aufrufbaren Anweisung noch keine Abfrage ausgeführt wurde, gibt die Methode null zurück.

Argumente:

Keine.

Rückgabewerte:

Diese Methode gibt die ID als Zeichenfolge (String) zurück, die eine UUID enthält. Informationen zu UUIDs finden Sie in der Beschreibung der SQL-Funktion UUID_STRING.

Auslöser:

Die Methode kann eine SQLException auslösen.

Methoden¶

Snowflake-spezifisches Verhalten¶

• close()

  Schließt die Verbindung. Nachdem ein Objekt geschlossen wurde, wird beim Aufrufen fast jeder Methode des geschlossenen Objekts eine SQLException ausgelöst. Das Aufrufen von close für ein bereits geschlossenes Objekt ist unproblematisch und löst keine Ausnahme aus.

• getMetaData()

  Hiermit erhalten Sie Metadaten zum JDBC-Treiber und zu Snowflake. Beispielsweise können Sie herausfinden, ob Transaktionen unterstützt werden.

  Weitere Informationen zu den Methoden, die Sie für den zurückgegebenen Wert aufrufen können, finden Sie unter Objekt: DatabaseMetaData.

• prepareStatement(String sql)

  Diese Methode gibt ein preparedStatement-Objekt zurück, mit dem die SQL-Anweisung ausgeführt werden kann. Die execute()-Methode des Objekts preparedStatement kann aufgerufen werden, um die Anweisung auszuführen. Die Anweisung kann unverändert oder nach Bindung von Werten an die Anweisung ausgeführt werden.

  Bemerkung

  In einigen Systemen kann diese Anweisung nach der Vorbereitung einer Anweisung wiederholt ausgeführt werden, ohne die Anweisung erneut zu kompilieren. Einmaliges Vorbereiten und wiederholtes Ausführen können Zeit und Ressourcen sparen.

  In Snowflake kompiliert prepareStatement() den Code nicht. Stattdessen kompilieren PreparedStatement.execute(), PreparedStatement.executeQuery() und PreparedStatement.executeUpdate() die Anweisung, und führen diese aus. Das Vorbereiten der Anweisung vor dem Ausführen spart daher keine Ressourcen im Vergleich zur einfachen Verwendung von Statement.execute().

• prepareCall(String sql)

• prepareCall(String sql, boolean)

• prepareCall(String sql, int, int)

• prepareCall(String sql, int, int, int)

  Wie in den meisten JDBC-Implementierungen können die prepareCall-Methoden verwendet werden, um Parameter an eine gespeicherte Prozedur zu binden. Zum Beispiel wird Folgendes unterstützt:

  CallableStatement stmt = testConnection.prepareCall("call read_result_set(?,?) ");
  

  Copy

  Im Snowflake-JDBC-Treiber unterstützen die Methoden prepareCall jedoch nicht die Syntax ? =, um die Bindung des Rückgabewerts einer gespeicherten Prozedur zu unterstützen. Folgendes wird beispielsweise nicht unterstützt:

  CallableStatement stmt = testConnection.prepareCall("? = call read_result_set() ");  -- INVALID
  

  Copy

Zusätzliche Methoden¶

Diese Methoden ergänzen die von der JDBC-Connection-Schnittstelle unterstützten Methoden.

public ResultSet createResultSet(String queryID)

Zweck:

Ruft die Abfrageergebnisse einer asynchron gestarteten SQL-Anweisung mithilfe der queryID ab und gibt diese Ergebnisse in einem ResultSet-Objekt zurück.

Diese Methode kann normalerweise bis zu 24 Stunden nach Abschluss der SQL-Anweisung aufgerufen werden.

Argumente:

queryID: Die Abfrage-ID der Abfrage, für die Sie die Ergebnisse wünschen.

Rückgabewerte:

Das ResultSet. Wenn die Abfrage noch nicht beendet ist, gibt der Server ein leeres ResultSet zurück. Der Benutzer kann resultSet.unwrap(SnowflakeResultSet.class).getStatus() aufrufen, um herauszufinden, wann die Daten verfügbar sind.

Auslöser:

Die Methode kann eine SQLException auslösen.

Anmerkungen:

Diese Methode ist eine Snowflake-Erweiterung des JDBC-Standards. Um diese Methode zu verwenden, müssen Sie das Connection-Objekt entpacken.

Beispiele:

ResultSet resultSet;
resultSet = connection.unwrap(SnowflakeConnection.class).createResultSet(queryID);

Copy

Unter Beispiele für asynchrone Abfragen finden Sie ein ausführlicheres Beispiel, das einen Aufruf dieser Methode enthält.

public InputStream downloadStream(String stageName, String sourceFileName, boolean decompress)

Zweck:

Diese Methode lädt eine Datei aus dem angegebenen internen Stagingbereich herunter und gibt einen Eingabestream zurück.

Argumente:

stageName: Name des Stagingbereichs.

sourceFileName: Dateipfad im Stagingbereich.

decompress: Ist „true“, wenn die Datei komprimiert ist.

Rückgabewerte:

Diese Methode gibt einen InputStream zurück.

Auslöser:

Diese Methode löst bei Auftreten eines SQL-Fehlers eine SQLException-Ausnahme aus.

Beispiele:

Ein unvollständiges Beispiel finden Sie unter Datendateien direkt von einem internen Stagingbereich in einen Stream herunterladen.

public String getSessionID()

Zweck:

Diese Methode gibt die Sitzungs-ID der aktuellen Sitzung zurück.

Argumente:

Keine

Rückgabewerte:

Gibt die Sitzungs-ID als Zeichenfolge (String) zurück.

Auslöser:

Diese Methode löst SQLException aus, wenn ein SQL-Fehler auftritt, z. B. wenn die Verbindung geschlossen wird.

Nutzungshinweise:

Da sich die Sitzungs-ID bei geöffneter Verbindung nicht ändert, wird die Sitzungs-ID lokal zwischengespeichert (und nicht jedes Mal vom Server abgerufen), um die Leistung zu verbessern.

public prepareStatement(String sql, Boolean skipParsing)

Diese Methode ist veraltet. Der Parameter skipParsing hat keine Auswirkungen mehr auf das Verhalten der Methode. Diese Methode verhält sich wie die prepareStatement(String sql)-Methode, unabhängig von der Einstellung des skipParsing-Parameters.

Neuer Code sollte die prepareStatement(String sql)-Methode verwenden.

Gegebenenfalls sollte vorhandener Code, der die Zwei-Argumente-Version dieser Methode verwendet, aktualisiert werden, um die Ein-Argument-Methode prepareStatement(String sql) zu verwenden.

public void uploadStream(String stageName, String destPrefix, InputStream inputStream, String destFileName, boolean compressData)

Zweck:

Diese Methode komprimiert Daten aus einem Stream und lädt sie an einen bestimmten Speicherort eines internen Stagingbereichs hoch. Die Daten werden als eine einzige Datei hochgeladen. Bei dieser Methode erfolgt keine Aufteilung.

Argumente:

stageName: Name des Stagingbereichs (z. B. ~ oder Tabellenname oder Stagingbereichsname).

destPrefix: Pfad/Präfix, unter dem die Daten in den Stagingbereich hochgeladen werden sollen.

inputStream: Eingabestream, von dem die Daten hochgeladen werden.

destFileName: Name der zu verwendenden Zieldatei.

compressData: Gibt an, ob Daten vor dem Hochladen des Streams komprimiert werden oder nicht.

Rückgabewerte:

Nichts.

Auslöser:

Diese Methode löst eine java.sql.SQLException aus, wenn die Komprimierung fehlgeschlagen ist und die Daten nicht aus einem Stream des Stagingbereichs übertragen werden konnten.

Anmerkungen:

Der Aufrufer ist dafür verantwortlich, den inputStream freizugeben, nachdem die Methode aufgerufen wurde.

Beispiele:

Ein unvollständiges Beispiel finden Sie unter Datendateien direkt von einem Stream in einen internen Stagingbereich hochladen.

Methoden¶

Snowflake-spezifisches Verhalten¶

public ResultSet getColumnPrivileges(String, String, String, String)

Diese Methode gibt immer ein leeres Set zurück, da Snowflake keine Berechtigungen auf Spaltenebene unterstützt.

public ResultSet getStreams(String, String, String)

Zweck:

Diese Methode gibt Informationen zu Streams zurück, die in den angegebenen Datenbanken und Schemas enthalten sind.

Argumente:

• originalCatalog: Name der Datenbank.

• orignalSchemaPattern: Muster zur Identifizierung des Schemas (unterstützt Platzhalter (Wildcards)).

• streamName: Name des Streams (unterstützt Platzhalter (Wildcards)).

Rückgabewerte:

Diese Methode gibt ein ResultSet mit Zeilen für jeden Stream zurück, wobei jede Zeile die folgenden Spalten enthält:

• name: Name des Streams.

• database_name: Name der Datenbank für das Schema, das den Stream enthält.

  Ein Datenbankobjekt (z. B. ein Stream) ist in einem Schema enthalten, das wiederum in einer Datenbank enthalten ist.

• schema_name: Name des Schemas, das den Stream enthält.

• owner: Rolle, der der Stream gehört.

• comment: Kommentare, die mit dem Stream verbundenen sind.

• table_name: Name der Tabelle, deren DML-Aktualisierungen vom Stream verfolgt werden.

• source_type: Quellobjekt des Streams. Mögliche Werte sind:

  • table

  • view

  • directory table

  • external table

• base_tables: Zugrunde liegende Tabellen der Ansicht. Diese Spalte gilt nur für Streams auf Ansichten.

• type: Typ des Streams. Die Funktion gibt immer einen DELTA-Wert zurück.

• stale: Gibt an, ob der Stream zuletzt vor dem Zeitpunkt stale_after gelesen wurde. Wenn TRUE, dann ist der Stream möglicherweise veraltet.

  Wenn ein Stream veraltet ist, kann er nicht gelesen werden. Sie können den Stream neu erstellen, um das Lesen aus dem Stream fortzusetzen. Um zu verhindern, dass ein Stream veraltet, müssen Sie den Stream vor Ablauf des stale_after-Zeitpunkts verarbeitet haben.

• mode: Typ des Streams. Mögliche Werte sind:

  • APPEND_ONLY: Gibt an, dass es sich bei dem Stream um einen Nur-Anfügen-Stream handelt.

  • INSERT_ONLY: Gibt an, dass der Stream nur Informationen zu eingefügte Zeilen zurückgibt. Dieser Wert gilt nur für Streams auf externen Tabellen.

  • DEFAULT: Gibt an, dass der Stream auf Tabellen ausgeführt wird.

Auslöser:

Diese Methode löst bei Auftreten eines SQL-Fehlers eine SQLException-Ausnahme aus.

Unterstützung von Nullparametern¶

Einige DatabaseMetaData-Methoden akzeptieren null-Werte für Datenbankobjektnamen (z. B. Tabellen-/Katalognamen). Standardmäßig bedeutet ein null-Wert, dass die Methode nicht nach diesem Argument filtert. Wenn Sie beispielsweise getColumns() einen null-Wert für das Argument schemaPattern übergeben, gibt getColumns() Werte für alle Schemas zurück.

Bei einigen dieser Methoden kann das Standardverhalten für null-Argumente mit den folgenden Parametern überschrieben werden:

• CLIENT_METADATA_REQUEST_USE_CONNECTION_CTX.

• CLIENT_METADATA_USE_SESSION_DATABASE.

Unterstützung von Platzhaltern in Datenbankobjektnamen¶

Einige DatabaseMetaData-Methoden unterstützen Platzhalter für Musterabgleich in Datenbankobjektnamen, z. B. Tabellen-/Katalognamen. Folgende Platzhalterzeichen werden unterstützt:

• %: Entspricht einer beliebigen Zeichenfolge mit null oder mehr Zeichen.

• _: Entspricht einem beliebigen Zeichen.

Das folgende Beispiel zeigt, was an die Methode getColumns() übergeben werden muss, um die Namen aller Tabellen und aller Spalten in der angegebenen Datenbank (TEMPORARYDB1) und im angegebenen Schema (TEMPORARYSCHEMA1) abzurufen:

getColumns( connection,
    "TEMPORARYDB1",      // Database name.
    "TEMPORARYSCHEMA1",  // Schema name.
    "%",                 // All table names.
    "%"                  // All column names.
    );

Es ist üblich, dass Datenbankobjektnamen wie Tabellennamen Unterstriche enthalten, z. B. SHIPPING_ADDRESSES. Wenn Sie nach SHIPPING_ADDRESSES suchen, ohne den Unterstrich zu umgehen, finden Sie natürlich nicht nur die Tabelle mit dem Namen SHIPPING_ADDRESSES, sondern auch Tabellen wie SHIPPING2ADDRESSES. Wenn Sie nach SHIPPING_ADDRESSES suchen möchten, aber nicht nach SHIPPING2ADDRESSES, müssen Sie das Platzhalterzeichen mit Escapezeichen versehen, um anzugeben, dass es als Literal behandelt werden soll. Stellen Sie dem Zeichen einen Backslash voran, um es zu maskieren.

Das Backslash-Zeichen selbst muss ebenfalls mit Escape-Zeichen versehen werden, wenn Sie es als Literalzeichen verwenden möchten. Um beispielsweise nach einer Tabelle mit dem Namen T_& zu suchen, in dem Unterstrich, kaufmännisches Und-Zeichen und Backslash literale Teile des Namens und keine Platzhalter- oder Escapezeichen sind, muss der Methodenaufruf wie folgt aussehen:

getColumns(
    connection, "TEMPORARYDB1", "TEMPORARYSCHEMA1", "T\\_\\\\", "%" // All column names.
    );

Jeder obige Backslash muss ein weiteres Mal maskiert werden, da der Java-Compiler erwartet, dass Backslashes maskiert werden:

Java sees...............: T\\_\\%\\\\
SQL sees................: T\_\%\\
The actual table name is: T_%\

Methoden¶

Snowflake-spezifisches Verhalten¶

Keine.

Beispiele¶

Der folgende Codeausschnitt zeigt einen Teil eines Programms zum Abrufen von Eigenschaftsinformationen:

  // Demonstrate the Driver.getPropertyInfo() method.
  public static void do_the_real_work(String connectionString) throws Exception {
    Properties properties = new Properties();
    Driver driver = DriverManager.getDriver(connectionString);
    DriverPropertyInfo[] dpinfo = driver.getPropertyInfo("", properties);
    System.out.println(dpinfo[0].description);
  }

Beachten Sie, dass sich der Aufruf dieser Methode im allgemeinen Fall innerhalb einer Schleife befinden sollte. Wenn Sie Informationen zu einer Eigenschaft abrufen und diese Eigenschaft dann festlegen, werden durch die neue Einstellung möglicherweise zusätzliche Eigenschaften relevant, sodass Sie diese möglicherweise abrufen und festlegen müssen.

Methoden¶

Snowflake-spezifisches Verhalten¶

Keine.

Methoden¶

Snowflake-spezifisches Verhalten¶

• addBatch()

  Wird nur für INSERT-Anweisungen unterstützt.

  Mit der addBatch-Methode (kombiniert mit executeBatch) können mehrere Datenzeilen als Teil einer einzelnen INSERT-Anweisung eingefügt werden.

  Der Unterschied zwischen Verwendung und Nichtverwendung eines Batches ähnelt dem Unterschied zwischen der Verwendung eines mehrzeiligen und eines einzeiligen INSERT:

  INSERT INTO t1 (c1, c2) VALUES (1, 'One');   -- single row inserted.
  
  INSERT INTO t1 (c1, c2) VALUES (1, 'One'),   -- multiple rows inserted.
                                 (2, 'Two'),
                                 (3, 'Three');
  

  Copy

  Das Einfügen von Zeilenbatches ist normalerweise effizienter als das Einfügen der gleichen Anzahl von Zeilen in einzelne INSERT-Anweisungen. Der Vorteil ist noch größer, wenn Sie AUTOCOMMIT verwenden (d. h. wenn jedes INSERT eine einzelne Transaktion ist).

  Ein Beispiel für die Verwendung von addBatch finden Sie unter Batcheinfügungen.

  Bemerkung

  Es gibt eine Obergrenze für die Datengröße, die Sie binden oder in einem Batch kombinieren können. Weitere Details dazu finden Sie unter Begrenzung der Abfragetextgröße.

• execute()

  Mit dieser Methode wird die SQL-Anweisung kompiliert und ausgeführt, die beim Erstellen des PreparedStatement-Objekts bereitgestellt wurde. Die Anweisung kann ein beliebiger Typ von SQL-Anweisung sein. Die Methode execute() gibt kein ResultSet zurück.

  Diese Methode gibt nichts zurück. Wenn Sie eine Abfrage ausführen und beim Ausführen der Anweisung eine ResultSet zurückerhalten müssen, verwenden Sie die Methode executeQuery().

• executeQuery()

  Mit dieser Methode wird die SQL-Anweisung kompiliert und ausgeführt, die beim Erstellen des PreparedStatement-Objekts bereitgestellt wurde, und sie gibt ein ResultSet zurück.

• executeUpdate()

  Mit dieser Methode wird die SQL-Anweisung kompiliert und ausgeführt, die beim Erstellen des PreparedStatement-Objekts bereitgestellt wurde. Die Anweisung muss eine DML-Anweisung (INSERT, UPDATE, DELETE usw.) oder eine SQL-Anweisung sein, die nichts zurückgibt (z. B. eine DDL-Anweisung).

  Die Methode executeUpdate() gibt eine Ganzzahl (Integer) zurück. Dies ist die Anzahl der Zeilen, die aktualisiert wurden, wenn die Anweisung eine DML-Anweisung war. Wenn die Anweisung keine Zeilen aktualisiert hat, gibt die Funktion 0 zurück.

  Wenn Sie eine SQL-Anweisung ausführen müssen, die ein ResultSet zurückgibt, verwenden Sie eine andere Methode, z. B. executeQuery().

• setObject()

  Wenn Sie eine Zeitstempelvariable an eine Zeitstempelspalte binden, können Sie mit dieser Methode die Zeitstempelvariante (TIMESTAMP_LTZ , TIMESTAMP_NTZ , TIMESTAMP_TZ) angeben, die zur Interpretation des Zeitstempelwerts verwendet werden soll. Weitere Details dazu finden Sie unter Binden von Variablen an Zeitstempelspalten.

Zusätzliche Methoden¶

Die folgenden Methoden ergänzen die von der PreparedStatement-Schnittstelle unterstützten Methoden.

executeAsyncQuery()¶

Zweck:

Diese Methode führt eine asynchrone Abfrage durch, bei der eine SQL-Anweisung zur Ausführung gesendet und anschließend die Kontrolle an den Aufrufer zurückgegeben wird, ohne auf den Abschluss der Abfrage zu warten.

Jede SQL-Anweisung, die für executeQuery() gültig ist, ist auch für executeAsyncQuery() gültig.

Bemerkung

Dateiübertragungsanweisungen wie PUT und GET sind für executeAsyncQuery() gültig, verhalten sich jedoch synchron.

Argumente:

Keine.

Rückgabewerte:

Ein leeres ResultSet. Der Benutzer sollte das Resultset mit resultSet.unwrap(SnowflakeResultSet.class).getStatus() abfragen, bis die Abfrageergebnisse verfügbar sind.

Auslöser:

Die Methode kann eine SQLException auslösen.

Anmerkungen:

Diese Methode ist eine Snowflake-Erweiterung des JDBC-Standards. Um diese Methode zu verwenden, müssen Sie das PreparedStatement-Objekt entpacken.

Beispiele:

...
PreparedStatement prepStatement = connection.prepareStatement("insert into testTable values (?)");
prepStatement.setInt(1, 33);
ResultSet rs = prepStatement.executeAsyncQuery();
...

Copy

In Beispiele für asynchrone Abfragen finden Sie ein ausführlicheres Beispiel mit der sehr ähnlichen SnowflakeStatement.executeAsyncQuery()-Methode.

getQueryID()

Zweck:

Diese Methode gibt die Snowflake-Abfrage-ID der zuletzt ausgeführten Abfrage von SnowflakePreparedStatement zurück. Wenn mit dieser vorbereiteten Anweisung noch keine Abfrage ausgeführt wurde, gibt die Methode null zurück.

Argumente:

Keine.

Rückgabewerte:

Die Methode gibt die ID als Zeichenfolge (String) zurück, die eine UUID enthält.

Auslöser:

Die Methode kann eine SQLException auslösen.

Anmerkungen:

Diese Methode ist eine Snowflake-Erweiterung des JDBC-Standards. Um diese Methode zu verwenden, müssen Sie das SnowflakePreparedStatement entpacken.

Für asynchrone Abfragen wird die Abfrage-ID erst verfügbar, wenn die Ausführung der Anweisung abgeschlossen ist. Wenn Sie SnowflakePreparedStatement.getQueryID() nach dem Aufruf von executeAsyncQuery() aufrufen, aber bevor die Ausführung der Anweisung abgeschlossen ist, kann der Rückgabewert NULL sein. Rufen Sie stattdessen resultSet.unwrap(SnowflakeResultSet.class).getQueryID() für das von executeAsyncQuery() zurückgegebene ResultSet-Objekt auf.

Beispiele:

Das folgende unvollständige Beispiel zeigt, wie die Methode aufgerufen wird:

    // Retrieve the query ID from the PreparedStatement.
    String queryID;
    queryID = preparedStatement.unwrap(SnowflakePreparedStatement.class).getQueryID();

Copy

Enumerationskonstanten¶

Jede Enumerationskonstante repräsentiert einen anderen möglichen Status der asynchronen Abfrage.

Methoden¶

Der Enumerationstyp definiert die folgenden Methoden, mit denen Sie Details zu einem Fehler abrufen können, wenn der Abfragestatus FAILED_WITH_ERROR ist.

getErrorCode()¶

Zweck:

Wenn während der Ausführung der Abfrage ein Fehler aufgetreten ist, gibt diese Methode den Fehlercode vom Server zurück.

Argumente:

Keine.

Rückgabewerte:

Die Methode gibt den Fehlercode als int zurück. Wenn kein Fehler aufgetreten ist, gibt die Methode den Wert 0 zurück.

Beispiele:

QueryStatus queryStatus = resultSet.unwrap(SnowflakeResultSet.class).getStatus();
if (queryStatus == queryStatus.FAILED_WITH_ERROR) {
  // Print the error code to stdout
  System.out.format("Error code: %d%n", queryStatus.getErrorCode());
}

Copy

Unter Beispiele für asynchrone Abfragen finden Sie ein ausführlicheres Beispiel, das einen Aufruf dieser Methode enthält.

getErrorMessage()¶

Zweck:

Wenn während der Ausführung der Abfrage ein Fehler aufgetreten ist, gibt diese Methode die Fehlermeldung des Servers zurück.

Argumente:

Keine.

Rückgabewerte:

Die Methode gibt die Fehlermeldung als String zurück. Wenn kein Fehler aufgetreten ist, gibt die Methode den Wert No error reported zurück.

Beispiele:

QueryStatus queryStatus = resultSet.unwrap(SnowflakeResultSet.class).getStatus();
if (queryStatus == queryStatus.FAILED_WITH_ERROR) {
  // Print the error message to stdout
  System.out.format("Error message: %s%n", queryStatus.getErrorMessage());
}

Copy

Unter Beispiele für asynchrone Abfragen finden Sie ein ausführlicheres Beispiel, das einen Aufruf dieser Methode enthält.

Methoden¶

Snowflake-spezifisches Verhalten¶

• close()

  Schließt die Verbindung. Nachdem ein Objekt geschlossen wurde, wird beim Aufrufen fast jeder Methode des geschlossenen Objekts eine SQLException ausgelöst. Das Aufrufen von close für ein bereits geschlossenes Objekt ist unproblematisch und löst keine Ausnahme aus.

• getDate(), getTime(), getTimestamp()

  In Version 3.12.17 und späteren Versionen des JDBC-Treibers verwenden diese Methoden die Sitzungszeitzone (angegeben durch den Parameter TIMEZONE). Ältere Versionen verwenden die Zeitzone der JVM.

  Um diese Methoden so zu ändern, dass sie die Zeitzone der JVM verwenden, setzen Sie den Parameter JDBC_USE_SESSION_TIMEZONE auf FALSE.

• getMetaData()

  Wenn das ResultSet-Objekt für eine asynchrone Abfrage ist, ist diese Methode gesperrt, bis die Ausführung der Abfrage abgeschlossen ist. Sie können resultSet.unwrap(SnowflakeResultSet.class).getStatus() verwenden, um den Abfragestatus abzurufen, bevor Sie diese Methode aufrufen.

• next()

  Damit wird die nächste Zeile im Resultset zur „aktuellen“ Zeile. Ruft die get*()-Methoden auf, z. B. getInt(), um Werte aus der aktuellen Zeile abzurufen.

  Wenn das ResultSet durch einen Aufruf der close-Methode geschlossen wurde, geben nachfolgende Aufrufe von next den Wert „false“ zurück.

  Wenn das ResultSet-Objekt für eine asynchrone Abfrage ist, ist diese Methode gesperrt, bis die Ergebnisse verfügbar sind. Sie können resultSet.unwrap(SnowflakeResultSet.class).getStatus() verwenden, um den Abfragestatus abzurufen, bevor Sie diese Methode aufrufen.

Zusätzliche Methoden¶

getQueryID()

Zweck:

Diese Methode gibt die Snowflake-Abfrage-ID der Anweisung zurück, die dieses Resultset generiert hat.

Argumente:

Keine.

Rückgabewerte:

Die Methode gibt die ID als Zeichenfolge (String) zurück, die eine UUID enthält.

Anmerkungen:

Diese Methode ist eine Snowflake-Erweiterung des JDBC-Standards. Um diese Methode zu verwenden, müssen Sie das ResultSet entpacken.

Beispiele:

    String queryID2;
    queryID2 = resultSet.unwrap(SnowflakeResultSet.class).getQueryID();

Copy

getStatus()¶

Zweck:

Für ein ResultSet, das von einer asynchronen Abfrage wie SnowflakeStatement.executeAsyncQuery() zurückgegeben wird, gibt diese Methode den Status der Abfrage zurück. Der Status gibt an, ob die Abfrage erfolgreich abgeschlossen wurde, nicht erfolgreich abgeschlossen wurde oder noch nicht abgeschlossen wurde.

Argumente:

Keine.

Rückgabewerte:

Eine QueryStatus Enumerationskonstante.

Auslöser:

Die Methode kann eine SQLException auslösen.

Anmerkungen:

Diese Methode ist eine Snowflake-Erweiterung des JDBC-Standards. Um diese Methode zu verwenden, müssen Sie das ResultSet-Objekt entpacken.

Beispiele:

QueryStatus queryStatus = resultSet.unwrap(SnowflakeResultSet.class).getStatus();

Copy

Unter Beispiele für asynchrone Abfragen finden Sie ein ausführlicheres Beispiel, das einen Aufruf dieser Methode enthält.

Methoden¶

Snowflake-spezifisches Verhalten¶

• Die Klasse ResultSetMetaData verfügt nicht über eine close()-Methode. Ein offenes ResultSetMetaData-Objekt wird implizit geschlossen, wenn der Benutzer das ResultSet schließt, aus dem das ResultSetMetaData-Objekt erstellt wurde.

• getCatalogName(), getSchemaName(), getTableName()

  Wenn das ResultSet-Objekt für eine asynchrone Abfrage ist, geben diese Methoden leere Zeichenfolgen zurück.

• Bei GEOGRAPHY-Spalten gibt getColumnTypeName einen GEOGRAPHY-Wert zurück.

  Beachten Sie, dass die Methoden getColumnType und getColumnClassName nicht angeben, dass der Spaltentyp GEOGRAPHY ist.

Zusätzliche Methoden¶

getColumnIndex(String columnName):

Zweck:

Gibt den Index der Spalte zurück, die dem Spaltennamen (columnName) entspricht. Wenn beispielsweise eine Spalte mit dem Namen „BirthDate“ die dritte Spalte in der Tabelle ist, gibt getColumnIndex(„BirthDate“) den Wert 2 zurück. (Indizes sind 0-basiert, nicht 1-basiert.)

Argumente:

Der Name der Spalte, für die Sie den Index suchen möchten.

Rückgabewerte:

Gibt eine Ganzzahl (Integer) zurück, die den Index der Spalte enthält, die dem Spaltennamen entspricht. Wenn der Spaltenname (columnName) keiner Spalte des Resultsets entspricht, wird -1 zurückgegeben.

Auslöser:

Die Methode kann eine SQLException auslösen.

getColumnNames():

Zweck:

Diese Funktion gibt die Liste aller Spaltennamen des Resultsets zurück.

Dies unterscheidet sich von der Funktion getColumnName(int column) in ResultSetMetaData, die einen einzelnen Spaltennamen auf Basis eines Index zurückgibt.

Argumente:

Keine.

Rückgabewerte:

Der Datentyp des zurückgegebenen Werts ist „List<Zeichenfolge>“. Die Liste enthält die Namen der Spalten. Die Namen sind in derselben Reihenfolge angegeben wie die Spaltenindizes.

Auslöser:

Die Methode kann eine SQLException auslösen.

getInternalColumnType(int column):

Zweck:

Diese Methode gibt den Datentyp der angegebenen Spalte zurück.

Argumente:

column: Gibt den Index (1-basiert) der Spalte an, für die Sie den Datentyp feststellen möchten.

Rückgabewerte:

Diese Methode gibt den Datentyp der angegebenen Spalte zurück. Der Datentyp ist eine Ganzzahl (Integer).

Auslöser:

Die Methode kann eine SQLException auslösen.

getQueryID()

Zweck:

Gibt die Snowflake-Abfrage-ID der Abfrage zurück, für die diese Metadaten gelten.

Argumente:

Keine.

Rückgabewerte:

Diese Methode gibt die Abfrage-ID der Abfrage zurück, für die diese Metadaten generiert wurden. Die Abfrage-ID ist eine Zeichenfolge (String), die eine UUID enthält. Weitere Informationen zu UUIDs finden Sie in der Beschreibung der SQL-Funktion UUID_STRING.

Auslöser:

Die Methode kann eine SQLException auslösen.

Methoden¶

SnowflakeTimestampWithTimezone(
    long seconds,
    int nanoseconds,
    TimeZone tz)

SnowflakeTimestampWithTimezone(
    Timestamp ts,
    TimeZone tz)

SnowflakeTimestampWithTimezone(
    Timestamp ts)

Snowflake-spezifisches Verhalten¶

• getTimezone()

  Gibt die Zeitzone aus dem Zeitstempel zurück.

  import java.sql.Timestamp;
  import java.time.ZonedDateTime;
  import java.util.TimeZone;
  
  public void testGetTimezone() {
      String timezone = "Australia/Sydney";
  
      // Create a timestamp from a point in time
      Long datetime = System.currentTimeMillis();
      Timestamp currentTimestamp = new Timestamp(datetime);
      SnowflakeTimestampWithTimezone ts =
          new SnowflakeTimestampWithTimezone(currentTimestamp, TimeZone.getTimeZone(timezone));
  
      // Verify timezone was set
      assertEquals(ts.getTimezone().getID(), timezone);
  }
  

  Copy

• toZonedDateTime()

  Konvertiert einen SnowflakeTimestampWithTimezone-Zeitstempel in eine zonierte Datumszeit (Java-ZonedDateTime-Objekt).

  import java.sql.Timestamp;
  import java.time.ZonedDateTime;
  import java.util.TimeZone;
  
  public void testToZonedDateTime() {
      String timezone = "Australia/Sydney";
      String zonedDateTime = "2022-03-17T10:10:08+11:00[Australia/Sydney]";
  
      // Create a timestamp from a point in time
      Long datetime = 1647472208000L;
      Timestamp timestamp = new Timestamp(datetime);
      SnowflakeTimestampWithTimezone ts =
          new SnowflakeTimestampWithTimezone(timestamp, TimeZone.getTimeZone(timezone));
      ZonedDateTime zd = ts.toZonedDateTime();
  
      // Verify timestamp was converted to zoned datetime
      assertEquals(zd.toString(), zonedDateTime);
  }
  

  Copy

Methoden¶

Snowflake-spezifisches Verhalten¶

• close()

  Mit dieser Methode wird das Objekt geschlossen. Nachdem ein Objekt geschlossen wurde, wird beim Aufrufen fast jeder Methode des geschlossenen Objekts eine SQLException ausgelöst. Das Aufrufen von close für ein bereits geschlossenes Objekt ist unproblematisch und löst keine Ausnahme aus.

• getBatchQueryID()

  Diese Methode gibt eine Liste der Snowflake-Abfrage-IDs des zuletzt ausgeführten Abfragebatches für dieses Statement zurück. Wenn mit der Anweisung noch keine Abfrage ausgeführt wurde, gibt die Methode null zurück.

  Diese Methode ist eine Snowflake-Erweiterung des JDBC-Standards. Um diese Methode zu verwenden, müssen Sie die Anweisung entpacken. Beispiel:

      connection.setAutoCommit(false);
      statement.addBatch("SELECT 1;");
      statement.addBatch("SELECT 2;");
      statement.executeBatch();
      connection.commit();
      connection.setAutoCommit(true);
      List<String> batchQueryIDs1;
      // Since getQueryID is not standard JDBC API, we must call unwrap() to
      // use these Snowflake methods.
      batchQueryIDs1 = statement.unwrap(SnowflakeStatement.class).getBatchQueryIDs();
      int num_query_ids = batchQueryIDs1.size();
      if (num_query_ids != 2) {
        System.out.println("ERROR: wrong number of query IDs in batch 1.");
      }
      // Check that each query ID is plausible.
      for (int i = 0; i < num_query_ids; i++) {
        String qid = batchQueryIDs1.get(i);
        if (!is_plausible_query_id(qid)) {
          msg = "SEVERE WARNING: suspicious query ID in batch";
          System.out.println("msg");
          System.out.println(qid);
        }
      }
  

  Copy

• getUpdateCount()

  Diese Methode gibt die Anzahl der Zeilen zurück, die von der zuletzt ausgeführten SQL-Anweisung aktualisiert wurden.

  • Wenn die Anweisung eine DML-Anweisung war (INSERT, UPDATE, DELETE usw.), gibt getUpdateCount() die Anzahl der Zeilen zurück, die hinzugefügt, gelöscht oder geändert wurden. Beachten Sie, dass dieser Wert 0 sein kann, wenn keine Zeile geändert wurde.

  • Wenn die Anweisung eine SELECT-Anweisung war, gibt getUpdateCount() den Wert -1 zurück.

  • Wenn die Anweisung eine DDL-Anweisung war, gibt getUpdateCount() den Wert -1 zurück.

Zusätzliche Methoden¶

executeAsyncQuery(String)

Zweck:

Diese Methode führt eine asynchrone Abfrage durch, bei der eine SQL-Anweisung zur Ausführung gesendet und anschließend die Kontrolle an den Aufrufer zurückgegeben wird, ohne auf den Abschluss der Abfrage zu warten.

Argumente:

Eine Zeichenfolge, die den auszuführenden SQL-Befehl enthält. Jede SQL-Anweisung, die für executeQuery() gültig ist, ist auch für executeAsyncQuery() gültig.

Bemerkung

Dateiübertragungsanweisungen wie PUT und GET sind für executeAsyncQuery() gültig, verhalten sich jedoch synchron.

Rückgabewerte:

Ein leeres ResultSet. Der Benutzer sollte das Resultset mit resultSet.unwrap(SnowflakeResultSet.class).getStatus() abfragen, bis die Abfrageergebnisse verfügbar sind.

Auslöser:

Die Methode kann eine SQLException auslösen.

Anmerkungen:

Diese Methode ist eine Snowflake-Erweiterung des JDBC-Standards. Um diese Methode zu verwenden, müssen Sie das Statement-Objekt entpacken.

Beispiele:

Unter Beispiele für asynchrone Abfragen finden Sie ein Beispiel, das einen Aufruf dieser Methode enthält.

getQueryID()

Zweck:

Diese Methode gibt die Snowflake-Abfrage-ID der zuletzt ausgeführten Abfrage von Statement zurück.

Argumente:

Keine.

Rückgabewerte:

Die Abfrage-ID der zuletzt ausgeführten Abfrage dieser Anweisung. Die Abfrage-ID ist eine Zeichenfolge (String), die ein UUID enthält. Wenn mit der Anweisung noch keine Abfrage ausgeführt wurde, gibt die Methode null zurück.

Auslöser:

Die Methode kann eine SQLException auslösen.

Anmerkungen:

Diese Methode ist eine Snowflake-Erweiterung des JDBC-Standards. Um diese Methode zu verwenden, müssen Sie das Statement-Objekt entpacken.

Für asynchrone Abfragen wird die Abfrage-ID erst verfügbar, wenn die Ausführung der Anweisung abgeschlossen ist. Wenn Sie SnowflakeStatement.getQueryID() nach dem Aufruf von executeAsyncQuery() aufrufen, aber bevor die Ausführung der Anweisung abgeschlossen ist, kann der Rückgabewert NULL sein. Rufen Sie stattdessen resultSet.unwrap(SnowflakeResultSet.class).getQueryID() für das von executeAsyncQuery() zurückgegebene ResultSet-Objekt auf.

Beispiele:

    String queryID1;
    queryID1 = statement.unwrap(SnowflakeStatement.class).getQueryID();

Copy

setParameter(String parameter_name, <type> <value>)¶

Zweck:

Die SnowflakeStatement-Klasse stellt die setParameter-Methode als Snowflake-Erweiterung bereit. Auf diese Weise kann der Aufrufer Snowflake-spezifische JDBC-Parameter festlegen.

Die Methode ist überladen. Unterschiedliche JDBC-Parameter erfordern unterschiedliche Datentypen. Für jeden gültigen Datentyp existiert eine Methode, die als zweites Argument an die Funktion übergeben werden kann.

Argumente:

parameter_name:

Diese Zeichenfolge muss den Namen eines vordefinierten Snowflake-JDBC-Parameters enthalten. Die vordefinierten JDBC-Parameter (und deren gültige Werte oder Bereiche) sind nachfolgend aufgeführt:

JDBC-Parameter	Anmerkungen
MULTI_STATEMENT_COUNT	Ganzzahl (Integer), die die Anzahl der Anweisungen angibt (0 = unbegrenzte Anzahl von Anweisungen; 1 oder höher gibt die genaue Anzahl der Anweisungen an, die ausgeführt werden sollen).

value:

Dies ist der Wert, der dem angegebenen JDBC-Parameter zugewiesen werden soll. Stellen Sie sicher, dass der Datentyp mit dem von Ihnen angegebenen JDBC-Parameter kompatibel ist.

Rückgabewerte:

Nichts.

Auslöser:

Diese Funktion kann eine SQLException auslösen.

Anmerkungen:

Diese Methode ist eine Snowflake-Erweiterung des JDBC-Standards. Um diese Methode zu verwenden, müssen Sie das Statement-Objekt entpacken.

Beispiele:

Statement statement1;
...
// Tell Statement to expect to execute 2 statements:
statement1.unwrap(SnowflakeStatement.class).setParameter(
        "MULTI_STATEMENT_COUNT", 2);

Copy