Verwenden des Node.js-Treibers¶

Der typische Workflow für die Verwendung des Treibers ist wie folgt:

Erstellen Sie eine Verbindung zu Snowflake.
Führen Sie die Anweisungen aus (z. B. SQL-Abfragen oder DDL/DML-Befehle).
Verarbeiten Sie die von Snowflake zurückgegebenen Abfrageergebnisse.
Beenden Sie die Verbindung.

Wichtig

Zum Hoch- und Herunterladen von Dateien in/aus Snowflake-Stagingbereichen müssen Sie die folgenden Mindestversionen des Treibers verwenden:

Version 1.6.2 zum Hochladen von Dateien (mit dem Befehl PUT)
Version 1.6.6 zum Herunterladen von Dateien (mit dem Befehl GET)

Unter diesem Thema:

Herstellen von Verbindungen
Verbinden über einen authentifizierten Proxy
Überprüfen der Netzwerkverbindung zu Snowflake mit SnowCD
OCSP (Online Certificate Status Protocol)
- Auswahl des Fail-open- oder Fail-close-Modus
- Überprüfen der OCSP-Konnektor- oder Treiber-Version
Ausführen von Anweisungen
Verwenden von Ergebnissen
Hochladen einer Datei in einen Snowflake-Stagingbereich
Beenden einer Verbindung

Herstellen von Verbindungen¶

Um Anweisungen in Snowflake auszuführen, müssen Sie zunächst eine Verbindung herstellen. Mit dem Snowflake-Node.js-Treiber können Sie Verbindungen wie folgt herstellen:

Erstellen einer einzelnen Verbindung
Erstellen eines Pools von Verbindungen

Erstellen einer einzelnen Verbindung¶

So erstellen Sie eine einzelne Verbindung zu Snowflake:

Rufen Sie snowflake.createConnection auf, um ein neues Connection-Objekt zu erstellen, und übergeben Sie ein JavaScript-Objekt, das die Verbindungsoptionen angibt.
Rufen Sie mit dem Connection-Objekt die Methode connect auf, um eine Verbindung herzustellen.

Bemerkung

Wenn Sie die Option authenticator auf EXTERNALBROWSER einstellen (um browserbasiertes SSO zu verwenden) oder auf https://<Name_des_Okta-Kontos>.okta.com (um natives SSO über Okta zu verwenden), rufen Sie die Methode connectAsync und nicht die Methode connect auf.

Um Verbindungsfehler zu behandeln, übergeben Sie eine Callback-Funktion, die folgende Signatur hat:
```
function(err, conn)
```
Wobei:
- err ist ein JavaScript-Error-Objekt.
- conn ist das aktuelle Connection-Objekt.
Wenn bei der Verbindung ein Fehler auftritt, übergibt die Methode connect ein Error-Objekt an Ihre Callback-Funktion. Sie können dieses Objekt in Ihrer Callback-Funktion verwenden, um Details über den Fehler abzurufen. Wenn Sie Informationen über das aktuelle Connection-Objekt benötigen, können Sie das an Ihre Callback-Funktion übergebene conn-Argument verwenden.

Das folgende Beispiel baut eine Verbindung auf und verwendet ein Kennwort zur Authentifizierung. Informationen zu weiteren Authentifizierungsmethoden finden Sie unter Authentifizierungsoptionen.

// Load the Snowflake Node.js driver.
var snowflake = require('snowflake-sdk');

// Create a Connection object that we can use later to connect.
var connection = snowflake.createConnection({
    account: account,
    username: user,
    password: password,
    application: application
  });

// Try to connect to Snowflake, and check whether the connection was successful.
connection.connect( 
    function(err, conn) {
        if (err) {
            console.error('Unable to connect: ' + err.message);
            } 
        else {
            console.log('Successfully connected to Snowflake.');
            // Optional: store the connection ID.
            connection_ID = conn.getId();
            }
    }
);

Beim Erstellen einer Verbindung können Sie die Verbindungsoptionen wie unter Einstellen der Verbindungsoptionen beschrieben einstellen.

Erstellen eines Verbindungspools¶

Anstatt jedes Mal eine neue Verbindung zu erstellen, wenn Ihre Clientanwendung auf Snowflake zugreifen muss, können Sie einen Cache für Snowflake-Verbindungen definieren, der bei Bedarf wiederverwendet werden kann. Verbindungspooling verringert normalerweise die Verzögerungszeit beim Herstellen einer Verbindung. Es kann jedoch das Client-Failover auf ein alternatives DNS verlangsamen, wenn ein DNS-Problem auftritt.

So erstellen Sie einen Verbindungspool:

Rufen Sie snowflake.createPool(connectionOptions, poolOptions) auf, um ein neues ConnectionPool-Objekt zu erstellen, und übergeben Sie zwei JavaScript-Objekte, die die Verbindungsoptionen und die Pooloptionen angeben.

Bemerkung

Der Snowflake-Node.js-Treiber verwendet die Open-Source-Bibliothek node-pool zur Implementierung von Verbindungspools. Weitere Informationen zu den unterstützten poolOptions finden Sie in der Beschreibung des Arguments opts in der Bibliotheksdokumentation zu node-pool.
Rufen Sie mit dem Objekt ConnectionPool die Funktion use auf, um Anweisungen für eine einzelne Verbindung im Verbindungspool auszuführen.

Um Verbindungsfehler zu behandeln, übergeben Sie eine Callback-Funktion, die folgende Signatur hat:
```
function(err, stmt, rows)
```
Wobei:
- err ist ein JavaScript-Error-Objekt.
- stmt ist ein Objekt mit Informationen zu der ausgeführte SQL-Anweisung, einschließlich des wörtlichen Textes der Anweisung.
- rows ist ein Array, das das „Resultset“ der Anweisung enthält.
Wenn beim Ausführen der Anweisung ein Fehler auftritt, übergibt die Methode connect ein Error-Objekt an Ihre Callback-Funktion. Sie können dieses Objekt in Ihrer Callback-Funktion verwenden, um Details über den Fehler abzurufen.

Im folgenden Beispiel wird ein Verbindungspool erstellt, der maximal zehn aktive Verbindungen unterstützt. Zur Authentifizierung wird ein Kennwort verwendet. Informationen zu weiteren Authentifizierungsmethoden finden Sie unter Authentifizierungsoptionen.

// Create the connection pool instance
const connectionPool = snowflake.createPool(
    // connection options
    {
      account: account,
      username: user,
      password: password
    },
    // pool options
    {
      max: 10, // specifies the maximum number of connections in the pool
      min: 0   // specifies the minimum number of connections in the pool
    }
);
  

Im folgenden Beispiel wird die Methode connectionPool.use verwendet, um eine SQL-Anweisung unter Verwendung der Verbindungen im Pool auszuführen. Die Methode clientConnection.execute gibt die auszuführende SQL-Anweisung an und definiert eine Callback-Funktion.

// Use the connection pool and execute a statement
connectionPool.use(async (clientConnection) =>
{
    const statement = await clientConnection.execute({
        sqlText: 'select 1;',
        complete: function (err, stmt, rows)
        {
            var stream = stmt.streamRows();
            stream.on('data', function (row)
            {
                console.log(row);
            });
            stream.on('end', function (row)
            {
                console.log('All rows consumed');
            });
        }
    });
});

Beim Erstellen eines Verbindungspools können Sie die Verbindungsoptionen wie unter Einstellen der Verbindungsoptionen beschrieben einstellen.

Einstellen der Verbindungsoptionen¶

Beim Erstellen eines neuen Connection-Objekts übergeben Sie ein JavaScript-Objekt, das die Optionen für die Verbindung angibt (z. B. Ihren Kontobezeichner, Ihren Benutzernamen usw.). In den folgenden Abschnitten werden die Optionen beschrieben, die Sie einstellen können. Um eine Option einzustellen, geben Sie den Optionsnamen als Eigenschaftsnamen im JavaScript-Objekte an.

Erforderliche Verbindungsoptionen
Authentifizierungsoptionen
Zusätzliche Verbindungsoptionen

Erforderliche Verbindungsoptionen¶

account

Ihr Kontobezeichner.

username

Der Anmeldename für Ihren Snowflake-Benutzer oder Ihren Identitätsanbieter (z. B. Ihr Anmeldename für Okta).

region (Veraltet)

ID der Region, in der sich Ihr Konto befindet.

Bemerkung

Diese Option ist veraltet und wird hier nur noch aus Gründen der Abwärtskompatibilität verwendet. Snowflake empfiehlt den Übergang zur Einbettung der Region in den Kontobezeichner, wie unter Verwenden eines Konto-Locators als Bezeichner beschrieben, etwa wie folgt.

var connection = snowflake.createConnection({
  account: "myaccount.us-east-2",
  username: "myusername",
  password: "mypassword"
});

Zusätzlich müssen Sie die Optionen für die Authentifizierung am Server angeben.

Authentifizierungsoptionen¶

application

Gibt den Namen der Clientanwendung an, die eine Verbindung zu Snowflake herstellt.

authenticator

Gibt den Authentifikator an, der für die Überprüfung der Anmeldeinformationen des Benutzers verwendet werden soll. Sie können dies auf einen der folgenden Werte einstellen:

Wert	Beschreibung
`SNOWFLAKE`	Verwenden des internen Snowflake-Authentifikators. Sie müssen auch die Option `password` einstellen.
`EXTERNALBROWSER`	Verwenden Ihres Webbrowsers zur Authentifizierung mit Okta, ADFS oder einem anderen SAML 2.0-kompatiblen Identitätsanbieter (IdP).
`https://<Name_des_Okta-Kontos>.okta.com`	Verwenden Sie native SSO über Okta.
`OAUTH`	Verwenden Sie OAuth für die Authentifizierung. Sie müssen auch die Option `token` auf das OAuth-Token setzen (siehe unten).
`SNOWFLAKE_JWT`	Verwenden der Schlüsselpaar-Authentifizierung Siehe Verwenden von Schlüsselpaar-Authentifizierung und Schlüsselpaar-Rotation.

Der Standardwert ist SNOWFLAKE.

Weitere Informationen zur Authentifizierung finden Sie unter Verwenden und Verwalten der Verbundauthentifizierung und OAuth mit Clients, Treibern und Konnektoren.

password

Kennwort für den Benutzer. Legen Sie diese Option fest, wenn Sie die Option authenticator auf SNOWFLAKE oder auf den Okta-URL-Endpunkt Ihres Okta-Kontos (z. B. https://<Name_des_Okta-Kontos>.okta.com) gesetzt haben oder wenn Sie die Option authenticator nicht gesetzt haben.

token: Gibt das OAuth-Token an, das für die Authentifizierung verwendet werden soll. Legen Sie diese Option fest, wenn Sie die Option authenticator auf OAUTH gesetzt haben.
privateKey: Privater Schlüssel (im PEM-Format) für die Schlüsselpaar-Authentifizierung. Weitere Details dazu finden Sie unter Verwenden von Schlüsselpaar-Authentifizierung und Schlüsselpaar-Rotation.
privateKeyPath: Gibt den lokalen Pfad zu der erstellten Datei mit dem privaten Schlüssel an (z. B rsa_key.p8). Weitere Details dazu finden Sie unter Verwenden von Schlüsselpaar-Authentifizierung und Schlüsselpaar-Rotation.
privateKeyPass: Gibt die Kennung zum Entschlüsseln der privaten Schlüsseldatei an, wenn die Datei verschlüsselt ist. Weitere Details dazu finden Sie unter Verwenden von Schlüsselpaar-Authentifizierung und Schlüsselpaar-Rotation.

Zusätzliche Verbindungsoptionen¶

arrayBindingThreshold

Legt die maximale Anzahl der Bindungen fest, die der Treiber bei einer Masseneinfügeoperation verwendet. Der Standardwert ist 100.000 (100K).

clientSessionKeepAlive

Standardmäßig kommt es bei Clientverbindungen ca. 3–4 Stunden nach der Ausführung der letzten Abfrage zu einem Timeout.

Wenn die Option clientSessionKeepAlive auf true gesetzt ist, bleibt die Verbindung des Clients zum Server auf unbestimmte Zeit bestehen, auch wenn keine Abfragen ausgeführt werden.

Die Standardeinstellung dieser Option lautet „false“.

Wenn Sie die Option auf true setzen, müssen Sie sicherstellen, dass Ihr Programm die Verbindung zum Server explizit trennt, sobald das Programm abgeschlossen ist. Trennen Sie erst die Verbindung, bevor Sie das Programm beenden.

clientSessionKeepAliveHeartbeatFrequency

(Gilt nur, wenn clientSessionKeepAlive den Wert „true“ hat)

Gibt die Frequenz (das Wiederholungsintervall in Sekunden) von Taktmeldungen an.

Sie können sich die Taktmeldung einer Verbindung wie einen Ersatz für eine Abfrage mit Neustart des Timeout-Countdowns der Verbindung vorstellen. Anders ausgedrückt: Wenn die Verbindung nach mindestens 4 Stunden Inaktivität abbrechen würde, setzt der Takt den Timer zurück, sodass das Timeout frühestens 4 Stunden nach dem letzten Takt (oder der letzten Abfrage) stattfindet.

Der Standardwert ist 3.600 Sekunden (eine Stunde). Der gültige Wertebereich liegt zwischen 900 und 3.600. Da Timeouts normalerweise nach frühestens 4 Stunden auftreten, reicht normalerweise ein Takt von einmal pro Stunde, damit die Verbindung aufrechterhalten bleibt. Taktintervalle von weniger als 3.600 Sekunden sind selten notwendig oder nützlich.

database

Die Standarddatenbank, die nach dem Verbinden für die Sitzung verwendet werden soll.

noProxy

Gibt die Listen der Hosts an, mit denen sich der Treiber unter Umgehung des Proxyservers direkt verbinden soll (z. B. *.amazonaws.com zur Umgehung des Amazon S3-Zugriffs). Bei mehreren Hosts werden die Hostnamen durch ein Pipe-Symbol (|) getrennt. Sie können auch ein Sternchen (*) als Platzhalter verwenden. Beispiel:

noProxy: "*.amazonaws.com|*.my_company.com"

proxyHost

Gibt den Hostnamen eines authentifizierten Proxyservers an.

proxyPassword

Gibt das Kennwort des Benutzers an, der von proxyUser festgelegt wurde.

proxyPort

Gibt den Port eines authentifizierten Proxyservers an.

proxyProtocol

Gibt das Protokoll an, das für die Verbindung zum authentifizierten Proxyserver verwendet wird. Verwenden Sie diese Eigenschaft, um das HTTP-Protokoll anzugeben: http oder https.

proxyUser

Gibt den Benutzernamen an, der für die Verbindung mit einem authentifizierten Proxyserver verwendet wird.

resultPrefetch

Anzahl der Threads, die Clients zum Vorabrufen großer Resultsets verwenden. Gültige Werte: 1–10.

role

Die Standardsicherheitsrolle, die nach dem Verbinden für die Sitzung verwendet werden soll.

schema

Das Standardschema, das nach dem Verbinden für die Sitzung verwendet werden soll.

timeout

Anzahl der Millisekunden, in denen die Verbindung aufrechterhalten wird, ohne dass eine Antwort erfolgt. Standardwert: 60.000 (1 Minute).

warehouse

Das standardmäßige virtuelle Warehouse, das nach dem Verbinden für die Sitzung verwendet werden soll. Wird zum Ausführen von Abfragen, Laden von Daten usw. verwendet.

Bei einigen Verbindungsoptionen wird davon ausgegangen, dass das angegebene Datenbankobjekt (Datenbank, Schema, Warehouse oder Rolle) bereits im System vorhanden ist. Wenn das angegebene Objekt nicht vorhanden ist, wird während der Verbindung kein Standard festgelegt.

Nach dem Verbinden können alle optionalen Verbindungsoptionen auch über den Befehl USE <Objekt> eingestellt oder überschrieben werden.

Authentifizierung mit Snowflake¶

Für die Authentifizierung bei Snowflake können Sie eine der folgenden Optionen verwenden:

Kennwortbasierte Authentifizierung. Um dies zu verwenden, legen Sie die Option password beim Aufbau der Verbindung fest.
Single Sign-On (SSO) über einen Webbrowser.
Natives SSO über Okta.
Schlüsselpaar-Authentifizierung.
OAuth.

Verwendung von Single Sign-on (SSO) über einen Webbrowser¶

Wenn Sie Snowflake für die Verwendung von Single Sign-On (SSO) konfiguriert haben, können Sie Ihre Clientanwendung so konfigurieren, dass browserbasiertes SSO für die Authentifizierung verwendet wird.

In Ihrem Anwendungscode:

Setzen Sie die Option authenticator auf EXTERNALBROWSER.
Rufen Sie zum Herstellen einer Verbindung die Methode connectAsync und nicht die Methode connect auf.

Beispiel:

// Use a browser to authenticate via SSO.
var connection = snowflake.createConnection({
  ...,
  authenticator: "EXTERNALBROWSER"
});
// Establish a connection. Use connectAsync, rather than connect.
connection.connectAsync(
  function (err, conn)
  {
    ... // Handle any errors.
  }
).then(() =>
{
  // Execute SQL statements.
  var statement = connection.execute({...});
});

Weitere Informationen zur Verwendung von browserbasiertem SSO für die Authentifizierung finden Sie unter Browser-basiertes SSO.

Natives SSO über Okta verwenden¶

Wenn Sie Snowflake für die Verwendung von Single Sign-On (SSO) konfiguriert haben, und zwar über Okta, können Sie Ihre Clientanwendung so konfigurieren, dass sie die native SSO-Authentifizierung über Okta verwendet.

In Ihrem Anwendungscode:

Legen Sie die folgenden Optionen fest:
- Setzen Sie die Option authenticator auf den Okta-URL-Endpunkt für Ihr Okta-Konto (z. B. https://<Name_des_Okta-Kontos>.okta.com).
- Setzen Sie die Optionen username und password auf den Benutzernamen und das Kennwort für Ihren Identitätsanbieter (IdP).
Rufen Sie zum Herstellen einer Verbindung die Methode connectAsync und nicht die Methode connect auf.

Beispiel:

// Use native SSO authentication through Okta.
var connection = snowflake.createConnection({
  ...,
  username: '<user_name_for_okta>',
  password: '<password_for_okta>',
  authenticator: "https://myaccount.okta.com"
});

// Establish a connection.
connection.connectAsync(
  function (err, conn)
  {
    ... // Handle any errors.
  }
);

// Execute SQL statements.
var statement = connection.execute({...});

Weitere Informationen zur Verwendung der nativen SSO-Authentifizierung über Okta finden Sie unter Natives SSO – Nur Okta.

Verwenden von Schlüsselpaar-Authentifizierung und Schlüsselpaar-Rotation¶

Der Treiber unterstützt Schlüsselpaar-Authentifizierung und Schlüsselrotation. Für die Verwendung müssen Sie Folgendes tun:

Konfigurieren Sie die Schlüsselpaar-Authentifizierung, wie unter Schlüsselpaar-Authentifizierung und Schlüsselpaar-Rotation erläutert.
In Ihrem Anwendungscode:
1. Setzen Sie die Option authenticator auf SNOWFLAKE_JWT.
2. Verwenden Sie den privaten Schlüssel zur Authentifizierung auf eine der folgenden Arten:
  - Setzen Sie die Option privateKey auf den privaten Schlüssel.
  - Setzen Sie die Option privateKeyPath auf den Pfad zur Datei des privaten Schlüssels.
    
    Wenn die Datei verschlüsselt ist, müssen Sie auch die Option privateKeyPass auf die Passphrase setzen, um den privaten Schlüssel zu entschlüsseln.

Im folgenden Beispiel wird der private Schlüssel aus einer Datei geladen und die Option privateKey auf den privaten Schlüssel gesetzt:

// Read the private key file from the filesystem.
var crypto = require('crypto');
var fs = require('fs');
var privateKeyFile = fs.readFileSync('<path_to_private_key_file>/rsa_key.p8');

// Get the private key from the file as an object.
const privateKeyObject = crypto.createPrivateKey({
  key: privateKeyFile,
  format: 'pem',
  passphrase: 'passphrase'
});

// Extract the private key from the object as a PEM-encoded string.
var privateKey = privateKeyObject.export({
  format: 'pem',
  type: 'pkcs8'
});

// Use the private key for authentication.
var connection = snowflake.createConnection({
  ...
  authenticator: "SNOWFLAKE_JWT",
  privateKey: privateKey
});

// Establish a connection.
connection.connect(
  function (err, conn)
  {
    ... // Handle any errors.
  }
);

// Execute SQL statements.
var statement = connection.execute({...});

Im folgenden Beispiel wird die Option privateKeyPath auf eine verschlüsselte Datei mit privatem Schlüssel gesetzt und die Option privateKeyPass auf die Passphrase gesetzt, die zum Entschlüsseln des privaten Schlüssels verwendet wird:

// Use an encrypted private key file for authentication.
// Specify the passphrase for decrypting the key.
var connection = snowflake.createConnection({
  ...
  authenticator: "SNOWFLAKE_JWT",
  privateKeyPath: "<path-to-privatekey>/privatekey.p8",
  privateKeyPass: '<passphrase_to_decrypt_the_private_key>'
});

// Establish a connection.
connection.connect(
  function (err, conn)
  {
    ... // Handle any errors.
  }
);

// Execute SQL statements.
var statement = connection.execute({...});

Verwenden von OAuth¶

Um eine Verbindung mit OAuth herzustellen, setzen Sie die Option authenticator auf OAUTH und die Option token auf das OAuth-Zugriffstoken. Beispiel:

// Use OAuth for authentication.
var connection = snowflake.createConnection({
  ...
  authenticator: "OAUTH",
  token: "<your_oauth_token>"
});

// Establish a connection.
connection.connect(
  function (err, conn)
  {
    ... // Handle any errors.
  }
);

// Execute SQL statements.
var statement = connection.execute({...});

Weitere Informationen dazu finden Sie unter OAuth mit Clients, Treibern und Konnektoren.

Verbinden über einen authentifizierten Proxy¶

Sie können eine Verbindung zu Snowflake über einen authentifizierten Proxy herstellen, indem Sie beim Erstellen eines Connection-Objekts Authentifizierungsdaten als Verbindungsoptionen angeben.

Bemerkung

Die Verbindung über einen authentifizierten Proxyserver wird ab Version 1.6.4 des Snowflake-Node.js-Treibers unterstützt.

Das folgende Beispiel zeigt, wie eine Verbindung zu einem authentifizierten Proxy mit HTTP hergestellt wird:

var connection = snowflake.createConnection({
      account: "account",
      username: "user",
      password: "password",
      proxyHost: "localhost",
      proxyPort: 3128,
      proxyUser: "myname",
      proxyPassword: "mypass"
});

Um eine Verbindung zu einem authentifizierten Proxy mit HTTPS herzustellen, müssen Sie auch die Verbindungseigenschaft proxyProtocol angeben, wie unten gezeigt:

var connection = snowflake.createConnection({
      account: "account",
      username: "user",
      password: "password",
      proxyHost: "localhost",
      proxyPort: 3128,
      proxyUser: "myname",
      proxyPassword: "mypass",
      proxyProtocol: "https"
});

Überprüfen der Netzwerkverbindung zu Snowflake mit SnowCD¶

Nach der Konfiguration des Treibers können Sie die Netzwerkkonnektivität zu Snowflake mit SnowCD testen und Probleme beheben.

Sie können während der Erstkonfiguration und bei Bedarf jederzeit SnowCD verwenden, um Ihre Netzwerkverbindung zu Snowflake zu testen und Probleme zu beheben.

OCSP (Online Certificate Status Protocol)¶

Wenn der Treiber eine Verbindung herstellt, sendet Snowflake ein Zertifikat, um zu bestätigen, dass die Verbindung zu Snowflake und nicht zu einem Host besteht, der sich als Snowflake ausgibt. Der Treiber sendet dieses Zertifikat an einen OCSP (Online Certificate Status Protocol)-Server, um zu überprüfen, ob das Zertifikat widerrufen wurde.

Wenn der Treiber den OCSP-Server nicht erreichen kann, um das Zertifikat zu überprüfen, kann beim Treiber „Fail-open“ oder „Fail-close“ auftreten.

Auswahl des Fail-open- oder Fail-close-Modus¶

Bei Node.js-Treiberversionen vor 1.2.0 findet standardmäßig „Fail-close“ statt. Bei Versionen ab 1.2.0 findet standardmäßig „Fail-open“ statt. Sie können das Standardverhalten überschreiben, indem Sie den globalen Parameter ocspFailOpen festlegen, bevor Sie die Methode snowflake.createConnection() aufrufen. Sie können den Parameter auf „true“ oder „false“ setzen.

snowflake.configure( {ocspFailOpen: false} );
const connection = snowflake.createConnection(
    {
    account: <account_identifier>,
    ...
    }
);

Überprüfen der OCSP-Konnektor- oder Treiber-Version¶

Weitere Informationen zu Version, Konfiguration und OCSP-Verhalten von Treiber oder Konnektor finden Sie unter OCSP-Konfiguration.

Ausführen von Anweisungen¶

Anweisungen können durch Aufruf der Methode connection.execute() ausgeführt werden. Die execute()-Methode akzeptiert ein options-Objekt, mit dem der SQL-Text und ein complete-Callback angegeben werden können. Der complete-Callback wird aufgerufen, wenn eine Anweisung die Ausführung beendet hat und das Ergebnis zur Weiterverarbeitung bereit steht:

var statement = connection.execute({
  sqlText: 'create database testdb',
  complete: function(err, stmt, rows) {
    if (err) {
      console.error('Failed to execute statement due to the following error: ' + err.message);
    } else {
      console.log('Successfully executed statement: ' + stmt.getSqlText());
    }
  }
});

Bemerkung

Die maximale Größe der Nutzlast einer einzelnen Anfrage beträgt 16 MB.

Datenbindung in Anweisungsparametern¶

Gelegentlich kann es sinnvoll sein, Daten in einer Anweisung mit einem Platzhalter zu verknüpfen. Die Ausführung von Anweisungen auf diese Weise ist nützlich, um Angriffe durch Einschleusung von SQL-Befehlen zu verhindern. Verwenden Sie ggf. die folgende Anweisung:

connection.execute({
  sqlText: 'select c1 from (select 1 as c1 union all select 2 as c1) where c1 = 1;'
});

Das gleiche Ergebnis erzielen Sie mit den folgenden Bindungen:

connection.execute({
  sqlText: 'select c1 from (select :1 as c1 union all select :2 as c1) where c1 = :1;',
  binds: [1, 2]
});

Die ?-Syntax für Bindungen wird ebenfalls unterstützt:

connection.execute({
  sqlText: 'select c1 from (select ? as c1 union all select ? as c1) where c1 = ?;',
  binds: [1, 2, 1]
});

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.

Ausführen eines Batches mit SQL-Anweisungen (Unterstützung für mehrere Anweisungen)¶

Ab Version 1.6.18 des Node.js-Konnektors können Sie einen Batch mit SQL-Anweisungen (durch Semikolons getrennt) senden, der mit einer einzigen Anforderung ausgeführt wird.

Bemerkung

Standardmäßig gibt Snowflake bei Abfragen mit mehreren Anweisungen einen Fehler zurück. Dieses Verhalten dient teilweise zum Schutz vor einer Einschleusung von SQL-Befehlen. Die Verwendung der Funktion für mehrere Anweisungen eröffnet die Möglichkeit der Einschleusung von SQL-Befehlen und sollte mit größter Sorgfalt verwendet werden. Sie können das Risiko verringern, indem Sie mit der SnowflakeStatement.setParameter()-Methode die Anzahl der auszuführenden Anweisungen angeben. Dies erschwert das Einschleusen einer Anweisung durch Anhängen. Weitere Details dazu finden Sie unter Schnittstelle: SnowflakeStatement.

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

Im folgenden Beispiel wird die Anzahl der Anweisungen auf Sitzungsebene auf unbegrenzt festgelegt und danach werden drei SQL-Anweisungen ausgeführt:

var statement = connection.execute({
  alter session set MULTI_STATEMENT_COUNT = 0;
  sqlText: 'create table test(n int); insert into test values (1), (2); select * from test order by n',
  complete: function(err, stmt, rows) {
    if (err) {
      console.error('Failed to execute statement due to the following error: ' + err.message);
    } else {
      // code to process the results
    }
  }
});

Binden eines Arrays für Masseneinfügen¶

Das Binden eines Arrays von Daten wird für INSERT-Massenoperationen unterstützt. Übergeben Sie ein Array von Arrays wie folgt:

connection.execute({
  sqlText: 'insert into t(c1, c2, c3) values(?, ?, ?)',
  binds: [[1, 'string1', 2.0], [2, 'string2', 4.0], [3, 'string3', 6.0]]
});

Bemerkung

Das Binden eines großen Arrays wirkt sich auf die Leistung aus und kann abgelehnt werden, wenn die Datenmenge zu groß ist, um vom Server verarbeitet zu werden.

Abbrechen von Anweisungen¶

Eine Anweisung kann durch Aufruf der Methode statement.cancel() abgebrochen werden:

statement.cancel(function(err, stmt) {
  if (err) {
    console.error('Unable to abort statement due to the following error: ' + err.message);
  } else {
    console.log('Successfully aborted statement');
  }
});

Erneutes Übermitteln von Anforderungen¶

Wenn Sie sich nicht sicher sind, ob Snowflake eine SQL-Anweisung erfolgreich ausgeführt hat, z. B. aufgrund eines Netzwerkfehlers oder eines Timeouts, können Sie dieselbe Anweisung unter Verwendung der Anforderungs-ID erneut übermitteln. Angenommen, Sie senden einen INSERT-Befehl zum Hinzufügen von Daten, erhalten aber nicht rechtzeitig eine Bestätigung, sodass Sie nicht wissen, was mit dem Befehl passiert ist. In diesem Szenario möchten Sie nicht einfach denselben Befehl als neuen Befehl ausführen, da dies dazu führen könnte, dass der Befehl zweimal ausgeführt wird, was zu einer Verdoppelung der Daten führt.

Indem Sie die Anforderungs-ID in die SQL-Anweisung einbeziehen, können Sie eine mögliche Duplizierung der Daten vermeiden. Das erneute Übermitteln der Anforderung unter Verwendung der Anforderung-ID der ursprünglichen Anforderung stellt sicher, dass der erneut übermittelte Befehl nur ausgeführt wird, wenn die ursprüngliche Anforderung fehlgeschlagen ist. Weitere Informationen dazu finden Sie unter Erneutes Übermitteln von Anforderungen zum Ausführen von SQL-Anweisungen.

Die folgenden Codebeispiele zeigen, wie Sie die Anforderungs-ID speichern und verwenden können, um eine Anweisung erneut zu übermitteln. Wenn Sie eine Anweisung ausführen, können Sie mit der Funktion getRequestId() die ID der übermittelten Anforderung abrufen. Sie können diese ID dann verwenden, um die gleiche Anweisung zu einem späteren Zeitpunkt auszuführen. Im folgenden Beispiel wird eine INSERT-Anweisung ausgeführt und deren Anforderungs-ID in der Variablen requestId gespeichert.

var requestId;
connection.execute({
  sqlText: 'INSERT INTO testTable VALUES (1);',
    complete: function (err, stmt, rows)
    {
      var stream = stmt.streamRows();
      requestId = stmt.getRequestId();   // Retrieves the request ID
      stream.on('data', function (row)
      {
        console.log(row);
      });
      stream.on('end', function (row)
      {
        console.log('done');
      });
    }
});

Wenn Sie keine Bestätigung erhalten, dass der Befehl erfolgreich ausgeführt wurde, können Sie die Anforderung unter Verwendung der gespeicherten Anfrage-ID wie gezeigt erneut übermitteln.

connection.execute({
  sqlText: 'INSERT INTO testTable VALUES (1);',  // optional
    requestId: requestId,  // Uses the request ID from before
    complete: function (err, stmt, rows)
    {
      var stream = stmt.streamRows();
      stream.on('data', function (row)
      {
        console.log(row);
      });
      stream.on('end', function (row)
      {
        console.log('done');
      });
  }
});

Wenn Sie sich entscheiden, eine Anforderung erneut mit requestId und sqlText zu übermitteln, müssen Sie folgende Wechselwirkungen beachten:

Wenn die Anforderungs-ID requestId bereits vorhanden ist, d. h. mit einer früheren Anforderung übereinstimmt, ignoriert der Befehl die sqlText-Abfrage und übermittelt erneut die Abfrage aus dem ursprünglichen Befehl.
Wenn die Anforderungs-ID requestId nicht vorhanden ist, d. h. mit keiner früheren Anforderung übereinstimmt, führt der Befehl die sqlText-Abfrage aus.

Verwenden von Ergebnissen¶

Inline-Rückgabe von Ergebnissen¶

Die gebräuchlichste Art, Ergebnisse zu verwenden, ist die Übergabe eines complete-Callbacks an connection.execute(). Wenn die Ausführung der Anweisung beendet und das Ergebnis zur Verwendung bereit ist, wird der complete-Callback gestartet, und die Ergebniszeilen werden inline zurückgegeben:

connection.execute({
  sqlText: 'select * from sometable',
  complete: function(err, stmt, rows) {
    if (err) {
      console.error('Failed to execute statement due to the following error: ' + err.message);
    } else {
      console.log('Number of rows produced: ' + rows.length);
    }
  }
});

Streamen von Ergebnissen¶

Es ist auch möglich, ein Ergebnis in Form eines Zeilenstream zu verarbeiten. Dies kann durch Aufruf der statement.streamRows()-Methode erfolgen. Dabei wird ein Readable-Node.js-Stream zurückgegeben, der verwendet werden kann, um Zeilen direkt beim Empfangen weiterzuverarbeiten. Weitere Informationen zum Readable-Stream finden Sie in der Dokumentation zu Node.js.

Beispiel:

var statement = connection.execute({
  sqlText: 'select * from sometable'
});

var stream = statement.streamRows();

stream.on('error', function(err) {
  console.error('Unable to consume all rows');
});

stream.on('data', function(row) {
  // consume result row...
});

stream.on('end', function() {
  console.log('All rows consumed');
});

Stapelverarbeitung von Ergebnissen¶

Standardmäßig wird mit der statement.streamRows()-Methode ein Stream produziert, der jede Zeile im Ergebnis enthält. Wenn Sie jedoch nur eine Teilmenge des Ergebnisses weiterverwenden möchten oder wenn Ergebniszeilen in Batches verwendet werden sollen, können Sie streamRows() mit start- und end-Argumenten aufrufen. Bei Angabe dieser zusätzlichen Optionen werden nur Zeilen im geforderten Bereich gestreamt:

connection.execute({
  sqlText: 'select * from sometable',
  streamResult: true, // prevent rows from being returned inline in the complete callback
  complete: function(err, stmt, rows) {
    // no rows returned inline because streamResult was set to true
    console.log('rows: ' + rows); // 'rows: undefined'

    // only consume at most the last 5 rows in the result
    rows = [];
    stmt.streamRows({
      start: Math.max(0, stmt.getNumRows() - 5),
      end: stmt.getNumRows() - 1,
    })
    .on('error', function(err) {
      console.error('Unable to consume requested rows');
    })
    .on('data', function(row) {
      rows.push(row);
    })
    .on('end', function() {
      console.log('Number of rows consumed: ' + rows.length);
    });
  }
})

Umwandeln des Datentyps¶

Wenn Ergebniszeilen erzeugt werden, ordnet der Treiber SQL-Datentypen automatisch den entsprechenden JavaScript-Äquivalenten zu. Beispielsweise werden Werte der Typen TIMESTAMP und DATE als JavaScript Date-Objekte zurückgegeben.

Die vollständige Zuordnung von JavaScript zu SQL-Datentypen finden Sie in der folgenden Tabelle:

SQL-Datentyp

JavaScript-Datentyp

Anmerkungen

VARCHAR, CHAR, CHARACTER, STRING, TEXT

String

INT, INTEGER, BIGINT, SMALLINT

Number

Dies ist die Standardzuordnung. Verwenden Sie den Sitzungsparameter JS_TREAT_INTEGER_AS_BIGINT, um eine Zuordnung zu JavaScript Bigint vorzunehmen.

NUMBER(Genauigkeit, Skalierung), DECIMAL(p, s), NUMERIC(p, s), wobei scale = 0

Number

Dies ist die Standardzuordnung. Verwenden Sie den Sitzungsparameter JS_TREAT_INTEGER_AS_BIGINT, um eine Zuordnung zu JavaScript Bigint vorzunehmen.

NUMBER(Genauigkeit, Skalierung), DECIMAL(p, s), NUMERIC(p, s) wobei scale > 0

Number

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

Number

TIMESTAMP, TIMESTAMP_LTZ, TIMESTAMP_NTZ, TIMESTAMP_TZ

Date

TIMESTAMP_NTZ Werte werden in UTC zurückgegeben.

DATE

Date

TIME

String

Beachten Sie, dass der TIME-Datentyp in SQL kein Äquivalent in JavaScript hat, sodass er auf eine JavaScript-Zeichenfolge (String) abgebildet wird.

BOOLEAN

Boolean

VARIANT, ARRAY, OBJECT

JSON

Abrufen von Ganzahl-Datentypen als Bigint¶

Standardmäßig werden die INTEGER-Spalten von Snowflake (einschließlich BIGINT, NUMBER(p, 0) usw.) in den JavaScript-Datentyp Number konvertiert. Die größten zulässigen Snowflake-Ganzzahlwerte sind jedoch größer als die größten zulässigen JavaScript-Zahlenwerte. Um Snowflake-INTEGER-Spalten in JavaScript Bigint zu konvertieren, in denen größere Werte als JavaScript Number gespeichert werden können, legen Sie den Sitzungsparameter JS_TREAT_INTEGER_AS_BIGINT fest.

Es gibt zwei Möglichkeiten, diesen Parameter festzulegen:

Verwenden Sie die ALTER SESSION-Anweisung wie folgt:

connection.execute( {
                    sqlText: 'ALTER SESSION SET JS_TREAT_INTEGER_AS_BIGINT = TRUE',
                    complete: function ...
                    }
                  );

Geben Sie den Parameter in den Verbindungskonfigurationsinformationen an:

var connection = snowflake.createConnection(
      {
      username: 'fakeusername',
      password: 'fakepassword',
      account: 'fakeaccountidentifier',
      jsTreatIntegerAsBigInt: true
      }
    );

Abrufen von Datentypen als Zeichenfolgen (String)¶

Wenn connection.execute() aufgerufen wird, kann die Option fetchAsString so eingestellt werden, dass alle Zahlen oder Daten als Zeichenfolge zurückgegeben werden. Dies kann verwendet werden, um zu Folgendes zu erhalten:

Formatierte Versionen von Werten des Typs DATE und TIMESTAMP (oder deren Varianten).
Zeichenfolgeversionen von numerischen SQL-Typen, die nicht ohne Genauigkeitsverlust in JavaScript-Zahlen umgewandelt werden können.

Beispiel:

connection.execute({
  sqlText: 'select 1.123456789123456789123456789 as "c1"',
  fetchAsString: ['Number'],
  complete: function(err, stmt, rows) {
    if (err) {
      console.error('Failed to execute statement due to the following error: ' + err.message);
    } else {
      console.log('c1: ' + rows[0].c1); // c1: 1.123456789123456789123456789
    }
  }
});

Hochladen einer Datei in einen Snowflake-Stagingbereich¶

Um eine Datei in einen Snowflake-Stagingbereich hochzuladen, verwenden Sie den Befehl PUT.

Im folgenden Beispiel wird gezeigt, wie eine Datei in einen internen Stagingbereich für eine Tabelle mit dem Namen TABLE hochgeladen wird. Sobald eine Datenzeile eingelesen ist, wird dies in der Konsole protokolliert.

connection.execute({
  sqlText: 'PUT file://C:\\Users\\Username\\Files\\employees0*.csv @DATABASE.SCHEMA.%TABLE;',
  complete: function (err)
  {
    var stream = statement.streamRows();
    stream.on('data', function (row)
    {
      console.log(row);
    });
    stream.on('end', function (row)
    {
      console.log('All rows consumed');
    });
  }
});

Beenden einer Verbindung¶

Eine Verbindung kann durch Aufruf der Methode connection.destroy() beendet werden. Dadurch wird die Verbindung zur Sitzung sofort beendet, ohne darauf zu warten, dass die in Ausführung befindlichen Anweisungen abgeschlossen werden:

connection.destroy(function(err, conn) {
  if (err) {
    console.error('Unable to disconnect: ' + err.message);
  } else {
    console.log('Disconnected connection with id: ' + connection.getId());
  }
});