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.jsyang 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 Nama Host Server dan Jalur HTTP untuk kluster atau gudang SQL yang ada.

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

Autentikasi

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

• Autentikasi token akses pribadi Databricks
• Autentikasi token Microsoft Entra ID
• 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:

• Mengautentikasi dengan identitas terkelola Azure
• Mengautentikasi dengan perwakilan layanan Microsoft Entra
• Mengautentikasi dengan Azure CLI

Catatan

Sebagai praktik terbaik keamanan, Anda sebaiknya tidak menanamkan langsung nilai-nilai variabel koneksi dalam kode Anda. Sebagai gantinya, Anda harus mengambil nilai variabel koneksi ini dari lokasi yang aman. Misalnya, cuplikan kode dan contoh dalam artikel ini menggunakan variabel lingkungan.

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 Membuat token akses pribadi 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, atur 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-mesin (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, atur 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',
  azureTenantId: '<tenant-id>',
  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',
  azureTenantId: '<tenant-id>',
  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 perwakilan layanan dan rahasia OAuth-nya, lihat Mengotorisasi akses perwakilan layanan ke Azure Databricks dengan OAuth. Catat nilai UUID atau ID Aplikasi dari perwakilan layanan, serta 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 Nama Host Server untuk kluster 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 perwakilan layanan.
• DATABRICKS_CLIENT_SECRET, tetapkan ke nilai Rahasia untuk kunci rahasia OAuth dari perwakilan 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',
  azureTenantId: '<tenant-id>',
  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',
  azureTenantId: '<tenant-id>',
  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 secara manual.
• Untuk perwakilan layanan ID Microsoft Entra, lihat Mendapatkan token untuk perwakilan layanan. Untuk membuat perwakilan layanan terkelola ID Microsoft Entra, lihat Perwakilan 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 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);
// ...

Atur User-Agent

Contoh kode berikut menunjukkan cara mengatur product_name aplikasi User-Agent untuk pelacakan penggunaan.

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

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 trips tabel dalam samples skema nyctaxi katalog.

Catatan

Contoh kode berikut menunjukkan cara menggunakan token akses pribadi Azure Databricks untuk autentikasi. Untuk menggunakan jenis autentikasi Azure Databricks lain yang tersedia, lihat Autentikasi.

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 mewakili nilai Nama Host Server dari persyaratan.
• DATABRICKS_HTTP_PATH, yang mewakili 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 ?', {
      runAsync: true,
      maxRows: 10000, // This option enables the direct results feature.
      ordinalParameters: [2],
    });

    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 ?', {
      runAsync: true,
      maxRows: 10000, // This option enables the direct results feature.
      ordinalParameters: [2],
    });

    const result = await queryOperation.fetchAll();

    await queryOperation.close();

    console.table(result);

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

Contoh tag kueri

Penting

Fitur ini ada di Pratinjau Privat. Untuk meminta akses, hubungi tim akun Anda.

Tag kueri adalah pasangan kunci-nilai yang dapat dilampirkan ke kueri SQL untuk tujuan pelacakan dan analitik. Saat diatur, mereka muncul dalam system.query.history tabel, memungkinkan Anda menganalisis pola dan penggunaan kueri.

Tentukan tag kueri sebagai pasangan kunci-nilai yang dipisahkan koma di mana setiap kunci dan nilai dipisahkan oleh titik dua, misalnya, key1:value1,key2:value2.

Contoh berikut menunjukkan cara menggunakan tag kueri dengan konfigurasi sesi:

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

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

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.

Konfigurasi sesi

Anda dapat meneruskan parameter konfigurasi sesi saat membuka sesi menggunakan configuration objek dalam openSession metode . Parameter ini memengaruhi perilaku semua operasi dalam sesi tersebut.

Parameter konfigurasi sesi umum meliputi:

• query_tags: Lampirkan tag kunci-nilai ke kueri SQL untuk pelacakan dan analitik. Untuk informasi selengkapnya, lihat Contoh tag kueri.
• ansi_mode: Mengontrol mode kepatuhan ANSI SQL ('true' atau 'false')
• timezone: Mengatur zona waktu sesi (misalnya, 'UTC', 'America/New_York')

Operasional

Seperti yang dijelaskan dalam Sesi, IOperation objek yang dikembalikan oleh IDBSQLSession metode sesi dalam Referensi API tidak sepenuhnya terisi. 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, terdapat file bernama helpers.js yang berisi fungsi getDBSQLClientWithPAT yang menggunakan token akses pribadi Azure Databricks untuk mengembalikan koneksi ke ruang kerja Azure Databricks. Fungsi getAllColumnsFromTable menggunakan koneksi untuk mendapatkan jumlah baris data yang ditentukan dari tabel tertentu (misalnya, tabel trips dalam skema samples di katalog nyctaxi), dan fungsi printResults untuk mencetak konten dari baris data tersebut.

// 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();
    // Note: Table names cannot be parameterized; validate tableSpec against allowed values
    queryOperation = await session.executeStatement(`SELECT * FROM ${tableSpec} LIMIT ?`, {
      runAsync: true,
      maxRows: 10000, // This option enables the direct results feature.
      ordinalParameters: [rowCount],
    });
  } 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 di-mock melalui koneksi yang di-mock, lalu memeriksa apakah salah satu nilai dari baris data yang di-mock cocok dengan nilai yang diharapkan.

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

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

Sumber Daya Tambahan:

• Driver SQL Databricks untuk repositori Node.js di GitHub
• Memulai dengan Driver Databricks SQL untuk Node.js
• Memecahkan masalah Driver SQL Databricks untuk Node.js

Referensi API

• Kelas
  • DBSQLClient kelas
    • Metode
      • connect Metode
      • openSession Metode
      • getClient Metode
      • close Metode
  • DBSQLSession kelas
    • Metode
      • executeStatement Metode
      • close Metode
      • getId Metode
      • getTypeInfo Metode
      • getCatalogs Metode
      • getSchemas Metode
      • getTables Metode
      • getFunctions Metode
      • getPrimaryKeys Metode
      • getCrossReference Metode
  • DBSQLOperation kelas
    • 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
Pilihan Jenis: ConnectionOptions Kumpulan opsi yang digunakan untuk menyambungkan ke database. Bidang host, path, dan bidang lain yang diperlukan harus diisi. Lihat Autentikasi. Bidang userAgentEntry ini memungkinkan Anda menyediakan User-Agent untuk disertakan dalam header permintaan HTTP untuk melacak penggunaan. Lihat Mengatur User-Agent.

Kembali: Promise<IDBSQLClient>

metode openSession

Membuka sesi antara DBSQLClient dan database.

Parameter-parameternya
minta 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-parameternya

pernyataan Jenis: str Pernyataan yang akan dijalankan. Pilihan 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-parameternya
minta Jenis: TypeInfoRequest Parameter permintaan.

Kembali: Promise<IOperation>

metode getCatalogs

Mendapatkan daftar katalog.

Parameter-parameternya
minta Jenis: CatalogsRequest Parameter permintaan.

Kembali: Promise<IOperation>

metode getSchemas

Mendapatkan daftar skema.

Parameter-parameternya
minta Jenis: SchemasRequest Parameter permintaan. Bidang catalogName dan schemaName dapat digunakan untuk tujuan pemfilteran.

Kembali: Promise<IOperation>

metode getTables

Mendapatkan daftar tabel.

Parameter-parameternya
minta Jenis: TablesRequest Parameter permintaan. Bidang catalogName, schemaName, dan tableName dapat digunakan untuk pemfilteran.

Kembali: Promise<IOperation>

metode getFunctions

Mendapatkan daftar tabel.

Parameter-parameternya
minta Jenis: FunctionsRequest Parameter permintaan. Kolom functionName diperlukan.

Kembali: Promise<IOperation>

metode getPrimaryKeys

Mendapatkan daftar kunci primer.

Parameter-parameternya
minta Jenis: PrimaryKeysRequest Parameter permintaan. schemaName dan tableName adalah wajib.

Kembali: Promise<IOperation>

metode getCrossReference

Mendapatkan informasi tentang kunci asing antara dua tabel.

Parameter-parameternya
minta 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-parameternya
Pilihan 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.