Ovladač SQL Databricks pro Node.js

Ovladač SQL Databricks pro Node.js je knihovnaNode.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. K instalaci a používání různých verzí Node.jsmůž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 váš 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 úložiště.

  • 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í M2M (machine-to-machine) OAuth
• Ověřování OAuth z uživatele na stroj (U2M)

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

• Ověřování pomocí spravovaných identit Azure
• Ověřte se pomocí Microsoft Entra service principals
• Ověřování pomocí Azure CLI

Poznámka:

Jako osvědčený postup zabezpečení byste neměli natvrdo zakódovat hodnoty proměnných připojení do svého 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, musíte nejprve vytvořit Azure Databricks osobní přístupový token. Podrobnosti o tomto kroku najdete v tématu Vytvoření osobních přístupových tokenů 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 DATABRICKS_SERVER_HOSTNAME hostitele serveru pro váš cluster nebo SQL sklad.
• DATABRICKS_HTTP_PATH, nastavte hodnotu cesty HTTP pro váš cluster nebo SQL Warehouse.
• 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č SQL Databricks pro Node.js verze 1.8.0 a vyšší podporuje ověřování uživatelem 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 DATABRICKS_SERVER_HOSTNAME hostitele serveru pro váš cluster nebo SQL sklad.
• 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',
  azureTenantId: '<tenant-id>',
  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',
  azureTenantId: '<tenant-id>',
  useDatabricksOAuthInAzure: true,
  host: serverHostname,
  path: httpPath,
};

client.connect(connectOptions);
// ...

Autentizace zařízení OAuth mezi stroji

Ovladač SQL Databricks pro Node.js verze 1.8.0 a vyšší podporuje ověřování OAuth typu machine-to-machine (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 přístupu instančního objektu k Azure Databricks pomocí OAuth. 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 hlavnímu služebnímu objektu přístup ke clusteru nebo datovému 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í:

• Nastavte na hodnotu DATABRICKS_SERVER_HOSTNAME hostitele serveru pro váš cluster nebo SQL sklad.
• 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 hodnotu na Secret pro heslo OAuth instančního objektu služby.

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',
  azureTenantId: '<tenant-id>',
  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',
  azureTenantId: '<tenant-id>',
  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 Ruční získání tokenů ID Microsoft Entra.
• Pro služební principál Microsoft Entra ID viz Získání tokenů pro služební principály. Informace o vytvoření spravovaného instančního objektu Microsoft Entra ID najdete v tématu Instanční objekty.

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í:

• Nastavte na hodnotu DATABRICKS_SERVER_HOSTNAME hostitele serveru pro váš cluster nebo SQL sklad.
• 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);
// ...

Nastavení User-Agent

Následující příklad kódu ukazuje, jak nastavit User-Agent aplikace product_name pro sledování využití.

JavaScript

const { DBSQLClient } = require('@databricks/sql');

const client = new DBSQLClient();
client.connect({
  host: process.env.DATABRICKS_SERVER_HOSTNAME,
  path: process.env.DATABRICKS_HTTP_PATH,
  token: process.env.DATABRICKS_TOKEN,
  userAgentEntry: 'product_name',
});

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 .

Poznámka:

Následující příklad kódu demonstruje, jak použít osobní přístupový token Azure Databricks pro autentizaci. 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 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 podle požadavků.
• DATABRICKS_SERVER_HOSTNAME, který představuje hodnotu názvu hostitele serveru z požadavků.
• Hodnota DATABRICKS_HTTP_PATH z požadavků je reprezentována pomocí .

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 ?', {
      runAsync: true,
      maxRows: 10000, // This option enables the direct results feature.
      ordinalParameters: [2],
    });

    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 ?', {
      runAsync: true,
      maxRows: 10000, // This option enables the direct results feature.
      ordinalParameters: [2],
    });

    const result = await queryOperation.fetchAll();

    await queryOperation.close();

    console.table(result);

    await session.close();
    client.close();
  })
  .catch((error) => {
    console.error(error);
  });

Příklad tagů dotazů

Důležité

Tato funkce je ve verzi Private Preview. Pokud chcete požádat o přístup, obraťte se na svůj tým účtů.

Značky dotazů jsou páry klíč-hodnota, které je možné připojit k dotazům SQL pro účely sledování a analýzy. Když je nastavíte, zobrazí se v system.query.history tabulce a umožní vám analyzovat vzory dotazů a použití.

Definujte značky dotazu jako dvojice klíč-hodnota oddělené čárkami, kde je každý klíč a hodnota oddělen dvojtečkou; například key1:value1,key2:value2.

Následující příklad ukazuje použití dotazových značek pomocí konfigurace relace:

JavaScript

const { DBSQLClient } = require('@databricks/sql');

const client = new DBSQLClient();

// Open session with query tags configuration
const session = await client.openSession({
  configuration: {
    query_tags: 'team:engineering,test:query-tags,driver:node',
  },
});

const queryOperation = await session.executeStatement('SELECT 1');
const result = await queryOperation.fetchAll();
console.log(result);

await queryOperation.close();
await session.close();

TypeScript

import { DBSQLClient } from '@databricks/sql';

const client: DBSQLClient = new DBSQLClient();

// Open session with query tags configuration
const session = await client.openSession({
  configuration: {
    query_tags: 'team:engineering,test:query-tags,driver:node',
  },
});

const queryOperation = await session.executeStatement('SELECT 1');
const result = await queryOperation.fetchAll();
console.log(result);

await queryOperation.close();
await session.close();

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.

Konfigurace relace

Když otevíráte relaci, můžete předat parametry konfigurace relace pomocí objektu configuration v metodě openSession. Tyto parametry ovlivňují chování všech operací v rámci tohoto sezení.

Mezi běžné parametry konfigurace relace patří:

• query_tags: Připojte značky klíč-hodnota k dotazům SQL pro sledování a analýzu. Další informace najdete v příkladu značek dotazu.
• ansi_mode: Řídí režim dodržování předpisů ANSI SQL ('true' nebo 'false')
• timezone: Nastaví časové pásmo relace (např 'UTC'. , 'America/New_York')

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 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á pomocí osobního tokenu přístupu Azure Databricks vrací připojení k pracovnímu prostoru Azure Databricks, funkci getAllColumnsFromTable, která pomocí tohoto připojení získá zadaný počet řádků dat ze zadané tabulky (například z tabulky trips ve schématu samples katalogu nyctaxi), a funkci printResults pro tisk obsahu řádků dat:

// 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();
    // Note: Table names cannot be parameterized; validate tableSpec against allowed values
    queryOperation = await session.executeStatement(`SELECT * FROM ${tableSpec} LIMIT ?`, {
      runAsync: true,
      maxRows: 10000, // This option enables the direct results feature.
      ordinalParameters: [rowCount],
    });
  } 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(() => {
      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

• Vyučování
  • DBSQLClient třída
    • Metody
      • connect metoda
      • openSession metoda
      • getClient metoda
      • close metoda
  • DBSQLSession třída
    • 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í. Pole userAgentEntry umožňuje zadat User-Agent, který může být zahrnut do hlavičky požadavku HTTP pro sledování využití. Viz Nastavení uživatelského agenta.

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 klienta TCLIService frameworku Thrift. 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 schemaNametableName lze je 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 využité pro 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.