Databricks SQL ドライバー for Node.js

Databricks SQLDriver forNode.js Node.jsは、JavaScript コードを使用してSQL Databricksコンピュート リソースに対して コマンドを実行できる ライブラリです。

必要条件

• Node.js バージョン 14 以降を実行している開発マシン。 インストールされている Node.jsのバージョンを印刷するには、コマンド node -v を実行します。 さまざまなバージョンの Node.js をインストールして使用するには、 Node Version Manager (nvm) などのツールを使用できます。

• ノード パッケージ マネージャー (npm)。 Node.js の新しいバージョンには、すでに npmが含まれています。 npmがインストールされているかどうかを確認するには、コマンドnpm -vを実行します。必要に応じて npm をインストールするには、「 npm のダウンロードとインストール」などの手順に従います。

• npm の @databricks/sql パッケージ。Node.js プロジェクトに @databricks/sql パッケージを依存関係としてインストールするには、 npm を使用して、プロジェクトと同じディレクトリ内から次のコマンドを実行します。

  Bash

  npm i @databricks/sql

• Node.jsプロジェクトにTypeScriptをdevDependenciesとしてインストールして使用する場合は、npmを使用して、プロジェクトと同じディレクトリ内から次のコマンドを実行します。

  Bash

  npm i -D typescript
  npm i -D @types/node

• 既存の クラスター または SQLウェアハウス。

• 既存のクラスターまたはSQL ウェアハウスの サーバーホスト名 と HTTPパス の値。

  • クラスターのためにこれらの値を取得します。
  • SQLウェアハウスのこれらの値を取得します。

認証

Databricks SQL Driver for Node.js では、次の Databricks 認証の種類がサポートされています。

• Databricks個人用アクセストークン認証
• OAuthマシン間 (M2M) 認証
• OAuthユーザー対マシン (U2M) 認証

注記

Databricks のユーザー名とパスワードを使用した基本認証は、2024 年 7 月 10 日にサポートが終了しました。 「Databricks で管理されるパスワードのサポート終了」を参照してください。

注記

セキュリティのベスト プラクティスとして、接続変数の値をコードにハード コーディングしないでください。 代わりに、これらの接続変数値を安全な場所から取得する必要があります。 たとえば、この記事のコード スニペットと例では、環境変数を使用しています。

Databricks 個人用アクセス トークン認証

Databricks SQL Driver for Node.jsを認証で使用するには、まずDatabricks個人アクセストークンを作成する必要があります。 このステップの詳細については、 「ワークスペース ユーザー向けの個人アクセストークンの作成」を参照してください。

Databricks SQL Driver for Node.js を認証するには、次のようにします。 次のコード スニペットを使用します。 このスニペットは、次の環境変数を設定していることを前提としています。

• DATABRICKS_SERVER_HOSTNAMEクラスターまたはウェアハウスの Server Hostname 値 SQLに設定します。
• DATABRICKS_HTTP_PATHで、クラスターまたはSQL ウェアハウスの HTTP パス 値に設定します。
• DATABRICKS_TOKENで、Databricks 個人用アクセス トークンに設定されます。

環境変数を設定するには、オペレーティングシステムのドキュメントを参照してください。

JavaScript

JavaScript

const { DBSQLClient } = require('@databricks/sql');

const serverHostname = process.env.DATABRICKS_SERVER_HOSTNAME;
const httpPath = process.env.DATABRICKS_HTTP_PATH;
const token = process.env.DATABRICKS_TOKEN;

if (!token || !serverHostname || !httpPath) {
  throw new Error(
    'Cannot find Server Hostname, HTTP Path, or ' +
      'personal access token. ' +
      'Check the environment variables DATABRICKS_SERVER_HOSTNAME, ' +
      'DATABRICKS_HTTP_PATH, and DATABRICKS_TOKEN.',
  );
}

const client = new DBSQLClient();
const connectOptions = {
  token: token,
  host: serverHostname,
  path: httpPath,
};

client.connect(connectOptions);
// ...

TypeScript

TypeScript

import { DBSQLClient } from '@databricks/sql';

const serverHostname: string = process.env.DATABRICKS_SERVER_HOSTNAME || '';
const httpPath: string = process.env.DATABRICKS_HTTP_PATH || '';
const token: string = process.env.DATABRICKS_TOKEN || '';

if (token == '' || serverHostname == '' || httpPath == '') {
  throw new Error(
    'Cannot find Server Hostname, HTTP Path, or personal access token. ' +
      'Check the environment variables DATABRICKS_SERVER_HOSTNAME, ' +
      'DATABRICKS_HTTP_PATH, and DATABRICKS_TOKEN.',
  );
}

const client: DBSQLClient = new DBSQLClient();
const connectOptions = {
  token: token,
  host: serverHostname,
  path: httpPath,
};

client.connect(connectOptions);
// ...

OAuth ユーザー間 (U2M) 認証

Node.js 用 Databricks SQL ドライバー バージョン 1.3.0 以降では、 OAuth ユーザーマシン (U2M) 認証がサポートされています。

OAuth U2M 認証を使用して Databricks SQL Driver for Node.js を認証するには、次のコード スニペットを使用します。 このスニペットは、次の環境変数を設定していることを前提としています。

• DATABRICKS_SERVER_HOSTNAMEクラスターまたはウェアハウスの Server Hostname 値 SQLに設定します。
• DATABRICKS_HTTP_PATHで、クラスターまたはSQL ウェアハウスの HTTP パス 値に設定します。

環境変数を設定するには、オペレーティングシステムのドキュメントを参照してください。

JavaScript

JavaScript

const { DBSQLClient } = require('@databricks/sql');

const serverHostname = process.env.DATABRICKS_SERVER_HOSTNAME;
const httpPath = process.env.DATABRICKS_HTTP_PATH;

if (!serverHostname || !httpPath) {
  throw new Error(
    'Cannot find Server Hostname or HTTP Path. ' +
      'Check the environment variables DATABRICKS_SERVER_HOSTNAME ' +
      'and DATABRICKS_HTTP_PATH.',
  );
}

const client = new DBSQLClient();
const connectOptions = {
  authType: 'databricks-oauth',
  host: serverHostname,
  path: httpPath,
};

client.connect(connectOptions);
// ...

TypeScript

TypeScript

import { DBSQLClient } from '@databricks/sql';

const serverHostname: string = process.env.DATABRICKS_SERVER_HOSTNAME || '';
const httpPath: string = process.env.DATABRICKS_HTTP_PATH || '';

if (serverHostname == '' || httpPath == '') {
  throw new Error(
    'Cannot find Server Hostname or HTTP Path. ' +
      'Check the environment variables DATABRICKS_SERVER_HOSTNAME ' +
      'and DATABRICKS_HTTP_PATH.',
  );
}

const client: DBSQLClient = new DBSQLClient();
const connectOptions = {
  authType: 'databricks-oauth',
  host: serverHostname,
  path: httpPath,
};

client.connect(connectOptions);
// ...

OAuth マシン間 (M2M) 認証

Node.js 用 Databricks SQL ドライバー バージョン 1.5.0 以降では、 OAuth マシン間 (M2M) 認証がサポートされています。

OAuth M2M 認証で Databricks SQL ドライバーを Node.js で使用するには、次の操作を行う必要があります。

1. DatabricksワークスペースにDatabricks サービスプリンシパルを作成し、そのサービスプリンシパルのOAuthシークレットを作成します。

   サービスプリンシパルとそのOAuthシークレットを作成するには、「サービスプリンシパルのアクセスをOAuthでDatabricksに許可する」を参照してください。サービスプリンシパルの UUID または アプリケーション ID の値と、サービスプリンシパルのOAuthシークレットの Secret 値をメモします。

2. サービスプリンシパルにクラスターまたはウェアハウスへのアクセス権を付与します。 「コンピュートの権限」または「SQLウェアハウスの管理」を参照してください。

Databricks SQL Driver for Node.js を認証するには、次のようにします。 次のコード スニペットを使用します。 このスニペットは、次の環境変数を設定していることを前提としています。

• DATABRICKS_SERVER_HOSTNAMEクラスターまたはウェアハウスの Server Hostname 値 SQLに設定します。
• DATABRICKS_HTTP_PATHで、クラスターまたはSQL ウェアハウスの HTTP パス 値に設定します。
• DATABRICKS_CLIENT_IDで、サービスプリンシパルの UUID または アプリケーション ID の値に設定します。
• DATABRICKS_CLIENT_SECRETで、サービスプリンシパルの OAuth シークレットの Secret 値に設定します。

環境変数を設定するには、オペレーティングシステムのドキュメントを参照してください。

JavaScript

JavaScript

const { DBSQLClient } = require('@databricks/sql');

const serverHostname = process.env.DATABRICKS_SERVER_HOSTNAME;
const httpPath = process.env.DATABRICKS_HTTP_PATH;
const clientId = process.env.DATABRICKS_CLIENT_ID;
const clientSecret = process.env.DATABRICKS_CLIENT_SECRET;

if (!serverHostname || !httpPath || !clientId || !clientSecret) {
  throw new Error(
    'Cannot find Server Hostname, HTTP Path, or ' +
      'service principal ID or secret. ' +
      'Check the environment variables DATABRICKS_SERVER_HOSTNAME, ' +
      'DATABRICKS_HTTP_PATH, DATABRICKS_CLIENT_ID, and ' +
      'DATABRICKS_CLIENT_SECRET.',
  );
}

const client = new DBSQLClient();
const connectOptions = {
  authType: 'databricks-oauth',
  host: serverHostname,
  path: httpPath,
  oauthClientId: clientId,
  oauthClientSecret: clientSecret,
};

client.connect(connectOptions);
// ...

TypeScript

TypeScript

import { DBSQLClient } from '@databricks/sql';

const serverHostname: string = process.env.DATABRICKS_SERVER_HOSTNAME || '';
const httpPath: string = process.env.DATABRICKS_HTTP_PATH || '';
const clientId: string = process.env.DATABRICKS_CLIENT_ID || '';
const clientSecret: string = process.env.DATABRICKS_CLIENT_SECRET || '';

if (serverHostname == '' || httpPath == '' || clientId == '' || clientSecret == '') {
  throw new Error(
    'Cannot find Server Hostname, HTTP Path, or ' +
      'service principal ID or secret. ' +
      'Check the environment variables DATABRICKS_SERVER_HOSTNAME, ' +
      'DATABRICKS_HTTP_PATH, DATABRICKS_CLIENT_ID, and ' +
      'DATABRICKS_CLIENT_SECRET.',
  );
}

const client: DBSQLClient = new DBSQLClient();
const connectOptions = {
  authType: 'databricks-oauth',
  host: serverHostname,
  path: httpPath,
  oauthClientId: clientId,
  oauthClientSecret: clientSecret,
};

client.connect(connectOptions);
// ...

User-Agent の設定

次のコード例は、使用状況の追跡のために User-Agent アプリケーションの product_name を設定する方法を示しています。

JavaScript

JavaScript

const { DBSQLClient } = require('@databricks/sql');

const client = new DBSQLClient();
client.connect({
  host: process.env.DATABRICKS_SERVER_HOSTNAME,
  path: process.env.DATABRICKS_HTTP_PATH,
  token: process.env.DATABRICKS_TOKEN,
  userAgentEntry: 'product_name',
});

データのクエリ

次のコード例は、Databricks SQL DriverNode.js SQLforDatabricks を呼び出して、 コンピュート リソースに対して基本的な クエリを実行する方法を示しています。このコマンドは、samples カタログの nyctaxi スキーマの trips テーブルから最初の 2 つのローを返します。

注記

次のコード例は、認証に Databricks 個人用アクセス トークンを使用する方法を示しています。 代わりに使用可能な他の Databricks 認証の種類を使用するには、「 認証」を参照してください。

このコード例では、一連の Databricks 環境変数から token、 server_hostname 、 http_path 接続変数の値を取得します。 これらの環境変数には、次の環境変数名があります。

• DATABRICKS_TOKENこれは、要件からの Databricks 個人用アクセス トークンを表します。
• DATABRICKS_SERVER_HOSTNAMEこれは、要件の サーバーホスト名 の値を表します。
• DATABRICKS_HTTP_PATH、これは要件からの HTTP Path 値を表します。

他の方法を使用して、これらの接続変数値を取得できます。 環境変数の使用は、多くのアプローチの1つにすぎません。

次のコード例は、Node.js の Databricks SQL コネクタを呼び出して、クラスターまたは SQLウェアハウスで基本的な SQL コマンドを実行する方法を示しています。 このコマンドは、 trips テーブルから最初の 2 行を返します。

JavaScript

JavaScript

const { DBSQLClient } = require('@databricks/sql');

const token = process.env.DATABRICKS_TOKEN;
const serverHostname = process.env.DATABRICKS_SERVER_HOSTNAME;
const httpPath = process.env.DATABRICKS_HTTP_PATH;

if (!token || !serverHostname || !httpPath) {
  throw new Error(
    'Cannot find Server Hostname, HTTP Path, or personal access token. ' +
      'Check the environment variables DATABRICKS_TOKEN, ' +
      'DATABRICKS_SERVER_HOSTNAME, and DATABRICKS_HTTP_PATH.',
  );
}

const client = new DBSQLClient();
const connectOptions = {
  token: token,
  host: serverHostname,
  path: httpPath,
};

client
  .connect(connectOptions)
  .then(async (client) => {
    const session = await client.openSession();
    const queryOperation = await session.executeStatement('SELECT * FROM samples.nyctaxi.trips LIMIT 2', {
      runAsync: true,
      maxRows: 10000, // This option enables the direct results feature.
    });

    const result = await queryOperation.fetchAll();

    await queryOperation.close();

    console.table(result);

    await session.close();
    await client.close();
  })
  .catch((error) => {
    console.error(error);
  });

TypeScript

TypeScript

import { DBSQLClient } from '@databricks/sql';
import IDBSQLSession from '@databricks/sql/dist/contracts/IDBSQLSession';
import IOperation from '@databricks/sql/dist/contracts/IOperation';

const serverHostname: string = process.env.DATABRICKS_SERVER_HOSTNAME || '';
const httpPath: string = process.env.DATABRICKS_HTTP_PATH || '';
const token: string = process.env.DATABRICKS_TOKEN || '';

if (serverHostname == '' || httpPath == '' || token == '') {
  throw new Error(
    'Cannot find Server Hostname, HTTP Path, or personal access token. ' +
      'Check the environment variables DATABRICKS_SERVER_HOSTNAME, ' +
      'DATABRICKS_HTTP_PATH, and DATABRICKS_TOKEN.',
  );
}

const client: DBSQLClient = new DBSQLClient();
const connectOptions = {
  host: serverHostname,
  path: httpPath,
  token: token,
};

client
  .connect(connectOptions)
  .then(async (client) => {
    const session: IDBSQLSession = await client.openSession();

    const queryOperation: IOperation = await session.executeStatement('SELECT * FROM samples.nyctaxi.trips LIMIT 2', {
      runAsync: true,
      maxRows: 10000, // This option enables the direct results feature.
    });

    const result = await queryOperation.fetchAll();

    await queryOperation.close();

    console.table(result);

    await session.close();
    client.close();
  })
  .catch((error) => {
    console.error(error);
  });

出力:

┌─────────┬─────┬────────┬───────────┬───────┬─────────┬────────┬───────┬───────┬────────┬────────┬────────┐
│ (index) │ _c0 │ carat  │    cut    │ color │ clarity │ depth  │ table │ price │   x    │   y    │   z    │
├─────────┼─────┼────────┼───────────┼───────┼─────────┼────────┼───────┼───────┼────────┼────────┼────────┤
│    0    │ '1' │ '0.23' │  'Ideal'  │  'E'  │  'SI2'  │ '61.5' │ '55'  │ '326' │ '3.95' │ '3.98' │ '2.43' │
│    1    │ '2' │ '0.21' │ 'Premium' │  'E'  │  'SI1'  │ '59.8' │ '61'  │ '326' │ '3.89' │ '3.84' │ '2.31' │
└─────────┴─────┴────────┴───────────┴───────┴─────────┴────────┴───────┴───────┴────────┴────────┴────────┘

クエリタグの例

備考

プレビュー

この機能はプライベートプレビュー段階です。アクセスをリクエストするには、アカウント チームにお問い合わせください。

クエリ タグは、追跡や分析の目的で SQL クエリに添付できるキーと値のペアです。設定すると、 system.query.historyテーブルに表示され、クエリのパターンと使用状況を分析できるようになります。

クエリ タグを、各キーと値がコロンで区切られた、コンマ区切りのキーと値のペアとして定義します (例: key1:value1,key2:value2 )。

次の例は、セッション構成でクエリ タグを使用する方法を示しています。

JavaScript

JavaScript

const { DBSQLClient } = require('@databricks/sql');

const client = new DBSQLClient();

// Open session with query tags configuration
const session = await client.openSession({
  configuration: {
    query_tags: 'team:engineering,test:query-tags,driver:node',
  },
});

const queryOperation = await session.executeStatement('SELECT 1');
const result = await queryOperation.fetchAll();
console.log(result);

await queryOperation.close();
await session.close();

TypeScript

TypeScript

import { DBSQLClient } from '@databricks/sql';

const client: DBSQLClient = new DBSQLClient();

// Open session with query tags configuration
const session = await client.openSession({
  configuration: {
    query_tags: 'team:engineering,test:query-tags,driver:node',
  },
});

const queryOperation = await session.executeStatement('SELECT 1');
const result = await queryOperation.fetchAll();
console.log(result);

await queryOperation.close();
await session.close();

セッション

API リファレンスで IOperation オブジェクトを返すすべての IDBSQLSession メソッドには、その動作に影響を与える次の共通パラメーターがあります。

• runAsync を true に設定すると、非同期モードが開始されます。IDBSQLSession メソッドは、操作をキューに入れ、できるだけ早く戻ります。 返された IOperation オブジェクトの現在の状態は異なる場合があり、クライアントは返された IOperationを使用する前にそのステータスを確認する必要があります。 「操作」を参照してください。runAsync を false に設定すると、IDBSQLSessionメソッドは操作の完了を待機します。Databricks では、常に runAsync を trueに設定することをお勧めします。
• maxRows を NULL 以外の値に設定すると、直接結果が得られます。直接結果の場合、サーバーは操作が完了するのを待ってから、データの一部をフェッチしようとします。 定義された時間内にサーバーが完了できた作業量に応じて、 IOperation オブジェクトは保留状態ではなく中間状態で戻ります。 多くの場合、すべてのメタデータとクエリ結果は、サーバーへの 1 つの要求内で返されます。 サーバーは maxRows を使用して、すぐに返すことができるレコードの数を決定します。 ただし、実際のチャンクのサイズは異なる場合があります。 IDBSQLSession.fetchChunkを参照してください。 直接結果はデフォルトで有効になっています。 Databricks では、直接結果を無効にしないことをお勧めします。

セッション構成

openSessionメソッドでconfigurationオブジェクトを使用してセッションを開くときに、セッション構成 引数 を渡すことができます。 これらの懸念は、そのセッション内のすべての操作の動作に影響します。

一般的なセッション構成には次のものが含まれます。

• query_tags: 追跡と分析のためにSQLクエリに key-value タグを添付します。 詳細については、 「クエリ タグの例」を参照してください。
• ansi_mode: ANSI SQLコンプライアンス モードを制御します ( 'true'または'false' )
• timezone: セッションのタイムゾーンを設定します（例: 'UTC' 、 'America/New_York' ）

オペレーションズ

セッションで説明されているように、API リファレンスの IDBSQLSession セッションメソッドによって返される IOperation オブジェクトは完全には入力されません。Databricks SQL ウェアハウスの開始を待機している、クエリを実行している、データをフェッチしているなど、関連するサーバー操作がまだ進行中である可能性があります。 IOperation クラスは、これらの詳細をユーザーから隠します。たとえば、 fetchAll、 fetchChunk、 getSchema などのメソッドは、操作が完了してから結果を返すまで内部的に待機します。 IOperation.finished() メソッドを使用すると、操作が完了するのを明示的に待機できます。これらのメソッドは、操作の完了を待機している間に定期的に呼び出されるコールバックを受け取ります。 progress オプションを true に設定すると、サーバーから追加の進行状況データを要求し、それをそのコールバックに渡そうとします。

close メソッドと cancel メソッドは、いつでも呼び出すことができます。呼び出されると、 IOperation オブジェクトはすぐに無効になります。 fetchAll、 fetchChunk、 getSchema などの保留中のすべての呼び出しはすぐにキャンセルされ、エラーが返されます。 場合によっては、サーバー操作がすでに完了しており、 cancel メソッドがクライアントにのみ影響することもあります。

fetchAllメソッドは、fetchChunkを内部的に呼び出し、すべてのデータを配列に収集します。これは便利ですが、大規模なデータセットで使用するとメモリ不足エラーが発生する可能性があります。 fetchAll オプションは通常、 fetchChunkに渡されます。

データのチャンクをフェッチする

データ チャンクのフェッチには、次のコード パターンを使用します。

JavaScript

do {
  const chunk = await operation.fetchChunk();
  // Process the data chunk.
} while (await operation.hasMoreRows());

API リファレンスの fetchChunk メソッドは、データを少しずつ処理してメモリ消費量を削減します。fetchChunk は、操作がまだ完了していない場合は、最初に操作が完了するのを待機し、待機サイクル中にコールバックを呼び出してから、次のデータ チャンクをフェッチします。

maxRows オプションを使用して、目的のチャンク サイズを指定できます。ただし、返されるチャンクのサイズは異なる場合があり、小さい場合や大きい場合もあります。 fetchChunk は、要求された部分にデータをスライスするために、内部でデータをプリフェッチしようとはしません。 maxRows オプションをサーバーに送信し、サーバーが返したものをすべて返します。この maxRows オプションと IDBSQLSession のオプションを混同しないでください。 fetchChunkに渡されるmaxRowsは、各チャンクのサイズを定義し、それ以外は何もしません。

Unity Catalog ボリューム内のファイルを管理する

Databricks SQL ドライバーを使用すると、次の例に示すように、Unity Catalog ボリュームへのローカル ファイルの書き込み、ボリュームからのファイルのダウンロード、ボリュームからのファイルの削除を行うことができます。

JavaScript

JavaScript

const { DBSQLClient } = require('@databricks/sql');

const serverHostname = process.env.DATABRICKS_SERVER_HOSTNAME;
const httpPath = process.env.DATABRICKS_HTTP_PATH;
const token = process.env.DATABRICKS_TOKEN;

if (!token || !serverHostname || !httpPath) {
  throw new Error(
    'Cannot find Server Hostname, HTTP Path, or ' +
      'personal access token. ' +
      'Check the environment variables DATABRICKS_SERVER_HOSTNAME, ' +
      'DATABRICKS_HTTP_PATH, and DATABRICKS_TOKEN.',
  );
}

const client = new DBSQLClient();
const connectOptions = {
  token: token,
  host: serverHostname,
  path: httpPath,
};

client
  .connect(connectOptions)
  .then(async (client) => {
    const session = await client.openSession();

    // Write a local file to a volume in the specified path.
    // For writing local files to volumes, you must first specify the path to the
    // local folder that contains the file to be written.
    // Specify OVERWRITE to overwrite any existing file in that path.
    await session.executeStatement("PUT 'my-data.csv' INTO '/Volumes/main/default/my-volume/my-data.csv' OVERWRITE", {
      stagingAllowedLocalPath: ['/tmp/'],
    });

    // Download a file from a volume in the specified path.
    // For downloading files in volumes, you must first specify the path to the
    // local folder that will contain the downloaded file.
    await session.executeStatement("GET '/Volumes/main/default/my-volume/my-data.csv' TO 'my-downloaded-data.csv'", {
      stagingAllowedLocalPath: ['/Users/paul.cornell/samples/nodejs-sql-driver/'],
    });

    // Delete a file in a volume from the specified path.
    // For deleting files from volumes, you must add stagingAllowedLocalPath,
    // but its value will be ignored. As such, in this example, an empty string is
    // specified.
    await session.executeStatement("REMOVE '/Volumes/main/default/my-volume/my-data.csv'", {
      stagingAllowedLocalPath: [''],
    });

    await session.close();
    await client.close();
  })
  .catch((error) => {
    console.error(error);
  });

TypeScript

TypeScript

import { DBSQLClient } from '@databricks/sql';

const serverHostname: string | undefined = process.env.DATABRICKS_SERVER_HOSTNAME;
const httpPath: string | undefined = process.env.DATABRICKS_HTTP_PATH;
const token: string | undefined = process.env.DATABRICKS_TOKEN;

if (!token || !serverHostname || !httpPath) {
  throw new Error(
    'Cannot find Server Hostname, HTTP Path, or ' +
      'personal access token. ' +
      'Check the environment variables DATABRICKS_SERVER_HOSTNAME, ' +
      'DATABRICKS_HTTP_PATH, and DATABRICKS_TOKEN.',
  );
}

const client: DBSQLClient = new DBSQLClient();
const connectOptions = {
  token: token,
  host: serverHostname,
  path: httpPath,
};

client
  .connect(connectOptions)
  .then(async (client) => {
    const session = await client.openSession();

    // Write a local file to a volume in the specified path.
    // For writing local files to volumes, you must first specify the path to the
    // local folder that contains the file to be written.
    // Specify OVERWRITE to overwrite any existing file in that path.
    await session.executeStatement("PUT 'my-data.csv' INTO '/Volumes/main/default/my-volume/my-data.csv' OVERWRITE", {
      stagingAllowedLocalPath: ['/tmp/'],
    });

    // Download a file from a volume in the specified path.
    // For downloading files in volumes, you must first specify the path to the
    // local folder that will contain the downloaded file.
    await session.executeStatement("GET '/Volumes/main/default/my-volume/my-data.csv' TO 'my-downloaded-data.csv'", {
      stagingAllowedLocalPath: ['/Users/paul.cornell/samples/nodejs-sql-driver/'],
    });

    // Delete a file in a volume from the specified path.
    // For deleting files from volumes, you must add stagingAllowedLocalPath,
    // but its value will be ignored. As such, in this example, an empty string is
    // specified.
    await session.executeStatement("REMOVE '/Volumes/main/default/my-volume/my-data.csv'", {
      stagingAllowedLocalPath: [''],
    });

    await session.close();
    await client.close();
  })
  .catch((error: any) => {
    console.error(error);
  });

ログ記録を構成する

ロガーは、コネクタの問題をデバッグするための情報を提供します。 すべての DBSQLClient オブジェクトは、コンソールに出力するロガーでインスタンス化されますが、カスタムロガーを渡すことで、この情報をファイルに送信できます。 次の例は、ロガーを構成し、そのレベルを変更する方法を示しています。

JavaScript

JavaScript

const { DBSQLLogger, LogLevel } = require('@databricks/sql');
const logger = new DBSQLLogger({
  filepath: 'log.txt',
  level: LogLevel.info,
});

// Set logger to different level.
logger.setLevel(LogLevel.debug);

TypeScript

TypeScript

import { DBSQLLogger, LogLevel } from '@databricks/sql';
const logger = new DBSQLLogger({
  filepath: 'log.txt',
  level: LogLevel.info,
});

// Set logger to different level.
logger.setLevel(LogLevel.debug);

その他の例については、GitHub の databricks/databricks-sql-nodejs リポジトリの examples フォルダーを参照してください。

テスティング

コードをテストするには、 Jest などの JavaScript テストフレームワークを使用できます。Databricks REST API エンドポイントを呼び出したり、Databricks アカウントやワークスペースの状態を変更したりせずに、シミュレートされた条件下でコードをテストするには、Jest の組み込みモック フレームワークを使用できます。

たとえば、Databricks パーソナル アクセス トークンを使用して Databricks ワークスペースへの接続を返す getDBSQLClientWithPAT 関数を含む helpers.js という名前の次のファイル、つまり、接続を使用して指定されたテーブル (たとえば、samples カタログの nyctaxi スキーマの trips テーブル) から指定された数のデータ行を取得する getAllColumnsFromTable 関数が含まれているとします。 また、データ行の内容を印刷するprintResults関数もあります。

JavaScript

// helpers.js

const { DBSQLClient } = require('@databricks/sql');

async function getDBSQLClientWithPAT(token, serverHostname, httpPath) {
  const client = new DBSQLClient();
  const connectOptions = {
    token: token,
    host: serverHostname,
    path: httpPath,
  };
  try {
    return await client.connect(connectOptions);
  } catch (error) {
    console.error(error);
    throw error;
  }
}

async function getAllColumnsFromTable(client, tableSpec, rowCount) {
  let session;
  let queryOperation;
  try {
    session = await client.openSession();
    queryOperation = await session.executeStatement(`SELECT * FROM ${tableSpec} LIMIT ${rowCount}`, {
      runAsync: true,
      maxRows: 10000, // This option enables the direct results feature.
    });
  } catch (error) {
    console.error(error);
    throw error;
  }
  let result;
  try {
    result = await queryOperation.fetchAll();
  } catch (error) {
    console.error(error);
    throw error;
  } finally {
    if (queryOperation) {
      await queryOperation.close();
    }
    if (session) {
      await session.close();
    }
  }
  return result;
}

function printResult(result) {
  console.table(result);
}

module.exports = {
  getDBSQLClientWithPAT,
  getAllColumnsFromTable,
  printResult,
};

そして、getDBSQLClientWithPAT、getAllColumnsFromTable、printResults 関数を呼び出す main.js という名前の次のファイルがあるとします。

JavaScript

// main.js

const { getDBSQLClientWithPAT, getAllColumnsFromTable, printResult } = require('./helpers');

const token = process.env.DATABRICKS_TOKEN;
const serverHostname = process.env.DATABRICKS_SERVER_HOSTNAME;
const httpPath = process.env.DATABRICKS_HTTP_PATH;
const tableSpec = process.env.DATABRICKS_TABLE_SPEC;

if (!token || !serverHostname || !httpPath) {
  throw new Error(
    'Cannot find Server Hostname, HTTP Path, or personal access token. ' +
      'Check the environment variables DATABRICKS_TOKEN, ' +
      'DATABRICKS_SERVER_HOSTNAME, and DATABRICKS_HTTP_PATH.',
  );
}

if (!tableSpec) {
  throw new Error(
    'Cannot find table spec in the format catalog.schema.table. ' +
      'Check the environment variable DATABRICKS_TABLE_SPEC.',
  );
}

getDBSQLClientWithPAT(token, serverHostname, httpPath)
  .then(async (client) => {
    const result = await getAllColumnsFromTable(client, tableSpec, 2);
    printResult(result);
    await client.close();
  })
  .catch((error) => {
    console.error(error);
  });

次の helpers.test.js という名前のファイルは、 getAllColumnsFromTable 関数が予期した応答を返すかどうかをテストします。このテストでは、ターゲット ワークスペースへの実際の接続を作成するのではなく、 DBSQLClient オブジェクトをモックします。また、このテストでは、実際のデータにあるスキーマと値に準拠する一部のデータをモックします。このテストでは、モックされた接続を介してモックされたデータが返され、モックされたデータ行の値の 1 つが期待値と一致するかどうかがチェックされます。

JavaScript

// helpers.test.js

const { getDBSQLClientWithPAT, getAllColumnsFromTable, printResult } = require('./helpers');

jest.mock('@databricks/sql', () => {
  return {
    DBSQLClient: jest.fn(() => {
      return {
        connect: jest.fn().mockResolvedValue({ mock: 'DBSQLClient' }),
      };
    }),
  };
});

test('getDBSQLClientWithPAT returns mocked Promise<DBSQLClient> object', async () => {
  const result = await getDBSQLClientWithPAT(
    (token = 'my-token'),
    (serverHostname = 'mock-server-hostname'),
    (httpPath = 'mock-http-path'),
  );

  expect(result).toEqual({ mock: 'DBSQLClient' });
});

const data = [
  {
    tpep_pickup_datetime: new Date(2016, 1, 13, 15, 51, 12),
    tpep_dropoff_datetime: new Date(2016, 1, 13, 16, 15, 3),
    trip_distance: 4.94,
    fare_amount: 19.0,
    pickup_zip: 10282,
    dropoff_zip: 10171,
  },
  {
    tpep_pickup_datetime: new Date(2016, 1, 3, 17, 43, 18),
    tpep_dropoff_datetime: new Date(2016, 1, 3, 17, 45),
    trip_distance: 0.28,
    fare_amount: 3.5,
    pickup_zip: 10110,
    dropoff_zip: 10110,
  },
];

const mockDBSQLClientForSession = {
  openSession: jest.fn().mockResolvedValue({
    executeStatement: jest.fn().mockResolvedValue({
      fetchAll: jest.fn().mockResolvedValue(data),
      close: jest.fn().mockResolvedValue(null),
    }),
    close: jest.fn().mockResolvedValue(null),
  }),
};

test('getAllColumnsFromTable returns the correct fare_amount for the second mocked data row', async () => {
  const result = await getAllColumnsFromTable(
    (client = mockDBSQLClientForSession),
    (tableSpec = 'mock-table-spec'),
    (rowCount = 2),
  );
  expect(result[1].fare_amount).toEqual(3.5);
});

global.console.table = jest.fn();

test('printResult mock prints the correct fare_amount for the second mocked data row', () => {
  printResult(data);
  expect(console.table).toHaveBeenCalledWith(data);
  expect(data[1].fare_amount).toBe(3.5);
});

TypeScript の場合、上記のコードは次のようになります。 TypeScript を使用した Jest テストには、 ts-jest を使用してください。

追加のリソース

• GitHub 上の Node.jsリポジトリ用の Databricks SQL Driver
• Databricks SQL Driver for Node.js の概要
• Databricks SQL Driver for Node.js のトラブルシューティング

API リファレンス

• クラス

  • DBSQLClient クラス

    • メソッド
      • connect メソッド
      • openSession メソッド
      • getClient メソッド
      • close メソッド

  • DBSQLSession クラス

    • メソッド
      • executeStatement メソッド
      • close メソッド
      • getId メソッド
      • getTypeInfo メソッド
      • getCatalogs メソッド
      • getSchemas メソッド
      • getTables メソッド
      • getFunctions メソッド
      • getPrimaryKeys メソッド
      • getCrossReference メソッド

  • DBSQLOperation クラス

    • メソッド
      • getId メソッド
      • fetchAll メソッド
      • fetchChunk メソッド
      • close メソッド

クラス

DBSQLClient クラス

データベースと対話するためのメイン エントリ ポイント。

メソッド

connect メソッド

データベースへの接続を開きます。

パラメータ
オプション タイプ： ConnectionOptions データベースへの接続に使用されるオプションのセット。 host、 path、およびその他の必須フィールドに入力する必要があります。「認証」を参照してください。 userAgentEntry フィールドを使用すると、使用状況の追跡のために HTTP 要求ヘッダーに含める User-Agent を指定できます。User-Agent の設定を参照してください。

収益： Promise<IDBSQLClient>

openSession メソッド

DBSQLClient とデータベース間のセッションを開きます。

パラメータ
request タイプ： OpenSessionRequest 初期スキーマと初期カタログを指定するためのオプション・パラメーターのセット 例： JavaScript const session = await client.openSession({ initialCatalog: 'catalog' });

収益： Promise<IDBSQLSession>

getClient メソッド

内部の thrift TCLIService.Client オブジェクトを返します。 DBSQLClient が接続された後に呼び出す必要があります。

パラメーターなし

戻り値 TCLIService.Client

close メソッド

データベースへの接続を閉じ、サーバー上のすべての関連リソースを解放します。 このクライアントをさらに呼び出すと、エラーがスローされます。

パラメーターはありません。

戻り値はありません。

DBSQLSession クラス

DBSQLSessions は、主にデータベースに対するステートメントの実行や、さまざまなメタデータのフェッチ操作に使用されます。

メソッド

executeStatement メソッド

指定されたオプションを使用してステートメントを実行します。

パラメータ
陳述 タイプ： str 実行するステートメント。 オプション タイプ： ExecuteStatementOptions クエリのタイムアウト、直接結果の最大行数、およびクエリを非同期に実行するかどうかを決定するための省略可能なパラメーターのセット。 デフォルトでは、 maxRows は 10000 に設定されています。 maxRows を null に設定すると、操作は直接結果機能をオフにして実行されます。 例： JavaScript const session = await client.openSession({ initialCatalog: 'catalog' }); queryOperation = await session.executeStatement('SELECT "Hello, World!"', { runAsync: true });

収益： Promise<IOperation>

close メソッド

セッションを閉じます。 セッションを使用した後に行う必要があります。

パラメーターはありません。

戻り値はありません。

getId メソッド

セッションの GUID を返します。

パラメーターはありません。

収益： str

getTypeInfo メソッド

サポートされているデータ型に関する情報を返します。

パラメータ
request タイプ： TypeInfoRequest 要求パラメーター。

収益： Promise<IOperation>

getCatalogs メソッド

カタログの一覧を取得します。

パラメータ
request タイプ： CatalogsRequest 要求パラメーター。

収益： Promise<IOperation>

getSchemas メソッド

スキーマの一覧を取得します。

パラメータ
request タイプ： SchemasRequest 要求パラメーター。 フィールド catalogName と schemaName は、フィルタリングの目的で使用できます。

収益： Promise<IOperation>

getTables メソッド

テーブルのリストを取得します。

パラメータ
request タイプ： TablesRequest リクエストを承ります。 フィールドcatalogName 、 schemaName 、 tableNameはフィルタリングに使用できます。

収益： Promise<IOperation>

getFunctions メソッド

テーブルのリストを取得します。

パラメータ
request タイプ： FunctionsRequest 要求パラメーター。 フィールド functionName は必須です。

収益： Promise<IOperation>

getPrimaryKeys メソッド

プライマリ・キーのリストを取得します。

パラメータ
request タイプ： PrimaryKeysRequest 要求パラメーター。 フィールド schemaName と tableName は必須です。

収益： Promise<IOperation>

getCrossReference メソッド

2 つのテーブル間の外部キーに関する情報を取得します。

パラメータ
request タイプ： CrossReferenceRequest 要求パラメーター。 スキーマ、親、およびカタログ名は、両方のテーブルに指定する必要があります。

収益： Promise<IOperation>

DBSQLOperation クラス

DBSQLOperations は DBSQLSessions によって作成され、文の結果をフェッチし、その実行をチェックするために使用できます。 データは、関数 fetchChunk と fetchAll を使用してフェッチされます。

メソッド

getId メソッド

オペレーションのGUIDを返します。

パラメーターはありません。

収益： str

fetchAll メソッド

操作の完了を待ってから、操作からすべての行をフェッチします。

パラメーター: None

収益： Promise<Array<object>>

fetchChunk メソッド

操作が完了するのを待ってから、操作から指定された行数まで取り出します。

パラメータ
オプション タイプ： FetchOptions フェッチに使用するオプション。 現在、唯一のオプションは maxRows で、これは特定の配列で返されるデータオブジェクトの最大数に対応します。

収益： Promise<Array<object>>

close メソッド

操作を閉じ、関連付けられているすべてのリソースを解放します。 操作を使用しなくなった後に行う必要があります。

パラメーターはありません。

戻り値はありません。