Databricks SQL-stuurprogramma voor Node.js

Artikel
11/16/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 npmuit om te controleren of npm -v 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 in uw Node.js-project wilt installeren en gebruiken, devDependencies gebruik dan npm 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 Microsoft Entra-id-token
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 een best practice voor beveiliging moet u geen waarden van verbindingsvariabelen hardcoden in uw code. 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 verificatie, moet u eerst een persoonlijk toegangstoken voor Azure Databricks maken. Zie persoonlijke toegangstokens van Azure Databricks voor werkruimtegebruikers voor meer informatie over deze stap.

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-authenticatie 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 Autoriseer ongecontroleerde toegang tot Azure Databricks-resources met een service-principal en OAuth om de service-principal en zijn OAuth-geheim te creëren. 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-magazijn 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 Microsoft Entra-id-token

Als u het Databricks SQL-stuurprogramma wilt gebruiken voor Node.js met Microsoft Entra ID-tokenverificatie, 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 Microsoft Entra ID-tokens ophalen voor gebruikers met behulp van de Azure CLI.
Voor een Microsoft Entra ID-service-principal, zie Een Microsoft Entra ID-toegangstoken ophalen met de Azure CLI. Zie Service-principals beheren om een door Microsoft Entra ID beheerde service-principal 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 samples de nyctaxi 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 is, zoals vermeld in 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:

runAsync instellen op true activeert de asynchrone modus. IDBSQLSession methoden plaatsen bewerkingen in de wachtrij en komen zo snel mogelijk terug. 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. Het instellen van runAsync op false betekent 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, zullen IOperation objecten een tussenliggende status retourneren in plaats van in een in behandeling zijnde status. 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 af om directe resultaten uit te schakelen.

Operations

Zoals beschreven in Sessions, IOperation worden objecten die worden geretourneerd door IDBSQLSession sessiemethoden in de API-referentie 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. nl-NL: Het stuurt de maxRows optie naar de server en retourneert wat de server retourneert. Verwar deze maxRows optie niet met de optie in IDBSQLSession. maxRows dat aan fetchChunk wordt doorgegeven, definieert de grootte van elk segment en doet verder niets.

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 schrijft, maar door een aangepaste logger in te voeren, kunt u deze informatie naar een bestand verzenden. In het volgende voorbeeld ziet u hoe u een logger configureert en het niveau 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 genaamd helpers.js, dat een getDBSQLClientWithPAT functie bevat die gebruikmaakt van een persoonlijk toegangstoken van Azure Databricks om een verbinding met een Azure Databricks-werkruimte tot stand te brengen, een tweede getAllColumnsFromTable functie die de verbinding gebruikt om het opgegeven aantal gegevensrijen op te halen uit de gespecificeerde tabel (bijvoorbeeld de trips tabel in het samples catalogus’s nyctaxi schema), en een derde printResults functie om de inhoud van de gegevensrijen weer te geven:

// 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 Typ: `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 een 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 statement uit met de gegeven 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` is ingesteld op null, wordt de bewerking uitgevoerd met uitgeschakelde directe resultaten functie. 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 is ingesteld op null, wordt de bewerking uitgevoerd met uitgeschakelde directe resultaten functie.
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 nadat de sessie is gebruikt.

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

Haalt een lijst van catalogi op.

Parameters
verzoek Typ: `CatalogsRequest` Aanvraagparameters.

Retourneert: Promise<IOperation>

`getSchemas` methode

Haalt 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` `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 vreemde sleutels tussen twee tabellen.

Parameters
verzoek Soort: `CrossReferenceRequest` Aanvraagparameters. De namen van het schema, het bovenliggende element en de catalogus moeten 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.

Parameterwaarden
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-authenticatie van gebruiker naar machine (U2M)

JavaScript

TypeScript

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

JavaScript

TypeScript

Verificatie van Microsoft Entra-id-token

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

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