Verwenden des Node.js-Treibers

.

Verwandte Themen

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

  1. Erstellen Sie eine Verbindung zu Snowflake.

  2. Führen Sie die Anweisungen aus (z. B. SQL-Abfragen oder DDL/DML-Befehle).

  3. Verarbeiten Sie die von Snowflake zurückgegebenen Abfrageergebnisse.

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

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

So erstellen Sie eine einzelne Verbindung zu Snowflake:

  1. Rufen Sie snowflake.createConnection auf, um ein neues Connection-Objekt zu erstellen, und übergeben Sie ein JavaScript-Objekt, das die Verbindungsoptionen angibt.

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

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

  2. 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 = statement.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

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

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.

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 Sekunden, in denen die Verbindung aufrechterhalten wird, ohne dass eine Antwort erfolgt. Standardeinstellung: 60.

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:

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:

  1. Setzen Sie die Option authenticator auf EXTERNALBROWSER.

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

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

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

  1. Konfigurieren Sie die Schlüsselpaar-Authentifizierung, wie unter Schlüsselpaar-Authentifizierung und Schlüsselpaar-Rotation erläutert.

  2. 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",
  privateKeyFile: "<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());
    }
  }
});

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.

Binden eines Array 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');
  }
});

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(
      {
      accessUrl: 'http://myorganization-myaccount.snowflakecomputing.com',
      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());
  }
});