Databricks SQL-illesztőprogram Node.js

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.js kü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 npmkövetkezőt: . Annak ellenőrzéséhez, hogy telepítve van-e npm , futtassa a parancsot npm -v. Ha szükséges, a telepítéshez npm kövesse az olyan utasításokat, mint a Letöltés és az npm telepítése.

• Az @databricks/sql-csomag az npm-bő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, devDependencieshasználja npm a következő parancsokat a projektével megegyező könyvtárból:

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

• Meglévő fürt vagy SQL Warehouse.

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

  • A fürt értékeinek lekérése.
  • 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 (korábbi nevén Azure Active Directory) jogkivonat-hitelesítés
• OAuth gépről gépre (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:

• Felügyelt Azure-identitások hitelesítése
• Microsoft Entra ID alkalmazáspéldányos hitelesítés
• Azure CLI hitelesítés

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

Ha a Databricks SQL Drivert Node.js azure Databricks személyes hozzáférési jogkivonat-hitelesítéssel szeretné használni, először létre kell hoznia egy Azure Databricks személyes hozzáférési jogkivonatot az alábbiak szerint:

1. Az Azure Databricks-munkaterületen kattintson az Azure Databricks-felhasználónevére a felső sávon, majd válassza a legördülő menü Beállítások elemét .
2. Kattintson a Fejlesztőeszközök elemre.
3. Az Access-jogkivonatok mellett kattintson a Kezelés gombra.
4. Kattintson az Új jogkivonat létrehozása elemre.
5. (Nem kötelező) Írjon be egy megjegyzést, amely segít azonosítani a jogkivonatot a jövőben, és módosíthatja a jogkivonat alapértelmezett 90 napos élettartamát. Élettartam nélküli (nem ajánlott) jogkivonat létrehozásához hagyja üresen az Élettartam (nap) mezőt (üres).
6. Kattintson a Létrehozás lehetőségre.
7. Másolja a megjelenített jogkivonatot egy biztonságos helyre, majd kattintson a Kész gombra.

Feljegyzés

Ügyeljen arra, hogy a másolt jogkivonatot biztonságos helyre mentse. Ne ossza meg másokkal a másolt jogkivonatot. Ha elveszíti a másolt jogkivonatot, nem tudja pontosan ugyanazt a jogkivonatot újragenerálni. Ehelyett meg kell ismételnie ezt az eljárást egy új jogkivonat létrehozásához. Ha elveszíti a másolt jogkivonatot, vagy úgy véli, hogy a jogkivonat sérült, a Databricks határozottan javasolja, hogy azonnal törölje a jogkivonatot a munkaterületről az Access-jogkivonatok lapon a jogkivonat melletti kuka (Visszavonás) ikonra kattintva.

Ha nem tud jogkivonatokat létrehozni vagy használni a munkaterületen, ennek az lehet az oka, hogy a munkaterület rendszergazdája letiltotta a jogkivonatokat, vagy nem adott engedélyt a jogkivonatok létrehozására vagy használatára. Tekintse meg a munkaterület rendszergazdáját vagy a következőket:

• Személyes hozzáférési jogkivonat hitelesítésének engedélyezése vagy letiltása a munkaterületen
• Személyes hozzáférési jogkivonat engedélyei

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_HOSTNAMEelemet a fürt vagy az SQL Warehouse kiszolgálói állomásnév értékére állítja.
• DATABRICKS_HTTP_PATHelemet, állítsa be a HTTP-elérési út értékét a fürthöz vagy az SQL Warehouse-hoz.
• DATABRICKS_TOKENbeállításnál állítsa be az Azure Databricks személyes hozzáférési jogkivonatá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 user-to-machine (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 Databricks SQL-illesztőprogram OAuth U2M-hitelesítéssel történő hitelesítéséhez használja az alábbi kódrészletet Node.js. Ez a kódrészlet feltételezi, hogy a következő környezeti változókat állította be:

• DATABRICKS_SERVER_HOSTNAMEelemet a fürt vagy az SQL Warehouse kiszolgálói állomásnév értékére állítja.
• DATABRICKS_HTTP_PATHelemet, állítsa be a HTTP-elérési út értékét a fürthöz vagy az SQL Warehouse-hoz.

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",
    useDatabricksOAuthInAzure: true,
    host:                      serverHostname,
    path:                      httpPath
  };

  client.connect(connectOptions)
  // ...

TypeScript

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

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

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

  const client: DBSQLClient = new DBSQLClient();
  const connectOptions = {
    authType:                  "databricks-oauth",
    useDatabricksOAuthInAzure: true,
    host:                      serverHostname,
    path:                      httpPath
  };

  client.connect(connectOptions)
  // ...

OAuth machine-to-machine (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 használata az Azure Databricks használatával történő hitelesítéshez. 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ásnévnek a fürthöz vagy a raktárhoz. 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_HOSTNAMEelemet a fürt vagy az SQL Warehouse kiszolgálói állomásnév értékére állítja.
• DATABRICKS_HTTP_PATHelemet, állítsa be a HTTP-elérési út értékét a fürthöz vagy az SQL Warehouse-hoz.
• DATABRICKS_CLIENT_ID, állítsa be a szolgáltatásnév UUID - vagy alkalmazásazonosító-értéké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",
    useDatabricksOAuthInAzure: true,
    host:                      serverHostname,
    path:                      httpPath,
    oauthClientId:             clientId,
    oauthClientSecret:         clientSecret
  };

  client.connect(connectOptions)
  // ...

TypeScript

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

const serverHostname: string = process.env.DATABRICKS_SERVER_HOSTNAME || '';
const httpPath: string       = process.env.DATABRICKS_HTTP_PATH || '';
const clientId: string       = process.env.DATABRICKS_CLIENT_ID || '';
const clientSecret: string   = process.env.DATABRICKS_CLIENT_SECRET || '';

if (serverHostname == '' || httpPath == '' || clientId == '' || clientSecret == '') {
    throw new Error("Cannot find Server Hostname, HTTP Path, or " +
                    "service principal ID or secret. " +
                    "Check the environment variables DATABRICKS_SERVER_HOSTNAME, " +
                    "DATABRICKS_HTTP_PATH, DATABRICKS_CLIENT_ID, and " +
                    "DATABRICKS_CLIENT_SECRET.");
  }

  const client: DBSQLClient = new DBSQLClient();
  const connectOptions = {
    authType:                  "databricks-oauth",
    useDatabricksOAuthInAzure: true,
    host:                      serverHostname,
    path:                      httpPath,
    oauthClientId:             clientId,
    oauthClientSecret:         clientSecret
  };

  client.connect(connectOptions)
  // ...

Microsoft Entra ID (korábbi nevén Azure Active Directory) jogkivonat-hitelesítés

Ha a Databricks SQL-illesztőprogramot a Microsoft Entra ID (korábbi nevén Azure Active Directory) jogkivonat-hitelesítéssel szeretné Node.js használni, meg kell adnia a Databricks SQL-illesztőprogramot Node.js a Microsoft Entra ID tokennel. 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-azonosítók (korábbi nevén Azure Active Directory-) jogkivonatok lekérése a felhasználók számára az Azure CLI használatával.
• A Microsoft Entra ID szolgáltatásnévvel kapcsolatban lásd : Microsoft Entra ID hozzáférési jogkivonat beszerzése az Azure CLI-vel. A Microsoft Entra ID által felügyelt szolgáltatásnév létrehozásához lásd: Szolgáltatásnevek kezelése.

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_HOSTNAMEelemet a fürt vagy az SQL Warehouse kiszolgálói állomásnév értékére állítja.
• DATABRICKS_HTTP_PATHelemet, állítsa be a HTTP-elérési út értékét a fürthöz vagy az SQL Warehouse-hoz.
• DATABRICKS_TOKENelemet, állítsa a Microsoft Entra ID-jogkivonatra.

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

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 katalógus sémájában lévő samples táblázat első két sorát trips nyctaxi adja vissza.

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 tokenkapcsolati server_hostname http_path és a 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ényekből.
• 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 hívhatja meg a Databricks SQL Connectort Node.js egy alapszintű SQL-parancs fürtben vagy SQL-raktárban való futtatásához. Ez a parancs a tábla első két sorát trips 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 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);
});

Hozam:

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

Előadások

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

• Aszinkron mód indításának true beállításarunAsync. IDBSQLSession metódusok a műveletet az üzenetsorba 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 false IDBSQLSession metódusok megvárják a műveletek befejezését. A Databricks mindig ezt runAsync truejavasolja.
• 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.

Üzemeltetés

A munkamenetekben IOperationleírtak szerint az API-referencia munkamenet-metódusai által IDBSQLSession 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 fetchAlla , fetchChunkés getSchema várjon belsőleg, amíg a műveletek befejeződnek, majd eredményeket adnak vissza. A metódus használatával IOperation.finished() explicit módon megvárhatja a műveletek befejezését. Ezek a metódusok rendszeres időközönként visszahívást végeznek, miközben a műveletek befejezésére várnak. A beállítás beállítása, progress hogy true megkísérlje a kiszolgálótól a további állapotadatok lekérését, és átadja azokat a visszahívásnak.

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óriakihasználtságot okozhat, ha nagy adathalmazokon használják. fetchAll beállításokat általában a rendszer átadja a következőnek fetchChunk: .

Adattömbök beolvasása

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 fetchChunk API-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: . maxRowsfetchChunk átadva határozza meg az egyes adattömbök méretét, és nem végez semmi 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, a konzolon kinyomtatott naplózóval példányosít, de egy egyéni naplózót átadva elküldheti ezeket az adatokat egy fájlnak. 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 getAllColumnsFromTable 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 trips katalógus sémájában nyctaxi lévő samples táblázatból), valamint egy printResults függvényből, amely kinyomtatja az adatsorok tartalmát:getDBSQLClientWithPAT

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

É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().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);
});

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 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. Példa: const client: DBSQLClient = new DBSQLClient(); client.connect( { host: serverHostname, path: httpPath, // ... } )

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ó utasítás.
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éri a táblák listáját.

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

Visszatér: Promise<IOperation>

getFunctions módszer

Lekéri 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 a művelet megszűnése után kell elvégezni.

Nincsenek paraméterek.

Nincs visszatérési érték.