Databricks SQL-Treiber für Node.js

Der Databricks SQL-Treiber für Node.js ist eine Node.js Bibliothek, mit der Sie JavaScript-Code zum Ausführen von SQL-Befehlen auf Azure Databricks-Computeressourcen verwenden können.

Anforderungen

• Ein Entwicklungscomputer mit Node.js, Version 14 oder höher Führen Sie den Befehl node -v aus, um die installierte Version von Node.js auszugeben. Um verschiedene Versionen von Node.jszu installieren und zu verwenden, können Sie Tools wie Node Version Manager (nvm) verwenden.

• Node-Paket-Manager (npm). Spätere Versionen von Node.js enthalten bereits npm. Führen Sie den Befehl npm aus, um zu überprüfen, ob npm -v installiert ist. Um bei Bedarf npm zu installieren, können Sie den Anweisungen, wie denen unter Download und Installation von npm, folgen.

• Das @databricks/sql-Paket von npm. Wenn Sie das @databricks/sql-Paket in Ihrem Node.js-Projekt als Abhängigkeit installieren möchten, verwenden Sie npm, um den folgenden Befehl im gleichen Verzeichnis auszuführen, in dem sich auch Ihr Projekt befindet:

  npm i @databricks/sql
  

• Wenn Sie TypeScript in Ihrem Node.js-Projekt installieren und verwenden möchten, verwenden Sie devDependencies, um die folgenden Befehle aus demselben Verzeichnis wie Ihr Projekt auszuführen:

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

• Ein vorhandener Cluster oder SQL Warehouse.

• Der Server-Hostname und der HTTP-Pfadwert für den vorhandenen Cluster oder SQL Warehouse.

  • Rufen Sie diese Werte für einen Cluster ab.
  • Rufen Sie diese Werte für ein SQL-Lagerhaus ab.

Authentifizierung

Der Databricks SQL-Treiber für Node.js unterstützt die folgenden Azure Databricks-Authentifizierungstypen:

• Databricks-Authentifizierung für persönliche Zugriffstoken
• Microsoft Entra ID-Tokenauthentifizierung
• OAuth-M2M (Machine-to-Machine)-Authentifizierung
• OAuth-Benutzer-zu-Computer-Authentifizierung (U2M)

Der Databricks SQL-Treiber für Node.js unterstützt die folgenden Azure Databricks-Authentifizierungstypen:

• Authentifizieren mit von Azure verwalteten Identitäten
• Authentifizieren mit Microsoft Entra-Dienstprinzipalen
• Authentifizieren mit der Azure CLI

Databricks persönliche Zugriffstoken-Authentifizierung

Um den Databricks SQL-Treiber für Node.js mit Authentifizierung zu verwenden, müssen Sie zuerst ein persönliches Azure Databricks-Zugriffstoken erstellen. Ausführliche Informationen zu diesem Schritt finden Sie unter Erstellen von persönlichen Zugriffstoken für Arbeitsbereichsbenutzer.

Verwenden Sie zum Authentifizieren des Databricks SQL-Treibers für Node.js das folgende Codeschnipsel. Dieses Codeschnipsel setzt voraus, dass Sie die folgenden Umgebungsvariablen gesetzt haben:

• DATABRICKS_SERVER_HOSTNAMEauf den Wert für den Server-Hostnamen Ihres Clusters oder SQL-Warehouses gesetzt.
• DATABRICKS_HTTP_PATH, legen Sie den HTTP-Pfadwert für Ihren Cluster oder SQL Warehouse fest.
• DATABRICKS_TOKEN ist auf das persönliche Azure Databricks-Zugriffstoken festgelegt.

Informationen zum Festlegen von Umgebungsvariablen finden Sie in der Dokumentation Ihres Betriebssystems.

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

Maschinenschrift

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

OAuth U2M-Authentifizierung (User-to-Machine)

Databricks SQL-Treiber für Node.js Version 1.8.0 und höher unterstützen die OAuth-Benutzer-zu-Computer-Authentifizierung (U2M).

Um den Databricks SQL-Treiber für Node.js mit der OAuth U2M-Authentifizierung zu authentifizieren, verwenden Sie den folgenden Codeausschnitt. Dieses Codeschnipsel setzt voraus, dass Sie die folgenden Umgebungsvariablen gesetzt haben:

• DATABRICKS_SERVER_HOSTNAMEauf den Wert für den Server-Hostnamen Ihres Clusters oder SQL-Warehouses gesetzt.
• DATABRICKS_HTTP_PATH, legen Sie den HTTP-Pfadwert für Ihren Cluster oder SQL Warehouse fest.

Informationen zum Festlegen von Umgebungsvariablen finden Sie in der Dokumentation Ihres Betriebssystems.

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

Maschinenschrift

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

OAuth-Computer-zu-Computer-Authentifizierung (M2M)

Databricks SQL-Treiber für Node.js Versionen 1.8.0 und höher unterstützen die OAuth-Computer-zu-Computer-Authentifizierung (U2M).

Um den Databricks-SQL-Treiber für Node.js mit der OAuth-M2M-Authentifizierung zu verwenden, müssen Sie die folgenden Schritte ausführen:

1. Erstellen Sie einen Azure Databricks-Dienstprinzipal in Ihrem Azure Databricks-Arbeitsbereich, und erstellen Sie ein OAuth-Geheimnis für diesen Dienstprinzipal.

   Informationen zum Erstellen des Dienstprinzipals und seines OAuth-Schlüssels finden Sie unter Autorisieren des Dienstprinzipalzugriffs auf Azure Databricks mit OAuth. Notieren Sie sich den UUID - oder Anwendungs-ID-Wert des Dienstprinzipals und den Geheimen Wert für den OAuth-Schlüssel des Dienstprinzipals.

2. Gewähren Sie dem Dienstprinzipal Zugriff auf Ihren Cluster oder Ihr Warehouse. Siehe Computerberechtigungen oder Ein SQL-Warehouse verwalten.

Verwenden Sie zum Authentifizieren des Databricks SQL-Treibers für Node.js das folgende Codeschnipsel. Dieses Codeschnipsel setzt voraus, dass Sie die folgenden Umgebungsvariablen gesetzt haben:

• DATABRICKS_SERVER_HOSTNAMEauf den Wert für den Server-Hostnamen Ihres Clusters oder SQL-Warehouses gesetzt.
• DATABRICKS_HTTP_PATH, legen Sie den HTTP-Pfadwert für Ihren Cluster oder SQL Warehouse fest.
• DATABRICKS_CLIENT_ID, auf den UUID - oder Anwendungs-ID-Wert des Dienstprinzipals festgelegt.
• DATABRICKS_CLIENT_SECRET, legen Sie den Geheimen Wert für den OAuth-Schlüssel des Dienstprinzipals fest.

Informationen zum Festlegen von Umgebungsvariablen finden Sie in der Dokumentation Ihres Betriebssystems.

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

Maschinenschrift

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

Microsoft Entra ID-Tokenauthentifizierung

Um den Databricks SQL-Treiber für Node.js mit der Microsoft Entra ID-Tokenauthentifizierung zu verwenden, müssen Sie den Databricks SQL-Treiber für Node.js mit dem Microsoft Entra ID-Token bereitstellen. Gehen Sie wie folgt vor, um ein Microsoft Entra ID-Zugriffstoken zu erstellen:

• Für einen Azure Databricks-Benutzer können Sie die Azure CLI verwenden. Siehe Manuelles Abrufen von Microsoft Entra-ID-Token.
• Ein Microsoft Entra ID-Dienstprinzipal finden Sie unter Abrufen von Token für Dienstprinzipale. Informationen zum Erstellen eines verwalteten Dienstprinzipals von Microsoft Entra ID finden Sie unter Dienstprinzipale.

Microsoft Entra ID-Token haben eine Standardlebensdauer von ca. 1 Stunde. Wiederholen Sie diesen Vorgang, um ein neues Microsoft Entra ID-Token zu erstellen.

Verwenden Sie zum Authentifizieren des Databricks SQL-Treibers für Node.js das folgende Codeschnipsel. Dieses Codeschnipsel setzt voraus, dass Sie die folgenden Umgebungsvariablen gesetzt haben:

• DATABRICKS_SERVER_HOSTNAMEauf den Wert für den Server-Hostnamen Ihres Clusters oder SQL-Warehouses gesetzt.
• DATABRICKS_HTTP_PATH, legen Sie den HTTP-Pfadwert für Ihren Cluster oder SQL Warehouse fest.
• DATABRICKS_TOKEN, auf das Microsoft Entra ID-Token gesetzt.

Informationen zum Festlegen von Umgebungsvariablen finden Sie in der Dokumentation Ihres Betriebssystems.

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

Maschinenschrift

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

Setze User-Agent

Im folgenden Codebeispiel wird veranschaulicht, wie die User-Agent Anwendung product_name für die Verwendungsnachverfolgung festgelegt wird.

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

Daten abfragen

Im folgenden Codebeispiel wird veranschaulicht, wie Sie den Databricks SQL-Treiber für Node.js aufrufen können, um eine einfache SQL-Abfrage in einer Azure Databricks-Computeressource auszuführen. Dieser Befehl gibt die ersten beiden Zeilen aus der trips Tabelle im Schema des samples Katalogs nyctaxi zurück.

Dieses Codebeispiel ruft die Verbindungsvariablenwerte für token, server_hostname und http_path aus einer Reihe von Azure Databricks-Umgebungsvariablen ab. Diese Umgebungsvariablen haben die folgenden Namen:

• DATABRICKS_TOKEN, das das persönliche Zugriffstoken für Azure Databricks aus den Anforderungen darstellt.
• DATABRICKS_SERVER_HOSTNAME, das den Server-Hostname-Wert aus den Anforderungen darstellt.
• DATABRICKS_HTTP_PATH, der den HTTP-Pfadwert aus den Anforderungen darstellt.

Sie können auch andere Methoden verwenden, um diese Verbindungsvariablenwerte abzurufen. Die Verwendung von Umgebungsvariablen ist nur ein Ansatz unter vielen.

Das folgende Codebeispiel veranschaulicht, wie der Databricks SQL-Connector für Node.js aufgerufen wird, um einen einfachen SQL-Befehl in einem Cluster oder SQL-Warehouse auszuführen. Dieser Befehl gibt die ersten beiden Zeilen der trips-Tabelle zurück.

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

Maschinenschrift

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

Beispiel für Abfragetags

Abfragetags sind Schlüsselwertpaare, die sql-Abfragen zur Nachverfolgung und Analyse angefügt werden können. Wenn festgelegt, werden sie in der system.query.history Tabelle angezeigt, sodass Sie Abfragemuster und -verwendung analysieren können.

Definieren Sie Abfragetags als durch Trennzeichen getrennte Schlüssel-Wert-Paare, wobei jeder Schlüssel und Wert durch einen Doppelpunkt getrennt ist, key1:value1,key2:value2z. B. .

Im folgenden Beispiel wird die Verwendung von Abfragetags mit der Sitzungskonfiguration veranschaulicht:

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

Maschinenschrift

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

Sitzungen

Alle IDBSQLSession-Methoden, die in der IOperation Objekte vom Typ zurückgeben, verfügen über die folgenden allgemeinen Parameter, die sich auf ihr Verhalten auswirken:

• Durch Festlegen von runAsync auf true wird der asynchrone Modus gestartet. IDBSQLSession-Methoden reihen Vorgänge in die Warteschlange ein und werden schnellstmöglich abgeschlossen. Der aktuelle Zustand des zurückgegebenen IOperation-Objekts kann variieren, und der Client ist dafür verantwortlich, vor der Verwendung des zurückgegebenen IOperation-Objekts den Status zu überprüfen. Siehe Vorgänge. Wenn runAsync auf false festgelegt wird, warten IDBSQLSession-Methoden auf den Abschluss von Vorgängen. Databricks empfiehlt, runAsync immer auf true festzulegen.
• Das Festlegen von maxRows auf einen Wert ungleich NULL ermöglicht direkte Ergebnisse. Bei direkten Ergebnissen versucht der Server, auf den Abschluss von Vorgängen zu warten, und ruft dann einen Teil der Daten ab. Abhängig davon, wie viel der Server innerhalb der definierten Zeit erledigen konnte, werden IOperation-Objekte ggf. in einem Zwischenzustand und nicht in einem ausstehenden Zustand zurückgegeben. Sehr häufig werden alle Metadaten und Abfrageergebnisse innerhalb einer einzelnen Anforderung an den Server zurückgegeben. Der Server verwendet maxRows, um zu bestimmen, wie viele Datensätze sofort zurückgegeben werden können. Der tatsächliche Block kann jedoch eine andere Größe aufweisen (siehe IDBSQLSession.fetchChunk). Direkte Ergebnisse sind standardmäßig aktiviert. Databricks rät davon ab, direkte Ergebnisse zu deaktivieren.

Sitzungskonfiguration

Sie können Sitzungskonfigurationsparameter übergeben, wenn Sie eine Sitzung mithilfe des configuration Objekts in der openSession Methode öffnen. Diese Parameter wirken sich auf das Verhalten aller Vorgänge innerhalb dieser Sitzung aus.

Allgemeine Sitzungskonfigurationsparameter sind:

• query_tags: Fügen Sie Schlüsselwerttags an SQL-Abfragen an, um Nachverfolgung und Analyse zu erhalten. Weitere Informationen finden Sie im Beispiel für Abfragetags.
• ansi_mode: Steuert den ANSI SQL-Kompatibilitätsmodus ('true' oder 'false')
• timezone: Legt die Sitzungszeitzone fest (z. B. 'UTC', ) 'America/New_York'

Operationen (Operations)

Wie unter Sitzungen beschrieben, werden IOperation-Objekte, die von IDBSQLSession-Sitzungsmethoden in der API-Referenz zurückgegeben werden, nicht vollständig aufgefüllt. Der zugehörige Servervorgang wird möglicherweise noch ausgeführt. Beispiele wären etwa das Warten auf den Start des Databricks SQL-Warehouse, das Ausführen der Abfrage oder das Abrufen der Daten. Die IOperation-Klasse blendet diese Details für Benutzer*innen aus. Methoden wie fetchAll, fetchChunk und getSchema warten beispielsweise intern, bis Vorgänge abgeschlossen sind, und geben dann Ergebnisse zurück. Sie können die IOperation.finished()-Methode verwenden, um explizit auf den Abschluss von Vorgängen zu warten. Diese Methoden verwenden einen Rückruf, der regelmäßig aufgerufen wird, während auf den Abschluss von Vorgängen gewartet wird. Wenn die Option progress auf true festgelegt wird, wird versucht, zusätzliche Fortschrittsdaten vom Server anzufordern und an diesen Rückruf zu übergeben.

Die Methoden close und cancel können jederzeit aufgerufen werden. Durch den Aufruf wird das IOperation-Objekt sofort ungültig gemacht. Alle ausstehenden Aufrufe wie fetchAll, fetchChunk und getSchema werden sofort abgebrochen, und ein Fehler wird zurückgegeben. In einigen Fällen ist der Servervorgang möglicherweise bereits abgeschlossen, und die cancel-Methode wirkt sich nur auf den Client aus.

Die fetchAll-Methode ruft intern fetchChunk auf und sammelt alle Daten in einem Array. Das ist zwar praktisch, kann bei der Verwendung in großen Datasets aber zu Fehlern aufgrund von unzureichendem Arbeitsspeicher führen. Optionen vom Typ fetchAll werden in der Regel an fetchChunkübergeben.

Abrufen von Datenblöcken

Beim Abrufen von Datenblöcken wird das folgende Codemuster verwendet:

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

Die fetchChunk Methode in der API-Referenz verarbeitet Daten in kleinen Teilen, um den Speicherverbrauch zu reduzieren. fetchChunk wartet zunächst, bis Vorgänge abgeschlossen sind (sofern sie noch nicht abgeschlossen wurden), ruft dann während des Wartezyklus einen Rückruf auf, und ruft anschließend den nächsten Datenblock ab.

Sie können die Option maxRows verwenden, um die gewünschte Blockgröße anzugeben. Der zurückgegebene Block kann jedoch eine andere Größe haben und kleiner oder manchmal auch größer sein. fetchChunk versucht nicht, Daten intern vorab abzurufen, um sie in die angeforderten Teile zu partitionieren. Die Option maxRows wird an den Server gesendet, und die Rückgabe des Servers wird zurückgegeben. Diese maxRows-Option darf nicht mit der Option in IDBSQLSession verwechselt werden. Die Übergabe von maxRows an fetchChunk definiert ausschließlich die Größe der einzelnen Blöcke.

Verwalten von Dateien in Unity Catalog-Volumes

Mit dem Databricks SQL-Treiber können Sie lokale Dateien in Unity-Katalogvolumes schreiben, Dateien aus Volumes herunterladen und Dateien aus Volumes löschen, wie im folgenden Beispiel gezeigt:

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

Maschinenschrift

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

Konfigurieren der Protokollierung

Die Protokollierung bietet Informationen zum Debuggen von Problemen mit dem Connector. Alle DBSQLClient-Objekte werden mit einer Protokollierung instanziiert, die Ergebnisse an die Konsole ausgibt, aber durch Übergeben einer benutzerdefinierten Protokollierung können Sie diese Informationen an eine Datei senden. Das folgende Beispiel zeigt, wie Sie eine Protokollierung konfigurieren und den Protokollierungsgrad ändern.

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

Maschinenschrift

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

Weitere Beispiele finden Sie im Beispielordner im Repository "databricks/databricks-sql-nodejs" auf GitHub.

Testen

Um Ihren Code zu testen, können Sie JavaScript-Testframeworks wie Jest verwenden. Um Ihren Code unter simulierten Bedingungen zu testen, ohne Azure Databricks-REST-API-Endpunkte aufzurufen oder den Status Ihrer Azure Databricks-Konten oder -Arbeitsbereiche zu ändern, können Sie die integrierten Modellframeworks von Jest verwenden.

Wenn beispielsweise die folgende Datei mit dem Namen helpers.js eine Funktion getDBSQLClientWithPAT enthält, die ein Azure Databricks-Persönliches Zugriffstoken verwendet, um eine Verbindung zu einem Azure Databricks-Arbeitsbereich zurückzugeben, eine Funktion getAllColumnsFromTable, die diese Verbindung nutzt, um die angegebene Anzahl von Datenzeilen aus der angegebenen Tabelle abzurufen (z. B. die Tabelle trips im Schema samples des Katalogs nyctaxi), und eine Funktion printResults, um den Inhalt der Datenzeilen zu drucken:

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

Nehmen wir außerdem an, die folgende Datei mit dem Namen main.js ruft die Funktionen getDBSQLClientWithPAT, getAllColumnsFromTable und printResults auf:

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

Die folgende Datei mit dem Namen helpers.test.js testet, ob die getAllColumnsFromTable Funktion die erwartete Antwort zurückgibt. Anstatt eine echte Verbindung mit dem Zielarbeitsbereich zu erstellen, simuliert dieser Test ein DBSQLClient-Objekt. Zudem simuliert der Test einige Daten, die dem Schema und den Werten aus den realen Daten entsprechen. Der Test gibt die simulierten Daten über die simulierte Verbindung zurück und überprüft dann, ob einer der Werte der simulierten Datenzeilen dem erwarteten Wert entspricht.

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

Für TypeScript sieht der voranstehende Code ähnlich aus. Verwenden Sie für Jest-Tests mit TypeScript ts-jest.

Zusätzliche Ressourcen

• Der Databricks SQL-Treiber für Node.js Repository auf GitHub
• Erste Schritte mit dem Databricks SQL-Treiber für Node.js
• Problembehandlung des Databricks SQL-Treibers für Node.js

API-Referenz

• Klassen
  • DBSQLClient-Klasse
    • Methodik
      • connect Methode
      • openSession Methode
      • getClient Methode
      • close Methode
  • DBSQLSession-Klasse
    • Methodik
      • executeStatement Methode
      • close Methode
      • getId Methode
      • getTypeInfo Methode
      • getCatalogs Methode
      • getSchemas Methode
      • getTables Methode
      • getFunctions Methode
      • getPrimaryKeys Methode
      • getCrossReference Methode
  • DBSQLOperation-Klasse
    • Methodik
      • getId Methode
      • fetchAll Methode
      • fetchChunk Methode
      • close Methode

Klassen

DBSQLClient-Klasse

Haupteinstiegspunkt für die Interaktion mit einer Datenbank.

Methoden

connect-Methode

Öffnet eine Verbindung mit der Datenbank.

Rückgabewert: Promise<IDBSQLClient>

openSession-Methode

Öffnet eine Sitzung zwischen DBSQLClient und Datenbank.

Rückgabewert: Promise<IDBSQLSession>

getClient-Methode

Gibt das interne Thrift-Objekt „TCLIService.Client“ zurück. Muss aufgerufen werden, nachdem DBSQLClient die Verbindung hergestellt hat.

Keine Parameter

Gibt TCLIService.Client zurück

close-Methode

Schließt die Verbindung mit der Datenbank und gibt alle zugeordneten Ressourcen auf dem Server frei. Jegliche zusätzlichen Aufrufe dieses Clients lösen einen Fehler aus.

Keine Parameter.

Kein Rückgabewert.

DBSQLSession-Klasse

DBSQLSessions werden in erster Linie für die Ausführung von Anweisungen für die Datenbank sowie für verschiedene Metadatenabrufvorgänge verwendet.

Methoden

executeStatement-Methode

Führt eine Anweisung mit den angegebenen Optionen aus.

Rückgabewert: Promise<IOperation>

close-Methode

Schließt die Sitzung. Muss nach der Verwendung der Sitzung ausgeführt werden.

Keine Parameter.

Kein Rückgabewert.

getId-Methode

Gibt die GUID der Sitzung zurück.

Keine Parameter.

Rückgabewert: str

getTypeInfo-Methode

Gibt Informationen zu unterstützten Datentypen zurück.

Rückgabewert: Promise<IOperation>

getCatalogs-Methode

Ruft eine Liste von Katalogen ab.

Rückgabewert: Promise<IOperation>

getSchemas-Methode

Ruft eine Liste von Schemas ab.

Rückgabewert: Promise<IOperation>

getTables-Methode

Ruft eine Liste von Tabellen ab.

Rückgabewert: Promise<IOperation>

getFunctions-Methode

Ruft eine Liste von Tabellen ab.

Rückgabewert: Promise<IOperation>

getPrimaryKeys-Methode

Ruft eine Liste von Primärschlüsseln ab.

Rückgabewert: Promise<IOperation>

getCrossReference-Methode

Ruft Informationen zu Fremdschlüsseln zwischen zwei Tabellen ab.

Rückgabewert: Promise<IOperation>

DBSQLOperation-Klasse

DBSQLOperations werden von DBSQLSessions erstellt und können verwendet werden, um die Ergebnisse von Anweisungen abzurufen und deren Ausführung zu überprüfen. Daten werden mit den Funktionen fetchChunk und fetchAll abgerufen.

Methoden

getId-Methode

Gibt die GUID des Vorgangs zurück.

Keine Parameter.

Rückgabewert: str

fetchAll-Methode

Wartet auf den Abschluss des Vorgangs und ruft dann alle Zeilen aus dem Vorgang ab.

Parameter: keine

Rückgabewert: Promise<Array<object>>

fetchChunk-Methode

Wartet auf den Abschluss des Vorgangs und ruft dann Zeilen bis zu einer angegebenen Anzahl aus dem Vorgang ab.

Rückgabewert: Promise<Array<object>>

close-Methode

Schließt die Verbindung und gibt alle zugeordneten Ressourcen frei. Muss ausgeführt werden, nachdem der Vorgang nicht mehr verwendet wird.

Keine Parameter.

Kein Rückgabewert.