Dela via

Databricks SQL-drivrutin för Node.js

  • Artikel

Databricks SQL-drivrutinen för Node.js är ett Node.js bibliotek som gör att du kan använda JavaScript-kod för att köra SQL-kommandon på Azure Databricks-beräkningsresurser.

Krav

  • En utvecklingsdator som kör Node.js version 14 eller senare. Om du vill skriva ut den installerade versionen av Node.js kör du kommandot node -v. Om du vill installera och använda olika versioner av Node.js kan du använda verktyg som Node Version Manager (nvm).

  • Node Package Manager (npm). Senare versioner av Node.js innehåller npmredan . Om du vill kontrollera om npm är installerat kör du kommandot npm -v. Om du vill installera npm om det behövs kan du följa anvisningarna i Ladda ned och installera npm.

  • paketet @databricks/sql från npm. Om du vill installera @databricks/sql paketet i ditt Node.js projekt som ett beroende använder du npm för att köra följande kommando från samma katalog som projektet:

    npm i @databricks/sql

  • Om du vill installera och använda TypeScript i ditt Node.js projekt som devDependenciesanvänder npm du för att köra följande kommandon från samma katalog som projektet:

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

  • Ett befintligt kluster eller SQL-lager.

  • Värdet för serverns värdnamn och HTTP-sökväg för det befintliga klustret eller SQL-datalagret.

Autentisering

Databricks SQL-drivrutinen för Node.js stöder följande Azure Databricks-autentiseringstyper:

Databricks SQL-drivrutinen för Node.js stöder ännu inte följande Azure Databricks-autentiseringstyper:

Anteckning

Som bästa säkerhet bör du inte hårdkoda variabelvärden för anslutning till koden. I stället bör du hämta dessa anslutningsvariabelvärden från en säker plats. Kodfragmenten och exemplen i den här artikeln använder till exempel miljövariabler.

Autentisering med personlig åtkomsttoken för Databricks

Om du vill använda Databricks SQL-drivrutinen för Node.js med autentisering måste du först skapa en personlig åtkomsttoken för Azure Databricks. Mer information om det här steget finns i Personliga åtkomsttoken för Azure Databricks för arbetsyteanvändare.

Om du vill autentisera Databricks SQL-drivrutinen för Node.js använder du följande kodfragment. Det här kodfragmentet förutsätter att du har angett följande miljövariabler:

  • DATABRICKS_SERVER_HOSTNAMEställ in till värdet Servervärdnamnet för ditt kluster eller SQL-datalager.
  • DATABRICKS_HTTP_PATHanger du till HTTP-sökvägsvärde för klustret eller SQL-lagret.
  • DATABRICKS_TOKEN, satt till Azure Databricks personliga åtkomsttoken.

Information om hur du anger miljövariabler finns i dokumentationen till operativsystemet.

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-autentisering från användare till dator (U2M)

Databricks SQL-drivrutin för Node.js version 1.8.0 och senare stöder OAuth-autentisering från användare till dator (U2M).

Om du vill autentisera Databricks SQL-drivrutinen för Node.js med OAuth U2M-autentisering använder du följande kodfragment. Det här kodfragmentet förutsätter att du har angett följande miljövariabler:

  • DATABRICKS_SERVER_HOSTNAMEställ in på värdet för servervärdnamn för ditt kluster eller din SQL-lagerlokal.
  • DATABRICKS_HTTP_PATHanger du till HTTP-sökvägsvärde för klustret eller SQL-lagret.

Information om hur du anger miljövariabler finns i dokumentationen till operativsystemet.

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-autentisering från dator till dator (M2M)

Databricks SQL-drivrutin för Node.js version 1.8.0 och senare stöder OAuth-autentisering från dator till dator (U2M).

Om du vill använda Databricks SQL-drivrutinen för Node.js med OAuth M2M-autentisering måste du göra följande:

  1. Skapa ett tjänstehuvudnamn för Azure Databricks i din Azure Databricks-arbetsyta och skapa en OAuth-hemlighet för det tjänstehuvudnamnet.

    Information om hur du skapar tjänstens huvudnamn och dess OAuth-hemlighet finns i Auktorisera obevakad åtkomst till Azure Databricks-resurser med ett huvudnamn för tjänsten med OAuth. Anteckna tjänstens huvudnamns UUID - eller program-ID-värde och det hemliga värdet för tjänstens huvudnamns OAuth-hemlighet.

  2. Ge tjänsthuvudnamnet åtkomst till din kluster eller ditt datalager. Se Beräkningsbehörigheter eller Hantera ett SQL-lager.

Om du vill autentisera Databricks SQL-drivrutinen för Node.js använder du följande kodfragment. Det här kodfragmentet förutsätter att du har angett följande miljövariabler:

  • DATABRICKS_SERVER_HOSTNAMEange värdet till servervärdnamnet för ditt kluster eller SQL-lager.
  • DATABRICKS_HTTP_PATH, ange HTTP-sökväg för ditt kluster eller SQL-databaslager.
  • DATABRICKS_CLIENT_ID, inställt på tjänstens huvudprincipals UUID eller applikations-ID-värde.
  • DATABRICKS_CLIENT_SECRET, ange värdet Hemlig för tjänstens huvudnamns OAuth-hemlighet.

Information om hur du anger miljövariabler finns i dokumentationen till operativsystemet.

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

Microsoft Entra ID-tokenautentisering

Om du vill använda Databricks SQL-drivrutinen för Node.js med Microsoft Entra ID-tokenautentisering måste du ange Databricks SQL-drivrutinen för Node.js med Microsoft Entra ID-token. Gör följande för att skapa en Microsoft Entra ID-åtkomsttoken:

Microsoft Entra-ID-token har en standardlivslängd på cirka 1 timme. Om du vill skapa en ny Microsoft Entra-ID-token upprepar du den här processen.

Om du vill autentisera Databricks SQL-drivrutinen för Node.js använder du följande kodfragment. Det här kodfragmentet förutsätter att du har angett följande miljövariabler:

  • DATABRICKS_SERVER_HOSTNAMEsätt till värdet Servervärdnamn för ditt kluster eller SQL-datalager.
  • DATABRICKS_HTTP_PATHsätt till HTTP-sökvägen för klustret eller SQL-datavaruhuset.
  • DATABRICKS_TOKEN, inställt på Microsoft Entra-ID-token.

Information om hur du anger miljövariabler finns i dokumentationen till operativsystemet.

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

Fråga efter data

Följande kodexempel visar hur du anropar Databricks SQL-drivrutinen för Node.js för att köra en grundläggande SQL-fråga på en Azure Databricks-beräkningsresurs. Det här kommandot returnerar de två första raderna trips från tabellen i samples katalogens nyctaxi schema.

Kommentar

I följande kodexempel visas hur du använder en personlig åtkomsttoken för Azure Databricks för autentisering. Om du vill använda andra tillgängliga autentiseringstyper för Azure Databricks i stället kan du läsa Autentisering.

Det här kodexemplet hämtar tokenvärdena för , server_hostname och http_path -anslutningsvariabeln från en uppsättning Azure Databricks-miljövariabler. Dessa miljövariabler har följande miljövariabelnamn:

  • DATABRICKS_TOKEN, som representerar din personliga åtkomsttoken för Azure Databricks enligt de specificerade kraven.
  • DATABRICKS_SERVER_HOSTNAME, som representerar värdet Servernamn från kraven.
  • DATABRICKS_HTTP_PATH, som representerar http-sökvägsvärdet från kraven.

Du kan använda andra metoder för att hämta dessa anslutningsvariabelvärden. Att använda miljövariabler är bara en metod bland många.

Följande kodexempel visar hur du anropar Databricks SQL Connector för Node.js för att köra ett grundläggande SQL-kommando i ett kluster eller SQL-lager. Det här kommandot returnerar de två första raderna trips från tabellen.

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

Utdata:

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

Sessioner

Alla IDBSQLSession metoder som returnerar IOperation objekt i API-referensen har följande vanliga parametrar som påverkar deras beteende:

  • Att ställa in runAsync till true startar asynkront läge. IDBSQLSession metoder placerar åtgärder i kön och returnerar så snabbt som möjligt. Det returnerade objektets IOperation aktuella tillstånd kan variera och klienten ansvarar för att kontrollera dess status innan den returnerade IOperation. Se Åtgärder. runAsync Inställningen false innebär att IDBSQLSession metoderna väntar på att åtgärderna ska slutföras. Databricks rekommenderar att du alltid ställer in runAsync på true.
  • Om du anger maxRows ett värde som inte är null kan du få direkta resultat. Med direkta resultat försöker servern vänta tills operationerna har slutförts och hämtar sedan en del av datan. Beroende på hur mycket arbete servern kunde utföra inom den definierade tiden IOperation , returnerar objekt i något mellanliggande tillstånd i stället för i något väntande tillstånd. Ofta returneras alla metadata och frågeresultat inom en enda begäran till servern. Servern använder maxRows för att avgöra hur många poster som kan returneras omedelbart. Det faktiska segmentet kan dock ha en annan storlek. se IDBSQLSession.fetchChunk. Direkta resultat är aktiverade som standard. Databricks rekommenderar att du inte inaktiverar direkta resultat.

Operations

Som beskrivs i Sessions, är objekt som returneras av IOperation sessionsmetoder i IDBSQLSession inte helt ifyllda. Den relaterade serveråtgärden kan fortfarande pågå, som att vänta på att Databricks SQL-lager ska starta, köra en fråga eller hämta data. Klassen IOperation döljer den här informationen för användare. Till exempel kan metoder som fetchAll, fetchChunkoch getSchema vänta internt på att åtgärderna ska slutföras och sedan returnera resultat. Du kan använda IOperation.finished() metoden för att uttryckligen vänta tills åtgärderna har slutförts. Dessa metoder tar ett återanrop som anropas regelbundet i väntan på att operationerna ska slutföras. Att ställa in progress-alternativet till true försöker begära extra förloppsdata från servern och skicka dem till den återanropet.

Metoderna close och cancel kan anropas när som helst. När det anropas ogiltigförklaras IOperation objektet omedelbart. Alla väntande anrop som fetchAll, fetchChunkoch getSchema avbryts omedelbart och ett fel returneras. I vissa fall kan serveråtgärden redan ha slutförts och cancel metoden påverkar endast klienten.

Metoden fetchAll anropar fetchChunk internt och samlar in alla data i en matris. Även om det är praktiskt kan det orsaka minnesfel när det används på stora datauppsättningar. fetchAll alternativ skickas vanligtvis till fetchChunk.

Hämta datasegment

När du hämtar datasegment används följande kodmönster:

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

Metoden fetchChunk i API-referensenbearbetar data i små delar för att minska minnesförbrukningen. fetchChunk först väntar på att åtgärderna ska slutföras om de inte redan har slutförts, anropar sedan ett återanrop under väntecykeln och hämtar sedan nästa datasegment.

Du kan använda alternativet maxRows för att ange önskad segmentstorlek. Det returnerade segmentet kan dock ha en annan storlek, mindre eller till och med ibland större. fetchChunk försöker inte förhämta data internt för att dela upp den i de begärda delarna. Den skickar maxRows alternativet till servern och returnerar det som servern returnerar. Blanda inte ihop det här maxRows alternativet med det i IDBSQLSession. maxRows som skickas till fetchChunk definierar storleken på varje segment och gör inget annat.

Hantera filer i Unity Catalog-volymer

Med Databricks SQL Driver kan du skriva lokala filer till Unity Catalog-volymer, ladda ned filer från volymer och ta bort filer från volymer, enligt följande exempel:

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

Konfigurera loggning

Loggern innehåller information för felsökning av problem med anslutningsappen. Alla DBSQLClient objekt instansieras med en loggare som skriver ut till konsolen, men genom att skicka in en anpassad loggare kan du skicka den här informationen till en fil. I följande exempel visas hur du konfigurerar en loggare och ändrar dess nivå.

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

Ytterligare exempel finns i exempelmappen i lagringsplatsen databricks/databricks-sql-nodejs på GitHub.

Testning

Om du vill testa koden kan du använda JavaScript-testramverk som Jest. Om du vill testa koden under simulerade förhållanden utan att anropa Azure Databricks REST API-slutpunkter eller ändra tillståndet för dina Azure Databricks-konton eller arbetsytor kan du använda Jests inbyggda modelleringsramverk.

Med tanke på följande fil med namnet helpers.js som innehåller en getDBSQLClientWithPAT funktion som använder en personlig åtkomsttoken för Azure Databricks för att returnera en anslutning till en Azure Databricks-arbetsyta, en getAllColumnsFromTable funktion som använder anslutningen för att hämta det angivna antalet datarader från den angivna tabellen (till exempel trips tabellen i samples katalogens nyctaxi schema) och en printResults funktion för att skriva ut dataradernas innehåll:

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

Och med följande fil med namnet main.js som anropar getDBSQLClientWithPATfunktionerna , getAllColumnsFromTableoch printResults :

// main.js

const { getDBSQLClientWithPAT, getAllColumnsFromTable, printResult } = require('./helpers');

const token = process.env.DATABRICKS_TOKEN;
const serverHostname = process.env.DATABRICKS_SERVER_HOSTNAME;
const httpPath = process.env.DATABRICKS_HTTP_PATH;
const tableSpec = process.env.DATABRICKS_TABLE_SPEC;

if (!token || !serverHostname || !httpPath) {
  throw new Error(
    'Cannot find Server Hostname, HTTP Path, or personal access token. ' +
      'Check the environment variables DATABRICKS_TOKEN, ' +
      'DATABRICKS_SERVER_HOSTNAME, and DATABRICKS_HTTP_PATH.',
  );
}

if (!tableSpec) {
  throw new Error(
    'Cannot find table spec in the format catalog.schema.table. ' +
      'Check the environment variable DATABRICKS_TABLE_SPEC.',
  );
}

getDBSQLClientWithPAT(token, serverHostname, httpPath)
  .then(async (client) => {
    const result = await getAllColumnsFromTable(client, tableSpec, 2);
    printResult(result);
    await client.close();
  })
  .catch((error) => {
    console.error(error);
  });

Följande fil med namnet helpers.test.js testar om getAllColumnsFromTable funktionen returnerar det förväntade svaret. I stället för att skapa en verklig anslutning till målarbetsytan hånar det här testet ett DBSQLClient objekt. Testet hånar också vissa data som överensstämmer med schemat och värdena som finns i verkliga data. Testet returnerar de simulerade data via den simulerade anslutningen och kontrollerar sedan om ett av de simulerade dataradernas värden matchar det förväntade värdet.

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

För TypeScript ser föregående kod ut ungefär så här. För Jest-testning med TypeScript använder du ts-jest.

Ytterligare resurser

API-referens

Klasser

DBSQLClient klass

Huvudinmatningspunkt för att interagera med en databas.

Metoder
connect metod

Öppnar en anslutning till databasen.

Parametrar
Alternativ
Typ: ConnectionOptions
Den uppsättning alternativ som används för att ansluta till databasen.
Fälten host, pathoch andra obligatoriska fält måste fyllas i. Se Autentisering.
Exempel:
const client: DBSQLClient = new DBSQLClient();
client.connect(
{
host: serverHostname,
path: httpPath,
// ...
}
)

Returnerar: Promise<IDBSQLClient>

openSession metod

Öppnar sessionen mellan DBSQLClient och databasen.

Parametrar
begäran
Typ: OpenSessionRequest
En uppsättning valfria parametrar för att ange inledande schema och inledande katalog
Exempel:
const session = await client.openSession(
{initialCatalog: 'catalog'}
);

Returnerar: Promise<IDBSQLSession>

getClient metod

Returnerar det interna TCLIService.Client-objektet thrift. Måste anropas när DBSQLClient har anslutits.

Inga parametrar

Returnerar TCLIService.Client

close metod

Stänger anslutningen till databasen och släpper alla associerade resurser på servern. Eventuella ytterligare anrop till den här klienten utlöser fel.

Inga parametrar.

Inget returvärde.

DBSQLSession klass

DBSQLSessioner används främst för körning av instruktioner mot databbase samt olika åtgärder för hämtning av metadata.

Metoder
executeStatement metod

Kör en instruktion med de angivna alternativen.

Parametrar
uttalande
Typ: str
Uttalandet som ska köras.
Alternativ
Typ: ExecuteStatementOptions
En uppsättning valfria parametrar för att fastställa tidsgränsen för frågor, maximalt antal rader för direkta resultat och om frågan ska köras asynkront. Som standard maxRows anges till 10000. Om maxRows värdet är null körs åtgärden med funktionen för direktresultat inaktiverad.
Exempel:
const session = await client.openSession(
{initialCatalog: 'catalog'}
);
queryOperation = await session.executeStatement(
'SELECT "Hello, World!"', { runAsync: true }
);

Returnerar: Promise<IOperation>

close metod

Stänger sessionen. Måste göras efter att sessionen har använts.

Inga parametrar.

Inget returvärde.

getId metod

Returnerar GUID för sessionen.

Inga parametrar.

Returnerar: str

getTypeInfo metod

Returnerar information om datatyper som stöds.

Parametrar
begäran
Typ: TypeInfoRequest
Begärandeparametrar.

Returnerar: Promise<IOperation>

getCatalogs metod

Hämtar en lista över kataloger.

Parametrar
begäran
Typ: CatalogsRequest
Begärandeparametrar.

Returnerar: Promise<IOperation>

getSchemas metod

Hämtar en lista över scheman.

Parametrar
begäran
Typ: SchemasRequest
Begärandeparametrar. Fält catalogName och schemaName kan användas för filtrering.

Returnerar: Promise<IOperation>

getTables metod

Hämtar en lista över tabeller.

Parametrar
begäran
Typ: TablesRequest
Begärandeparametrar. Fält catalogName och schemaName
tableName kan användas för filtrering.

Returnerar: Promise<IOperation>

getFunctions metod

Hämtar en lista över tabeller.

Parametrar
begäran
Typ: FunctionsRequest
Begärandeparametrar. Fält functionName krävs.

Returnerar: Promise<IOperation>

getPrimaryKeys metod

Hämtar en lista över primära nycklar.

Parametrar
begäran
Typ: PrimaryKeysRequest
Begärandeparametrar. Fält schemaName och tableName krävs.

Returnerar: Promise<IOperation>

getCrossReference metod

Hämtar information om främmande nycklar mellan två tabeller.

Parametrar
begäran
Typ: CrossReferenceRequest
Begärandeparametrar. Schema, Förälder och Katalognamn måste anges för båda tabellerna.

Returnerar: Promise<IOperation>

DBSQLOperation klass

DBSQLOperations skapas av DBSQLSessions och kan användas för att hämta resultaten av kommandon och kontrollera deras körning. Data hämtas via funktionerna fetchChunk och fetchAll.

Metoder
getId metod

Returnerar GUID för åtgärden.

Inga parametrar.

Returnerar: str

fetchAll metod

Väntar på att åtgärden ska slutföras och hämtar sedan alla rader från åtgärden.

Parametrar: Ingen

Returnerar: Promise<Array<object>>

fetchChunk metod

Väntar på att åtgärden ska slutföras och hämtar sedan upp till ett angivet antal rader från en åtgärd.

Parametrar
Alternativ
Typ: FetchOptions
Alternativ som används för att hämta. För närvarande är det enda alternativet maxRows, vilket motsvarar det maximala antalet dataobjekt som ska returneras i en viss matris.

Returnerar: Promise<Array<object>>

close metod

Stänger operationen och släpper alla associerade resurser. Måste göras när operationen inte längre används.

Inga parametrar.

Inget returvärde.