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 za pomocą 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.js i korzystać z nich, możesz użyć narzędzi, takich jak Node Version Manager (nvm).

• Węzeł Menedżer pakietów (npm). Nowsze wersje Node.js już obejmują npm. Aby sprawdzić, czy npm jest zainstalowana, uruchom polecenie npm -v. Aby zainstalować w npm razie potrzeby, możesz postępować zgodnie z instrukcjami, takimi jak pobieranie i instalowanie narzędzia npm.

• Pakiet @databricks/sql z narzędzia npm. Aby zainstalować @databricks/sql pakiet w projekcie Node.js jako zależność, uruchom npm następujące polecenie z tego samego katalogu co projekt:

  npm i @databricks/sql
  

• Jeśli chcesz zainstalować język TypeScript i używać go w projekcie Node.js jako devDependencies, użyj polecenia npm , aby uruchomić następujące polecenia z tego samego katalogu co projekt:

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

• Istniejący klaster lub magazyn SQL Warehouse.

• 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 identyfikatora entra firmy Microsoft
• 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 tożsamości zarządzanych platformy Azure
• Uwierzytelnianie jednostki usługi MS Entra
• Uwierzytelnianie interfejsu wiersza polecenia platformy Azure

Uwaga

Najlepszym rozwiązaniem w zakresie zabezpieczeń nie powinno być zakodowanie wartości zmiennych połączenia w kodzie. Zamiast tego należy pobrać te wartości zmiennych połączenia z bezpiecznej lokalizacji. Na przykład fragmenty kodu i przykłady w tym artykule używają zmiennych środowiskowych.

Uwierzytelnianie osobistego tokenu dostępu usługi Databricks

Aby użyć sterownika SQL usługi Databricks na potrzeby Node.js z uwierzytelnianiem osobistego tokenu dostępu usługi Azure Databricks, należy najpierw utworzyć osobisty token dostępu usługi Azure Databricks w następujący sposób:

1. W obszarze roboczym usługi Azure Databricks kliknij nazwę użytkownika usługi Azure Databricks na górnym pasku, a następnie wybierz pozycję Ustawienia z listy rozwijanej.
2. Kliknij pozycję Deweloper.
3. Obok pozycji Tokeny dostępu kliknij pozycję Zarządzaj.
4. Kliknij pozycję Generuj nowy token.
5. (Opcjonalnie) Wprowadź komentarz, który pomaga zidentyfikować ten token w przyszłości i zmienić domyślny okres istnienia tokenu na 90 dni. Aby utworzyć token bez okresu istnienia (niezalecane), pozostaw puste pole Okres istnienia (dni) (puste).
6. Kliknij pozycję Generate (Generuj).
7. Skopiuj wyświetlony token do bezpiecznej lokalizacji, a następnie kliknij przycisk Gotowe.

Uwaga

Pamiętaj, aby zapisać skopiowany token w bezpiecznej lokalizacji. Nie udostępniaj skopiowanego tokenu innym osobom. W przypadku utraty skopiowanego tokenu nie można wygenerować tego samego tokenu. Zamiast tego należy powtórzyć tę procedurę, aby utworzyć nowy token. Jeśli utracisz skopiowany token lub uważasz, że token został naruszony, usługa Databricks zdecydowanie zaleca natychmiastowe usunięcie tego tokenu z obszaru roboczego, klikając ikonę kosza (Odwołaj) obok tokenu na stronie Tokeny dostępu.

Jeśli nie możesz utworzyć lub użyć tokenów w obszarze roboczym, może to być spowodowane tym, że administrator obszaru roboczego wyłączył tokeny lub nie udzielił Ci uprawnień do tworzenia lub używania tokenów. Zapoznaj się z administratorem obszaru roboczego lub następującymi tematami:

• Włączanie lub wyłączanie uwierzytelniania osobistego tokenu dostępu dla obszaru roboczego
• Uprawnienia osobistego tokenu dostępu

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 wartość ścieżka HTTP dla klastra lub usługi SQL Warehouse.
• DATABRICKS_TOKEN, ustaw na 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 między użytkownikami (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 wartość ścieżka HTTP dla klastra lub usługi SQL Warehouse.

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",
    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)
  // ...

Uwierzytelnianie maszyny do maszyny 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 jednostkę usługi Azure Databricks w obszarze roboczym usługi Azure Databricks i utwórz wpis tajny OAuth dla tej jednostki usługi.

   Aby utworzyć jednostkę usługi i jej wpis tajny OAuth, zobacz Uwierzytelnianie dostępu do usługi Azure Databricks przy użyciu jednostki usługi przy użyciu protokołu OAuth (OAuth M2M). Zanotuj wartość UUID lub Identyfikator aplikacji jednostki usługi oraz wartość wpisu tajnego dla wpisu tajnego OAuth jednostki usługi.

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 wartość ścieżka HTTP dla klastra lub usługi SQL Warehouse.
• DATABRICKS_CLIENT_ID, ustaw wartość UUID jednostki usługi lub Identyfikator aplikacji.
• DATABRICKS_CLIENT_SECRET, ustaw wartość wpisu tajnego dla wpisu tajnego OAuth jednostki 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",
    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)
  // ...

Uwierzytelnianie tokenu identyfikatora entra firmy Microsoft

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 Uzyskiwanie tokenów identyfikatora entra firmy Microsoft dla użytkowników przy użyciu interfejsu wiersza polecenia platformy Azure.
• Aby uzyskać jednostkę usługi Microsoft Entra ID, zobacz Uzyskiwanie tokenu dostępu identyfikatora Entra firmy Microsoft za pomocą interfejsu wiersza polecenia platformy Azure. Aby utworzyć jednostkę usługi zarządzanej identyfikatora entra firmy Microsoft, zobacz Zarządzanie jednostkami 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 wartość ścieżka HTTP dla klastra lub usługi SQL Warehouse.
• DATABRICKS_TOKEN, ustaw wartość tokenu 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)
  // ...

Zapytania o dane

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 trips tabeli w schemacie samples wykazu nyctaxi .

Uwaga

W poniższym przykładzie kodu pokazano, jak używać osobistego tokenu dostępu usługi Azure Databricks do uwierzytelniania. Aby zamiast tego użyć innych dostępnych typów uwierzytelniania usługi Azure Databricks, zobacz Uwierzytelnianie.

Ten przykładowy kod pobiera tokenserver_hostname wartości zmiennych środowiskowych , i http_path parametrów połączenia z zestawu zmiennych środowiskowych usługi Azure Databricks. Te zmienne środowiskowe mają następujące nazwy zmiennych środowiskowych:

• DATABRICKS_TOKEN, który reprezentuje osobisty token dostępu usługi Azure Databricks z wymagań.
• 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 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);
});

Wyjście:

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

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 true uruchomienie trybu asynchronicznego. IDBSQLSession metody umieszczają operacje w kolejce i zwracają je 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. Usługa Databricks zaleca zawsze ustawienie wartości runAsync 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 metody , aby określić, 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 zaleca wyłączenie wyników bezpośrednich.

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. progress Ustawienie opcji true na próby zażądania dodatkowych danych postępu z serwera i przekazanie 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, fetchChunki są natychmiast anulowane, a getSchema 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 w przypadku użycia w dużych zestawach 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 program nie próbuje wstępnie pobrać danych wewnętrznie, aby podzielić je na żądane fragmenty. Wysyła maxRows ona opcję do serwera i zwraca niezależnie od tego, co zwraca serwer. Nie należy mylić tej maxRows opcji z tą w IDBSQLSessionpliku . maxRows przekazana do fetchChunk definiuje rozmiar każdego fragmentu i nie wykonuje żadnych innych czynności.

Zarządzanie plikami w woluminach wykazu aparatu Unity

Sterownik SQL usługi Databricks umożliwia zapisywanie plików lokalnych w woluminach wykazu aparatu Unity, 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 drukuje do konsoli, ale przekazując niestandardowy rejestrator, można 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, biorąc pod uwagę następujący plik o nazwie helpers.js zawierający getDBSQLClientWithPAT funkcję, która używa osobistego tokenu dostępu usługi Azure Databricks w celu zwrócenia połączenia z obszarem roboczym usługi Azure Databricks, getAllColumnsFromTable funkcja korzystająca z połączenia w celu pobrania określonej liczby wierszy danych z określonej tabeli (na przykład trips tabeli w samples schemacie wykazu nyctaxi ) oraz printResults funkcji 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();
    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
};

I biorąc pod uwagę następujący plik o nazwie main.js , który wywołuje getDBSQLClientWithPATfunkcje , getAllColumnsFromTablei 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, ten test wyśmiewa DBSQLClient obiekt. Test wyśmiewa również niektóre dane zgodne ze schematem i wartościami, które znajdują się w rzeczywistych danych. Test zwraca wyśmiewane dane za pośrednictwem pozorowanego połączenia, a następnie sprawdza, czy jedna z wyśmiewanych wartości wierszy danych jest zgodna z oczekiwaną wartością.

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

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

Dodatkowe zasoby

• Sterownik SQL usługi Databricks dla repozytorium Node.js w usłudze GitHub
• Wprowadzenie do sterownika SQL usługi Databricks dla Node.js
• Rozwiązywanie problemów ze sterownikiem SQL usługi Databricks dla Node.js

Odwołanie do interfejsu API

• Klasy
  • Klasa DBSQLClient
    • Metody
      • connect metoda
      • openSession metoda
      • getClient metoda
      • close metoda
  • Klasa DBSQLSession
    • Metody
      • executeStatement metoda
      • close metoda
      • getId metoda
      • getTypeInfo metoda
      • getCatalogs metoda
      • getSchemas metoda
      • getTables metoda
      • getFunctions metoda
      • getPrimaryKeys metoda
      • getCrossReference metoda
  • Klasa DBSQLOperation
    • 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.

Parametry
Opcje Typ: ConnectionOptions Zestaw opcji używanych do nawiązywania połączenia z bazą danych. hostNależy wypełnić pola , pathi inne wymagane. Zobacz Uwierzytelnianie. Przykład: const client: DBSQLClient = new DBSQLClient(); client.connect( { host: serverHostname, path: httpPath, // ... } )

Zwroty: Promise<IDBSQLClient>

openSession metoda

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

Parametry
prosić Typ: OpenSessionRequest Zestaw parametrów opcjonalnych do określania początkowego schematu i katalogu początkowego Przykład: const session = await client.openSession( {initialCatalog: 'catalog'} );

Zwroty: Promise<IDBSQLSession>

getClient metoda

Zwraca wewnętrzny obiekt TCLIService.Client. Należy wywołać wywołanie po nawiązaniu połączenia z klientem 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

Bazy danych DBSQLSessions są używane głównie do wykonywania instrukcji względem bazy danych, a także różnych operacji pobierania metadanych.

Metody

executeStatement metoda

Wykonuje instrukcję z podanymi opcjami.

Parametry
wypowiedź Typ: str Instrukcja do wykonania.
Opcje Typ: ExecuteStatementOptions Zestaw opcjonalnych parametrów do określania limitu czasu zapytania, maksymalnej liczby wierszy dla wyników bezpośrednich oraz tego, czy zapytanie ma być uruchamiane asynchronicznie. Domyślnie maxRows ustawiono wartość 10000. Jeśli maxRows ustawiono wartość null, operacja zostanie uruchomiona z wyłączoną funkcją wyników bezpośrednich. Przykład: const session = await client.openSession( {initialCatalog: 'catalog'} ); queryOperation = await session.executeStatement( 'SELECT "Hello, World!"', { runAsync: true } );

Zwroty: Promise<IOperation>

close metoda

Zamyka sesję. Należy wykonać po użyciu 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.

Parametry
prosić Typ: TypeInfoRequest Parametry żądania.

Zwroty: Promise<IOperation>

getCatalogs metoda

Pobiera listę wykazów.

Parametry
prosić Typ: CatalogsRequest Parametry żądania.

Zwroty: Promise<IOperation>

getSchemas metoda

Pobiera listę schematów.

Parametry
prosić Typ: SchemasRequest Parametry żądania. Pola catalogName i schemaName mogą być używane do celów filtrowania.

Zwroty: Promise<IOperation>

getTables metoda

Pobiera listę tabel.

Parametry
prosić Typ: TablesRequest Parametry żądania. Pola catalogName i schemaName tableName może służyć do filtrowania.

Zwroty: Promise<IOperation>

getFunctions metoda

Pobiera listę tabel.

Parametry
prosić Typ: FunctionsRequest Parametry żądania. Pole functionName jest wymagane.

Zwroty: Promise<IOperation>

getPrimaryKeys metoda

Pobiera listę kluczy podstawowych.

Parametry
prosić Typ: PrimaryKeysRequest Parametry żądania. Pola schemaName i tableName są wymagane.

Zwroty: Promise<IOperation>

getCrossReference metoda

Pobiera informacje o kluczach obcych między dwiema tabelami.

Parametry
prosić Typ: CrossReferenceRequest Parametry żądania. Nazwa schematu, elementu nadrzędnego i wykazu musi być określona dla obu tabel.

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 pobierania fragmentów i pobieraniaWszystkie.

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

Parametry
Opcje Typ: FetchOptions Opcje używane do pobierania. Obecnie jedyną opcją jest maxRows, która odpowiada maksymalnej liczbie obiektów danych zwracanych w dowolnej tablicy.

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.