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

• Manajer Paket Simpul (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 ID Microsoft Entra (sebelumnya Azure Active Directory)
• 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 perwakilan layanan ID Microsoft Entra
• Autentikasi Azure CLI

Catatan

Sebagai praktik terbaik keamanan, Anda tidak boleh melakukan hard code nilai variabel koneksi ke 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 token akses pribadi Azure Databricks, Anda harus terlebih dahulu membuat token akses pribadi Azure Databricks, sebagai berikut:

1. Di ruang kerja Azure Databricks Anda, klik nama pengguna Azure Databricks Anda di bilah atas, lalu pilih Pengaturan dari menu drop-down.
2. Klik Pengembang.
3. Di samping Token akses, klik Kelola.
4. Klik Buat token baru.
5. (Opsional) Masukkan komentar yang membantu Anda mengidentifikasi token ini di masa mendatang, dan mengubah masa pakai default token selama 90 hari. Untuk membuat token tanpa masa pakai (tidak disarankan), biarkan kotak Seumur Hidup (hari) kosong (kosong).
6. Klik Buat.
7. Salin token yang ditampilkan ke lokasi aman, lalu klik Selesai.

Catatan

Pastikan untuk menyimpan token yang disalin di lokasi yang aman. Jangan bagikan token yang Anda salin dengan orang lain. Jika Anda kehilangan token yang disalin, Anda tidak dapat meregenerasi token yang sama persis. Sebagai gantinya, Anda harus mengulangi prosedur ini untuk membuat token baru. Jika Anda kehilangan token yang disalin, atau Anda yakin bahwa token telah disusupi, Databricks sangat menyarankan agar Anda segera menghapus token tersebut dari ruang kerja Anda dengan mengklik ikon tempat sampah (Cabut) di samping token di halaman Token akses.

Jika Anda tidak dapat membuat atau menggunakan token di ruang kerja, ini mungkin karena administrator ruang kerja Anda telah menonaktifkan token atau belum memberi Anda izin untuk membuat atau menggunakan token. Lihat administrator ruang kerja Anda atau berikut ini:

• Mengaktifkan atau menonaktifkan autentikasi token akses pribadi untuk ruang kerja
• Izin token akses pribadi

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 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, 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",
    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 perwakilan layanan dan rahasia OAuth-nya, lihat Menggunakan perwakilan layanan untuk mengautentikasi dengan Azure Databricks. 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 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, atur ke nilai Rahasia untuk rahasia OAuth 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",
    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 ID Microsoft Entra (sebelumnya Azure Active Directory)

Untuk menggunakan Driver SQL Databricks untuk Node.js dengan autentikasi token ID Microsoft Entra (sebelumnya Azure Active Directory), 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 MICROSOFT Entra ID (sebelumnya Azure Active Directory) untuk pengguna dengan menggunakan Azure CLI.
• Untuk perwakilan layanan ID Microsoft Entra, lihat Mendapatkan token akses ID Microsoft Entra dengan Azure CLI. Untuk membuat perwakilan layanan terkelola ID Microsoft Entra, lihat Mengelola 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, atur 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 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 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);
});

Output:

┌─────────┬─────┬────────┬───────────┬───────┬─────────┬────────┬───────┬───────┬────────┬────────┬────────┐
│ (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 Sesi, IOperation objek yang dikembalikan oleh IDBSQLSession metode sesi dalam Referensi API tidak sepenuhnya diisi. 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 ini mengambil panggilan balik yang secara berkala dipanggil sambil menunggu operasi selesai. progress Mengatur opsi untuk true mencoba meminta data kemajuan tambahan dari server dan meneruskannya ke panggilan balik tersebut.

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

Metode ini fetchAll memanggil fetchChunk secara internal dan mengumpulkan semua data ke dalam array. Meskipun nyaman, ini dapat menyebabkan kesalahan kehabisan memori ketika digunakan pada himpunan data besar. fetchAll opsi biasanya diteruskan ke fetchChunk.

Mengambil potongan 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 menggorengnya ke bagian yang diminta. Ini mengirim maxRows opsi ke server lalu dan mengembalikan apa pun yang dikembalikan server. Jangan bingung opsi ini maxRows dengan opsi di IDBSQLSession. maxRows diteruskan untuk fetchChunk menentukan ukuran setiap gugus dan tidak melakukan hal 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

Pencatat menyediakan informasi untuk men-debug masalah dengan konektor. Semua DBSQLClient objek dibuat dengan pencatat yang mencetak ke konsol, tetapi dengan meneruskan pencatat kustom, 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 mengembalikan koneksi ke ruang kerja Azure Databricks, getAllColumnsFromTable fungsi yang menggunakan koneksi untuk mendapatkan jumlah baris data yang ditentukan dari tabel yang ditentukan (misalnya, trips tabel dalam samples skema nyctaxi katalog), 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 bernama main.js yang memanggil getDBSQLClientWithPATfungsi , , getAllColumnsFromTabledan 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 mengejek DBSQLClient objek. Pengujian ini juga meniru beberapa data yang sesuai dengan skema dan nilai yang ada dalam data nyata. Pengujian mengembalikan data yang ditidakan melalui koneksi yang ditidakan lalu memeriksa apakah salah satu nilai baris data yang ditidakan 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:

• Driver SQL Databricks untuk repositori 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
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 thrift internal. 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 ditampilkan.

DBSQLSession kelas

DBSQLSessions terutama digunakan untuk eksekusi pernyataan terhadap databbase 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 menggunakan sesi.

Tidak ada parameter.

Tidak ada nilai yang ditampilkan.

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. catalogName Bidang dan schemaName dapat digunakan untuk tujuan pemfilteran.

Kembali: Promise<IOperation>

metode getTables

Mendapatkan daftar tabel.

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

Kembali: Promise<IOperation>

metode getFunctions

Mendapatkan daftar tabel.

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

Kembali: Promise<IOperation>

metode getPrimaryKeys

Mendapatkan daftar kunci primer.

Parameter
Permintaan Jenis: PrimaryKeysRequest Parameter permintaan. schemaName Bidang dan tableName diperlukan.

Kembali: Promise<IOperation>

metode getCrossReference

Mendapatkan informasi tentang kunci asing di 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 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 ditampilkan.