Databricks SQL-drivrutin för Node.js

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 servervärdnamn och HTTP-sökväg för det befintliga klustret eller SQL-lagret.

  • Hämta dessa värden för ett kluster.
  • Hämta dessa värden för ett SQL-lager.

Autentisering

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

• Autentisering med personlig åtkomsttoken för Databricks
• Microsoft Entra ID-tokenautentisering
• OAuth-autentisering från dator till dator (M2M)
• OAuth-autentisering från användare till dator (U2M)

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

• Azure-hanterad identitetsautentisering
• MS Entra-tjänstens huvudnamnsautentisering
• Azure CLI-autentisering

Autentisering med personlig åtkomsttoken för Databricks

Om du vill använda Databricks SQL-drivrutinen för Node.js med personlig åtkomsttokenautentisering i Azure Databricks måste du först skapa en personlig åtkomsttoken för Azure Databricks enligt följande:

1. I din Azure Databricks-arbetsyta klickar du på ditt Användarnamn för Azure Databricks i det övre fältet och väljer sedan Inställningar i listrutan.
2. Klicka på Utvecklare.
3. Bredvid Åtkomsttoken klickar du på Hantera.
4. Klicka på Generera ny token.
5. (Valfritt) Ange en kommentar som hjälper dig att identifiera den här token i framtiden och ändra tokens standardlivslängd på 90 dagar. Om du vill skapa en token utan livslängd (rekommenderas inte) lämnar du rutan Livslängd (dagar) tom (tom).
6. Klicka på Generera.
7. Kopiera den visade token till en säker plats och klicka sedan på Klar.

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 servervärdnamn för klustret eller SQL-lagret.
• DATABRICKS_HTTP_PATHanger du till HTTP-sökvägsvärde för klustret eller SQL-lagret.
• DATABRICKS_TOKEN, inställt på den personliga åtkomsttoken för Azure Databricks.

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_HOSTNAMEange värdet servervärdnamn för klustret eller SQL-lagret.
• 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 Huvudnamn för Azure Databricks-tjänsten på din Azure Databricks-arbetsyta och skapa en OAuth-hemlighet för tjänstens huvudnamn.

   Information om hur du skapar tjänstens huvudnamn och dess OAuth-hemlighet finns i Autentisera åtkomst till Azure Databricks med ett huvudnamn för tjänsten med OAuth (OAuth M2M). 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änstens huvudnamn åtkomst till klustret eller informationslagret. 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 servervärdnamn för klustret eller SQL-lagret.
• DATABRICKS_HTTP_PATHanger du till HTTP-sökvägsvärde för klustret eller SQL-lagret.
• DATABRICKS_CLIENT_ID, inställt på tjänstens huvudnamns UUID - eller program-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:

• För en Azure Databricks-användare kan du använda Azure CLI. Se Hämta Microsoft Entra-ID-token för användare med hjälp av Azure CLI.
• Ett microsoft entra-ID-tjänsthuvudnamn finns i Hämta en Microsoft Entra ID-åtkomsttoken med Azure CLI. Information om hur du skapar ett microsoft entra-ID för hanterad tjänsthuvudnamn finns i Hantera tjänstens huvudnamn.

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_HOSTNAMEange värdet servervärdnamn för klustret eller SQL-lagret.
• DATABRICKS_HTTP_PATHanger du till HTTP-sökvägsvärde för klustret eller SQL-lagret.
• 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.

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 från kraven.
• DATABRICKS_SERVER_HOSTNAME, som representerar värdet servervärdnamn 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:

• Inställningen runAsync startar true 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. false Inställningen runAsync 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 åtgärderna har slutförts och hämtar sedan en del av data. 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

Enligt beskrivningen i Sessioner IOperationär objekt som returneras av IDBSQLSession sessionsmetoder i API-referensen inte helt ifyllda. Den relaterade serveråtgärden kan fortfarande pågår, till exempel väntar på att Databricks SQL-lagret ska starta, köra frågan 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 åtgärderna ska slutföras. Ange alternativet progress för att true försöka begära extra förloppsdata från servern och skicka dem till å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-referensen bearbetar 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örinstallera data internt för att dela upp dem 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

• Databricks SQL-drivrutinen för Node.js lagringsplats på GitHub
• Komma igång med Databricks SQL-drivrutinen för Node.js
• Felsöka Databricks SQL-drivrutinen för Node.js

API-referens

• Klasser
  • Klassen DBSQLClient
    • Metoder
      • connect metod
      • openSession metod
      • getClient metod
      • close metod
  • Klassen DBSQLSession
    • Metoder
      • executeStatement metod
      • close metod
      • getId metod
      • getTypeInfo metod
      • getCatalogs metod
      • getSchemas metod
      • getTables metod
      • getFunctions metod
      • getPrimaryKeys metod
      • getCrossReference metod
  • Klassen DBSQLOperation
    • Metoder
      • getId metod
      • fetchAll metod
      • fetchChunk metod
      • close metod

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 -instruktionen 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 sekundärnycklar mellan två tabeller.

Parametrar
begäran Typ: CrossReferenceRequest Begärandeparametrar. Schema,Överordnad 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 resultatet av -instruktioner och kontrollera körningen. 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 åtgärden och släpper alla associerade resurser. Måste göras efter att åtgärden inte längre har använts.

Inga parametrar.

Inget returvärde.