Node.jsドライバーの使用

.

関連トピック

• クエリ構文

• SQL コマンドリファレンス

• SQL 関数リファレンス

ドライバーを使用するための一般的なワークフローは次のとおりです。

1. Snowflakeへの接続を作成します。

2. ステートメントを実行します（例: SQL クエリまたは DDL/DML コマンド）。

3. Snowflakeから返されたクエリ結果を使用します。

4. 接続を終了します。

重要

Snowflakeステージからファイルをアップロードおよびダウンロードするには、次の最小バージョンのドライバーを使用する必要があります。

• ファイルをアップロードするには、バージョン1.6.2（PUT コマンドを使用）

• ファイルをダウンロードするには、バージョン1.6.6（GET コマンドを使用）

このトピックの内容:

接続の確立

Snowflakeに対してステートメントを実行するには、最初に接続を確立する必要があります。Snowflake Node.jsドライバーを使用すると、次の方法で接続を確立できます。

• 単一の接続を作成する

• 接続のプールを作成する

単一の接続の作成

Snowflakeへの単一の接続を作成するには、

1. snowflake.createConnection を呼び出して新しい Connection オブジェクトを作成し、 接続オプション を指定する JavaScript オブジェクトを渡します。

2. Connection オブジェクトを使用して connect メソッドを呼び出し、接続を確立します。

   注釈

   authenticator オプションを EXTERNALBROWSER （ブラウザーベースの SSO を使用するため）、または https://<Oktaアカウント名>.okta.com （Oktaを介したネイティブ SSO を使用するため）に設定した場合、 connect メソッドではなく connectAsync メソッドを呼び出します。

   接続エラーを処理するには、次の署名を持つコールバック関数を渡します。

   function(err, conn)
   

   条件:

   • err は、 JavaScript Error オブジェクトです。

   • conn は、現在の Connection オブジェクトです。

   接続中にエラーが発生した場合、 connect メソッドは Error オブジェクトをコールバック関数に渡します。コールバック関数でこのオブジェクトを使用すると、エラーの詳細を取得できます。現在の Connection オブジェクトに関する情報が必要な場合は、コールバック関数に渡された conn 引数を使用できます。

次の例では、接続を確立し、認証にパスワードを使用します。他の認証方法を使用するには、 認証オプション をご参照ください。

// 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();
            }
    }
);

接続を作成するときは、 接続オプションの設定 の説明に従って接続オプションを設定できます。

接続プールの作成

クライアントアプリケーションがSnowflakeにアクセスする必要があるたびに接続を作成する代わりに、必要に応じて再利用できるSnowflake接続のキャッシュを定義できます。接続プーリングは、通常、接続を確立するための遅延時間を短縮します。ただし、DNS の問題が発生すると、代替の DNS へのクライアントフェールオーバーが遅くなる可能性があります。

接続プールを作成するには、

1. snowflake.createPool(connectionOptions, poolOptions) を呼び出して新しい ConnectionPool オブジェクトを作成し、 接続オプション とプールオプションを指定する2つの JavaScript オブジェクトを渡します。

   注釈

   Snowflake Node.jsドライバーは、接続プールを実装するためにオープンソースの ノード-プール ライブラリを使用します。サポートされている poolOptions については、 ノード-プールライブラリのドキュメント の opts 引数の説明をご参照ください。

2. ConnectionPool オブジェクトを使用して、 use 関数を呼び出し、接続プール内にある単一の接続のステートメントを実行します。

   接続エラーを処理するには、次の署名を持つコールバック関数を渡します。

   function(err, stmt, rows)
   

   条件:

   • err は、 JavaScript Error オブジェクトです。

   • stmt は、ステートメントのリテラルテキストを含む、実行された SQL ステートメントに関する情報を持つオブジェクトです。

   • rows は、ステートメントの「結果セット」を含む配列です。

   
   

   ステートメントの実行中にエラーが発生した場合、 connect メソッドは Error オブジェクトをコールバック関数に渡します。コールバック関数でこのオブジェクトを使用すると、エラーの詳細を取得できます。

次の例では、最大10個のアクティブな接続をサポートする接続プールを作成します。認証にパスワードを使用します。他の認証方法を使用するには、 認証オプション をご参照ください。

// 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
    }
);
  

次の例では、プール内の接続を使用して SQL ステートメントを実行するために、 connectionPool.use メソッドを使用します。 clientConnection.execute メソッドは、実行する SQL ステートメントを指定し、コールバック関数を定義します。

// 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');
            });
        }
    });
});

接続プールを作成するときは、 接続オプションの設定 の説明に従って接続オプションを設定できます。

接続オプションの設定

新しい Connection オブジェクトを構築するときは、接続のオプション（例: 使用するアカウント識別子、ユーザー名など）を指定する JavaScript オブジェクトで渡します。次のセクションでは、設定できるオプションについて説明します。オプションを設定するには、 JavaScript オブジェクトのプロパティ名としてオプション名を指定します。

• 必要な接続オプション

• 認証オプション

• 追加の接続オプション

必要な接続オプション

account

使用する アカウント識別子。

username

SnowflakeユーザーまたはIDプロバイダーのログイン名（例: Oktaのログイン名）。

region （廃止）

アカウントが存在する リージョン の ID。

注釈

このオプションは廃止されており、下位互換性のためにのみここに含まれています。Snowflakeは、 アカウントロケーターを識別子として使用する で説明されているように、アカウント識別子へのリージョン埋め込み（例: 以下）に移行することをお勧めします。

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

加えて、 サーバーに対する認証のオプション を指定する必要があります。

認証オプション

application

Snowflakeに接続するクライアントアプリケーションの名前を指定します。

authenticator

ユーザーログイン認証情報の検証に使用する認証方式を指定します。これは、次のいずれかの値に設定できます。

値	説明
SNOWFLAKE	内部Snowflake認証方式を使用します。 password オプションも設定する必要があります。
EXTERNALBROWSER	自分のウェブブラウザーを使用 して、Okta、 ADFS、またはアカウントに定義されている他の SAML 2.0準拠の識別プロバイダー（IdP）で認証します。
https://<Oktaアカウント名>.okta.com	Oktaを介したネイティブ SSO の使用。
OAUTH	認証には OAuth を使用します。また、 token オプションを OAuth トークンに設定する必要があります（以下を参照）。
SNOWFLAKE_JWT	キーペア認証を使用します。 キーペア認証およびキーペアローテーションの使用 をご参照ください。

デフォルト値は SNOWFLAKE です。

認証の詳細については、 フェデレーション認証の管理/使用 および OAuth のクライアント、ドライバー、およびコネクター をご参照ください。

password

ユーザーのパスワード。 authenticator オプションを SNOWFLAKE を設定するか、 Oktaアカウント用のOkta URL エンドポイント （例: https://<Oktaアカウント名>.okta.com）を設定した場合や、 authenticator オプションを未設定にした場合は、このオプションを設定します。

token

認証に使用する OAuth トークンを指定します。 authenticator オプションを OAUTH に設定する場合は、このオプションを設定します。

privateKey

キーペア認証の秘密キー（ PEM 形式内）を指定します。詳細については、 キーペア認証およびキーペアローテーションの使用 をご参照ください。

privateKeyPath

秘密キーファイル（例: rsa_key.p8）に対するローカルパスを指定します。詳細については、 キーペア認証およびキーペアローテーションの使用 をご参照ください。

privateKeyPass

ファイルが暗号化されている場合に、秘密キーファイルを復号化するためのパスコードを指定します。詳細については、 キーペア認証およびキーペアローテーションの使用 をご参照ください。

追加の接続オプション

arrayBindingThreshold

ドライバーが一括挿入操作で使用するバインドの最大数を設定します。デフォルト値は100000（100K）です。

clientSessionKeepAlive

デフォルトでは、クライアント接続は通常、最新のクエリが実行されてから約3～4時間後にタイムアウトします。

clientSessionKeepAlive オプションが true に設定されている場合、クエリが実行されなくても、サーバーへのクライアントの接続は無期限に維持されます。

このオプションのデフォルト設定はfalseです。

このオプションを true に設定する場合は、プログラムの終了時にプログラムがサーバーから明示的に切断されていることを確認します。切断せずに終了しないでください。

clientSessionKeepAliveHeartbeatFrequency

（ clientSessionKeepAlive がtrueの場合にのみ適用）

ハートビートメッセージの頻度（秒単位の間隔）を設定します。

接続ハートビートメッセージは、クエリを置き換え、接続のタイムアウトカウントダウンを再開するものと大まかに考えることができます。つまり、少なくとも4時間の非アクティブ後に接続がタイムアウトすると、ハートビートはタイマーをリセットし、最新のハートビート（またはクエリ）の少なくとも4時間後までタイムアウトが発生しないようにします。

デフォルト値は3600秒（1時間）です。有効な値の範囲は900～3600です。通常、タイムアウトは少なくとも4時間後に発生するため、通常、接続を維持するには1時間ごとのハートビートで十分です。3600秒未満のハートビート間隔が必要になることはほとんどありません。

database

接続後にセッションに使用するデフォルトのデータベース。

noProxy

プロキシサーバーをバイパス（例: *.amazonaws.com が Amazon S3のアクセスをバイパス）して、ドライバーが直接接続する必要があるホストのリストを指定します。複数のホストの場合は、ホスト名をパイプ記号（|）で区切ります。アスタリスクをワイルドカードとして使用することもできます。例:

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

proxyHost

認証されたプロキシサーバーのホスト名を指定します。

proxyPassword

proxyUser により指定されたユーザーのパスワードを指定します。

proxyPort

認証されたプロキシサーバーのポートを指定します。

proxyProtocol

認証されたプロキシサーバーへの接続に使用するプロトコルを指定します。このプロパティを使用して HTTP （http または https）のプロトコルを指定します:。

proxyUser

認証されたプロキシサーバーへの接続に使用されるユーザー名を指定します。

resultPrefetch

クライアントが大きな結果セットをプリフェッチするために使用するスレッドの数。有効な値: 1～10。

role

接続後にセッションに使用するデフォルトのセキュリティロール。

schema

接続後にセッションに使用するデフォルトのスキーマ。

timeout

応答なしで接続を維持するためのミリ秒数。デフォルト: 60000（1分）。

warehouse

接続後にセッションに使用するデフォルトの仮想ウェアハウス。クエリの実行、データのロードなどに使用されます。

一部の接続オプションは、指定されたデータベースオブジェクト（データベース、スキーマ、ウェアハウス、またはロール）がシステムに既に存在することを前提としています。指定したオブジェクトが存在しない場合は、接続中にデフォルトは設定されません。

接続後、オプションの接続オプションはすべて USE <オブジェクト> コマンドで設定または上書きすることもできます。

Snowflakeに対する認証

Snowflakeに対する認証には、次のいずれかのオプションを使用できます。

• パスワードベースの認証。これを使用するには、接続を確立するときに password オプションを設定します。

• ウェブブラウザーを介した シングルサインオン（SSO）。

• Oktaを介したネイティブ SSO。

• キーペア認証。

• OAuth。

ウェブブラウザーを介したシングルサインオン（SSO）の使用

シングルサインオン（SSO）を使用するようにSnowflakeを構成 している場合は、認証にブラウザーベースの SSO を使用するようにクライアントアプリケーションを構成できます。

アプリケーションコード内で、

1. authenticator オプションを EXTERNALBROWSER に設定します。

2. 接続を確立するには、 connect メソッドではなく connectAsync メソッドを呼び出します。

例:

// 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({...});
});

認証にブラウザーベースの SSO を使用する方法の詳細については、 ブラウザーベース SSO をご参照ください。

Oktaを介したネイティブ SSO の使用

Oktaを介して シングルサインオン（SSO）を使用するようにSnowflakeを構成 している場合は、Oktaを介してネイティブ SSO 認証を使用するようにクライアントアプリケーションを構成できます。

アプリケーションコード内で、

1. 次のオプションを設定します。

   • authenticator オプションをOktaアカウントのOkta URL エンドポイントに設定します（例: https://<Oktaアカウント名>.okta.com）。

   • username および password オプションをIDプロバイダー（IdP）のユーザー名とパスワードに設定します。

2. 接続を確立するには、 connect メソッドではなく connectAsync メソッドを呼び出します。

例:

// 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({...});

Oktaを介したネイティブ SSO 認証の使用の詳細については、 ネイティブ SSO --- Oktaのみ をご参照ください。

キーペア認証およびキーペアローテーションの使用

ドライバーは、キーペア認証とキーローテーションをサポートします。これを使用するには、

1. キーペア認証およびキーペアローテーション で説明されているように、キーペア認証を構成します。

2. アプリケーションコード内で、

   1. authenticator オプションを SNOWFLAKE_JWT に設定します。

   2. 秘密キーを使用して、次のいずれかの方法で認証します。

      • privateKey オプションを秘密キーに設定します。

      • privateKeyPath オプションを秘密キーファイルへのパスに設定します。

        ファイルが暗号化されている場合は、 privateKeyPass オプションをパスフレーズに設定して秘密キーを復号化する必要もあります。

次の例では、ファイルから秘密キーをロードし、 privateKey オプションを秘密キーに設定します。

// 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({...});

次の例では、 privateKeyPath オプションを暗号化された秘密キーファイルに設定し、 privateKeyPass オプションを秘密キーの復号化に使用されるパスフレーズに設定します。

// 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({...});

OAuth の使用

OAuth を使用して接続するには、 authenticator オプションを OAUTH に設定し、 token オプションを OAuth アクセストークンに設定します。例:

// 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({...});

詳細については、 OAuth のクライアント、ドライバー、およびコネクター をご参照ください。

認証されたプロキシを介した接続

Connection オブジェクトを作成するときに、接続オプションとして認証情報を提供することにより、認証されたプロキシを介してSnowflakeに接続できます。

注釈

Snowflake Node.jsドライバーのバージョン1.6.4以降、認証済みプロキシサーバーを介した接続がサポートされています。

次の例は、 HTTP を使用して認証されたプロキシに接続する方法を示しています。

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

HTTPS を使用して認証済みプロキシに接続するには、以下に示すように proxyProtocol 接続プロパティも指定する必要があります。

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

SnowCD を使用したSnowflakeへのネットワーク接続の検証

ドライバーを設定したら、 SnowCD を使用して、Snowflakeへのネットワーク接続を評価およびトラブルシューティングできます。

初期設定プロセス中にオンデマンドで SnowCD をいつでも使用して、Snowflakeへのネットワーク接続を評価およびトラブルシューティングできます。

OCSP （オンライン証明書状態プロトコル）

ドライバーが接続すると、Snowflakeは証明書を送信して、Snowflakeを偽装しているホストではなく、Snowflakeへの接続であることを確認します。ドライバーはその証明書を OCSP （オンライン証明書状態プロトコル）サーバーに送信し、証明書が失効していないことを確認します。

ドライバーが証明書を確認するために OCSP サーバーに到達できない場合、ドライバーは "fail open" or "fail closed" できます。

フェールオープンまたはフェールクローズモードの選択

1.2.0より前のバージョンのNode.jsドライバーは、デフォルトでフェールクローズになります。バージョン1.2.0以降はデフォルトでフェールオープンになります。 snowflake.createConnection() メソッドを呼び出す前に ocspFailOpen グローバルパラメーターを設定することにより、デフォルトの動作を上書きできます。パラメーターは、trueまたはfalseに設定できます。

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

OCSP コネクタまたはドライバーバージョンの確認

ドライバーまたはコネクタのバージョン、構成、および OCSP の動作の詳細については、 OCSP 設定 をご参照ください。

ステートメントの実行

ステートメントは connection.execute() メソッドを呼び出すことで実行できます。 execute() メソッドは、 SQL テキストと complete コールバックを指定するために使用できる options オブジェクトを受け入れます。 complete コールバックは、ステートメントの実行が終了し、結果を使用する準備ができたときに呼び出されます。

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());
    }
  }
});

注釈

1回のリクエストの最大ペイロードサイズは16 MB です。

ステートメントパラメーターのバインド

時には、ステートメント内のデータをプレースホルダーにバインドする場合があります。この方法でステートメントを実行すると、 SQL インジェクション攻撃の防止に役立つため便利です。次のステートメントを考慮します。

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

次のバインドを使用して同じ結果を達成できます。

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

バインドの ? 構文もサポートされています。

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

注釈

バインドできるデータのサイズ、またはバッチで結合できるデータのサイズには上限があります。詳細については、 クエリテキストサイズの制限 をご参照ください。

SQL ステートメントのバッチの実行（複数ステートメントのサポート）

Node.jsコネクタのバージョン1.6.18以降では、セミコロンで区切られた SQL ステートメントのバッチを送信して、単一のリクエストで実行することができます。

注釈

デフォルトでは、Snowflakeは、複数のステートメントで発行されたクエリに対してエラーを返します。この動作は、 SQL インジェクション から保護するために部分的に行われます。複数ステートメント機能を使用すると、 SQL インジェクションを受ける可能性があるため、慎重に使用する必要があります。 SnowflakeStatement.setParameter() メソッドを使用して実行するステートメントの数を指定すると、ステートメントを追加して注入することがより困難になるため、リスクを軽減できます。詳細については、 インターフェイス： SnowflakeStatement をご参照ください。

複数のステートメントを含むクエリは、クエリ文字列にセミコロンで区切られた複数のステートメントが含まれていることを除いて、単一ステートメントのクエリと同じ方法で実行できます。

複数のステートメントを許可するには、次の2つの方法があります。

• Statement.setParameter("MULTI_STATEMENT_COUNT", n) を呼び出して、このステートメントが一度に実行できるステートメントの数を指定します。

• 次のコマンドの1つを実行して、セッションレベルまたはアカウントレベルで MULTI_STATEMENT_COUNT パラメーターを設定します。

  alter session set MULTI_STATEMENT_COUNT = 0;
  

  または、

  alter account set MULTI_STATEMENT_COUNT = 0;
  

  パラメーターを0に設定すると、ステートメントの数に制限がなくなります。パラメーターを1に設定すると、一度に1つのステートメントのみが許可されます。

次の例では、セッションレベルでステートメントの数を無制限に設定し、3つの SQL ステートメントを実行します。

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
    }
  }
});

一括挿入の配列のバインド

データの配列のバインドは、一括 INSERT 操作でサポートされています。次のように配列の配列を渡します。

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

注釈

大きな配列をバインドするとパフォーマンスに影響し、データのサイズが大きすぎてサーバーで処理できない場合は拒否される可能性があります。

ステートメントのキャンセル

statement.cancel() メソッドを呼び出すと、ステートメントをキャンセルできます。

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

リクエストの再送信

ネットワークエラーまたはタイムアウトなどが原因で、Snowflakeが SQL ステートメントを正常に実行したかどうかが分からない場合は、リクエスト ID を使用して同じステートメントを再送信できます。たとえば、データを追加するために INSERT コマンドを送信したが、確認応答がタイムリーに受信されなかったため、コマンドで何が起こったのかが分からない場合があります。このシナリオでは、コマンドを2回実行してデータの重複が発生する可能性があるため、同じコマンドを新しいコマンドとして実行することは望ましくありません。

SQL ステートメントにリクエスト ID を含めると、データが重複する可能性を回避できます。最初のリクエストからのリクエスト ID を使用してリクエストを再送信すると、最初のリクエストが失敗した場合にのみ、再送信されたコマンドが実行されるようになります。詳細については、 SQL ステートメントの実行リクエストの再送信 をご参照ください。

次のコードサンプルは、リクエスト ID を保存して使用し、ステートメントを再送信する方法を示しています。ステートメントを実行すると、 getRequestId() 関数を使用して、送信されたリクエストの ID を取得できます。そうすると、その ID を使用して、後で同じステートメントを実行できます。次の例では、INSERT ステートメントを実行し、そのリクエスト ID を requestId 変数に保存します。

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

コマンドが正常に実行されたという確認を受信しない場合は、示されているように、保存されたリクエスト ID を使用してリクエストを再送信できます。

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

requestId と sqlText を使用したリクエストの再送信を選択する場合は、次の相互作用に注意してください。

• requestId がすでに存在する場合、つまり以前のリクエストと一致する場合、コマンドは sqlText クエリを無視し、元のコマンドからクエリを再送信します。

• requestId が存在しない場合、つまり以前のリクエストと一致しない場合、コマンドは sqlText クエリを実行します。

結果の利用

インラインによる結果の返答

結果を利用する最も一般的な方法は、 connection.execute() に complete コールバックを渡すことです。ステートメントの実行が終了し、結果を使用できる状態になると、 complete コールバックが呼び出され、結果行がインラインで返されます。

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);
    }
  }
});

結果のストリーミング

結果を行のストリームとして使用することもできます。これは、 statement.streamRows() メソッドを呼び出すことで実行できます。これは、受信した行を使用するために使用できるNode.js Readable ストリームを返します。 Readable ストリームの詳細については、 Node.jsのドキュメント をご参照ください。

例:

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

結果のバッチ処理

デフォルトでは、 statement.streamRows() メソッドは結果のすべての行を含むストリームを生成します。ただし、結果のサブセットのみを使用する場合、または結果行をバッチで使用する場合は、 start および end 引数で streamRows() を呼び出すことができます。これらの追加オプションを指定すると、リクエストされた範囲内の行のみがストリーミングされます。

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);
    });
  }
})

データ型のキャスト

結果の行が生成されると、ドライバーは対応する JavaScriptSQL 相当物にデータ型を自動的にマッピングします。たとえば、タイプ TIMESTAMP および DATE の値は JavaScript 日付オブジェクトとして返されます。

JavaScript から SQL データ型への完全なマッピングについては、以下のテーブルをご参照ください。

SQL データ型	JavaScript データ型	メモ
VARCHAR, CHAR, CHARACTER, STRING, TEXT	String
INT, INTEGER, BIGINT, SMALLINT	Number	これがデフォルトのマッピングです。セッションパラメーター JS_TREAT_INTEGER_AS_BIGINT を使用して、 JavaScript Bigintにマッピングします。
scale = 0で、NUMBER（精度、スケール）、 DECIMAL（p、s）、 NUMERIC（p、s）	Number	これがデフォルトのマッピングです。セッションパラメーター JS_TREAT_INTEGER_AS_BIGINT を使用して、 JavaScript Bigintにマッピングします。
scale > 0で、NUMBER（精度、スケール）、 DECIMAL（p、s）、 NUMERIC（p、s）	Number
FLOAT, FLOAT4, FLOAT8, DOUBLE, DOUBLE PRECISION, REAL	Number
TIMESTAMP, TIMESTAMP_LTZ, TIMESTAMP_NTZ, TIMESTAMP_TZ	Date	TIMESTAMP_NTZ 値は UTCに返されます。
DATE	Date
TIME	String	SQL の TIME データ型には JavaScript に相当するものがないため、 JavaScript 文字列にマッピングされます。
BOOLEAN	Boolean
VARIANT, ARRAY, OBJECT	JSON

Bigintとしての整数データ型の取得

デフォルトでは、Snowflake INTEGER 列（ BIGINT、 NUMBER（p、0）などを含む）は JavaScriptのNumberデータ型に変換されます。ただし、有効なSnowflake整数の最大値は、有効な JavaScript Numberの最大値よりも大きくなります。Snowflakeの INTEGER 列を、 JavaScript Numberより大きな値を保存できる JavaScript Bigintに変換するには、セッションパラメーター JS_TREAT_INTEGER_AS_BIGINTを設定します。

このパラメーターを設定するには次の2つの方法があります。

• 以下に示すように、 ALTER SESSION ステートメントを使用します。

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

• 接続構成情報でパラメーターを指定します。

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

文字列としたデータ型のフェッチ

connection.execute() が呼び出されると、 fetchAsString オプションを設定して、すべての数値または日付を強制的に文字列として返すことができます。これは以下を取得するために使用できます。

• タイプ DATE および TIMESTAMP （またはそのバリアント）の値のフォーマットされたバージョン。

• 精度を損なうことなく JavaScript 数値に変換できない、数値表記の SQL 型の文字列バージョン。

例:

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
    }
  }
});

Snowflakeステージへのファイルのアップロード

Snowflakeステージにファイルをアップロードするには、 PUT コマンドを使用します。

次の例は、 TABLE という名前のテーブルの内部ステージにファイルをアップロードする方法を示しています。データの各行がインジェストされると、コンソールに記録されます。

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

接続の終了

connection.destroy() メソッドを呼び出すことにより、接続を終了できます。これにより、実行中のステートメントの完了を待たずに、接続に関連付けられたセッションが直ちに終了します。

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