Databricks SQL-stuurprogramma voor Node.js

Artikel
06/28/2024

Het Databricks SQL-stuurprogramma voor Node.js is een Node.js bibliotheek waarmee u JavaScript-code kunt gebruiken om SQL-opdrachten uit te voeren op Azure Databricks-rekenresources.

Vereisten

Een ontwikkelcomputer met Node.js, versie 14 of hoger. Als u de geïnstalleerde versie van Node.js wilt afdrukken, voert u de opdracht node -vuit. Als u verschillende versies van Node.js wilt installeren en gebruiken, kunt u hulpprogramma's zoals Node Version Manager (nvm) gebruiken.
Node Pakketbeheer (npm). Latere versies van Node.js bevatten al npm. Voer de opdracht npm -vuit om te controleren of npm deze is geïnstalleerd. Als u indien nodig wilt installeren npm , kunt u instructies volgen, zoals de instructies bij Downloaden en npm installeren.
Het @databricks/sql-pakket van npm. Als u het @databricks/sql pakket in uw Node.js project als een afhankelijkheid wilt installeren, gebruikt npm u om de volgende opdracht uit te voeren vanuit dezelfde map als uw project:
```
npm i @databricks/sql
```
Als u TypeScript wilt installeren en gebruiken in uw Node.js-project, devDependenciesgebruikt npm u om de volgende opdrachten uit te voeren vanuit dezelfde map als uw project:
```
npm i -D typescript
npm i -D @types/node
```
Een bestaand cluster of SQL-magazijn.
De serverhostnaam en HTTP-padwaarde voor het bestaande cluster of SQL Warehouse.
- Haal deze waarden op voor een cluster.
- Haal deze waarden op voor een SQL-warehouse.

Verificatie

Het Databricks SQL-stuurprogramma voor Node.js ondersteunt de volgende Azure Databricks-verificatietypen:

Verificatie van persoonlijke toegangstokens van Databricks
Verificatie van tokens van Microsoft Entra ID (voorheen Azure Active Directory)
OAuth-verificatie van machine-naar-machine (M2M)
OAuth-verificatie van gebruiker naar machine (U2M)

Het Databricks SQL-stuurprogramma voor Node.js biedt nog geen ondersteuning voor de volgende Azure Databricks-verificatietypen:

Notitie

Als best practice voor beveiliging moet u geen waarden voor de verbindingsvariabele voor code in uw code vastmaken. In plaats daarvan moet u deze verbindingsvariabelewaarden ophalen van een veilige locatie. De codefragmenten en voorbeelden in dit artikel maken bijvoorbeeld gebruik van omgevingsvariabelen.

Verificatie van persoonlijke toegangstokens van Databricks

Als u het Databricks SQL-stuurprogramma wilt gebruiken voor Node.js met persoonlijke toegangstokenverificatie van Azure Databricks, moet u eerst een persoonlijk toegangstoken van Azure Databricks maken:

Klik in uw Azure Databricks-werkruimte op uw Azure Databricks-gebruikersnaam in de bovenste balk en selecteer vervolgens Instellingen in de vervolgkeuzelijst.
Klik op Ontwikkelaars.
Klik naast Access-tokens op Beheren.
Klik op Nieuw token genereren.
(Optioneel) Voer een opmerking in waarmee u dit token in de toekomst kunt identificeren en de standaardlevensduur van het token van 90 dagen kunt wijzigen. Als u een token zonder levensduur wilt maken (niet aanbevolen), laat u het vak Levensduur (dagen) leeg (leeg).
Klik op Genereren.
Kopieer het weergegeven token naar een veilige locatie en klik vervolgens op Gereed.

Notitie

Zorg ervoor dat u het gekopieerde token op een veilige locatie opslaat. Deel uw gekopieerde token niet met anderen. Als u het gekopieerde token kwijtraakt, kunt u dat token niet opnieuw genereren. In plaats daarvan moet u deze procedure herhalen om een nieuw token te maken. Als u het gekopieerde token kwijtraakt of als u denkt dat het token is aangetast, raadt Databricks u ten zeerste aan dat u dat token onmiddellijk uit uw werkruimte verwijdert door te klikken op het prullenbakpictogram (Intrekken) naast het token op de pagina Toegangstokens .

Als u geen tokens in uw werkruimte kunt maken of gebruiken, kan dit komen doordat uw werkruimtebeheerder tokens heeft uitgeschakeld of u geen toestemming hebt gegeven om tokens te maken of te gebruiken. Neem de werkruimtebeheerder of het volgende weer:

Gebruik het volgende codefragment om het Databricks SQL-stuurprogramma voor Node.js te verifiëren. In dit fragment wordt ervan uitgegaan dat u de volgende omgevingsvariabelen hebt ingesteld:

DATABRICKS_SERVER_HOSTNAMEingesteld op de serverhostnaamwaarde voor uw cluster of SQL Warehouse.
DATABRICKS_HTTP_PATH, ingesteld op HTTP-padwaarde voor uw cluster of SQL Warehouse.
DATABRICKS_TOKEN, ingesteld op het persoonlijke toegangstoken van Azure Databricks.

Als u omgevingsvariabelen wilt instellen, raadpleegt u de documentatie van uw besturingssysteem.

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

OAuth-verificatie van gebruiker naar machine (U2M)

Databricks SQL-stuurprogramma voor Node.js versies 1.8.0 en hoger bieden ondersteuning voor OAuth-gebruikers-naar-machine-verificatie (U2M).

Gebruik het volgende codefragment om het Databricks SQL-stuurprogramma te verifiëren voor Node.js met OAuth U2M-verificatie. In dit fragment wordt ervan uitgegaan dat u de volgende omgevingsvariabelen hebt ingesteld:

DATABRICKS_SERVER_HOSTNAMEingesteld op de serverhostnaamwaarde voor uw cluster of SQL Warehouse.
DATABRICKS_HTTP_PATH, ingesteld op HTTP-padwaarde voor uw cluster of SQL Warehouse.

Als u omgevingsvariabelen wilt instellen, raadpleegt u de documentatie van uw besturingssysteem.

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

OAuth-verificatie van machine-naar-machine (M2M)

Databricks SQL-stuurprogramma voor Node.js versies 1.8.0 en hoger bieden ondersteuning voor OAuth-verificatie van machine-naar-machine (U2M).

Als u het Databricks SQL-stuurprogramma wilt gebruiken voor Node.js met OAuth M2M-verificatie, moet u het volgende doen:

Maak een Azure Databricks-service-principal in uw Azure Databricks-werkruimte en maak een OAuth-geheim voor die service-principal.

Zie Een service-principal gebruiken om te verifiëren met Azure Databricks om de service-principal en het bijbehorende OAuth-geheim te maken. Noteer de UUID- of toepassings-id van de service-principal en de geheime waarde voor het OAuth-geheim van de service-principal.
Geef de service-principal toegang tot uw cluster of magazijn. Zie Compute-machtigingen of een SQL-warehouse beheren.

Gebruik het volgende codefragment om het Databricks SQL-stuurprogramma voor Node.js te verifiëren. In dit fragment wordt ervan uitgegaan dat u de volgende omgevingsvariabelen hebt ingesteld:

DATABRICKS_SERVER_HOSTNAMEingesteld op de serverhostnaamwaarde voor uw cluster of SQL Warehouse.
DATABRICKS_HTTP_PATH, ingesteld op HTTP-padwaarde voor uw cluster of SQL Warehouse.
DATABRICKS_CLIENT_ID, ingesteld op de UUID- of toepassings-id van de service-principal.
DATABRICKS_CLIENT_SECRET, ingesteld op de geheime waarde voor het OAuth-geheim van de service-principal.

Als u omgevingsvariabelen wilt instellen, raadpleegt u de documentatie van uw besturingssysteem.

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

Verificatie van tokens van Microsoft Entra ID (voorheen Azure Active Directory)

Als u het Databricks SQL-stuurprogramma wilt gebruiken voor Node.js met Microsoft Entra ID-tokenverificatie (voorheen Azure Active Directory), moet u het Databricks SQL-stuurprogramma opgeven voor Node.js met het Microsoft Entra ID-token. Ga als volgt te werk om een Microsoft Entra ID-toegangstoken te maken:

Voor een Azure Databricks-gebruiker kunt u de Azure CLI gebruiken. Zie Tokens voor Microsoft Entra-id (voorheen Azure Active Directory) ophalen voor gebruikers met behulp van de Azure CLI.
Zie Een Microsoft Entra ID-toegangstoken ophalen met de Azure CLI voor een Service-principal van Microsoft Entra ID. Zie Service-principals beheren om een door Microsoft Entra ID beheerde service-principals te maken.

Microsoft Entra ID-tokens hebben een standaardlevensduur van ongeveer 1 uur. Herhaal dit proces om een nieuw Microsoft Entra ID-token te maken.

Gebruik het volgende codefragment om het Databricks SQL-stuurprogramma voor Node.js te verifiëren. In dit fragment wordt ervan uitgegaan dat u de volgende omgevingsvariabelen hebt ingesteld:

DATABRICKS_SERVER_HOSTNAMEingesteld op de serverhostnaamwaarde voor uw cluster of SQL Warehouse.
DATABRICKS_HTTP_PATH, ingesteld op HTTP-padwaarde voor uw cluster of SQL Warehouse.
DATABRICKS_TOKEN, ingesteld op het Microsoft Entra ID-token.

Als u omgevingsvariabelen wilt instellen, raadpleegt u de documentatie van uw besturingssysteem.

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

Querygegevens

In het volgende codevoorbeeld ziet u hoe u het Databricks SQL-stuurprogramma aanroept voor Node.js om een eenvoudige SQL-query uit te voeren op een Azure Databricks-rekenresource. Met deze opdracht worden de eerste twee rijen uit de trips tabel in het schema van nyctaxi de samples catalogus geretourneerd.

Notitie

In het volgende codevoorbeeld ziet u hoe u een persoonlijk toegangstoken van Azure Databricks gebruikt voor verificatie. Als u in plaats daarvan andere beschikbare Azure Databricks-verificatietypen wilt gebruiken, raadpleegt u Verificatie.

In dit codevoorbeeld worden de tokenserver_hostname waarden en http_path verbindingsvariabelen opgehaald uit een set azure Databricks-omgevingsvariabelen. Deze omgevingsvariabelen hebben de volgende namen van omgevingsvariabelen:

DATABRICKS_TOKEN, dat uw persoonlijke toegangstoken van Azure Databricks aangeeft op basis van de vereisten.
DATABRICKS_SERVER_HOSTNAME, die de serverhostnaamwaarde van de vereisten vertegenwoordigt.
DATABRICKS_HTTP_PATH, die de HTTP-padwaarde van de vereisten vertegenwoordigt.

U kunt andere methoden gebruiken om deze verbindingsvariabelewaarden op te halen. Het gebruik van omgevingsvariabelen is slechts één benadering tussen veel.

In het volgende codevoorbeeld ziet u hoe u de Databricks SQL-connector aanroept voor Node.js om een eenvoudige SQL-opdracht uit te voeren op een cluster of SQL Warehouse. Met deze opdracht worden de eerste twee rijen uit de trips tabel geretourneerd.

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

Uitvoer:

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

Sessies

Alle IDBSQLSession methoden die objecten retourneren IOperation in de API-verwijzing hebben de volgende algemene parameters die van invloed zijn op hun gedrag:

De instelling runAsync voor het true starten van de asynchrone modus. IDBSQLSession methoden plaatsen bewerkingen in de wachtrij en retourneren zo snel mogelijk. De huidige status van het geretourneerde IOperation object kan variëren en de client is verantwoordelijk voor het controleren van de status voordat het geretourneerde object wordt gebruikt IOperation. Zie Bewerkingen. Instelling runAsync betekent false dat IDBSQLSession methoden wachten tot de bewerkingen zijn voltooid. Databricks raadt aan altijd in te stellen runAsync op true.
Als u een maxRows niet-null-waarde instelt, worden directe resultaten mogelijk. Met directe resultaten probeert de server te wachten tot de bewerkingen zijn voltooid en vervolgens een deel van de gegevens ophaalt. Afhankelijk van hoeveel werk de server binnen de gedefinieerde tijd kon voltooien, IOperation retourneren objecten een tussenliggende status in plaats van in een status die in behandeling is. Heel vaak worden alle metagegevens en queryresultaten geretourneerd binnen één aanvraag naar de server. De server gebruikt maxRows om te bepalen hoeveel records het onmiddellijk kan retourneren. Het werkelijke segment kan echter van een andere grootte zijn; zie IDBSQLSession.fetchChunk. Directe resultaten zijn standaard ingeschakeld. Databricks raadt aan om directe resultaten uit te schakelen.

Operations

Zoals beschreven in sessies, IOperation worden objecten die worden geretourneerd door IDBSQLSession sessiemethoden in de API-verwijzing niet volledig ingevuld. De gerelateerde serverbewerking wordt mogelijk nog steeds uitgevoerd, zoals wachten totdat het Databricks SQL Warehouse wordt gestart, de query wordt uitgevoerd of de gegevens worden opgehaald. De IOperation klasse verbergt deze gegevens voor gebruikers. Methoden zoals fetchAll, fetchChunken getSchema wachten intern totdat bewerkingen zijn voltooid en vervolgens resultaten retourneren. U kunt de IOperation.finished() methode gebruiken om expliciet te wachten tot de bewerkingen zijn voltooid. Deze methoden nemen een callback op die periodiek wordt aangeroepen terwijl wordt gewacht tot de bewerkingen zijn voltooid. Stel de progress optie in om true extra voortgangsgegevens van de server aan te vragen en door te geven aan die callback.

De close en cancel methoden kunnen op elk gewenst moment worden aangeroepen. Wanneer ze worden aangeroepen, wordt het IOperation object onmiddellijk ongeldig. Alle aanroepen die in behandeling zijn, zoals fetchAll, fetchChunken getSchema worden onmiddellijk geannuleerd en er wordt een fout geretourneerd. In sommige gevallen is de serverbewerking mogelijk al voltooid en heeft de cancel methode alleen invloed op de client.

De fetchAll methode roept fetchChunk intern aan en verzamelt alle gegevens in een matrix. Hoewel dit handig is, kan dit leiden tot geheugenfouten bij gebruik op grote gegevenssets. fetchAll opties worden doorgaans doorgegeven aan fetchChunk.

Segmenten van gegevens ophalen

Bij het ophalen van gegevenssegmenten wordt het volgende codepatroon gebruikt:

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

De fetchChunk methode in de API-verwijzing verwerkt gegevens in kleine gedeelten om het geheugenverbruik te verminderen. fetchChunk wacht eerst totdat bewerkingen zijn voltooid als ze nog niet zijn voltooid, roept vervolgens een callback aan tijdens de wachtcyclus en haalt vervolgens het volgende gegevenssegment op.

U kunt de maxRows optie gebruiken om de gewenste segmentgrootte op te geven. Het geretourneerde segment kan echter een andere grootte hebben, kleiner of zelfs soms groter. fetchChunk probeert geen gegevens intern vooraf te maken, om deze in de aangevraagde gedeelten te segmenteren. De optie wordt verzonden naar de server en retourneert maxRows wat de server retourneert. Verwar deze maxRows optie niet met de optie in IDBSQLSession. maxRows doorgegeven om de grootte van elk segment te fetchChunk definiëren en doet niets anders.

Bestanden beheren in Unity Catalog-volumes

Met het Databricks SQL-stuurprogramma kunt u lokale bestanden schrijven naar Unity Catalog-volumes, bestanden downloaden van volumes en bestanden verwijderen uit volumes, zoals wordt weergegeven in het volgende voorbeeld:

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

Logboekregistratie configureren

De logger biedt informatie over foutopsporingsproblemen met de connector. Alle DBSQLClient objecten worden geïnstantieerd met een logger die naar de console wordt afgedrukt, maar door een aangepaste logboekregistratie door te geven, kunt u deze informatie naar een bestand verzenden. In het volgende voorbeeld ziet u hoe u een logboekregistratie configureert en het niveau ervan wijzigt.

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

Zie de map met voorbeelden in de opslagplaats databricks/databricks-sql-nodejs op GitHub voor meer voorbeelden.

Testen

Als u uw code wilt testen, kunt u JavaScript-testframeworks zoals Jest gebruiken. Als u uw code wilt testen onder gesimuleerde omstandigheden zonder Azure Databricks REST API-eindpunten aan te roepen of de status van uw Azure Databricks-accounts of -werkruimten te wijzigen, kunt u de ingebouwde mockingframeworks van Jest gebruiken.

Op basis van het volgende bestand met de naam helpers.js van een functie die gebruikmaakt van een getDBSQLClientWithPAT persoonlijk toegangstoken van Azure Databricks om een verbinding met een Azure Databricks-werkruimte te retourneren, is een getAllColumnsFromTable functie die gebruikmaakt van de verbinding om het opgegeven aantal gegevensrijen op te halen uit de opgegeven tabel (bijvoorbeeld de trips tabel in het schema van nyctaxi de samples catalogus) en een printResults functie om de inhoud van de gegevensrijen af te drukken:

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

En gezien het volgende bestand met de naam main.js die de getDBSQLClientWithPAT, getAllColumnsFromTableen printResults functies aanroept:

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

Het volgende bestand met de naam helpers.test.js test of de getAllColumnsFromTable functie het verwachte antwoord retourneert. In plaats van een echte verbinding met de doelwerkruimte te maken, wordt met deze test een DBSQLClient object gesimuleerd. Met de test worden ook enkele gegevens gesimuleerd die voldoen aan het schema en de waarden die zich in de echte gegevens bevinden. De test retourneert de gesimuleerde gegevens via de gesimuleerde verbinding en controleert vervolgens of een van de gesimuleerde gegevensrijen overeenkomt met de verwachte waarde.

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

Voor TypeScript ziet de voorgaande code er ongeveer als volgt uit. Gebruik ts-jest voor het testen met TypeScript.

Aanvullende bronnen

Het Databricks SQL-stuurprogramma voor Node.js-opslagplaats op GitHub
Aan de slag met het Databricks SQL-stuurprogramma voor Node.js
Problemen met het Databricks SQL-stuurprogramma voor Node.js oplossen

API-verwijzing

Klassen

Klassen

`DBSQLClient` klas

Hoofdinvoerpunt voor interactie met een database.

Methoden

`connect` methode

Hiermee opent u een verbinding met de database.

Parameters
Opties Type: `ConnectionOptions` De set opties die worden gebruikt om verbinding te maken met de database. De `host`velden , `path`en andere vereiste velden moeten worden ingevuld. Zie Verificatie. Voorbeeld: `const client: DBSQLClient = new DBSQLClient();` `client.connect(` `{` `host: serverHostname,` `path: httpPath,` `// ...` `}` `)`

Retourneert: Promise<IDBSQLClient>

`openSession` methode

Hiermee opent u een sessie tussen DBSQLClient en database.

Parameters
verzoek Type: `OpenSessionRequest` Een set optionele parameters voor het opgeven van het eerste schema en de eerste catalogus Voorbeeld: `const session = await client.openSession(` `{initialCatalog: 'catalog'}` `);`

Retourneert: Promise<IDBSQLSession>

`getClient` methode

Retourneert intern thrift TCLIService.Client-object. Moet worden aangeroepen nadat DBSQLClient verbinding heeft gemaakt.

Geen parameters

Retourneert TCLIService.Client

`close` methode

Hiermee sluit u de verbinding met de database en worden alle gekoppelde resources op de server vrijgegeven. Eventuele extra aanroepen naar deze client veroorzaken een fout.

Geen parameters.

Geen retourwaarde.

`DBSQLSession` klas

DBSQLSessions worden voornamelijk gebruikt voor het uitvoeren van instructies voor de databbase, evenals verschillende bewerkingen voor het ophalen van metagegevens.

Methoden

`executeStatement` methode

Voert een instructie uit met de beschikbare opties.

Parameters

Parameters
verklaring Type: `str` De instructie die moet worden uitgevoerd.
Opties Type: `ExecuteStatementOptions` Een set optionele parameters voor het bepalen van querytime-out, maximumrijen voor directe resultaten en of de query asynchroon moet worden uitgevoerd. `maxRows` Standaard is ingesteld op 10000. Als `maxRows` deze is ingesteld op null, wordt de bewerking uitgevoerd met de functie directe resultaten uitgeschakeld. Voorbeeld: `const session = await client.openSession(` `{initialCatalog: 'catalog'}` `);` `queryOperation = await session.executeStatement(` `'SELECT "Hello, World!"', { runAsync: true }` `);`

verklaring

Type: str

De instructie die moet worden uitgevoerd.

Opties

Type: ExecuteStatementOptions

Een set optionele parameters voor het bepalen van querytime-out, maximumrijen voor directe resultaten en of de query asynchroon moet worden uitgevoerd. maxRows Standaard is ingesteld op 10000. Als maxRows deze is ingesteld op null, wordt de bewerking uitgevoerd met de functie directe resultaten uitgeschakeld.

Voorbeeld:

const session = await client.openSession(
{initialCatalog: 'catalog'}
);

queryOperation = await session.executeStatement(
'SELECT "Hello, World!"', { runAsync: true }
);

Retourneert: Promise<IOperation>

`close` methode

Hiermee sluit u de sessie. Moet worden uitgevoerd na het gebruik van de sessie.

Geen parameters.

Geen retourwaarde.

`getId` methode

Retourneert de GUID van de sessie.

Geen parameters.

Retourneert: str

`getTypeInfo` methode

Retourneert informatie over ondersteunde gegevenstypen.

Parameters
verzoek Type: `TypeInfoRequest` Aanvraagparameters.

Retourneert: Promise<IOperation>

`getCatalogs` methode

Hiermee haalt u een lijst met catalogi op.

Parameters
verzoek Type: `CatalogsRequest` Aanvraagparameters.

Retourneert: Promise<IOperation>

`getSchemas` methode

Hiermee haalt u een lijst met schema's op.

Parameters
verzoek Type: `SchemasRequest` Aanvraagparameters. Velden `catalogName` en `schemaName` kunnen worden gebruikt voor filterdoeleinden.

Retourneert: Promise<IOperation>

`getTables` methode

Hiermee haalt u een lijst met tabellen op.

Parameters
verzoek Type: `TablesRequest` Aanvraagparameters. Velden `catalogName` en `schemaName` en `tableName` kan worden gebruikt voor filteren.

Retourneert: Promise<IOperation>

`getFunctions` methode

Hiermee haalt u een lijst met tabellen op.

Parameters
verzoek Type: `FunctionsRequest` Aanvraagparameters. Veld `functionName` is vereist.

Retourneert: Promise<IOperation>

`getPrimaryKeys` methode

Hiermee haalt u een lijst met primaire sleutels op.

Parameters
verzoek Type: `PrimaryKeysRequest` Aanvraagparameters. Velden `schemaName` en `tableName` zijn vereist.

Retourneert: Promise<IOperation>

`getCrossReference` methode

Hiermee wordt informatie opgehaald over refererende sleutels tussen twee tabellen.

Parameters
verzoek Type: `CrossReferenceRequest` Aanvraagparameters. De naam van het schema, de bovenliggende en de catalogus moet worden opgegeven voor beide tabellen.

Retourneert: Promise<IOperation>

`DBSQLOperation` klas

DBSQLOperations worden gemaakt door DBSQLSessions en kunnen worden gebruikt om de resultaten van instructies op te halen en de uitvoering ervan te controleren. Gegevens worden opgehaald via functies fetchChunk en fetchAll.

Methoden

`getId` methode

Retourneert de GUID van de bewerking.

Geen parameters.

Retourneert: str

`fetchAll` methode

Wacht tot de bewerking is voltooid en haalt vervolgens alle rijen uit de bewerking op.

Parameters: Geen

Retourneert: Promise<Array<object>>

`fetchChunk` methode

Wacht totdat de bewerking is voltooid en haalt vervolgens een opgegeven aantal rijen op uit een bewerking.

Parameters
Opties Type: `FetchOptions` Opties die worden gebruikt om op te halen. Momenteel is de enige optie maxRows, die overeenkomt met het maximum aantal gegevensobjecten dat moet worden geretourneerd in een bepaalde matrix.

Retourneert: Promise<Array<object>>

`close` methode

Hiermee sluit u de bewerking en worden alle bijbehorende resources vrijgegeven. Moet worden uitgevoerd nadat u de bewerking niet meer hebt gebruikt.

Geen parameters.

Geen retourwaarde.

Delen via

Databricks SQL-stuurprogramma voor Node.js

Vereisten

Verificatie

Verificatie van persoonlijke toegangstokens van Databricks

JavaScript

TypeScript

OAuth-verificatie van gebruiker naar machine (U2M)

JavaScript

TypeScript

OAuth-verificatie van machine-naar-machine (M2M)

JavaScript

TypeScript

Verificatie van tokens van Microsoft Entra ID (voorheen Azure Active Directory)

JavaScript

TypeScript

Querygegevens

JavaScript

TypeScript

Sessies

Operations

Segmenten van gegevens ophalen

Bestanden beheren in Unity Catalog-volumes

JavaScript

TypeScript

Logboekregistratie configureren

JavaScript

TypeScript

Testen

Aanvullende bronnen

API-verwijzing

Klassen

DBSQLClient klas

Methoden

connect methode

openSession methode

getClient methode

close methode

DBSQLSession klas

Methoden

executeStatement methode

close methode

getId methode

getTypeInfo methode

getCatalogs methode

getSchemas methode

getTables methode

getFunctions methode

getPrimaryKeys methode

getCrossReference methode

DBSQLOperation klas

Methoden

getId methode

fetchAll methode

fetchChunk methode

close methode

Feedback

Feedback

Aanvullende resources

`DBSQLClient` klas

`connect` methode

`openSession` methode

`getClient` methode

`close` methode

`DBSQLSession` klas

`executeStatement` methode

`close` methode

`getId` methode

`getTypeInfo` methode

`getCatalogs` methode

`getSchemas` methode

`getTables` methode

`getFunctions` methode

`getPrimaryKeys` methode

`getCrossReference` methode

`DBSQLOperation` klas

`getId` methode

`fetchAll` methode

`fetchChunk` methode

`close` methode