Ovladač SQL Databricks pro Node.js

Ovladač SQL Databricks pro Node.js je knihovna Node.js, která umožňuje používat javascriptový kód ke spouštění příkazů SQL na výpočetních prostředcích Azure Databricks.

Požadavky

• Vývojový počítač se systémem Node.js verze 14 nebo novější. Pokud chcete vytisknout nainstalovanou verzi Node.js, spusťte příkaz node -v. Pokud chcete nainstalovat a používat různé verze Node.js, můžete použít nástroje, jako je Node Version Manager (nvm).

• Správce balíčků uzlu (npm). Novější verze Node.js již obsahují npm. Chcete-li zkontrolovat, zda npm je nainstalován, spusťte příkaz npm -v. npm Pokud je to potřeba, můžete postupovat podle pokynů, například podle pokynů ke stažení a instalaci npm.

• Balíček @databricks/SQL z npm. Pokud chcete balíček nainstalovat @databricks/sql do projektu Node.js jako závislost, použijte npm ke spuštění následujícího příkazu ze stejného adresáře jako projekt:

  npm i @databricks/sql
  

• Pokud chcete nainstalovat a používat TypeScript v projektu Node.js jako devDependencies, použijte npm ke spuštění následujících příkazů ve stejném adresáři jako projekt:

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

• Existující klastr nebo SQL sklad.

• Hodnota Název hostitele serveru a Cesta HTTP pro stávající cluster nebo SQL Warehouse.

  • Získejte tyto hodnoty pro cluster.
  • Získejte tyto hodnoty pro SQL Warehouse.

Ověřování

Ovladač SQL Databricks pro Node.js podporuje následující typy ověřování Azure Databricks:

• Ověřování osobního přístupového tokenu Databricks
• Ověřování tokenu Microsoft Entra ID
• Ověřování OAuth mezi počítači (M2M)
• Ověřování uživatele OAuth na počítač (U2M)

Ovladač SQL Databricks pro Node.js zatím nepodporuje následující typy ověřování Azure Databricks:

• Ověřování spravovaných identit Azure
• Ověřování služebního objektu MS Entra
• Ověřování přes Azure CLI

Ověřování osobního přístupového tokenu Databricks

Pokud chcete použít ovladač SQL Databricks pro Node.js s ověřováním, musíte nejprve vytvořit Azure Databricks osobní přístupový token. Podrobnosti o tomto kroku najdete v tématu Osobní přístupové tokeny Azure Databricks pro uživatele pracovního prostoru.

K ověření ovladače SQL Databricks pro Node.js použijte následující fragment kódu. Tento fragment kódu předpokládá, že jste nastavili následující proměnné prostředí:

• Nastavte na hodnotu Název hostitele serveru pro váš cluster nebo SQL sklad.
• DATABRICKS_HTTP_PATH, nastavte hodnotu HTTP Cesty pro váš cluster nebo SQL skladiště.
• DATABRICKS_TOKEN, nastavte na hodnotu osobního přístupového tokenu Azure Databricks.

Pokud chcete nastavit proměnné prostředí, přečtěte si dokumentaci k vašemu operačnímu systému.

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

Ověřování uživatele pomocí OAuth pro přístup k počítači (U2M)

Ovladač Databricks SQL pro Node.js ve verzích 1.8.0 a vyšší podporuje ověřování uživatele pomocí OAuth (U2M).

K ověření ovladače SQL Databricks pro Node.js pomocí ověřování OAuth U2M použijte následující fragment kódu. Tento fragment kódu předpokládá, že jste nastavili následující proměnné prostředí:

• Nastavte na hodnotu názvu hostitele serveru pro váš cluster nebo SQL sklad.
• DATABRICKS_HTTP_PATH, nastavte hodnotu HTTP cesty pro váš cluster nebo SQL Warehouse.

Pokud chcete nastavit proměnné prostředí, přečtěte si dokumentaci k vašemu operačnímu systému.

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

Autentizace zařízení OAuth mezi stroji

Databricks SQL ovladač pro Node.js verze 1.8.0 a vyšší podporuje OAuth ověřování stroj-stroj (U2M).

Pokud chcete použít ovladač SQL Databricks pro Node.js s ověřováním OAuth M2M, musíte udělat toto:

1. V pracovním prostoru Azure Databricks vytvořte instanční objekt Azure Databricks a vytvořte pro tento instanční objekt tajný klíč OAuth.

   Pokud chcete vytvořit instanční objekt a jeho tajný klíč OAuth, přečtěte si téma Autorizace bezobslužného přístupu k prostředkům Azure Databricks pomocí instančního objektu pomocí OAuth. Poznamenejte si hodnotu UUID nebo ID aplikace pro instanční objekt služby a hodnotu tajemství pro OAuth tajný klíč instančního objektu.

2. Udělte hlavnímu služebnímu objektu přístup ke clusteru nebo datovému skladu. Podívejte se na výpočetní oprávnění nebo správu SQL skladu.

K ověření ovladače SQL Databricks pro Node.js použijte následující fragment kódu. Tento fragment kódu předpokládá, že jste nastavili následující proměnné prostředí:

• Nastavte na hodnotu název hostitele serveru pro váš cluster nebo SQL warehouse.
• DATABRICKS_HTTP_PATH, nastavte na hodnotu HTTP Path pro váš cluster nebo SQL Warehouse.
• nastavte na hodnotu UUID nebo ID aplikace hlavního objektu služby.
• DATABRICKS_CLIENT_SECRET, nastavte na hodnotu Secret pro tajný klíč OAuth instančního objektu.

Pokud chcete nastavit proměnné prostředí, přečtěte si dokumentaci k vašemu operačnímu systému.

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

Ověřování tokenu Microsoft Entra ID

Pokud chcete použít ovladač SQL Databricks pro Node.js s ověřováním tokenu ID Microsoft Entra, musíte zadat ovladač SQL Databricks pro Node.js s tokenem Microsoft Entra ID. Pokud chcete vytvořit přístupový token Microsoft Entra ID, postupujte takto:

• Pro uživatele Azure Databricks můžete použít Azure CLI. Viz Získání tokenů ID Microsoft Entra pro uživatele pomocí Azure CLI.
• Pro instanční objekt služby Microsoft Entra ID viz Získání přístupového tokenu Microsoft Entra ID pomocí Azure CLI. Informace o vytvoření spravovaného instančního objektu Microsoft Entra ID najdete v tématu Správa instančních objektů.

Tokeny MICROSOFT Entra ID mají výchozí životnost přibližně 1 hodinu. Pokud chcete vytvořit nový token ID Microsoft Entra, opakujte tento proces.

K ověření ovladače SQL Databricks pro Node.js použijte následující fragment kódu. Tento fragment kódu předpokládá, že jste nastavili následující proměnné prostředí:

• DATABRICKS_SERVER_HOSTNAMEnastavte na hodnotu Server Hostname pro váš cluster nebo SQL warehouse.
• DATABRICKS_HTTP_PATH, nastavte hodnotu cesty HTTP pro váš cluster nebo SQL Warehouse.
• DATABRICKS_TOKEN, nastaveno na token Microsoft Entra ID.

Pokud chcete nastavit proměnné prostředí, přečtěte si dokumentaci k vašemu operačnímu systému.

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

Dotazování dat

Následující příklad kódu ukazuje, jak volat ovladač SQL Databricks pro Node.js ke spuštění základního dotazu SQL na výpočetní prostředek Azure Databricks. Tento příkaz vrátí první dva řádky z trips tabulky ve schématu samples katalogu nyctaxi .

Tento příklad kódu načte hodnoty proměnných připojení token, server_hostname a http_path ze sady proměnných prostředí Azure Databricks. Tyto proměnné prostředí mají následující názvy proměnných prostředí:

• DATABRICKS_TOKEN, který představuje váš osobní přístupový token Azure Databricks z požadavků.
• DATABRICKS_SERVER_HOSTNAME, který představuje název hostitele serveru požadovaný dle požadavků.
• Hodnota cesty HTTP z požadavků je reprezentována pomocí DATABRICKS_HTTP_PATH.

K načtení těchto hodnot proměnných připojení můžete použít jiné přístupy. Použití proměnných prostředí je jen jedním z mnoha přístupů.

Následující příklad kódu ukazuje, jak volat Konektor SQL Databricks pro Node.js ke spuštění základního příkazu SQL v clusteru nebo SQL Warehouse. Tento příkaz vrátí první dva řádky z trips tabulky.

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

Výstup:

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

Přednášky

Všechny IDBSQLSession metody, které vrací IOperation objekty v referenčních informacích rozhraní API, mají následující společné parametry, které ovlivňují jejich chování:

• Nastavení runAsync na true spouští asynchronní režim. IDBSQLSession metody zařadí operace do fronty a co nejrychleji dokončí své provádění. Aktuální stav vráceného IOperation objektu se může lišit a klient je zodpovědný za kontrolu jeho stavu před použitím vráceného IOperationobjektu . Podívejte se na Operace. Nastavením runAsync na false se rozumí, že metody IDBSQLSession čekají na dokončení operací. Databricks doporučuje vždy nastavit runAsynctrue.
• Nastavení maxRows na hodnotu, která není null, umožňuje přímé výsledky. Při přímých výsledcích se server pokusí počkat na dokončení operací a pak načte část dat. V závislosti na tom, kolik práce server dokázal dokončit v definovaném čase, IOperation vrátí se objekty v určitém přechodném stavu místo v některém čekajícího stavu. Velmi často se všechna metadata a výsledky dotazu vrací v rámci jednoho požadavku na server. Server používá maxRows k určení, kolik záznamů může okamžitě vrátit. Skutečný blok dat však může mít jinou velikost; viz .IDBSQLSession.fetchChunk Přímé výsledky jsou ve výchozím nastavení povolené. Databricks nedoporučuje zakazovat přímé výsledky.

Operace

Jak je popsáno v Sezeních, IOperation objekty vrácené metodami IDBSQLSession sezení v referenční dokumentaci API nejsou plně vyplněny. Související operace serveru může stále probíhat, například čekání na spuštění databricks SQL Warehouse, spuštění dotazu nebo načtení dat. Třída IOperation skryje tyto podrobnosti uživatelům. Například metody jako fetchAll, fetchChunka getSchema čekat interně na dokončení operací a pak vrátit výsledky. Metodu IOperation.finished() můžete použít k explicitní čekání na dokončení operací. Tyto metody používají zpětné volání, které se pravidelně volá při čekání na dokončení operací. Nastavení možnosti progress na true se snaží získat dodatečné údaje o průběhu ze serveru a předat je do tohoto zpětného volání.

Metody close a cancel lze volat kdykoli. Při volání okamžitě zneplatní objekt IOperation; všechna čekající volání, jako fetchAll, fetchChunk a getSchema, jsou okamžitě zrušena a vrátí se chyba. V některých případech může být operace serveru již dokončena a cancel metoda ovlivňuje pouze klienta.

Metoda fetchAll volá fetchChunk interně a shromažďuje všechna data do pole. I když je to praktické, může to způsobit chyby kvůli nedostatku paměti při použití u velkých datových sad. fetchAll parametry jsou obvykle předávány fetchChunk.

Načtení částí dat

Při načítání bloků dat se používá následující vzor kódu:

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

Metoda fetchChunk v referenčních informacích rozhraní API zpracovává data v malých částech za účelem snížení spotřeby paměti. fetchChunk Nejprve počká, až se operace dokončí, pokud ještě nejsou dokončené, zavolá zpětné volání během cyklu čekání a pak načte další blok dat.

Pomocí této možnosti můžete maxRows zadat požadovanou velikost bloku dat. Vrácený blok dat ale může mít jinou velikost, menší nebo dokonce i větší. fetchChunk se nepokouší předem načíst data interně, aby je bylo možné rozdělit do požadovaných částí. maxRows Odešle možnost na server a vrátí vše, co server vrátí. Nezaměňujte tuto maxRows možnost s možností v IDBSQLSession. maxRows předané do fetchChunk určuje velikost každého bloku a nedělá nic jiného.

Správa souborů ve svazcích katalogu Unity

Ovladač SQL Databricks umožňuje zapisovat místní soubory do svazků katalogu Unity, stahovat soubory ze svazků a odstraňovat soubory ze svazků, jak je znázorněno v následujícím příkladu:

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

Konfigurujte protokolování

Záznamový nástroj poskytuje informace pro diagnostikování problémů s konektorem. Všechny DBSQLClient objekty jsou instancovány s protokolovacím nástrojem, který tiskne na konzoli, ale pokud použijete vlastní protokolovací nástroj, můžete tyto informace posílat do souboru. Následující příklad ukazuje, jak nakonfigurovat protokolovací nástroj a změnit jeho úroveň.

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

Další příklady najdete ve složce s příklady v úložišti databricks/databricks-sql-nodejs na GitHubu.

Testování

K otestování kódu můžete použít testovací architektury JavaScriptu, jako je Jest. K otestování kódu za simulovaných podmínek bez volání koncových bodů rozhraní REST API Služby Azure Databricks nebo změny stavu účtů nebo pracovních prostorů Azure Databricks můžete použít předdefinované architektury napodobování Jestu.

Pokud například následující soubor s názvem helpers.js obsahuje funkci getDBSQLClientWithPAT, která používá osobní přístupový token Azure Databricks k vrácení připojení k pracovnímu prostoru Azure Databricks, funkci getAllColumnsFromTable, která pomocí připojení získá zadaný počet řádků dat ze zadané tabulky (například tabulky trips ve schématu nyctaxi katalogu samples) a funkci printResults pro tisk obsahu datových řádků:

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

A vzhledem k následujícímu souboru s názvem main.js, který volá funkce getDBSQLClientWithPAT, getAllColumnsFromTable a 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);
  });

Následující soubor s názvem helpers.test.js testuje, zda getAllColumnsFromTable funkce vrátí očekávanou odpověď. Místo vytvoření skutečného připojení k cílovému pracovnímu prostoru tento test napodobí DBSQLClient objekt. Test také napodobí některá data, která odpovídají schématu a hodnotám, které jsou ve skutečných datech. Test vrátí napodobená data prostřednictvím napodobeného připojení a pak zkontroluje, jestli jedna z hodnot napodobených řádků dat odpovídá očekávané hodnotě.

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

U TypeScriptu vypadá předchozí kód podobně. Pro testování Jest pomocí TypeScriptu použijte ts-jest.

Další materiály

• Ovladač SQL Databricks pro úložiště Node.js na GitHubu
• Začínáme s ovladačem SQL Databricks pro Node.js
• Řešení potíží s ovladačem SQL Databricks pro Node.js

Reference rozhraní API

• Třídy
  • Třída DBSQLClient
    • Metody
      • connect metoda
      • openSession metoda
      • getClient metoda
      • close metoda
  • Třída DBSQLSession
    • Metody
      • executeStatement metoda
      • close metoda
      • getId metoda
      • getTypeInfo metoda
      • getCatalogs metoda
      • getSchemas metoda
      • getTables metoda
      • getFunctions metoda
      • getPrimaryKeys metoda
      • getCrossReference metoda
  • DBSQLOperation Třída
    • Metody
      • getId metoda
      • fetchAll metoda
      • fetchChunk metoda
      • close metoda

Třídy

Třída DBSQLClient

Hlavní vstupní bod pro interakci s databází

Metody

connect metoda

Otevře připojení k databázi.

Parametry
volby Typ: ConnectionOptions Sada možností použitých pro připojení k databázi. Pole host, patha další povinná pole musí být vyplněna. Viz Ověřování. Příklad: const client: DBSQLClient = new DBSQLClient(); client.connect( { host: serverHostname, path: httpPath, // ... } )

Vrací: Promise<IDBSQLClient>

openSession metoda

Otevře relaci mezi DBSQLClient a databází.

Parametry
prosba Typ: OpenSessionRequest Sada volitelných parametrů pro zadání počátečního schématu a počátečního katalogu Příklad: const session = await client.openSession( {initialCatalog: 'catalog'} );

Vrací: Promise<IDBSQLSession>

getClient metoda

Vrátí interní objekt TCLIService.Client. Musí být provedena po připojení DBSQLClient.

Žádné parametry

Vrátí TCLIService.Client

close metoda

Zavře připojení k databázi a uvolní všechny přidružené prostředky na serveru. Jakákoli další volání tohoto klienta způsobí chybu.

Žádné parametry

Žádná návratová hodnota.

Třída DBSQLSession

DbSQLSessions se primárně používají k provádění příkazů proti databázi databbase a také k různým operacím načítání metadat.

Metody

executeStatement metoda

Spustí příkaz s dostupnými možnostmi.

Parametry
výrok Typ: str Příkaz, který se má provést.
volby Typ: ExecuteStatementOptions Sada volitelných parametrů pro určení časového limitu dotazu, maximální počet řádků pro přímé výsledky a jestli se má dotaz spouštět asynchronně. Ve výchozím nastavení maxRows je nastavená hodnota 1 0000. Pokud maxRows je nastavená hodnota null, operace se spustí s vypnutou funkcí přímých výsledků. Příklad: const session = await client.openSession( {initialCatalog: 'catalog'} ); queryOperation = await session.executeStatement( 'SELECT "Hello, World!"', { runAsync: true } );

Vrací: Promise<IOperation>

close metoda

Zavře relaci. Po skončení relace je třeba provést.

Žádné parametry

Žádná návratová hodnota.

getId metoda

Vrátí identifikátor GUID této relace.

Žádné parametry

Vrací: str

getTypeInfo metoda

Vrátí informace o podporovaných datových typech.

Parametry
prosba Typ: TypeInfoRequest Parametry požadavku.

Vrací: Promise<IOperation>

getCatalogs metoda

Získá seznam katalogů.

Parametry
prosba Typ: CatalogsRequest Parametry požadavku.

Vrací: Promise<IOperation>

getSchemas metoda

Získá seznam schémat.

Parametry
prosba Typ: SchemasRequest Parametry požadavku. Pole catalogName a schemaName lze je použít pro účely filtrování.

Vrací: Promise<IOperation>

getTables metoda

Získá seznam tabulek.

Parametry
prosba Typ: TablesRequest Parametry požadavku. Pole catalogName a schemaName tableName lze použít k filtrování.

Vrací: Promise<IOperation>

getFunctions metoda

Získá seznam tabulek.

Parametry
prosba Typ: FunctionsRequest Parametry požadavku. Pole functionName je povinné.

Vrací: Promise<IOperation>

getPrimaryKeys metoda

Získá seznam primárních klíčů.

Parametry
prosba Typ: PrimaryKeysRequest Parametry požadavku. Pole schemaName a tableName jsou povinná.

Vrací: Promise<IOperation>

getCrossReference metoda

Získá informace o cizích klíčích mezi dvěma tabulkami.

Parametry
prosba Typ: CrossReferenceRequest Parametry požadavku. Pro obě tabulky musí být zadán název schématu, nadřazeného objektu a katalogu.

Vrací: Promise<IOperation>

Třída DBSQLOperation

DbSQLOperations jsou vytvořeny dbSQLSessions a lze je použít k načtení výsledků příkazů a kontrole jejich spuštění. Data se načítají prostřednictvím funkcí fetchChunk a fetchAll.

Metody

getId metoda

Vrátí identifikátor GUID operace.

Žádné parametry

Vrací: str

fetchAll metoda

Čeká na dokončení operace a pak načte všechny řádky z operace.

Parametry: Žádné

Vrací: Promise<Array<object>>

fetchChunk metoda

Čeká na dokončení operace a pak z operace načte až zadaný počet řádků.

Parametry
volby Typ: FetchOptions Možnosti použité k načtení V současné době je jedinou možností maxRows, která odpovídá maximálnímu počtu datových objektů, které se mají vrátit v libovolném poli.

Vrací: Promise<Array<object>>

close metoda

Zavře operaci a uvolní všechny přidružené prostředky. Musí být provedeno, až již nebudete používat operaci.

Žádné parametry

Žádná návratová hodnota.