Verwenden des JDBC-Treibers

Unter diesem Thema werden Informationen zur Verwendung des JDBC-Treibers bereitgestellt.

Snowflake-JDBC-API-Erweiterungen

Der Snowflake-JDBC-Treiber unterstützt zusätzliche Methoden, die über JDBC-die Standardspezifikation hinausgehen. In diesem Abschnitt wird beschrieben, wie Sie beim Entpacken den Zugriff auf die Snowflake-spezifischen Methoden bereitstellen. Anschließend werden drei Situationen beschrieben, in denen ein Entpacken möglicherweise erforderlich ist:

Entpacken von Snowflake-spezifischen Klassen

Der Snowflake-JDBC-Treiber unterstützt Snowflake-spezifische Methoden. Folgende Methoden sind Snowflake-spezifische, in Java codierte Schnittstellen wie SnowflakeConnection, SnowflakeStatement und SnowflakeResultSet. Beispielsweise enthält die SnowflakeStatement-Schnittstelle eine getQueryID()-Methode, die in der JDBC-Statement-Schnittstelle nicht definiert ist.

Wenn der Snowflake-JDBC-Treiber aufgefordert wird, ein JDBC-Objekt zu erstellen (z. B. Erstellen eines JDBC-Statement-Objekts durch Aufrufen der createStatement()-Methode eines Connection-Objekts), erstellt der Snowflake-JDBC-Treiber tatsächlich Snowflake-spezifische Objekte, die nicht nur die Methoden des JDBC-Standards, sondern auch die zusätzlichen Methoden der Snowflake-Schnittstellen implementieren.

Um auf diese Snowflake-Methoden zuzugreifen, „entpacken“ Sie das Objekt (z. B. ein Statement-Objekt), sodass das Snowflake-Objekt und seine Methoden verfügbar sind. Sie können dann die zusätzlichen Methoden aufrufen.

Der folgende Code zeigt, wie Sie ein JDBC-Statement-Objekt entpacken, um die Methoden der SnowflakeStatement-Schnittstelle verfügbar zu machen, und dann eine dieser Methoden aufrufen, in diesem Fall setParameter:

Statement statement1;
...
// Unwrap the statement1 object to expose the SnowflakeStatement object, and call the
// SnowflakeStatement object's setParameter() method.
statement1.unwrap(SnowflakeStatement.class).setParameter(...);

Ausführen einer asynchronen Abfrage

Der Snowflake-JDBC-Treiber unterstützt asynchrone Abfragen (etwa Abfragen, die den Benutzenden vor dem Abschluss die Kontrolle zurückgeben). Sie können eine Abfrage starten und dann durch Abrufen feststellen, wann die Abfrage abgeschlossen ist. Wenn dies der Fall ist, können die Benutzenden das Resultset lesen.

Mit diesem Feature kann ein Clientprogramm mehrere Abfragen parallel ausführen, ohne dass das Clientprogramm selbst Multithreading verwendet.

Asynchrone Abfragen verwenden Methoden, die den Klassen SnowflakeConnection, SnowflakeStatement, SnowflakePreparedStatement und SnowflakeResultSet hinzugefügt wurden.

Bemerkung

Um asynchrone Abfragen auszuführen, müssen Sie sicherstellen, dass der Konfigurationsparameter ABORT_DETACHED_QUERY den Wert FALSE hat (Standardwert).

Wenn die Verbindung zum Client unterbrochen wird:

  • Bei synchronen Abfragen werden alle laufenden synchronen Abfragen unabhängig vom Wert des Parameters sofort abgebrochen.

  • Für asynchrone Abfragen:

    • Wenn ABORT_DETACHED_QUERY auf FALSE eingestellt ist, werden laufende asynchrone Abfragen weiter ausgeführt, bis sie normal beendet werden.

    • Wenn ABORT_DETACHED_QUERY auf TRUE eingestellt ist, bricht Snowflake automatisch alle laufenden asynchronen Abfragen ab, wenn die Verbindung zum Client nach fünf Minuten nicht wiederhergestellt ist.

      Sie können verhindern, dass die asynchrone Abfrage an der Fünf-Minuten-Marke abgebrochen wird, indem Sie cursor.query_result(queryId) aufrufen. Dieser Aufruf ruft zwar nicht das tatsächliche Abfrageergebnis ab, da die Abfrage noch läuft, verhindert jedoch, dass die Abfrage abgebrochen wird. Der Aufruf von query_result ist eine synchrone Operation, die für Ihren speziellen Anwendungsfall geeignet sein kann oder auch nicht.

Sie können in derselben Sitzung eine Mischung aus synchronen und asynchronen Abfragen ausführen.

Bemerkung

Asynchrone Abfragen unterstützen nicht PUT/GET-Anweisungen.

Wenn executeAsyncQuery(query) verwendet wird, verfolgt der Snowflake-JDBC-Treiber automatisch die asynchron übermittelten Abfragen. Wenn die Verbindung explizit mit connection.close() geschlossen wird, wird die Liste der asynchronen Abfragen geprüft. Wenn eine Abfrage noch ausgeführt wird, wird die Snowflake-seitige Sitzung nicht gelöscht.

Wenn innerhalb der gleichen Verbindung keine asynchronen Abfragen laufen, wird die zur Verbindung gehörende Snowflake-Sitzung abgemeldet, wenn connection.close() aufgerufen wird, wodurch implizit alle anderen Abfragen in derselben Sitzung abgebrochen werden.

Dieses Verhalten hängt auch vom Parameter SQL ABORT_DETACHED_QUERY ab. Weitere Informationen dazu finden Sie in der Dokumentation zum Parameter ABORT_DETACHED_QUERY.

Als bewährte Methode sollten Sie alle asynchronen Aufgaben mit langer Ausführungszeit (insbesondere solche, die nach dem Schließen der Verbindung fortgesetzt werden sollen) in einer separaten Verbindung isolieren.

Zum besseren Verständnis der Hierarchie der Geschäftslogik der Treiber und der Interaktion des Parameters ABORT_DETACHED_QUERY betrachten Sie das folgende Flussdiagramm:

Ablaufplan für asynchrone Abfragen

Best Practices für asynchrone Abfragen

  • Stellen Sie vor der parallelen Ausführung von Abfragen sicher, dass Sie die Abhängigkeiten der Abfragen von anderen Abfragen genau kennen. Abfragen, die voneinander und von der Ausführungsreihenfolge abhängig sind, eignen sich nicht für die Parallelisierung. Beispielsweise kann eine INSERT-Anweisung erst beginnen, nachdem die entsprechende CREATE TABLE-Anweisung abgeschlossen wurde.

  • Stellen Sie sicher, dass die Anzahl der gestarteten Abfragen auf den verfügbaren Arbeitsspeicher abgestimmt ist. Das parallele Ausführen mehrerer Abfragen beansprucht normalerweise mehr Speicher, insbesondere wenn mehr als ein ResultSet gleichzeitig im Arbeitsspeicher gespeichert ist.

  • Behandeln Sie beim Abrufen die seltenen Fälle, in denen eine Abfrage nicht erfolgreich ist. Vermeiden Sie beispielsweise die folgende potenzielle Endlosschleife:

    QueryStatus queryStatus = resultSet.unwrap(SnowflakeAsyncResultSet.class).getStatus();
while (!queryStatus.isSuccess())  {     //  NOT RECOMMENDED
    Thread.sleep(2000);   // 2000 milliseconds.
    queryStatus = resultSet.unwrap(SnowflakeAsyncResultSet.class).getStatus();
    }

    Verwenden Sie stattdessen ungefähr folgenden Code:

    // Assume that the query is not done yet.
QueryStatus queryStatus = resultSet.unwrap(SnowflakeAsyncResultSet.class).getStatus();
while (queryStatus.isStillRunning())  {
    Thread.sleep(2000);   // 2000 milliseconds.
    queryStatus = resultSet.unwrap(SnowflakeAsyncResultSet.class).getStatus();
    }

if (queryStatus.isSuccess()) {
    ...
    }

  • Stellen Sie sicher, dass Anweisungen zur Transaktionssteuerung (BEGIN, COMMIT und ROLLBACK) nicht parallel zu anderen Anweisungen ausgeführt werden.

Beispiele für asynchrone Abfragen

In den meisten dieser Beispiele muss das Programm die folgenden Klassen importieren:

import java.sql.Connection;
import java.sql.ResultSet;
import java.sql.Statement;
import net.snowflake.client.api.resultset.QueryStatus;
import net.snowflake.client.api.resultset.SnowflakeAsyncResultSet;
import net.snowflake.client.api.connection.SnowflakeConnection;
import net.snowflake.client.api.resultset.SnowflakeResultSet;
import net.snowflake.client.api.statement.SnowflakeStatement;

Dies ist ein sehr einfaches Beispiel:

String sql_command = "";
ResultSet resultSet;

System.out.println("Create JDBC statement.");
Statement statement = connection.createStatement();
sql_command = "SELECT PI()";
System.out.println("Simple SELECT query: " + sql_command);
resultSet = statement.unwrap(SnowflakeStatement.class).executeAsyncQuery(sql_command);

// Assume that the query isn't done yet.
QueryStatus queryStatus = resultSet.unwrap(SnowflakeAsyncResultSet.class).getStatus();
while (queryStatus.isStillRunning()) {
  Thread.sleep(2000); // 2000 milliseconds.
  queryStatus = resultSet.unwrap(SnowflakeAsyncResultSet.class).getStatus();
}

if (queryStatus.getStatus() == QueryStatus.Status.FAILED_WITH_ERROR) {
  // Print the error code to stdout
  System.out.format("Error code: %d%n", queryStatus.getErrorCode());
  System.out.format("Error message: %s%n", queryStatus.getErrorMessage());
} else if (!queryStatus.isSuccess()) {
  System.out.println("ERROR: unexpected QueryStatus: " + queryStatus.getStatus());
} else {
  boolean result_exists = resultSet.next();
  if (!result_exists) {
    System.out.println("ERROR: No rows returned.");
  } else {
    float pi_result = resultSet.getFloat(1);
    System.out.println("pi = " + pi_result);
  }
}

In diesem Beispiel wird die Abfrage-ID gespeichert, die Verbindung geschlossen, die Verbindung erneut geöffnet und die Daten werden mithilfe der Abfrage-ID abgerufen:

String sql_command = "";
ResultSet resultSet;
String queryID = "";

System.out.println("Create JDBC statement.");
Statement statement = connection.createStatement();
sql_command = "SELECT PI() * 2";
System.out.println("Simple SELECT query: " + sql_command);
resultSet = statement.unwrap(SnowflakeStatement.class).executeAsyncQuery(sql_command);
queryID = resultSet.unwrap(SnowflakeResultSet.class).getQueryID();
System.out.println("INFO: Closing statement.");
statement.close();
System.out.println("INFO: Closing connection.");
connection.close();

System.out.println("INFO: Re-opening connection.");
connection = create_connection(args);
use_warehouse_db_and_schema(connection);
resultSet = connection.unwrap(SnowflakeConnection.class).createResultSet(queryID);

// Assume that the query isn't done yet.
QueryStatus queryStatus = resultSet.unwrap(SnowflakeAsyncResultSet.class).getStatus();
while (queryStatus.isStillRunning()) {
  Thread.sleep(2000); // 2000 milliseconds.
  queryStatus = resultSet.unwrap(SnowflakeAsyncResultSet.class).getStatus();
}

if (queryStatus.getStatus() == QueryStatus.Status.FAILED_WITH_ERROR) {
  System.out.format(
      "ERROR %d: %s%n", queryStatus.getErrorMessage(), queryStatus.getErrorCode());
} else if (!queryStatus.isSuccess()) {
  System.out.println("ERROR: unexpected QueryStatus: " + queryStatus.getStatus());
} else {
  boolean result_exists = resultSet.next();
  if (!result_exists) {
    System.out.println("ERROR: No rows returned.");
  } else {
    float pi_result = resultSet.getFloat(1);
    System.out.println("pi = " + pi_result);
  }
}

Datendateien direkt von einem Stream in einen internen Stagingbereich hochladen

Sie können Datendateien mit dem PUT-Befehl hochladen. Manchmal ist es jedoch sinnvoll, Daten direkt von einem Stream in einen internen (d. h. Snowflake) Stagingbereich als Datei zu übertragen. (Der Stagingbereich kann ein beliebiger interner Stagingbereich vom Typ Tabellen-, Benutzer- oder benannter Stagingbereich sein. Der JDBC-Treiber bietet keine Unterstützung für das Hochladen in einen externen Stagingbereich.) Folgende Methode wird in der Klasse SnowflakeConnection bereitgestellt:

/**
  * Method to compress data from a stream and upload it at a stage location.
  * The data will be uploaded as one file. No splitting is done in this method.
  *
  * Caller is responsible for releasing the inputStream after the method is
  * called.
  *
  * @param stageName    stage name: e.g. ~ or table name or stage name
  * @param destPrefix   path / prefix under which the data should be uploaded on the stage
  * @param inputStream  input stream from which the data will be uploaded
  * @param destFileName destination file name to use
  * @param compressData compress data or not before uploading stream
  * @throws java.sql.SQLException failed to compress and put data from a stream at stage
  */
  void uploadStream(String stageName, String destFileName, InputStream inputStream)
      throws SQLException;

  void uploadStream(String stageName, String destFileName, InputStream inputStream,
                    UploadStreamConfig config)
      throws SQLException;

Anwendung des Beispiels:

Connection connection = DriverManager.getConnection(url, prop);
File file = new File("/tmp/test.csv");
FileInputStream fileInputStream = new FileInputStream(file);

// upload file stream to user stage
UploadStreamConfig config = UploadStreamConfig.builder()
    .setDestPrefix("testUploadStream")
    .setCompressData(true)
    .build();

connection.unwrap(SnowflakeConnection.class).uploadStream("MYSTAGE", "destFile.csv",
  fileInputStream, config);

Datendateien direkt von einem internen Stagingbereich in einen Stream herunterladen

Sie können Datendateien mit dem GET-Befehl herunterladen. Manchmal ist es jedoch sinnvoll, Daten direkt aus einer Datei in einen internen (d. h. Snowflake) Stagingbereich für einen Stream zu übertragen. (Der Stagingbereich kann ein beliebiger interner Stagingbereich vom Typ Tabellen-, Benutzer- oder benannter Stagingbereich sein. Der JDBC-Treiber bietet keine Unterstützung für das Herunterladen in einen externen Stagingbereich.) Folgende Methode wird in der Klasse SnowflakeConnection bereitgestellt:

/**
  * Download a file from a Snowflake stage as a stream with required parameters only.
  *
  * <p>This is a convenience method that uses default options (no decompression). For advanced
  * configuration, use {@link #downloadStream(String, String, DownloadStreamConfig)}.
  *
  * <p>The caller is responsible for closing the returned input stream.
  *
  * @param stageName the name of the stage (e.g., "@my_stage")
  * @param sourceFileName the path to the file within the stage
  * @return an input stream containing the file data
  * @throws SQLException if download fails
  */
  InputStream downloadStream(String stageName, String sourceFileName) throws SQLException;

  /**
  * Download a file from a Snowflake stage as a stream with optional configuration.
  *
  * <p>This method allows customization of download behavior via {@link DownloadStreamConfig}, such
  * as automatic decompression.
  *
  * <p>The caller is responsible for closing the returned input stream.
  *
  * @param stageName the name of the stage (e.g., "@my_stage")
  * @param sourceFileName the path to the file within the stage
  * @param config optional configuration for download behavior
  * @return an input stream containing the file data
  * @throws SQLException if download fails
  */
  InputStream downloadStream(String stageName, String sourceFileName, DownloadStreamConfig config)
      throws SQLException;

Anwendung des Beispiels:

Connection connection = DriverManager.getConnection(url, prop);
DownloadStreamConfig config = DownloadStreamConfig.builder()
    .setDecompress(true)
    .build();

InputStream out = connection.unwrap(SnowflakeConnection.class).downloadStream(
    "~",
    DEST_PREFIX + "/" + TEST_DATA_FILE + ".gz",
    config);

Unterstützung für mehrere Anweisungen

In diesem Abschnitt wird beschrieben, wie Sie mit JDBC-Treiber mehrere Anweisungen in einer einzelnen Anforderung ausführen.

Bemerkung

  • Die Ausführung mehrerer Anweisungen in einer einzigen Abfrage setzt voraus, dass ein gültiges Warehouse in einer Sitzung verfügbar ist.

  • Standardmäßig gibt Snowflake bei Abfragen, die mehrere Anweisungen enthalten, einen Fehler zurück, um sich vor SQL-Einschleusungen zu schützen. Die Ausführung mehrerer Anweisungen in einer einzigen Abfrage erhöht das Risiko einer SQL-Einschleusung. Snowflake empfiehlt, es sparsam zu verwenden. Um das SQL-Einschleusungsrisiko zu verringern, verwenden Sie die SnowflakeStatement class’s setParameter()-Methode, um die Anzahl der auszuführenden Anweisungen anzugeben. Dies erschwert das Einschleusen einer Anweisung durch Anhängen. Weitere Informationen zu SnowflakeStatement finden Sie unter Schnittstelle: SnowflakeStatement.

Senden mehrerer Anweisungen und Verarbeiten der Ergebnisse

Abfragen, die mehrere Anweisungen enthalten, können auf dieselbe Weise wie Abfragen mit einer einzelnen Anweisung ausgeführt werden, mit der Ausnahme, dass die Abfragezeichenfolge mehrere durch Semikolons getrennte Anweisungen enthält.

Es gibt zwei Möglichkeiten, mehrere Anweisungen zuzulassen:

  • Rufen Sie Statement.setParameter („MULTI_STATEMENT_COUNT“, n) auf, um anzugeben, wie viele Anweisungen gleichzeitig ausgeführt werden dürfen. Weitere Details dazu finden Sie unten.

  • Legen Sie den Parameter MULTI_STATEMENT_COUNT auf Sitzungsebene oder Kontoebene fest, indem Sie einen der folgenden Befehle ausführen:

    alter session set MULTI_STATEMENT_COUNT = 0;

    Oder:

    alter account set MULTI_STATEMENT_COUNT = 0;

    Wenn Sie den Parameter auf 0 setzen, wird eine unbegrenzte Anzahl von Anweisungen zugelassen. Wenn Sie den Parameter auf 1 setzen, wird jeweils nur eine Anweisung zugelassen.

Um Angriffe durch Einschleusung von SQL-Befehlen zu erschweren, können Benutzer mithilfe der setParameter-Methode die Anzahl der Anweisungen angeben, die durch einen einzelnen Aufruf ausgeführt werden sollen (siehe unten). In diesem Beispiel beträgt die Anzahl der Anweisungen, die durch einen einzelnen Aufruf ausgeführt werden sollen, 3:

// Specify the number of statements that we expect to execute.
statement.unwrap(SnowflakeStatement.class).setParameter(
        "MULTI_STATEMENT_COUNT", 3);

Die Standardanzahl der Anweisungen ist 1. Mit anderen Worten, der Mehrfachanweisungsmodus ist deaktiviert.

Übergeben Sie den Wert 0, um mehrere Anweisungen auszuführen, ohne die genaue Anzahl anzugeben.

Der Parameter MULTI_STATEMENT_COUNT ist nicht Teil des JDBC-Standards, sondern eine Snowflake-Erweiterung. Dieser Parameter betrifft mehr als einen Snowflake-Treiber oder -Konnektor.

Wenn in einer einzigen execute()-Anweisung mehrere Anweisungen ausgeführt werden, ist das Ergebnis der ersten Anweisung über die Standardmethoden getResultSet() und getUpdateCount() verfügbar. Verwenden Sie die Methode getMoreResults(), um auf die Ergebnisse der nachfolgenden Anweisungen zuzugreifen. Diese Methode gibt true zurück, wenn weitere Anweisungen für die Iteration verfügbar sind, und false falls nicht.

Im folgenden Beispiel wird der Parameter MULTI_STATEMENT_COUNT festgelegt, dann werden 3 Anweisungen ausgeführt und schließlich werden die Aktualisierungszähler und die Resultsets abgerufen:

// Create a string that contains multiple SQL statements.
String command_string = "create table test(n int); " +
                        "insert into test values (1), (2); " +
                        "select * from test order by n";
Statement stmt = connection.createStatement();
// Specify the number of statements (3) that we expect to execute.
stmt.unwrap(SnowflakeStatement.class).setParameter(
        "MULTI_STATEMENT_COUNT", 3);

// Execute all of the statements.
stmt.execute(command_string);                       // false

// --- Get results. ---
// First statement (create table)
stmt.getUpdateCount();                              // 0 (DDL)

// Second statement (insert)
stmt.getMoreResults();                              // true
stmt.getUpdateCount();                              // 2

// Third statement (select)
stmt.getMoreResults();                              // true
ResultSet rs = stmt.getResultSet();
rs.next();                                          // true
rs.getInt(1);                                       // 1
rs.next();                                          // true
rs.getInt(1);                                       // 2
rs.next();                                          // false

// Past the last statement executed.
stmt.getMoreResults();                              // false
stmt.getUpdateCount();                              // 0 (no more results)

Snowflake empfiehlt die Verwendung von execute() für Abfragen mit mehreren Anweisungen. Die Methoden executeQuery() und executeUpdate() unterstützen auch mehrere Anweisungen, lösen jedoch eine Ausnahme aus, wenn das erste Ergebnis nicht dem erwarteten Ergebnistyp entspricht (Resultset bzw. Aktualisierungsanzahl).

Fehlgeschlagene Anweisungen

Wenn eine der SQL-Anweisungen nicht kompiliert oder ausgeführt werden kann, wird die Ausführung abgebrochen. Alle vorherigen Anweisungen, die zuvor ausgeführt wurden, bleiben davon unberührt.

Im folgenden Beispiel werden Anweisungen als einzelne Abfrage mit mehreren Anweisungen ausgeführt. Dabei schlägt die Abfrage bei der dritten Anweisung fehl, und es wird eine Ausnahme ausgelöst.

CREATE OR REPLACE TABLE test(n int);
INSERT INTO TEST VALUES (1), (2);
INSERT INTO TEST VALUES ('not_an_int');  -- execution fails here
INSERT INTO TEST VALUES (3);

Wenn Sie dann den Inhalt der Tabelle test abfragen würden, wären die Werte 1 und 2 vorhanden.

Nicht unterstützte Features

PUT- und GET-Anweisungen werden für Abfragen mit mehreren Anweisungen nicht unterstützt.

Das Vorbereiten von Anweisungen und die Verwendung von Bindungsvariablen werden für Abfragen mit mehreren Anweisungen ebenfalls nicht unterstützt.

Binden von Variablen an Anweisungen

Durch Binden können SQL-Anweisungen Werte verwenden, die in einer Java-Variablen gespeichert sind.

Einfaches Binden

Ohne Binden gibt eine SQL-Anweisung Werte an, indem sie Literale innerhalb der Anweisung angibt. Die folgende Anweisung verwendet z. B. den Literalwert 42 in einer UPDATE-Anweisung:

stmt.execute("UPDATE table1 SET integer_column = 42 WHERE ID = 1000");

Durch Binden können Sie eine SQL-Anweisung ausführen, die einen Wert verwendet, der sich innerhalb einer Variablen befindet. Beispiel:

int my_integer_variable = 42;
PreparedStatement pstmt = connection.prepareStatement("UPDATE table1 SET integer_column = ? WHERE ID = 1000");
pstmt.setInt(1, my_integer_variable);
pstmt.executeUpdate();

Das ? innerhalb der VALUES-Klausel gibt an, dass die SQL-Anweisung den Wert aus einer Variablen verwendet. Die Methode setInt() gibt an, dass das erste Fragezeichen in der SQL-Anweisung durch den Wert in der Variable mit dem Namen my_integer_variable ersetzt werden soll. Beachten Sie, dass setInt() 1-basierte und nicht 0-basierte Werte verwendet, d. h. das erste Fragezeichen von 1 und nicht von 0 referenziert wird.

Binden von Variablen an Zeitstempelspalten

Snowflake unterstützt drei verschiedene Varianten für Zeitstempel: TIMESTAMP_LTZ , TIMESTAMP_NTZ , TIMESTAMP_TZ. Wenn Sie PreparedStatement.setTimestamp aufrufen, um eine Variable an eine Zeitstempelspalte zu binden, wird der JDBC-Treiber den Zeitstempelwert in Bezug zur lokalen Zeitzone (TIMESTAMP_LTZ) interpretieren oder die Zeitzone des Calendar-Objekts wird als Argument übergeben:

// The following call interprets the timestamp in terms of the local time zone.
insertStmt.setTimestamp(1, myTimestamp);
// The following call interprets the timestamp in terms of the time zone of the Calendar object.
insertStmt.setTimestamp(1, myTimestamp, Calendar.getInstance(TimeZone.getTimeZone("America/New_York")));

Wenn Sie möchten, dass der Treiber den Zeitstempel anhand einer anderen Variante (z. B. TIMESTAMP_NTZ) interpretiert, verwenden Sie einen der folgenden Ansätze:

  • Setzen Sie den Sitzungsparameter CLIENT_TIMESTAMP_TYPE_MAPPING auf die Variante.

    Beachten Sie, dass der Parameter alle Bindungsoperationen für die aktuelle Sitzung beeinflusst. Wenn Sie die Variante ändern müssen (z. B. zurück zu TIMESTAMP_LTZ), müssen Sie diesen Sitzungsparameter erneut einstellen.

  • (In JDBC-Treiber 3.13.3 und späteren Versionen) Rufen Sie die Methode PreparedStatement.setObject auf, und geben Sie mit dem Parameter targetSqlType eine der folgenden Snowflake-Zeitstempelvarianten an:

    • SnowflakeType.EXTRA_TYPES_TIMESTAMP_LTZ

    • SnowflakeType.EXTRA_TYPES_TIMESTAMP_TZ

    • SnowflakeType.EXTRA_TYPES_TIMESTAMP_NTZ

    • SnowflakeType.EXTRA_TYPES_VECTOR

    • SnowflakeType.EXTRA_TYPES_DECFLOAT

    • SnowflakeType.EXTRA_TYPES_YEAR_MONTH_INTERVAL

    • SnowflakeType.EXTRA_TYPES_DAY_TIME_INTERVAL

    Beispiel:

    import net.snowflake.client.api.resultset.SnowflakeType;
...
insertStmt.setObject(1, myTimestamp, SnowflakeType.EXTRA_TYPES_TIMESTAMP_NTZ);

Batcheinfügungen

In Ihrem Java-Anwendungscode können Sie mehrere Zeilen in einen einzelnen Batch einfügen, indem Sie Parameter in einer INSERT-Anweisung binden und dann addBatch() und executeBatch() aufrufen.

Der folgende Code fügt beispielsweise zwei Zeilen in eine Tabelle ein, die eine INTEGER-Spalte und eine VARCHAR-Spalte enthält. Im Beispiel werden Werte an die Parameter der INSERT-Anweisung gebunden und dann addBatch() und executeBatch() aufgerufen, um eine Batcheinfügung durchzuführen.

Connection connection = DriverManager.getConnection(url, prop);
connection.setAutoCommit(false);

PreparedStatement pstmt = connection.prepareStatement("INSERT INTO t(c1, c2) VALUES(?, ?)");
pstmt.setInt(1, 101);
pstmt.setString(2, "test1");
pstmt.addBatch();

pstmt.setInt(1, 102);
pstmt.setString(2, "test2");
pstmt.addBatch();

int[] count = pstmt.executeBatch(); // After execution, count[0]=1, count[1]=1
connection.commit();

Wenn Sie dieses Verfahren verwenden, um eine große Anzahl von Werten einzufügen, kann die Treiberleistung verbessert werden, indem die Daten (ohne Erstellen von Dateien auf dem lokalen Computer) an einen temporären Stagingbereich gestreamt werden. Der Treiber führt dies automatisch durch, wenn die Anzahl der Werte einen Schwellenwert überschreitet.

Außerdem müssen die aktuelle Datenbank und das aktuelle Schema für die Sitzung festgelegt sein. Wenn diese nicht festgelegt sind, kann der vom Treiber ausgeführte CREATE TEMPORARY STAGE-Befehl folgenden Fehler generieren:

CREATE TEMPORARY STAGE SYSTEM$BIND file_format=(type=csv field_optionally_enclosed_by='"')
Cannot perform CREATE STAGE. This session does not have a current schema. Call 'USE SCHEMA', or use a qualified name.

Bemerkung

Alternative Möglichkeiten zum Laden von Daten in die Snowflake-Datenbank (einschließlich Massenladen mit dem COPY-Befehl) finden Sie unter Daten in Snowflake laden.

Java-Beispielprogramm

Für ein in Java geschriebenes Beispiel klicken Sie mit der rechten Maustaste auf den Namen der Datei SnowflakeJDBCExample.java, und speichern Sie den Link bzw. die Datei in Ihrem lokalen Dateisystem.

Problembehandlung

E/A-Fehler: Verbindung zurückgesetzt

In einigen Fällen kann der JDBC-Treiber nach einer gewissen Zeit der Inaktivität möglicherweise mit der folgenden Fehlermeldung fehlschlagen:

I/O error: Connection reset

Sie können das Problem umgehen, indem Sie eine bestimmte Lebensdauer („time to live“) für die Verbindungen einstellen. Wenn eine Verbindung länger als die Lebensdauer inaktiv ist, entfernt der JDBC-Treiber die Verbindung aus dem Verbindungspool und erstellt eine neue Verbindung.

Um die Lebensdauer einzustellen, setzen Sie die Java-Systemeigenschaft net.snowflake.jdbc.ttl auf die Anzahl der Sekunden, die die Verbindung bestehen bleiben soll:

  • Um diese Eigenschaft programmseitig festzulegen, rufen Sie System.setProperty auf:

    // Set the "time to live" to 60 seconds.
System.setProperty("net.snowflake.jdbc.ttl", "60")

  • Um diese Eigenschaft beim Ausführen des Befehls java festzulegen, verwenden Sie das Flag -D:

    # Set the "time to live" to 60 seconds.
java -cp .:snowflake-jdbc-<version>.jar -Dnet.snowflake.jdbc.ttl=60 <ClassName>

Der Standardwert der Eigenschaft net.snowflake.jdbc.ttl ist -1, was bedeutet, dass inaktive Verbindungen nicht aus dem Verbindungspool entfernt werden.

Fehlerbehandlung

Bei der Behandlung von Fehlern und Ausnahmen für eine JDBC-Anwendung können Sie die Datei ErrorCode.java verwenden, die von Snowflake zur Verfügung gestellt wird, um die Ursache von Problemen zu ermitteln. Die für den JDBC-Treiber spezifischen Fehlercodes beginnen mit 2, in der Form: 2NNNNN.

Bemerkung

Der Link zu „ErrorCode.java“ im öffentlichen „snowflake-jdbc“-Git-Repository verweist auf die aktuelle Version der Datei, die sich von der Version des derzeit verwendeten JDBC-Treibers unterscheiden kann.