Sterownik SQL usługi Databricks dla Node.js

Sterownik SQL usługi Databricks dla Node.js to biblioteka Node.js, która umożliwia uruchamianie poleceń SQL w zasobach obliczeniowych usługi Azure Databricks przy użyciu kodu JavaScript.

Wymagania

• Maszyna deweloperna z systemem Node.js w wersji 14 lub nowszej. Aby wydrukować zainstalowaną wersję Node.js, uruchom polecenie node -v. Aby zainstalować różne wersje Node.jsi korzystać z nich, można użyć narzędzi, takich jak Node Version Manager (nvm).

• Menedżer pakietów Node (npm). Nowsze wersje Node.js już obejmują npm. Aby sprawdzić, czy npm jest zainstalowana, uruchom polecenie npm -v. Aby zainstalować npm, w razie potrzeby możesz postępować zgodnie z takimi instrukcjami, jak te zamieszczone w Pobierz i zainstaluj npm.

• Pakiet @databricks/sql dostępny w npm. Aby zainstalować @databricks/sql pakiet w projekcie Node.js jako zależność, uruchom npm następujące polecenie z tego samego katalogu, który zawiera projekt:

  npm i @databricks/sql
  

• Jeśli chcesz zainstalować i używać języka TypeScript w swoim projekcie Node.js, użyj następujących poleceń, uruchamiając je w katalogu, w którym znajduje się Twój projekt:

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

• Istniejący klaster lub magazyn SQL.

• Wartość Nazwa hosta serwera i Ścieżka HTTP dla istniejącego klastra lub usługi SQL Warehouse.

  • Pobierz te wartości dla klastra.
  • Pobierz te wartości dla usługi SQL Warehouse.

Uwierzytelnianie

Sterownik SQL usługi Databricks dla Node.js obsługuje następujące typy uwierzytelniania usługi Azure Databricks:

• Uwierzytelnianie osobistego tokenu dostępu usługi Databricks
• Uwierzytelnianie tokenu Microsoft Entra ID
• Uwierzytelnianie OAuth między maszynami (M2M)
• Uwierzytelnianie typu użytkownik-komputer (U2M) OAuth

Sterownik SQL usługi Databricks dla Node.js nie obsługuje jeszcze następujących typów uwierzytelniania usługi Azure Databricks:

• Uwierzytelnianie za pomocą tożsamości zarządzanych platformy Azure
• Uwierzytelnianie za pomocą jednostek usługi Entra firmy Microsoft
• Uwierzytelnianie za pomocą interfejsu wiersza polecenia platformy Azure

Uwierzytelnianie osobistego tokenu dostępu usługi Databricks

Aby użyć sterownika SQL usługi Databricks na potrzeby Node.js z uwierzytelnianiem, należy najpierw utworzyć osobisty token dostępu usługi Azure Databricks. Aby uzyskać szczegółowe informacje na temat tego kroku, zobacz Tworzenie osobistych tokenów dostępu dla użytkowników obszaru roboczego.

Aby uwierzytelnić sterownik SQL usługi Databricks dla Node.js, użyj następującego fragmentu kodu. W tym fragmencie kodu założono, że ustawiono następujące zmienne środowiskowe:

• DATABRICKS_SERVER_HOSTNAMEustaw wartość Nazwa hosta serwera dla klastra lub usługi SQL Warehouse.
• DATABRICKS_HTTP_PATH, ustaw na wartość ścieżki HTTP dla klastra lub magazynu SQL.
• DATABRICKS_TOKEN, ustawiony jako osobisty token dostępu usługi Azure Databricks.

Aby ustawić zmienne środowiskowe, zapoznaj się z dokumentacją systemu operacyjnego.

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

Uwierzytelnianie typu użytkownik-komputer (U2M) OAuth

Sterownik SQL usługi Databricks dla Node.js w wersji 1.8.0 lub nowszej obsługuje uwierzytelnianie OAuth użytkownik-maszyna (U2M).

Aby uwierzytelnić sterownik SQL usługi Databricks dla Node.js przy użyciu uwierzytelniania OAuth U2M, użyj następującego fragmentu kodu. W tym fragmencie kodu założono, że ustawiono następujące zmienne środowiskowe:

• DATABRICKS_SERVER_HOSTNAMEustaw wartość Nazwa hosta serwera dla klastra lub usługi SQL Warehouse.
• DATABRICKS_HTTP_PATH, ustaw na wartość ścieżki HTTP dla klastra lub magazynu SQL.

Aby ustawić zmienne środowiskowe, zapoznaj się z dokumentacją systemu operacyjnego.

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

Uwierzytelnianie komunikacji maszyna-maszyna OAuth (M2M)

Sterownik SQL usługi Databricks dla Node.js w wersji 1.8.0 lub nowszej obsługuje uwierzytelnianie między maszynami OAuth (U2M).

Aby użyć sterownika SQL usługi Databricks na potrzeby Node.js z uwierzytelnianiem OAuth M2M, należy wykonać następujące czynności:

1. Utwórz obiekt usługi Azure Databricks w swoim obszarze roboczym Azure Databricks i utwórz wpis tajny OAuth dla tego obiektu usługi.

   Aby utworzyć jednostkę usługi i jej wpis tajny OAuth, zobacz Autoryzowanie dostępu jednostki usługi do usługi Azure Databricks przy użyciu protokołu OAuth. Zanotuj wartość UUID lub Identyfikator aplikacji dla jednostki usługowej oraz wartość Tajna jako tajne OAuth dla tej jednostki.

2. Nadaj jednostce usługi dostęp do klastra lub magazynu. Zobacz Uprawnienia obliczeniowe lub Zarządzanie usługą SQL Warehouse.

Aby uwierzytelnić sterownik SQL usługi Databricks dla Node.js, użyj następującego fragmentu kodu. W tym fragmencie kodu założono, że ustawiono następujące zmienne środowiskowe:

• DATABRICKS_SERVER_HOSTNAMEustaw wartość Nazwa hosta serwera dla klastra lub usługi SQL Warehouse.
• DATABRICKS_HTTP_PATH, ustaw na wartość ścieżki HTTP dla klastra lub magazynu SQL.
• DATABRICKS_CLIENT_ID, przypisz do wartości UUID jednostki głównej usługi lub Identyfikator aplikacji.
• DATABRICKS_CLIENT_SECRET, ustaw wartość tajnego klucza dla tajnego klucza OAuth głównego obiektu usługi.

Aby ustawić zmienne środowiskowe, zapoznaj się z dokumentacją systemu operacyjnego.

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

Uwierzytelnianie tokenu Microsoft Entra ID

Aby użyć sterownika SQL usługi Databricks dla Node.js z uwierzytelnianiem tokenu identyfikatora Entra firmy Microsoft, należy podać sterownik SQL usługi Databricks dla Node.js z tokenem identyfikatora Entra firmy Microsoft. Aby utworzyć token dostępu microsoft Entra ID, wykonaj następujące czynności:

• W przypadku użytkownika usługi Azure Databricks możesz użyć interfejsu wiersza polecenia platformy Azure. Zobacz Pobieranie ręczne tokenów Microsoft Entra ID.
• Aby zapoznać się z jednostką usługi Microsoft Entra ID, zobacz Uzyskiwanie tokenów dla jednostek usługi. Aby utworzyć zarządzaną jednostkę usługi Identyfikatora Entra firmy Microsoft, zobacz Jednostki usługi.

Tokeny identyfikatora Entra firmy Microsoft mają domyślny okres istnienia około 1 godziny. Aby utworzyć nowy token identyfikatora Entra firmy Microsoft, powtórz ten proces.

Aby uwierzytelnić sterownik SQL usługi Databricks dla Node.js, użyj następującego fragmentu kodu. W tym fragmencie kodu założono, że ustawiono następujące zmienne środowiskowe:

• DATABRICKS_SERVER_HOSTNAMEustaw wartość Nazwa hosta serwera dla klastra lub usługi SQL Warehouse.
• DATABRICKS_HTTP_PATH, ustaw na wartość ścieżki HTTP dla klastra lub magazynu SQL.
• DATABRICKS_TOKEN, ustawione na token Microsoft Entra ID.

Aby ustawić zmienne środowiskowe, zapoznaj się z dokumentacją systemu operacyjnego.

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

Ustawianie User-Agent

W poniższym przykładzie kodu pokazano, jak ustawić aplikację User-Agent do śledzenia użycia product_name.

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

Zapytanie danych

W poniższym przykładzie kodu pokazano, jak wywołać sterownik SQL usługi Databricks dla Node.js w celu uruchomienia podstawowego zapytania SQL w zasobie obliczeniowym usługi Azure Databricks. To polecenie zwraca dwa pierwsze wiersze z tabeli trips w schemacie samples katalogu nyctaxi.

Ten przykład kodu pobiera wartości zmiennych połączenia token, server_hostname i http_path z zestawu zmiennych środowiskowych usługi Azure Databricks. Te zmienne środowiskowe mają następujące nazwy zmiennych środowiskowych:

• DATABRICKS_TOKEN, który reprezentuje Twój osobisty token dostępu usługi Azure Databricks zgodnie z wymaganiami.
• DATABRICKS_SERVER_HOSTNAME, który reprezentuje wartość Nazwa hosta serwera z wymagań.
• DATABRICKS_HTTP_PATH, który reprezentuje wartość ścieżki HTTP z wymagań.

Możesz użyć innych metod pobierania tych wartości zmiennych połączenia. Używanie zmiennych środowiskowych jest tylko jednym z wielu podejść.

W poniższym przykładzie kodu pokazano, jak wywołać łącznik SQL usługi Databricks dla Node.js w celu uruchomienia podstawowego polecenia SQL w klastrze lub usłudze SQL Warehouse. To polecenie zwraca dwa pierwsze wiersze z trips tabeli.

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

Przykład tagów zapytań

Tagi zapytań to pary klucz-wartość, które można dołączyć do zapytań SQL w celu śledzenia i analizy. Po ustawieniu są one wyświetlane w system.query.history tabeli, co umożliwia analizowanie wzorców i użycia zapytań.

Zdefiniuj tagi zapytania jako pary klucz-wartość rozdzielane przecinkami, w których każdy klucz i wartość są oddzielone dwukropkiem, na przykład key1:value1,key2:value2.

W poniższym przykładzie pokazano, jak używać tagów zapytań z konfiguracją sesji:

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

Sesje

Wszystkie IDBSQLSession metody zwracające IOperation obiekty w dokumentacji interfejsu API mają następujące typowe parametry wpływające na ich zachowanie:

• Ustawienie runAsync powoduje uruchomienie trybu asynchronicznego w true. IDBSQLSession metody umieszczają operacje w kolejce i kończą działanie tak szybko, jak to możliwe. Bieżący stan zwróconego IOperation obiektu może się różnić, a klient jest odpowiedzialny za sprawdzenie jego stanu przed użyciem zwróconego IOperationobiektu . Zobacz Operacje. Ustawienie runAsync na false wartość oznacza, że IDBSQLSession metody oczekują na zakończenie operacji. Databricks zaleca zawsze ustawianie runAsync na true.
• Ustawienie maxRows wartości innej niż null umożliwia bezpośrednie wyniki. W przypadku bezpośrednich wyników serwer próbuje poczekać na zakończenie operacji, a następnie pobrać część danych. W zależności od tego, ile pracy serwer mógł wykonać w zdefiniowanym czasie, IOperation obiekty są zwracane w pewnym stanie pośrednim zamiast w stanie oczekiwania. Bardzo często wszystkie metadane i wyniki zapytania są zwracane w ramach jednego żądania do serwera. Serwer używa maxRows do określenia, ile rekordów może zwrócić natychmiast. Jednak rzeczywisty fragment może mieć inny rozmiar; zobacz IDBSQLSession.fetchChunk. Wyniki bezpośrednie są domyślnie włączone. Usługa Databricks odradza wyłączanie wyników bezpośrednich.

Konfiguracja sesji

Parametry konfiguracji sesji można przekazać podczas otwierania sesji przy użyciu configuration obiektu w metodzie openSession . Te parametry wpływają na zachowanie wszystkich operacji w ramach tej sesji.

Typowe parametry konfiguracji sesji obejmują:

• query_tags: Dołączanie tagów klucz-wartość do zapytań SQL na potrzeby śledzenia i analizy. Aby uzyskać więcej informacji, zobacz Przykład tagów zapytań.
• ansi_mode: Kontroluje tryb zgodności ANSI SQL ('true' lub 'false')
• timezone: Ustawia strefę czasową sesji (np. 'UTC', 'America/New_York')

Operacje

Zgodnie z opisem w temacie SesjeIOperation obiekty zwracane przez IDBSQLSession metody sesji w dokumentacji interfejsu API nie są w pełni wypełniane. Powiązana operacja serwera może nadal trwać, na przykład oczekiwanie na uruchomienie usługi Databricks SQL Warehouse, uruchomienie zapytania lub pobranie danych. Klasa IOperation ukrywa te szczegóły przed użytkownikami. Na przykład metody, takie fetchAlljak , fetchChunk, i getSchema oczekują wewnętrznie na zakończenie operacji, a następnie zwracają wyniki. Możesz użyć IOperation.finished() metody , aby jawnie poczekać na zakończenie operacji. Te metody przyjmują wywołanie zwrotne, które jest okresowo wywoływane podczas oczekiwania na zakończenie operacji. Ustawienie opcji progress na true powoduje próbę zażądania dodatkowych danych postępu z serwera i przekazania ich do tego wywołania zwrotnego.

Metody close i cancel można wywołać w dowolnym momencie. Po wywołaniu natychmiast unieważniają IOperation obiekt; wszystkie oczekujące wywołania, takie jak fetchAll, fetchChunk, i getSchema, są natychmiast anulowane, a zwracany jest błąd. W niektórych przypadkach operacja serwera mogła już zostać ukończona, a cancel metoda ma wpływ tylko na klienta.

Metoda fetchAll wywołuje fetchChunk wewnętrznie i zbiera wszystkie dane do tablicy. Chociaż jest to wygodne, może to spowodować błędy braku pamięci podczas korzystania z dużych zestawów danych. fetchAll opcje są zwykle przekazywane do fetchChunk.

Pobieranie fragmentów danych

Pobieranie fragmentów danych używa następującego wzorca kodu:

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

Metoda fetchChunk w dokumentacji interfejsu API przetwarza dane w małych częściach, aby zmniejszyć zużycie pamięci. fetchChunk najpierw oczekuje na ukończenie operacji, jeśli nie zostały jeszcze ukończone, a następnie wywołuje wywołanie zwrotne podczas cyklu oczekiwania, a następnie pobiera następny fragment danych.

Możesz użyć maxRows opcji , aby określić żądany rozmiar fragmentu. Jednak zwrócony fragment może mieć inny rozmiar, mniejszy lub nawet czasami większy. fetchChunk nie próbuje prefetchować danych wewnętrznie, aby podzielić je na żądane fragmenty. Wysyła opcję maxRows do serwera i zwraca to, co zwraca serwer. Nie należy mylić tej maxRows opcji z tą w IDBSQLSession. maxRows przekazana do fetchChunk definiuje rozmiar każdego fragmentu i nie wykonuje żadnych innych czynności.

Zarządzanie plikami w wolumenach Unity Catalog

Sterownik SQL usługi Databricks umożliwia zapisywanie plików lokalnych w woluminach Unity Catalog , pobieranie plików z woluminów i usuwanie plików z woluminów, jak pokazano w poniższym przykładzie:

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

Konfigurowanie rejestrowania

Rejestrator zawiera informacje dotyczące debugowania problemów z łącznikiem. Wszystkie DBSQLClient obiekty są tworzone za pomocą rejestratora, który wypisuje do konsoli, ale można przekazując niestandardowy rejestrator, wysłać te informacje do pliku. W poniższym przykładzie pokazano, jak skonfigurować rejestrator i zmienić jego poziom.

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

Aby uzyskać dodatkowe przykłady, zobacz folder examples w repozytorium databricks/databricks-sql-nodejs w witrynie GitHub.

Testowanie

Aby przetestować kod, możesz użyć platform testowych JavaScript, takich jak Jest. Aby przetestować kod w symulowanych warunkach bez wywoływania punktów końcowych interfejsu API REST usługi Azure Databricks lub zmieniania stanu kont lub obszarów roboczych usługi Azure Databricks, możesz użyć wbudowanych struktur pozorowania w usłudze Jest.

Na przykład, dany jest następujący plik o nazwie helpers.js, który zawiera funkcję getDBSQLClientWithPAT, wykorzystującą osobisty token dostępu usługi Azure Databricks do uzyskania połączenia z obszarem roboczym tej usługi, funkcję getAllColumnsFromTable, która używa tego połączenia do pobrania określonej liczby wierszy danych z określonej tabeli (na przykład tabeli trips w schemacie samples katalogu nyctaxi), oraz funkcję printResults do drukowania zawartości wierszy danych.

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

I biorąc pod uwagę następujący plik o nazwie main.js, który wywołuje funkcję getDBSQLClientWithPAT, getAllColumnsFromTable oraz 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);
  });

Poniższy plik o nazwie helpers.test.js testuje, czy getAllColumnsFromTable funkcja zwraca oczekiwaną odpowiedź. Zamiast tworzyć rzeczywiste połączenie z docelowym obszarem roboczym, w tym teście symuluje się obiekt DBSQLClient. Test wyśmiewa również niektóre dane zgodne ze schematem i wartościami, które znajdują się w rzeczywistych danych. Test zwraca dane próbne za pośrednictwem udawanego połączenia, a następnie sprawdza, czy jedna z wartości wierszy danych próbnych jest zgodna z oczekiwaną wartością.

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

W przypadku języka TypeScript powyższy kod wygląda podobnie. W przypadku testowania za pomocą TypeScript, użyj ts-jest.

Dodatkowe zasoby

• Sterownik SQL usługi Databricks dla repozytorium Node.js w witrynie GitHub
• Rozpoczęcie pracy z sterownikiem SQL dla usługi Databricks dla Node.js
• Rozwiązywanie problemów ze sterownikiem SQL usługi Databricks dla Node.js

Referencja API

• Klasy
  • DBSQLClient klasa
    • Metody
      • connect metoda
      • openSession metoda
      • getClient metoda
      • close metoda
  • DBSQLSession klasa
    • Metody
      • executeStatement metoda
      • close metoda
      • getId metoda
      • getTypeInfo metoda
      • getCatalogs metoda
      • getSchemas metoda
      • getTables metoda
      • getFunctions metoda
      • getPrimaryKeys metoda
      • getCrossReference metoda
  • DBSQLOperation klasa
    • Metody
      • getId metoda
      • fetchAll metoda
      • fetchChunk metoda
      • close metoda

Klasy

Klasa DBSQLClient

Główny punkt wejścia do interakcji z bazą danych.

Metody

connect metoda

Otwiera połączenie z bazą danych.

Zwroty: Promise<IDBSQLClient>

openSession metoda

Otwiera sesję między elementem DBSQLClient i bazą danych.

Zwroty: Promise<IDBSQLSession>

getClient metoda

Zwraca wewnętrzny obiekt TCLIService.Client. Należy wykonać po nawiązaniu połączenia z DBSQLClient.

Brak parametrów

Zwraca TCLIService.Client

close metoda

Zamyka połączenie z bazą danych i zwalnia wszystkie skojarzone zasoby na serwerze. Wszelkie dodatkowe wywołania tego klienta będą zgłaszać błąd.

Brak parametrów.

Brak wartości zwracanej.

Klasa DBSQLSession

DBSQLSessions są używane głównie do wykonywania instrukcji w bazie danych oraz do różnych operacji pobierania metadanych.

Metody

executeStatement metoda

Wykonuje instrukcję z podanymi opcjami.

Zwroty: Promise<IOperation>

close metoda

Zamyka sesję. Należy wykonać po zakończeniu sesji.

Brak parametrów.

Brak wartości zwracanej.

getId metoda

Zwraca identyfikator GUID sesji.

Brak parametrów.

Zwroty: str

getTypeInfo metoda

Zwraca informacje o obsługiwanych typach danych.

Zwroty: Promise<IOperation>

getCatalogs metoda

Pobiera listę katalogów.

Zwroty: Promise<IOperation>

getSchemas metoda

Pobiera listę schematów.

Zwroty: Promise<IOperation>

getTables metoda

Pobiera listę tabel.

Zwroty: Promise<IOperation>

getFunctions metoda

Pobiera listę tabel.

Zwroty: Promise<IOperation>

getPrimaryKeys metoda

Pobiera listę kluczy podstawowych.

Zwroty: Promise<IOperation>

getCrossReference metoda

Pobiera informacje o kluczach obcych między dwiema tabelami.

Zwroty: Promise<IOperation>

Klasa DBSQLOperation

Operacje DBSQL Są tworzone przez narzędzia DBSQLSessions i mogą służyć do pobierania wyników instrukcji i sprawdzania ich wykonywania. Dane są pobierane za pośrednictwem funkcji fetchChunk i fetchAll.

Metody

getId metoda

Zwraca identyfikator GUID operacji.

Brak parametrów.

Zwroty: str

fetchAll metoda

Czeka na zakończenie operacji, a następnie pobiera wszystkie wiersze wynikowe operacji.

Parametry: Brak

Zwroty: Promise<Array<object>>

fetchChunk metoda

Czeka na zakończenie operacji, a następnie pobiera maksymalnie określoną liczbę wierszy z operacji.

Zwroty: Promise<Array<object>>

close metoda

Zamyka operację i zwalnia wszystkie skojarzone zasoby. Należy wykonać po zakończeniu korzystania z operacji.

Brak parametrów.

Brak wartości zwracanej.