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í cluster nebo SQL Warehouse.

• Hodnota Název hostitele serveru a cesta HTTP pro existují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í instančního objektu MS Entra
• Ověřování přes Azure CLI

Poznámka:

Osvědčeným postupem zabezpečení byste neměli pevně zakódovat hodnoty proměnných připojení do kódu. Místo toho byste měli tyto hodnoty proměnných připojení načíst ze zabezpečeného umístění. Například fragmenty kódu a příklady v tomto článku používají proměnné prostředí.

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 osobního přístupového tokenu Azure Databricks, musíte nejprve vytvořit osobní přístupový token Azure Databricks následujícím způsobem:

1. V pracovním prostoru Azure Databricks klikněte na své uživatelské jméno Azure Databricks v horním panelu a pak v rozevíracím seznamu vyberte Nastavení .
2. Klikněte na Vývojář.
3. Vedle přístupových tokenů klikněte na Spravovat.
4. Klikněte na Vygenerovat nový token.
5. (Volitelné) Zadejte komentář, který vám pomůže identifikovat tento token v budoucnu a změnit výchozí životnost tokenu na 90 dnů. Pokud chcete vytvořit token bez životnosti (nedoporučuje se), nechte pole Životnost (dny) prázdné (prázdné).
6. Klikněte na Vygenerovat.
7. Zkopírujte zobrazený token do zabezpečeného umístění a klikněte na tlačítko Hotovo.

Poznámka:

Nezapomeňte zkopírovaný token uložit do zabezpečeného umístění. Nesdílejte svůj zkopírovaný token s ostatními. Pokud ztratíte zkopírovaný token, nemůžete tento úplně stejný token znovu vygenerovat. Místo toho musíte tento postup zopakovat, abyste vytvořili nový token. Pokud ztratíte zkopírovaný token nebo se domníváte, že došlo k ohrožení zabezpečení tokenu, databricks důrazně doporučuje tento token okamžitě odstranit z pracovního prostoru kliknutím na ikonu koše (Odvolat) vedle tokenu na stránce Přístupové tokeny .

Pokud v pracovním prostoru nemůžete vytvářet nebo používat tokeny, může to být proto, že správce pracovního prostoru zakázal tokeny nebo vám neudělil oprávnění k vytváření nebo používání tokenů. Projděte si správce pracovního prostoru nebo následující témata:

• Povolení nebo zakázání ověřování osobního přístupového tokenu pro pracovní prostor
• Oprávnění osobního přístupového tokenu

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_HOSTNAMEna hodnotu Název hostitele serveru pro váš cluster nebo SQL Warehouse.
• DATABRICKS_HTTP_PATH, nastavte hodnotu cesty HTTP pro váš cluster nebo SQL Warehouse.
• DATABRICKS_TOKEN, nastavte na osobní přístupový token 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 OAuth na počítač (U2M)

Ovladač SQL Databricks pro Node.js verze 1.8.0 a vyšší podporují ověřování uživatele AAuth (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í:

• DATABRICKS_SERVER_HOSTNAMEna hodnotu Název hostitele serveru pro váš cluster nebo SQL Warehouse.
• DATABRICKS_HTTP_PATH, nastavte hodnotu cesty HTTP 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)
  // ...

Ověřování M2M (machine-to-machine) OAuth

Ovladač SQL Databricks pro Node.js verze 1.8.0 a vyšší podporují ověřování U2M (machine-to-machine).

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 Ověřování přístupu k Azure Databricks pomocí instančního objektu pomocí OAuth (OAuth M2M). Poznamenejte si hodnotu UUID nebo ID aplikace instančního objektu a hodnotu Secret pro tajný klíč OAuth instančního objektu.

2. Udělte instančnímu objektu přístup ke clusteru nebo skladu. Přečtěte si informace o výpočetních oprávněních nebo správě SLUŽBY SQL Warehouse.

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_HOSTNAMEna hodnotu Název hostitele serveru pro váš cluster nebo SQL Warehouse.
• DATABRICKS_HTTP_PATH, nastavte hodnotu cesty HTTP pro váš cluster nebo SQL Warehouse.
• DATABRICKS_CLIENT_ID, nastavte na hodnotu UUID nebo ID aplikace instančního objektu.
• 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.
• Instanční objekt Microsoft Entra ID najdete v tématu 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_HOSTNAMEna hodnotu Název hostitele serveru pro váš cluster nebo SQL Warehouse.
• DATABRICKS_HTTP_PATH, nastavte hodnotu cesty HTTP pro váš cluster nebo SQL Warehouse.
• DATABRICKS_TOKEN, nastavte 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)
  // ...

Zadávání dotazů na data

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 .

Poznámka:

Následující příklad kódu ukazuje použití tokenu patu Azure Databricks k ověřování. Pokud chcete místo toho použít jiné dostupné typy ověřování Azure Databricks, přečtěte si téma Ověřování.

Tento příklad kódu načte tokenserver_hostname hodnoty proměnných připojení ze http_path 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 hodnotu názvu hostitele serveru z požadavků.
• DATABRICKS_HTTP_PATH, který představuje hodnotu cesty HTTP z požadavků.

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 pro true spuštění asynchronního režimu IDBSQLSession metody zařadí operace do fronty a vrátí co nejrychleji. 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 . Viz Operace. Nastavení runAsync znamená false , že IDBSQLSession metody čekají na dokončení operací. Databricks doporučuje vždy nastavit runAsync true.
• 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 doporučuje zakázat přímé výsledky.

Operace

Jak je popsáno v relacích, IOperation objekty vrácené metodami IDBSQLSession relace v referenčních informacích rozhraní API nejsou plně naplně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 přebírají zpětné volání, které se pravidelně volá při čekání na dokončení operací. Nastavení možnosti pokusu progress true o vyžádání dodatečných údajů o průběhu ze serveru a jejich předání do zpětného volání.

Metody close a cancel metody lze volat kdykoli. Při volání okamžitě zneplatní IOperation objekt; všechna čekající volání, jako fetchAllje , fetchChunka getSchema jsou okamžitě zrušeny 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 nedostatku paměti při použití u velkých datových sad. fetchAll možnosti jsou obvykle předány fetchChunk.

Načtení bloků 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 nepokoušá se interně načíst data, aby je bylo možné rozdělit do požadovaných částí. maxRows Odešle možnost potom server a vrátí vše, co server vrátí. Nezaměňujte tuto maxRows možnost s možností v IDBSQLSession. maxRows předané k fetchChunk definování velikosti 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);
  });

Konfigurace protokolování

Protokolovací nástroj poskytuje informace o ladění problémů s konektorem. Všechny DBSQLClient objekty se vytvářejí pomocí protokolovacího nástroje, který se vytiskne do konzoly, ale předáním vlastního protokolovacího nástroje můžete tyto informace odeslat 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 getDBSQLClientWithPAT funkci, která k vrácení připojení k pracovnímu prostoru Azure Databricks používá token pat Azure Databricks, funkce, getAllColumnsFromTable která pomocí připojení získá zadaný počet řádků dat ze zadané tabulky (například trips tabulky ve samples schématu katalogu nyctaxi ) a printResults funkci 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, main.js který volá getDBSQLClientWithPAT, getAllColumnsFromTablea printResults funkce:

// 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
  • Třída DBSQLOperation
    • 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 volána po připojení DBSQLClient.

Žádné parametry

Návraty 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 použití relace se musí provést.

Žádné parametry

Žádná návratová hodnota.

getId metoda

Vrátí identifikátor GUID 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. Po použití operace se musí provést.

Žádné parametry

Žádná návratová hodnota.