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 anpm
következőt: . Annak ellenőrzéséhez, hogy telepítve van-enpm
, futtassa a parancsotnpm -v
. Ha szükséges, a telepítésheznpm
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, futtassanpm
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,
devDependencies
használjanpm
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:
- 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 .
- Kattintson a Fejlesztőeszközök elemre.
- Az Access-jogkivonatok mellett kattintson a Kezelés gombra.
- Kattintson az Új jogkivonat létrehozása elemre.
- (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).
- Kattintson a Létrehozás lehetőségre.
- 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:
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
elemet a fürt vagy az SQL Warehouse kiszolgálói állomásnév értékére állítja.DATABRICKS_HTTP_PATH
elemet, állítsa be a HTTP-elérési út értékét a fürthöz vagy az SQL Warehouse-hoz.DATABRICKS_TOKEN
beá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_HOSTNAME
elemet a fürt vagy az SQL Warehouse kiszolgálói állomásnév értékére állítja.DATABRICKS_HTTP_PATH
elemet, á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:
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.
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_HOSTNAME
elemet a fürt vagy az SQL Warehouse kiszolgálói állomásnév értékére állítja.DATABRICKS_HTTP_PATH
elemet, á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_HOSTNAME
elemet a fürt vagy az SQL Warehouse kiszolgálói állomásnév értékére állítja.DATABRICKS_HTTP_PATH
elemet, állítsa be a HTTP-elérési út értékét a fürthöz vagy az SQL Warehouse-hoz.DATABRICKS_TOKEN
elemet, á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 token
kapcsolati 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 visszaadottIOperation
objektum aktuális állapota eltérő lehet, és az ügyfél felelős az állapotának ellenőrzéséért a visszaadottIOperation
objektum használata előtt. Lásd: Műveletek. A beállításrunAsync
azt jelenti, hogy afalse
IDBSQLSession
metódusok megvárják a műveletek befejezését. A Databricks mindig eztrunAsync
true
javasolja. - 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ározzamaxRows
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 IOperation
leí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 fetchAll
a , 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 fetchAll
a , 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
: . maxRows
fetchChunk
á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
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.
Visszajelzés
https://aka.ms/ContentUserFeedback.
Hamarosan elérhető: 2024-ben fokozatosan kivezetjük a GitHub-problémákat a tartalom visszajelzési mechanizmusaként, és lecseréljük egy új visszajelzési rendszerre. További információ:Visszajelzés küldése és megtekintése a következőhöz: