Driver SQL Databricks untuk Node.js

Driver SQL Databricks untuk Node.js adalah pustaka Node.js yang memungkinkan Anda menggunakan kode JavaScript untuk menjalankan perintah SQL pada sumber daya komputasi Azure Databricks.

Persyaratan

• Mesin pengembangan yang menjalankan Node.js, versi 14 atau yang lebih tinggi. Untuk mencetak versi Node.js yang diinstal, jalankan perintah node -v. Untuk menginstal dan menggunakan versi Node.js yang berbeda, Anda dapat menggunakan alat seperti Node Version Manager (nvm).

• Node Package Manager (npm) (npm). Versi Node.js yang lebih baru sudah menyertakan npm. Untuk memeriksa apakah npm diinstal, jalankan perintah npm -v. Untuk menginstal npm jika diperlukan, Anda dapat mengikuti instruksi seperti yang ada di Unduh dan instal npm.

• Paket @databricks/sql dari npm. Untuk menginstal @databricks/sql paket di proyek Node.js Anda sebagai dependensi, gunakan npm untuk menjalankan perintah berikut dari dalam direktori yang sama dengan proyek Anda:

  npm i @databricks/sql
  

• Jika Anda ingin menginstal dan menggunakan TypeScript di proyek Node.js Anda sebagai devDependencies, gunakan npm untuk menjalankan perintah berikut dari dalam direktori yang sama dengan proyek Anda:

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

• Kluster atau Gudang SQL yang sudah ada.

• Nilai Server Hostname dan HTTP Path untuk kluster atau gudang SQL yang ada.

  • Dapatkan nilai-nilai ini untuk kluster.
  • Dapatkan nilai-nilai ini untuk gudang data SQL.

Autentikasi

Driver SQL Databricks untuk Node.js mendukung jenis autentikasi Azure Databricks berikut:

• Autentikasi token akses pribadi Databricks
• Autentikasi penanda 'ID Microsoft Entra'
• Autentikasi mesin-ke-mesin (M2M) OAuth
• Autentikasi pengguna ke komputer (U2M) OAuth

Driver SQL Databricks untuk Node.js belum mendukung jenis autentikasi Azure Databricks berikut:

• Autentikasi identitas terkelola Azure
• Autentikasi prinsipal layanan MS Entra
• Autentikasi Azure CLI

Autentikasi token akses pribadi Databricks

Untuk menggunakan Driver SQL Databricks untuk Node.js dengan autentikasi, Anda harus terlebih dahulu membuat token akses pribadi Azure Databricks. Untuk detail tentang langkah ini, lihat Token akses pribadi Azure Databricks untuk pengguna ruang kerja.

Untuk mengautentikasi Driver SQL Databricks untuk Node.js, gunakan cuplikan kode berikut. Cuplikan ini mengasumsikan bahwa Anda telah mengatur variabel lingkungan berikut:

• DATABRICKS_SERVER_HOSTNAMEatur ke nilai Nama Host Server untuk kluster atau gudang SQL Anda.
• DATABRICKS_HTTP_PATH, tetapkan ke nilai Jalur HTTP untuk kluster atau gudang SQL Anda.
• DATABRICKS_TOKEN, atur ke token akses pribadi Azure Databricks.

Untuk mengatur variabel lingkungan, lihat dokumentasi sistem operasi Anda.

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

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

Autentikasi pengguna ke komputer (U2M) OAuth

Driver SQL Databricks untuk Node.js versi 1.8.0 ke atas mendukung autentikasi pengguna ke komputer (U2M) OAuth.

Untuk mengautentikasi Driver SQL Databricks untuk Node.js dengan autentikasi OAuth U2M, gunakan cuplikan kode berikut. Cuplikan ini mengasumsikan bahwa Anda telah mengatur variabel lingkungan berikut:

• DATABRICKS_SERVER_HOSTNAMEatur ke nilai Nama Host Server untuk kluster atau gudang SQL Anda.
• DATABRICKS_HTTP_PATH, tetapkan ke nilai Jalur HTTP untuk kluster atau gudang SQL Anda.

Untuk mengatur variabel lingkungan, lihat dokumentasi sistem operasi Anda.

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',
  useDatabricksOAuthInAzure: true,
  host: serverHostname,
  path: httpPath,
};

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

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',
  useDatabricksOAuthInAzure: true,
  host: serverHostname,
  path: httpPath,
};

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

Autentikasi mesin-ke-mesin (M2M) OAuth

Driver SQL Databricks untuk Node.js versi 1.8.0 ke atas mendukung autentikasi komputer-ke-mesin (U2M) OAuth.

Untuk menggunakan Driver SQL Databricks untuk Node.js dengan autentikasi M2M OAuth, Anda harus melakukan hal berikut:

1. Buat perwakilan layanan Azure Databricks di ruang kerja Azure Databricks Anda, dan buat rahasia OAuth untuk perwakilan layanan tersebut.

   Untuk membuat prinsipal layanan dan rahasia OAuth-nya, lihat Mengotorisasi akses tanpa pengawasan ke sumber daya Azure Databricks dengan prinsipal layanan menggunakan OAuth. Catat nilai UUID atau ID Aplikasi perwakilan layanan, dan nilai Rahasia untuk rahasia OAuth perwakilan layanan.

2. Berikan akses perwakilan layanan ke kluster atau gudang Anda. Lihat Izin komputasi atau Mengelola gudang SQL.

Untuk mengautentikasi Driver SQL Databricks untuk Node.js, gunakan cuplikan kode berikut. Cuplikan ini mengasumsikan bahwa Anda telah mengatur variabel lingkungan berikut:

• DATABRICKS_SERVER_HOSTNAMEatur ke nilai Server Hostname untuk klaster atau gudang SQL Anda.
• DATABRICKS_HTTP_PATH, atur ke nilai Jalur HTTP untuk kluster atau gudang SQL Anda.
• DATABRICKS_CLIENT_ID, atur ke nilai UUID atau ID Aplikasi prinsipal layanan.
• DATABRICKS_CLIENT_SECRET, diatur ke nilai Rahasia untuk rahasia OAuth prinsipal layanan.

Untuk mengatur variabel lingkungan, lihat dokumentasi sistem operasi Anda.

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',
  useDatabricksOAuthInAzure: true,
  host: serverHostname,
  path: httpPath,
  oauthClientId: clientId,
  oauthClientSecret: clientSecret,
};

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

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',
  useDatabricksOAuthInAzure: true,
  host: serverHostname,
  path: httpPath,
  oauthClientId: clientId,
  oauthClientSecret: clientSecret,
};

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

Autentikasi token untuk ID Microsoft Entra

Untuk menggunakan Driver SQL Databricks untuk Node.js dengan autentikasi token ID Microsoft Entra, Anda harus menyediakan Driver SQL Databricks untuk Node.js dengan token ID Microsoft Entra. Untuk membuat token akses ID Microsoft Entra, lakukan hal berikut:

• Untuk pengguna Azure Databricks, Anda dapat menggunakan Azure CLI. Lihat Mendapatkan token ID Microsoft Entra untuk pengguna dengan menggunakan Azure CLI.
• Untuk perwakilan layanan ID Microsoft Entra, lihat Mendapatkan token akses ID Microsoft Entra dengan Azure CLI. Untuk membuat prinsipal layanan terkelola di Microsoft Entra ID, lihat Mengelola prinsipal layanan.

Token ID Microsoft Entra memiliki masa pakai default sekitar 1 jam. Untuk membuat token ID Microsoft Entra baru, ulangi proses ini.

Untuk mengautentikasi Driver SQL Databricks untuk Node.js, gunakan cuplikan kode berikut. Cuplikan ini mengasumsikan bahwa Anda telah mengatur variabel lingkungan berikut:

• DATABRICKS_SERVER_HOSTNAMEatur ke nilai Nama Host Server untuk kluster atau gudang SQL Anda.
• DATABRICKS_HTTP_PATH, atur ke nilai Jalur HTTP untuk kluster atau gudang data SQL Anda.
• DATABRICKS_TOKEN, diatur ke token ID Microsoft Entra.

Untuk mengatur variabel lingkungan, lihat dokumentasi sistem operasi Anda.

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 ' +
      '<ms-entra-id> 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

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 ' +
      '<ms-entra-id> 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);
// ...

Mengkueri data

Contoh kode berikut menunjukkan cara memanggil Driver SQL Databricks untuk Node.js menjalankan kueri SQL dasar pada sumber daya komputasi Azure Databricks. Perintah ini mengembalikan dua baris pertama dari tabel trips dalam katalog samples skema nyctaxi.

Contoh kode ini mengambil tokennilai variabel koneksi , server_hostname dan http_path dari sekumpulan variabel lingkungan Azure Databricks. Variabel lingkungan ini memiliki nama variabel lingkungan berikut:

• DATABRICKS_TOKEN, yang mewakili token akses pribadi Azure Databricks Anda dari spesifikasi persyaratan.
• DATABRICKS_SERVER_HOSTNAME, yang merepresentasikan nilai Nama Host Server dari persyaratan.
• DATABRICKS_HTTP_PATH, yang merepresentasikan nilai Jalur HTTP dari persyaratan.

Anda dapat menggunakan pendekatan lain untuk mengambil nilai variabel koneksi ini. Menggunakan variabel lingkungan hanyalah satu dari sekian banyak pendekatan.

Contoh kode berikut menunjukkan cara memanggil Konektor SQL Databricks untuk Node.js menjalankan perintah SQL dasar pada kluster atau gudang SQL. Perintah ini menampilkan dua baris pertama dari tabel trips.

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

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

Keluaran:

┌─────────┬─────┬────────┬───────────┬───────┬─────────┬────────┬───────┬───────┬────────┬────────┬────────┐
│ (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' │
└─────────┴─────┴────────┴───────────┴───────┴─────────┴────────┴───────┴───────┴────────┴────────┴────────┘

Sesi

Semua IDBSQLSession metode yang mengembalikan IOperation objek dalam Referensi API memiliki parameter umum berikut yang memengaruhi perilakunya:

• Pengaturan runAsync untuk true memulai mode asinkron. IDBSQLSession metode menempatkan operasi ke dalam antrean dan kembali secepat mungkin. Status objek yang dikembalikan IOperation saat ini mungkin bervariasi, dan klien bertanggung jawab untuk memeriksa statusnya sebelum menggunakan yang dikembalikan IOperation. Lihat Operasi. Pengaturan runAsync ke false berarti bahwa IDBSQLSession metode menunggu operasi selesai. Databricks merekomendasikan selalu mengatur runAsync ke true.
• Pengaturan maxRows ke nilai non-null memungkinkan hasil langsung. Dengan hasil langsung, server mencoba menunggu operasi selesai dan kemudian mengambil sebagian data. Tergantung pada berapa banyak pekerjaan yang dapat diselesaikan server dalam waktu yang ditentukan, IOperation objek kembali dalam beberapa status perantara alih-alih dalam beberapa status tertunda. Sangat sering semua metadata dan hasil kueri dikembalikan dalam satu permintaan ke server. Server menggunakan maxRows untuk menentukan berapa banyak rekaman yang dapat segera dikembalikan. Namun, potongan aktual mungkin berukuran berbeda; lihat IDBSQLSession.fetchChunk. Hasil langsung diaktifkan secara default. Databricks merekomendasikan untuk tidak menonaktifkan hasil langsung.

Operasional

Seperti yang dijelaskan dalam Sessions, IOperation objek yang dikembalikan oleh IDBSQLSession metode sesi dalam API Reference tidak terisi penuh. Operasi server terkait mungkin masih berlangsung, seperti menunggu gudang Databricks SQL dimulai, menjalankan kueri, atau mengambil data. Kelas IOperation menyembunyikan detail ini dari pengguna. Misalnya, metode seperti fetchAll, fetchChunk, dan getSchema tunggu secara internal agar operasi selesai lalu mengembalikan hasil. Anda dapat menggunakan IOperation.finished() metode untuk secara eksplisit menunggu operasi selesai. Metode-metode ini menerima callback yang dipanggil secara berkala saat menunggu operasi selesai. Mengatur opsi progress ke true berusaha meminta data kemajuan tambahan dari server dan meneruskannya ke panggilan balik tersebut.

Metode close dan cancel dapat dipanggil kapan saja. Ketika dipanggil, mereka segera menghapus validitas IOperation objek; semua panggilan yang tertunda seperti fetchAll, fetchChunk, dan getSchema segera dibatalkan dan pesan kesalahan dikembalikan. Dalam beberapa kasus, operasi server mungkin telah selesai dan cancel metode hanya memengaruhi klien.

fetchAll memanggil metode fetchChunk secara internal dan mengumpulkan semua data ke dalam array. Meskipun ini nyaman, hal ini dapat menyebabkan kesalahan kekurangan memori ketika digunakan pada kumpulan data yang besar. fetchAll opsi biasanya diteruskan ke fetchChunk.

Mengambil bagian-bagian data

Mengambil potongan data menggunakan pola kode berikut:

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

Metode fetchChunk dalam Referensi API memproses data dalam bagian kecil untuk mengurangi konsumsi memori. fetchChunk pertama-tama menunggu operasi selesai jika belum selesai, lalu memanggil panggilan balik selama siklus tunggu, lalu mengambil potongan data berikutnya.

Anda dapat menggunakan maxRows opsi untuk menentukan ukuran potongan yang diinginkan. Namun, potongan yang dikembalikan mungkin memiliki ukuran yang berbeda, lebih kecil atau bahkan kadang-kadang lebih besar. fetchChunk tidak mencoba untuk melakukan prefetch data secara internal, untuk membaginya menjadi bagian yang diminta. Ini mengirim opsi maxRows ke server, lalu mengembalikan apa pun yang server balas. Jangan bingung opsi ini maxRows dengan opsi di IDBSQLSession. maxRows diteruskan ke fetchChunk menentukan ukuran setiap potongan dan tidak memiliki fungsi lain.

Mengelola file dalam volume Katalog Unity

Driver Databricks SQL memungkinkan Anda menulis file lokal ke volume Unity Catalog, mengunduh file dari volume, dan menghapus file dari volume, seperti yang ditunjukkan dalam contoh berikut:

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

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

Mengonfigurasi pengelogan

Logger menyediakan informasi untuk memperbaiki masalah dengan konektor. Semua DBSQLClient objek dibuat dengan pencatat yang mencetak ke layar, tetapi dengan menggunakan pencatat khusus, Anda dapat mengirim informasi ini ke file. Contoh berikut menunjukkan cara mengonfigurasi pencatat dan mengubah tingkatnya.

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

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

Untuk contoh tambahan, lihat folder contoh di repositori databricks/databricks-sql-nodejs di GitHub.

Pengujian

Untuk menguji kode, Anda dapat menggunakan kerangka kerja pengujian JavaScript seperti Jest. Untuk menguji kode Anda dalam kondisi simulasi tanpa memanggil titik akhir REST API Azure Databricks atau mengubah status akun atau ruang kerja Azure Databricks, Anda dapat menggunakan kerangka kerja tiruan bawaan Jest.

Misalnya, mengingat file berikut bernama helpers.js yang berisi getDBSQLClientWithPAT fungsi yang menggunakan token akses pribadi Azure Databricks untuk menghasilkan koneksi ke ruang kerja Azure Databricks, getAllColumnsFromTable fungsi yang menggunakan koneksi untuk mendapatkan jumlah baris data yang ditentukan dari tabel yang ditentukan (misalnya, tabel trips dalam skema nyctaxi di katalog samples), dan printResults fungsi untuk mencetak konten baris data:

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

Dan diberikan file berikut yang bernama main.js yang memanggil fungsi getDBSQLClientWithPAT, getAllColumnsFromTable, dan printResults:

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

File berikut bernama helpers.test.js menguji apakah getAllColumnsFromTable fungsi mengembalikan respons yang diharapkan. Daripada membuat koneksi nyata ke ruang kerja target, pengujian ini mensimulasikan objek DBSQLClient. Pengujian ini juga meniru beberapa data yang sesuai dengan skema dan nilai yang ada dalam data nyata. Pengujian mengembalikan data yang disimulasikan melalui koneksi yang disimulasikan, lalu memeriksa apakah salah satu nilai dari baris data yang disimulasikan cocok dengan nilai yang diharapkan.

// helpers.test.js

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

jest.mock('@databricks/sql', () => {
  return {
    DBSQLClient: jest.fn().mockImplementation(() => {
      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);
});

Untuk TypeScript, kode sebelumnya terlihat mirip. Untuk pengujian Jest dengan TypeScript, gunakan ts-jest.

Sumber Daya Tambahan:

• Repositori Databricks SQL Driver untuk Node.js di GitHub
• Mulai menggunakan Driver SQL Databricks untuk Node.js
• Memecahkan masalah Driver SQL Databricks untuk Node.js

Referensi API

• Kelas
  • DBSQLClient class
    • Metode
      • connect metode
      • openSession metode
      • getClient metode
      • close metode
  • DBSQLSession class
    • Metode
      • executeStatement metode
      • close metode
      • getId metode
      • getTypeInfo metode
      • getCatalogs metode
      • getSchemas metode
      • getTables metode
      • getFunctions metode
      • getPrimaryKeys metode
      • getCrossReference metode
  • DBSQLOperation class
    • Metode
      • getId metode
      • fetchAll metode
      • fetchChunk metode
      • close metode

Kelas

DBSQLClient kelas

Titik masuk utama untuk berinteraksi dengan database.

Metode

metode connect

Membuka koneksi ke database.

Parameter-parameternya
opsi Jenis: ConnectionOptions Kumpulan opsi yang digunakan untuk menyambungkan ke database. Bidang host, path, dan bidang lain yang diperlukan harus diisi. Lihat Autentikasi. Contoh: const client: DBSQLClient = new DBSQLClient(); client.connect( { host: serverHostname, path: httpPath, // ... } )

Kembali: Promise<IDBSQLClient>

metode openSession

Membuka sesi antara DBSQLClient dan database.

Parameter
Permintaan Jenis: OpenSessionRequest Sekumpulan parameter opsional untuk menentukan skema awal dan katalog awal Contoh: const session = await client.openSession( {initialCatalog: 'catalog'} );

Kembali: Promise<IDBSQLSession>

metode getClient

Mengembalikan objek TCLIService.Client internal thrift. Harus dipanggil setelah DBSQLClient tersambung.

Tidak ada parameter

Mengembalikan TCLIService.Client

metode close

Menutup sambungan ke database dan merilis semua sumber daya terkait di server. Setiap panggilan tambahan ke klien ini akan melemparkan kesalahan.

Tidak ada parameter.

Tidak ada nilai yang dikembalikan.

DBSQLSession kelas

DBSQLSessions terutama digunakan untuk eksekusi perintah terhadap database serta berbagai operasi pengambilan metadata.

Metode

metode executeStatement

Menjalankan pernyataan dengan opsi yang disediakan.

Parameter
statement Jenis: str Pernyataan yang akan dijalankan.
opsi Jenis: ExecuteStatementOptions Sekumpulan parameter opsional untuk menentukan batas waktu kueri, baris maks untuk hasil langsung, dan apakah akan menjalankan kueri secara asinkron. Secara default maxRows diatur ke 10000. Jika maxRows diatur ke null, operasi akan berjalan dengan fitur hasil langsung nonaktif. Contoh: const session = await client.openSession( {initialCatalog: 'catalog'} ); queryOperation = await session.executeStatement( 'SELECT "Hello, World!"', { runAsync: true } );

Kembali: Promise<IOperation>

metode close

Menutup sesi. Harus dilakukan setelah sesi selesai.

Tidak ada parameter.

Tidak ada nilai yang dikembalikan.

metode getId

Mengembalikan GUID sesi.

Tidak ada parameter.

Kembali: str

metode getTypeInfo

Mengembalikan informasi tentang jenis data yang didukung.

Parameter
Permintaan Jenis: TypeInfoRequest Parameter permintaan.

Kembali: Promise<IOperation>

metode getCatalogs

Mendapatkan daftar katalog.

Parameter
Permintaan Jenis: CatalogsRequest Parameter permintaan.

Kembali: Promise<IOperation>

metode getSchemas

Mendapatkan daftar skema.

Parameter
Permintaan Jenis: SchemasRequest Parameter permintaan. Bidang catalogName dan schemaName dapat digunakan untuk tujuan pemfilteran.

Kembali: Promise<IOperation>

metode getTables

Mendapatkan daftar tabel.

Parameter
Permintaan Jenis: TablesRequest Parameter permintaan. Bidang catalogName dan schemaName tableName dapat digunakan untuk pemfilteran.

Kembali: Promise<IOperation>

metode getFunctions

Mendapatkan daftar tabel.

Parameter
Permintaan Jenis: FunctionsRequest Parameter permintaan. Kolom functionName diperlukan.

Kembali: Promise<IOperation>

metode getPrimaryKeys

Mendapatkan daftar kunci primer.

Parameter
Permintaan Jenis: PrimaryKeysRequest Parameter permintaan. schemaName dan tableName adalah wajib.

Kembali: Promise<IOperation>

metode getCrossReference

Mendapatkan informasi tentang kunci asing antara dua tabel.

Parameter
Permintaan Jenis: CrossReferenceRequest Parameter permintaan. Nama Skema, Induk, dan Katalog harus ditentukan untuk kedua tabel.

Kembali: Promise<IOperation>

DBSQLOperation kelas

DBSQLOperations dibuat oleh DBSQLSessions dan dapat digunakan untuk mengambil hasil pernyataan dan memeriksa eksekusinya. Data diambil melalui fungsi fetchChunk dan fetchAll.

Metode

metode getId

Mengembalikan GUID dari operasi.

Tidak ada parameter.

Kembali: str

metode fetchAll

Menunggu penyelesaian operasi, lalu mengambil semua baris dari operasi.

Parameter: Tidak ada

Kembali: Promise<Array<object>>

metode fetchChunk

Menunggu penyelesaian operasi, lalu mengambil hingga jumlah baris tertentu dari operasi.

Parameter
opsi Jenis: FetchOptions Opsi yang digunakan untuk mengambil. Saat ini, satu-satunya opsi adalah maxRows, yang sesuai dengan jumlah maksimum objek data yang akan dikembalikan dalam array tertentu.

Kembali: Promise<Array<object>>

metode close

Menutup operasi dan merilis semua sumber daya terkait. Harus dilakukan setelah tidak lagi menggunakan operasi.

Tidak ada parameter.

Tidak ada nilai yang dikembalikan.