A Databricks SQL-illesztőprogram a Node.js-hez

A Databricks SQL Driver for Node.js egy Node.js kódtár, amellyel JavaScript-kód használatával futtathat SQL-parancsokat az Azure Databricks számítási erőforrásain.

Követelmények

• Egy Node.js, 14-es vagy újabb verziót futtató fejlesztőgép. A Node.js telepített verziójának nyomtatásához futtassa a parancsot node -v. A Node.jskülönböző verzióinak telepítéséhez és használatához használhat olyan eszközöket, mint a Node Version Manager (nvm).

• Csomópont Csomagkezelő (npm). A Node.js későbbi verziói már tartalmazzák a npm. Annak ellenőrzéséhez, hogy telepítve van-e npm , futtassa a parancsot npm -v. Ha szükségesnek tartja, a npm telepítéséhez kövesse az utasításokat, például a Letöltés és az npm telepítése oldalon.

• A @databricks/sql csomag az npm-ról. Ha függőségként szeretné telepíteni a @databricks/sql csomagot a Node.js projektbe, futtassa npm a következő parancsot a projektével megegyező könyvtárból:

  npm i @databricks/sql
  

• Ha TypeScriptet szeretne telepíteni és használni a Node.js projektben, használja ezt: devDependencies, majd a következő parancsokat futtassa a projektjével megegyező könyvtárból:

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

• Meglévő fürt vagy SQL raktár.

• A meglévő fürt vagy SQL raktár kiszolgálói állomásneve és HTTP-elérési útja.

  • Szerezze be ezeket az értékeket egy fürthez.
  • Ezeket az értékeket lekérheti egy SQL Warehouse-hoz.

Hitelesítés

A Databricks SQL Driver for Node.js a következő Azure Databricks-hitelesítési típusokat támogatja:

• Databricks személyes hozzáférési jogkivonat hitelesítése
• Microsoft Entra ID token hitelesítése
• OAuth gép-gép közötti (M2M) hitelesítés
• OAuth user-to-machine (U2M) hitelesítés

A Databricks SQL Driver for Node.js még nem támogatja a következő Azure Databricks-hitelesítési típusokat:

• Hitelesítés felügyelt Azure-identitásokkal
• Hitelesítés a Microsoft Entra szolgáltatás-fiókokkal
• Hitelesítés az Azure CLI-vel

Feljegyzés

Ajánlott biztonsági eljárásként ne írja be a kódba a kapcsolat változóértékeit. Ehelyett le kell kérnie ezeket a kapcsolatváltozó-értékeket egy biztonságos helyről. A cikkben szereplő kódrészletek és példák például környezeti változókat használnak.

Databricks személyes hozzáférési jogkivonat hitelesítése

Ahhoz, hogy a Databricks SQL-illesztőprogramot Node.js hitelesítéssel használja, először létre kell hoznia egy Azure Databricks személyes hozzáférési jogkivonatot. A lépés részleteiért lásd: Személyes hozzáférési jogkivonatok létrehozása munkaterület-felhasználók számára.

A Databricks SQL Driver Node.js hitelesítéséhez használja a következő kódrészletet. Ez a kódrészlet feltételezi, hogy a következő környezeti változókat állította be:

• DATABRICKS_SERVER_HOSTNAMEállítsa a fürt vagy az SQL warehouse kiszolgálói állomásnév értékére.
• Állítsa be a DATABRICKS_HTTP_PATH értékét a fürthöz vagy az SQL-tárházhoz.
• DATABRICKS_TOKEN állítsa be az Azure Databricks személyes hozzáférési tokenjét.

A környezeti változók beállításához tekintse meg az operációs rendszer dokumentációját.

JavaScript

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

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

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

const client = new DBSQLClient();
const connectOptions = {
  token: token,
  host: serverHostname,
  path: httpPath,
};

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

TypeScript

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

const serverHostname: string = process.env.DATABRICKS_SERVER_HOSTNAME || '';
const httpPath: string = process.env.DATABRICKS_HTTP_PATH || '';
const token: string = process.env.DATABRICKS_TOKEN || '';

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

const client: DBSQLClient = new DBSQLClient();
const connectOptions = {
  token: token,
  host: serverHostname,
  path: httpPath,
};

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

OAuth felhasználó-gép (U2M) hitelesítés

A Databricks SQL Driver Node.js 1.8.0-s és újabb verziói támogatják az OAuth felhasználó–gép (U2M) hitelesítést.

A Node.js-hez tartozó Databricks SQL-illesztőprogram OAuth U2M-hitelesítéséhez használja az alábbi kódrészletet. Ez a kódrészlet feltételezi, hogy a következő környezeti változókat állította be:

• DATABRICKS_SERVER_HOSTNAMEállítsa a fürt vagy az SQL warehouse kiszolgálói állomásnév értékére.
• Állítsa be a DATABRICKS_HTTP_PATH értékét a fürthöz vagy az SQL-tárházhoz.

A környezeti változók beállításához tekintse meg az operációs rendszer dokumentációját.

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

OAuth gép-gép (M2M) hitelesítés

A Databricks SQL-illesztőprogram Node.js 1.8.0-s és újabb verziói támogatják az OAuth gépről gépre (U2M) történő hitelesítést.

A Databricks SQL-illesztőprogram OAuth M2M-hitelesítéssel történő Node.js használatához a következőket kell tennie:

1. Hozzon létre egy Azure Databricks-szolgáltatásnevet az Azure Databricks-munkaterületen, és hozzon létre egy OAuth-titkos kulcsot a szolgáltatásnévhez.

   A szolgáltatásnév és az OAuth-titkos kód létrehozásához lásd: Szolgáltatásnév hozzáférésének engedélyezése az Azure Databrickshez az OAuth használatával. Jegyezze fel a szolgáltatásnév UUID - vagy alkalmazásazonosító-értékét , valamint a szolgáltatásnév OAuth-titkos kódjának titkos értékét.

2. Adjon hozzáférést a szolgáltatási főszereplőnek a fürtjéhez vagy az adattárházhoz. Lásd : Számítási engedélyek vagy SQL-raktár kezelése.

A Databricks SQL Driver Node.js hitelesítéséhez használja a következő kódrészletet. Ez a kódrészlet feltételezi, hogy a következő környezeti változókat állította be:

• DATABRICKS_SERVER_HOSTNAMEállítsa a fürt vagy az SQL warehouse kiszolgálói állomásnév értékére.
• Állítsa be a DATABRICKS_HTTP_PATH értékét a fürthöz vagy az SQL-tárházhoz.
• DATABRICKS_CLIENT_ID, állítsa be a szolgáltatás főképviselőjének UUID - vagy alkalmazásazonosítóját.
• DATABRICKS_CLIENT_SECRET, állítsa be a szolgáltatásnév OAuth-titkos kódjának titkos értékét.

A környezeti változók beállításához tekintse meg az operációs rendszer dokumentációját.

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

Microsoft Entra-azonosítójegy hitelesítése

A Databricks SQL Driver for Node.js használatához Microsoft Entra ID-jogkivonat-hitelesítéssel biztosítania kell a Databricks SQL Driver for Node.js számára a Microsoft Entra ID-jogkivonatot. Microsoft Entra ID hozzáférési jogkivonat létrehozásához tegye a következőket:

• Azure Databricks-felhasználó esetén használhatja az Azure CLI-t. Lásd: Microsoft Entra ID-jogkivonatok manuális beszerzése.
• A Microsoft Entra ID szolgáltatásnévvel kapcsolatban lásd: Jogkivonatok lekérése szolgáltatásnevekhez. A Microsoft Entra ID által felügyelt szolgáltatásnév létrehozásához tekintse meg a szolgáltatásnevek című témakört.

A Microsoft Entra ID-jogkivonatok alapértelmezett élettartama körülbelül 1 óra. Új Microsoft Entra ID-jogkivonat létrehozásához ismételje meg ezt a folyamatot.

A Databricks SQL Driver Node.js hitelesítéséhez használja a következő kódrészletet. Ez a kódrészlet feltételezi, hogy a következő környezeti változókat állította be:

• DATABRICKS_SERVER_HOSTNAMEállítsa a fürt vagy az SQL warehouse kiszolgálói állomásnév értékére.
• Állítsa be a DATABRICKS_HTTP_PATH értékét a fürthöz vagy az SQL-tárházhoz.
• Állítsa be a DATABRICKS_TOKEN-t a Microsoft Entra ID tokenre.

A környezeti változók beállításához tekintse meg az operációs rendszer dokumentációját.

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

User-Agent beállítása

Az alábbi példakód bemutatja, hogyan állíthatja be a User-Agent alkalmazás product_name a használatkövetéshez.

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

Adatok lekérdezése

Az alábbi példakód bemutatja, hogyan hívhatja meg a Databricks SQL-illesztőprogramot Node.js egy alapszintű SQL-lekérdezés futtatásához egy Azure Databricks számítási erőforráson. Ez a parancs a trips katalógus samples sémájának nyctaxi táblázatából adja vissza az első két sort.

Feljegyzés

Az alábbi példakód bemutatja, hogyan használható az Azure Databricks személyes hozzáférési jogkivonata a hitelesítéshez. Ha ehelyett más elérhető Azure Databricks-hitelesítési típusokat szeretne használni, tekintse meg a Hitelesítés című témakört.

Ez a példakód az Azure Databricks környezeti változóinak egy készletéből kéri le a token, server_hostname és http_path kapcsolati változó értékeit. Ezek a környezeti változók a következő környezeti változónevekkel rendelkeznek:

• DATABRICKS_TOKEN, amely az Azure Databricks személyes hozzáférési jogkivonatát jelöli a követelményekben leírtak szerint.
• DATABRICKS_SERVER_HOSTNAME, amely a kiszolgáló állomásnevének értékét jelöli a követelményekből.
• DATABRICKS_HTTP_PATH, amely a követelmények HTTP-elérési útját jelöli.

Ezeket a kapcsolatváltozó-értékeket más módszerekkel is beolvashatja. A környezeti változók használata csak egy megközelítés a sok közül.

Az alábbi példakód bemutatja, hogyan használhatja a Databricks SQL Connectort Node.js-ben egy alapszintű SQL-parancs futtatásához egy fürtön vagy SQL tárolón. Ez a parancs az trips tábla első két sorát adja vissza.

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élda lekérdezéscímkékre

Fontos

A funkció privát előzetes verzióban érhető el. A hozzáférés kéréséhez lépjen kapcsolatba a fiókcsapattal.

A lekérdezéscímkék kulcs-érték párok, amelyek nyomon követés és elemzés céljából csatolhatók az SQL-lekérdezésekhez. Ha be van állítva, megjelennek a táblázatban, így elemezheti a system.query.history lekérdezési mintákat és a használatot.

A lekérdezéscímkéket vesszővel tagolt kulcs-érték párként definiálhatja, ahol az egyes kulcsokat és értékeket kettőspont választja el, key1:value1,key2:value2például.

Az alábbi példa bemutatja, hogyan használhat lekérdezéscímkéket munkamenet-konfigurációval:

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

Előadások

Az IDBSQLSession objektumait visszaadó IOperation összes metódus a következő gyakori paraméterekkel rendelkezik, amelyek befolyásolják a viselkedésüket:

• A(z) runAsynctrue-re állítása elindítja az aszinkron módot. IDBSQLSession metódusok a műveleteket sorba helyezik, és a lehető leggyorsabban visszatérnek. A visszaadott IOperation objektum aktuális állapota eltérő lehet, és az ügyfél felelős az állapotának ellenőrzéséért a visszaadott IOperationobjektum használata előtt. Lásd : Műveletek. A beállítás runAsync azt jelenti, hogy a falseIDBSQLSession metódusok megvárják a műveletek befejezését. A Databricks azt javasolja, hogy mindig állítsa be a runAsync értéket true-ra.
• A nem null értékre való beállítás maxRows közvetlen eredményeket tesz lehetővé. Közvetlen eredmények esetén a kiszolgáló megpróbálja megvárni a műveletek befejezését, majd beolvassa az adatok egy részét. Attól függően, hogy a kiszolgáló mennyi munkát tudott elvégezni a megadott időn belül, IOperation az objektumok köztes állapotban térnek vissza a függőben lévő állapot helyett. Az összes metaadat és lekérdezési eredmény gyakran egyetlen kérésen belül lesz visszaadva a kiszolgálónak. A kiszolgáló azt határozza maxRows meg, hogy hány rekordot tud azonnal visszaadni. A tényleges adattömb azonban eltérő méretű lehet; lásd: IDBSQLSession.fetchChunk. A közvetlen eredmények alapértelmezés szerint engedélyezve vannak. A Databricks a közvetlen eredmények letiltását javasolja.

Munkamenet-konfiguráció

Munkamenetkonfigurációs paramétereket akkor adhat meg, amikor megnyit egy munkamenetet a configurationopenSession metódus objektumával. Ezek a paraméterek befolyásolják az adott munkameneten belüli összes művelet viselkedését.

Gyakori munkamenet-konfigurációs paraméterek:

• query_tags: Kulcs-érték címkék csatolása SQL-lekérdezésekhez nyomon követés és elemzés céljából. További információ: Példa lekérdezéscímkékre.
• ansi_mode: AZ ANSI SQL megfelelőségi mód ('true' vagy 'false') vezérlése
• timezone: Beállítja a munkamenet időzónáját (pl. 'UTC', ) 'America/New_York'

Üzemeltetés

A munkamenetekbenIOperation leírtak szerint az IDBSQLSession munkamenet-metódusai által visszaadott objektumok nem lesznek teljesen kitöltve. Előfordulhat, hogy a kapcsolódó kiszolgálóművelet még folyamatban van, például arra vár, hogy a Databricks SQL Warehouse elinduljon, futtassa a lekérdezést, vagy beolvassa az adatokat. Az IOperation osztály elrejti ezeket a részleteket a felhasználók elől. Például az olyan metódusok, mint fetchAll, fetchChunk és getSchema, belsőleg várnak, amíg a műveletek befejeződnek, majd visszatérnek az eredményekkel. A metódus használatával IOperation.finished() explicit módon megvárhatja a műveletek befejezését. Ezek a metódusok időszakosan visszahívást hajtanak végre, miközben a műveletek befejezésére várnak. A(z) progress opció beállítása megkísérli a kiszolgálótól további állapotadatok lekérését, és továbbítja azokat a visszahívási függvénynek.

A close metódusok és cancel a metódusok bármikor meghívhatók. Híváskor azonnal érvényteleníti az IOperation objektumot; az összes függőben lévő hívás, például fetchAlla , fetchChunkés getSchema azonnal megszakad, és a rendszer hibát ad vissza. Bizonyos esetekben előfordulhat, hogy a kiszolgálói művelet már befejeződött, és a cancel metódus csak az ügyfelet érinti.

A fetchAll metódus belső hívásokat indít fetchChunk , és az összes adatot egy tömbbe gyűjti. Bár ez kényelmes, memóriahibákat okozhat, ha nagy adathalmazokon használják. fetchAll beállításokat általában a rendszer átadja a következőnek fetchChunk: .

Adatrészek lekérése

Az adattömbök beolvasása a következő kódmintát használja:

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

Az fetchChunkAPI-referencia metódusa kis mennyiségben dolgozza fel az adatokat a memóriahasználat csökkentése érdekében. fetchChunk először megvárja a műveletek befejezését, ha még nem fejezték be őket, majd visszahívást hív meg a várakozási ciklus során, majd lekéri a következő adattömbet.

A beállítással maxRows megadhatja a kívánt adattömbméretet. A visszaadott adattömb mérete azonban eltérő lehet, kisebb vagy néha nagyobb is lehet. fetchChunk nem próbálja meg belsőleg elővenni az adatokat, hogy a kért részekre szeletelje őket. Elküldi a lehetőséget a maxRows kiszolgálónak, és visszaadja a kiszolgáló által visszaadott értéket. Ne keverje össze ezt a maxRows lehetőséget a következővel IDBSQLSession: . Az maxRows elemként átadott fetchChunk határozza meg az egyes adattömbök méretét és nem csinál mást.

Fájlok kezelése Unity Catalog-kötetekben

A Databricks SQL-illesztővel helyi fájlokat írhat a Unity Catalog-kötetekbe, fájlokat tölthet le kötetekről, és fájlokat törölhet a kötetekből, ahogyan az alábbi példában látható:

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

Naplózás konfigurálása

A naplózó információt nyújt az összekötővel kapcsolatos hibakeresési problémákról. A rendszer minden DBSQLClient objektumot egy naplózóval példányosít, ami a konzolra ír, de ha egy egyéni naplózót ad meg, elküldheti ezt az információt egy fájlba. Az alábbi példa bemutatja, hogyan konfigurálhat egy naplózót, és hogyan módosíthatja annak szintjét.

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

További példákért tekintse meg a GitHub databricks/databricks-sql-nodejs adattárának példák mappáját.

Tesztelés

A kód teszteléséhez JavaScript-tesztelési keretrendszereket, például Jest-keretrendszereket használhat. Ha szimulált körülmények között szeretné tesztelni a kódot az Azure Databricks REST API-végpontok meghívása vagy az Azure Databricks-fiókok vagy -munkaterületek állapotának módosítása nélkül, használhatja a Jest beépített szimulálási keretrendszereit.

Ha például a következő fájl neve egy olyan függvényt helpers.js tartalmaz, amely egy Azure Databricks személyes hozzáférési jogkivonatot használ egy Azure Databricks-munkaterülethez való kapcsolat visszaadásához, egy getDBSQLClientWithPAT függvény, amely a kapcsolatot használja a megadott számú adatsor lekéréséhez a megadott táblából (például a getAllColumnsFromTable katalógus sémájában trips lévő samples táblázatból), valamint egy nyctaxi függvényből, amely kinyomtatja az adatsorok tartalmát:printResults

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

És mivel a következő fájl neve main.js meghívja a getDBSQLClientWithPAT, getAllColumnsFromTableés printResults függvényeket:

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

A következő elnevezett helpers.test.js fájl ellenőrzi, hogy a getAllColumnsFromTable függvény a várt választ adja-e vissza. Ahelyett, hogy valódi kapcsolatot hoz létre a cél-munkaterülethez, ez a teszt egy DBSQLClient objektumot szimulál. A teszt néhány olyan adatot is szimulál, amely megfelel a valós adatok sémájának és értékeinek. A teszt a szimulált kapcsolaton keresztül adja vissza a szimulált adatokat, majd ellenőrzi, hogy a szimulált adatsorok egyik értéke megegyezik-e a várt értékkel.

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

TypeScript esetén az előző kód hasonló. A TypeScript használatával végzett Jest-teszteléshez használja a ts-jest parancsot.

További erőforrások

• A Databricks SQL Driver for Node.js adattár a GitHubon
• A Databricks SQL Driver használatának első lépései a Node.js
• A Databricks SQL-illesztőprogram hibaelhárítása Node.js

API-referencia

• Osztályok
  • DBSQLClient osztály
    • Módszerek
      • connect módszer
      • openSession módszer
      • getClient módszer
      • close módszer
  • DBSQLSession osztály
    • Módszerek
      • executeStatement módszer
      • close módszer
      • getId módszer
      • getTypeInfo módszer
      • getCatalogs módszer
      • getSchemas módszer
      • getTables módszer
      • getFunctions módszer
      • getPrimaryKeys módszer
      • getCrossReference módszer
  • DBSQLOperation osztály
    • Módszerek
      • getId módszer
      • fetchAll módszer
      • fetchChunk módszer
      • close módszer

Osztályok

DBSQLClient osztály

Az adatbázisokkal való interakció fő belépési pontja.

Metódusok

connect módszer

Kapcsolatot nyit meg az adatbázissal.

Paraméterek
beállítások Típus: ConnectionOptions Az adatbázishoz való csatlakozáshoz használt beállítások készlete. A host, pathés egyéb kötelező mezőket ki kell tölteni. Lásd: Hitelesítés. A userAgentEntry mező lehetővé teszi, hogy megadja a User-Agent-t, amelyet a HTTP-kérelem fejlécébe kell belefoglalni a használat nyomon követéséhez. Lásd: Felhasználóügynök beállítása.

Visszatér: Promise<IDBSQLClient>

openSession módszer

Munkamenet megnyitása a DBSQLClient és az adatbázis között.

Paraméterek
kérés Típus: OpenSessionRequest Választható paraméterek készlete a kezdeti séma és a kezdeti katalógus megadásához Példa: const session = await client.openSession({ initialCatalog: 'catalog' });

Visszatér: Promise<IDBSQLSession>

getClient módszer

Belső thrift TCLIService.Client objektumot ad vissza. A DBSQLClient csatlakoztatása után kell meghívni.

Nincsenek paraméterek

Visszatér TCLIService.Client

close módszer

Bezárja az adatbázishoz való kapcsolatot, és felszabadítja az összes társított erőforrást a kiszolgálón. Az ügyfélhez intézett további hívások hibát fognak eredményezni.

Nincsenek paraméterek.

Nincs visszatérési érték.

DBSQLSession osztály

A DBSQLSessions elsősorban az adatbázison lévő utasítások végrehajtására, valamint a különböző metaadat-lekérési műveletek végrehajtására szolgál.

Metódusok

executeStatement módszer

Végrehajt egy utasítást a megadott beállításokkal.

Paraméterek

állítás Típus: str A végrehajtandó parancs. beállítások Típus: ExecuteStatementOptions Választható paraméterek készlete a lekérdezés időtúllépésének meghatározásához, a közvetlen eredmények maximális sorainak meghatározásához, valamint a lekérdezés aszinkron futtatásához. Alapértelmezés szerint maxRows 10000 értékre van állítva. Ha maxRows null értékre van állítva, a művelet a közvetlen eredmények funkció kikapcsolásával fog futni. Példa: const session = await client.openSession({ initialCatalog: 'catalog' }); `` queryOperation = await session.executeStatement('SELECT "Hello, World!"', { runAsync: true });

Visszatér: Promise<IOperation>

close módszer

Bezárja a munkamenetet. A munkamenet használata után kell elvégezni.

Nincsenek paraméterek.

Nincs visszatérési érték.

getId módszer

A munkamenet GUID azonosítóját adja vissza.

Nincsenek paraméterek.

Visszatér: str

getTypeInfo módszer

A támogatott adattípusokra vonatkozó információkat ad vissza.

Paraméterek
kérés Típus: TypeInfoRequest Kérelemparaméterek.

Visszatér: Promise<IOperation>

getCatalogs módszer

Lekéri a katalógusok listáját.

Paraméterek
kérés Típus: CatalogsRequest Kérelemparaméterek.

Visszatér: Promise<IOperation>

getSchemas módszer

Lekéri a sémák listáját.

Paraméterek
kérés Típus: SchemasRequest Kérelemparaméterek. Mezők catalogName , és schemaName szűrési célokra használhatók.

Visszatér: Promise<IOperation>

getTables módszer

Lekérdezi a táblák listáját.

Paraméterek
kérés Típus: TablesRequest Kérelemparaméterek. Mezők catalogName, schemaName és tableName szűrésre használhatók.

Visszatér: Promise<IOperation>

getFunctions módszer

Lekérdezi a táblák listáját.

Paraméterek
kérés Típus: FunctionsRequest Kérelemparaméterek. A mező functionName megadása kötelező.

Visszatér: Promise<IOperation>

getPrimaryKeys módszer

Lekéri az elsődleges kulcsok listáját.

Paraméterek
kérés Típus: PrimaryKeysRequest Kérelemparaméterek. Mezők schemaName és tableName kötelezőek.

Visszatér: Promise<IOperation>

getCrossReference módszer

Információt kap a két tábla közötti idegen kulcsokról.

Paraméterek
kérés Típus: CrossReferenceRequest Kérelemparaméterek. A séma, a szülő és a katalógus nevét mindkét táblához meg kell adni.

Visszatér: Promise<IOperation>

DBSQLOperation osztály

A DBSQLOperations-t a DBSQLSessions hozza létre, és az utasítások eredményeinek lekérésére és a végrehajtásuk ellenőrzésére használható. Az adatok lekérése a fetchChunk és a fetchAll függvényeken keresztül történik.

Metódusok

getId módszer

A művelet GUID azonosítóját adja vissza.

Nincsenek paraméterek.

Visszatér: str

fetchAll módszer

Megvárja a művelet befejezését, majd lekéri az összes sort a műveletből.

Paraméterek: Nincs

Visszatér: Promise<Array<object>>

fetchChunk módszer

Megvárja a művelet befejezését, majd egy művelet megadott számú sorát lekéri.

Paraméterek
beállítások Típus: FetchOptions A beolvasáshoz használt beállítások. Jelenleg az egyetlen lehetőség a maxRows, amely egy adott tömbben visszaadandó adatobjektumok maximális számának felel meg.

Visszatér: Promise<Array<object>>

close módszer

Bezárja a műveletet, és felszabadítja az összes társított erőforrást. A műveletet akkor kell elvégezni, amikor az már nincs használatban.

Nincsenek paraméterek.

Nincs visszatérési érték.