Databricks SQL Driver for Node.js

مقالة
07/09/2024

برنامج تشغيل Databricks SQL ل Node.js هو مكتبة Node.js تسمح لك باستخدام تعليمات JavaScript البرمجية لتشغيل أوامر SQL على موارد حساب Azure Databricks.

المتطلبات

جهاز تطوير يعمل Node.js، الإصدار 14 أو أعلى. لطباعة الإصدار المثبت من Node.js، قم بتشغيل الأمر node -v. لتثبيت واستخدام إصدارات مختلفة من Node.js، يمكنك استخدام أدوات مثل Node Version Manager (nvm).
مدير الحِزَم العقدة (npm). تتضمن npmالإصدارات اللاحقة من Node.js بالفعل . للتحقق مما إذا كان npm مثبتا، قم بتشغيل الأمر npm -v. لتثبيت npm إذا لزم الأمر، يمكنك اتباع إرشادات مثل تلك الموجودة في تنزيل npm وتثبيته.
حزمة @databricks/sql من npm. لتثبيت الحزمة @databricks/sql في مشروع Node.js الخاص بك كتبعية، استخدم npm لتشغيل الأمر التالي من داخل نفس الدليل مثل مشروعك:
```
npm i @databricks/sql
```
إذا كنت تريد تثبيت TypeScript واستخدامه في مشروع Node.js الخاص بك ك devDependencies، فاستخدم npm لتشغيل الأوامر التالية من داخل نفس الدليل مثل مشروعك:
```
npm i -D typescript
npm i -D @types/node
```
نظام مجموعة موجود أو مستودع SQL.
قيمة Server Hostname وHTTP Path للمجموعة الموجودة أو مستودع SQL.
- احصل على هذه القيم لنظام مجموعة.
- احصل على هذه القيم لمستودع SQL.

المصادقة

يدعم برنامج تشغيل Databricks SQL ل Node.js أنواع مصادقة Azure Databricks التالية:

مصادقة رمز الوصول الشخصي ل Databricks
مصادقة الرمز المميز لمعرف Microsoft Entra (المعروف سابقا ب Azure Active Directory)
مصادقة OAuth من جهاز إلى جهاز (M2M)
مصادقة OAuth من مستخدم إلى جهاز (U2M)

لا يدعم برنامج تشغيل Databricks SQL ل Node.js بعد أنواع مصادقة Azure Databricks التالية:

إشعار

كأفضل ممارسة أمان، يجب عدم تضمين قيم متغير اتصال التعليمات البرمجية الثابتة في التعليمات البرمجية الخاصة بك. بدلا من ذلك، يجب استرداد قيم متغير الاتصال هذه من موقع آمن. على سبيل المثال، تستخدم القصاصات البرمجية والأمثلة في هذه المقالة متغيرات البيئة.

مصادقة رمز الوصول الشخصي ل Databricks

لاستخدام برنامج تشغيل Databricks SQL ل Node.js مع مصادقة رمز الوصول الشخصي Azure Databricks، يجب أولا إنشاء رمز مميز للوصول الشخصي ل Azure Databricks، كما يلي:

في مساحة عمل Azure Databricks، انقر فوق اسم مستخدم Azure Databricks في الشريط العلوي، ثم حدد الإعدادات من القائمة المنسدلة.
انقر فوق المطور.
إلى جانب رموز الوصول المميزة، انقر فوق إدارة.
النقر على Generate new token.
(اختياري) أدخل تعليقا يساعدك على تحديد هذا الرمز المميز في المستقبل، وتغيير العمر الافتراضي للرمز المميز وهو 90 يوما. لإنشاء رمز مميز بدون مدة بقاء (غير مستحسن)، اترك مربع مدة البقاء (أيام) فارغا (فارغ).
انقر فوق "Generate".
انسخ الرمز المميز المعروض إلى موقع آمن، ثم انقر فوق تم.

إشعار

تأكد من حفظ الرمز المميز المنسخ في موقع آمن. لا تشارك الرمز المميز المنسخ مع الآخرين. إذا فقدت الرمز المميز المنسخ، فلا يمكنك إعادة إنشاء نفس الرمز المميز بالضبط. بدلا من ذلك، يجب تكرار هذا الإجراء لإنشاء رمز مميز جديد. إذا فقدت الرمز المميز الذي تم نسخه، أو كنت تعتقد أنه تم اختراق الرمز المميز، فإن Databricks يوصي بشدة بحذف هذا الرمز المميز على الفور من مساحة العمل الخاصة بك عن طريق النقر فوق أيقونة سلة المهملات (إبطال) بجوار الرمز المميز في صفحة رموز Access المميزة .

إذا لم تتمكن من إنشاء الرموز المميزة أو استخدامها في مساحة العمل الخاصة بك، فقد يرجع ذلك إلى قيام مسؤول مساحة العمل بتعطيل الرموز المميزة أو عدم منحك الإذن لإنشاء الرموز المميزة أو استخدامها. راجع مسؤول مساحة العمل أو ما يلي:

لمصادقة برنامج تشغيل Databricks SQL ل Node.js، استخدم القصاصة البرمجية التالية. تفترض هذه القصاصة البرمجية أنك قمت بتعيين متغيرات البيئة التالية:

DATABRICKS_SERVER_HOSTNAMEتعيين إلى قيمة Server Hostname لنظام المجموعة أو مستودع SQL.
DATABRICKS_HTTP_PATH، قم بتعيين إلى قيمة مسار HTTP لنظام المجموعة أو مستودع SQL.
DATABRICKS_TOKEN، قم بتعيين إلى رمز الوصول الشخصي Azure Databricks.

لتعيين متغيرات البيئة، راجع وثائق نظام التشغيل الخاص بك.

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 من مستخدم إلى جهاز (U2M)

يدعم Databricks SQL Driver للإصدارات Node.js 1.8.0 والإصدارات الأحدث مصادقة OAuth من مستخدم إلى جهاز (U2M).

لمصادقة برنامج تشغيل Databricks SQL ل Node.js باستخدام مصادقة OAuth U2M، استخدم مقتطف التعليمات البرمجية التالي. تفترض هذه القصاصة البرمجية أنك قمت بتعيين متغيرات البيئة التالية:

DATABRICKS_SERVER_HOSTNAMEتعيين إلى قيمة Server Hostname لنظام المجموعة أو مستودع SQL.
DATABRICKS_HTTP_PATH، قم بتعيين إلى قيمة مسار HTTP لنظام المجموعة أو مستودع SQL.

لتعيين متغيرات البيئة، راجع وثائق نظام التشغيل الخاص بك.

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 من جهاز إلى جهاز (M2M)

يدعم Databricks SQL Driver للإصدارات Node.js 1.8.0 والإصدارات الأحدث مصادقة OAuth من جهاز إلى جهاز (U2M).

لاستخدام برنامج تشغيل Databricks SQL ل Node.js مع مصادقة OAuth M2M، يجب عليك القيام بما يلي:

إنشاء كيان خدمة Azure Databricks في مساحة عمل Azure Databricks، وإنشاء سر OAuth لكيان الخدمة هذا.

لإنشاء كيان الخدمة وسر OAuth الخاص به، راجع استخدام كيان خدمة للمصادقة مع Azure Databricks. دون ملاحظة عن قيمة UUID أو Application ID الخاصة بكيان الخدمة، والقيمة السرية لسر OAuth الخاص بكيان الخدمة.
امنح كيان الخدمة حق الوصول إلى نظام المجموعة أو المستودع. راجع حساب الأذونات أو إدارة مستودع SQL.

DATABRICKS_SERVER_HOSTNAMEتعيين إلى قيمة Server Hostname لنظام المجموعة أو مستودع SQL.
DATABRICKS_HTTP_PATH، قم بتعيين إلى قيمة مسار HTTP لنظام المجموعة أو مستودع SQL.
DATABRICKS_CLIENT_ID، قم بتعيين إلى قيمة UUID أو معرف التطبيق الخاصة بكيان الخدمة.
DATABRICKS_CLIENT_SECRET، قم بتعيين إلى القيمة السرية لسر OAuth الخاص بكيان الخدمة.

لتعيين متغيرات البيئة، راجع وثائق نظام التشغيل الخاص بك.

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 (المعروف سابقا ب Azure Active Directory)

لاستخدام برنامج تشغيل Databricks SQL ل Node.js مع مصادقة الرمز المميز لمعرف Microsoft Entra (المعروف سابقا ب Azure Active Directory)، يجب توفير برنامج تشغيل Databricks SQL ل Node.js مع الرمز المميز لمعرف Microsoft Entra. لإنشاء رمز مميز للوصول إلى معرف Microsoft Entra، قم بما يلي:

بالنسبة لمستخدم Azure Databricks، يمكنك استخدام Azure CLI. راجع الحصول على الرموز المميزة لمعرف Microsoft Entra (المعروف سابقا ب Azure Active Directory) للمستخدمين باستخدام Azure CLI.
للحصول على أساس خدمة معرف Microsoft Entra، راجع الحصول على رمز مميز للوصول إلى معرف Microsoft Entra باستخدام Azure CLI. لإنشاء كيان خدمة مدار من Microsoft Entra ID، راجع إدارة كيانات الخدمة.

الرموز المميزة لمعرف Microsoft Entra لها عمر افتراضي يبلغ حوالي ساعة واحدة. لإنشاء رمز مميز جديد لمعرف Microsoft Entra، كرر هذه العملية.

DATABRICKS_SERVER_HOSTNAMEتعيين إلى قيمة Server Hostname لنظام المجموعة أو مستودع SQL.
DATABRICKS_HTTP_PATH، قم بتعيين إلى قيمة مسار HTTP لنظام المجموعة أو مستودع SQL.
DATABRICKS_TOKEN، قم بتعيين إلى الرمز المميز لمعرف Microsoft Entra.

لتعيين متغيرات البيئة، راجع وثائق نظام التشغيل الخاص بك.

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

بيانات الاستعلام

يوضح مثال التعليمات البرمجية التالي كيفية استدعاء برنامج تشغيل Databricks SQL ل Node.js لتشغيل استعلام SQL أساسي على مورد حساب Azure Databricks. يقوم هذا الأمر بإرجاع أول صفين من trips الجدول في مخطط الكتالوج nyctaxi samples.

إشعار

يوضح مثال التعليمات البرمجية التالي كيفية استخدام رمز وصول شخصي Azure Databricks للمصادقة. لاستخدام أنواع مصادقة Azure Databricks الأخرى المتوفرة بدلا من ذلك، راجع المصادقة.

يسترد مثال التعليمات البرمجية tokenserver_hostname هذا قيم متغيرات الاتصال و http_path من مجموعة من متغيرات بيئة Azure Databricks. تحتوي متغيرات البيئة هذه على أسماء متغيرات البيئة التالية:

DATABRICKS_TOKEN، الذي يمثل رمز الوصول الشخصي الخاص بك في Azure Databricks من المتطلبات.
DATABRICKS_SERVER_HOSTNAME، الذي يمثل قيمة Server Hostname من المتطلبات.
DATABRICKS_HTTP_PATH، الذي يمثل قيمة مسار HTTP من المتطلبات.

يمكنك استخدام أساليب أخرى لاسترداد قيم متغيرات الاتصال هذه. استخدام متغيرات البيئة هو نهج واحد فقط بين العديد من.

يوضح مثال التعليمات البرمجية التالي كيفية استدعاء Databricks SQL Connector Node.js لتشغيل أمر SQL أساسي على نظام مجموعة أو مستودع SQL. يقوم هذا الأمر بإرجاع أول صفين من trips الجدول.

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

إخراج:

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

جلسات العمل

تحتوي جميع IDBSQLSession الأساليب التي ترجع IOperation الكائنات في مرجع واجهة برمجة التطبيقات على المعلمات الشائعة التالية التي تؤثر على سلوكها:

يؤدي الإعداد runAsync إلى true بدء الوضع غير المتزامن. IDBSQLSession تضع الأساليب العمليات في قائمة الانتظار وترجع في أسرع وقت ممكن. قد تختلف الحالة الحالية للكائن الذي تم إرجاعه IOperation ، والعميل مسؤول عن التحقق من حالته قبل استخدام الذي تم إرجاعه IOperation. راجع العمليات. يعني الإعداد runAsync إلى false أن IDBSQLSession الأساليب تنتظر اكتمال العمليات. توصي Databricks دائما بتعيين runAsync إلى true.
يؤدي الإعداد maxRows إلى قيمة غير خالية إلى تمكين النتائج المباشرة. مع النتائج المباشرة، يحاول الخادم انتظار اكتمال العمليات ثم إحضار جزء من البيانات. اعتمادا على مقدار العمل الذي تمكن الخادم من إكماله خلال الوقت المحدد، IOperation ترجع الكائنات في حالة وسيطة بدلا من بعض الحالات المعلقة. غالبا ما يتم إرجاع جميع بيانات التعريف ونتائج الاستعلام ضمن طلب واحد إلى الخادم. يستخدم maxRows الخادم لتحديد عدد السجلات التي يمكنه إرجاعها على الفور. ومع ذلك، قد تكون المجموعة الفعلية بحجم مختلف؛ راجع IDBSQLSession.fetchChunk. يتم تمكين النتائج المباشرة بشكل افتراضي. توصي Databricks بعدم تعطيل النتائج المباشرة.

العمليات

كما هو موضح في جلسات العمل، IOperation لا يتم ملء الكائنات التي يتم إرجاعها بواسطة IDBSQLSession أساليب جلسة العمل في مرجع واجهة برمجة التطبيقات بالكامل. قد تظل عملية الخادم ذات الصلة قيد التقدم، مثل انتظار بدء مستودع Databricks SQL أو تشغيل الاستعلام أو إحضار البيانات. IOperation تخفي الفئة هذه التفاصيل عن المستخدمين. على سبيل المثال، أساليب مثل fetchAll، fetchChunk، وانتظر getSchema داخليا حتى تكتمل العمليات ثم ترجع النتائج. يمكنك استخدام IOperation.finished() الأسلوب لانتظار اكتمال العمليات بشكل صريح. تأخذ هذه الأساليب رد اتصال يتم استدعاؤه بشكل دوري أثناء انتظار اكتمال العمليات. progress تعيين الخيار لمحاولات true طلب بيانات تقدم إضافية من الخادم وتمريرها إلى رد الاتصال هذا.

يمكن استدعاء الأسلوبين close و cancel في أي وقت. عند استدعائها، فإنها تبطل IOperation الكائن على الفور؛ ويتم إلغاء جميع الاستدعاءات المعلقة مثل fetchAllfetchChunkو و getSchema على الفور ويتم إرجاع خطأ. في بعض الحالات، قد تكون عملية الخادم قد اكتملت بالفعل ويؤثر cancel الأسلوب على العميل فقط.

fetchAll يستدعي fetchChunk الأسلوب داخليا ويجمع جميع البيانات في صفيف. على الرغم من أن هذا ملائم، فقد يتسبب في حدوث أخطاء نفاد الذاكرة عند استخدامها في مجموعات البيانات الكبيرة. fetchAll عادة ما يتم تمرير الخيارات إلى fetchChunk.

إحضار مجموعات من البيانات

يستخدم إحضار مجموعات البيانات نمط التعليمات البرمجية التالي:

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

يعالج fetchChunk الأسلوب في مرجع واجهة برمجة التطبيقات البيانات في أجزاء صغيرة لتقليل استهلاك الذاكرة. fetchChunk ينتظر أولا اكتمال العمليات إذا لم تكن قد اكتملت بالفعل، ثم يستدعي رد الاتصال أثناء دورة الانتظار، ثم يجلب مجموعة البيانات التالية.

يمكنك استخدام maxRows الخيار لتحديد حجم المجموعة المطلوبة. ومع ذلك، قد يكون للمساحة التي تم إرجاعها حجم مختلف، أصغر أو حتى أكبر في بعض الأحيان. fetchChunk لا يحاول الإحضار المسبق للبيانات داخليا، من أجل تقسيمها إلى الأجزاء المطلوبة. maxRows يرسل الخيار إلى الخادم ثم يرجع كل ما يرجعه الخادم. لا تخلط بين هذا maxRows الخيار والخيار الموجود في IDBSQLSession. maxRows تم تمريرها لتحديد fetchChunk حجم كل مجموعة ولا تفعل أي شيء آخر.

إدارة الملفات في وحدات تخزين كتالوج Unity

يمكنك برنامج تشغيل Databricks SQL من كتابة الملفات المحلية إلى وحدات تخزين كتالوج Unity، وتنزيل الملفات من وحدات التخزين، وحذف الملفات من وحدات التخزين، كما هو موضح في المثال التالي:

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

تكوين التسجيل

يوفر المسجل معلومات عن مشاكل تصحيح الأخطاء في الموصل. يتم إنشاء مثيل لكافة DBSQLClient الكائنات باستخدام مسجل يطبع إلى وحدة التحكم، ولكن عن طريق تمرير مسجل مخصص، يمكنك إرسال هذه المعلومات إلى ملف. يوضح المثال التالي كيفية تكوين مسجل وتغيير مستواه.

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

للحصول على أمثلة إضافية، راجع مجلد الأمثلة في مستودع databricks/databricks-sql-nodejs على GitHub.

الاختبار

لاختبار التعليمات البرمجية الخاصة بك، يمكنك استخدام أطر عمل اختبار JavaScript مثل Jest. لاختبار التعليمات البرمجية الخاصة بك في ظل ظروف محاكاة دون استدعاء نقاط نهاية Azure Databricks REST API أو تغيير حالة حسابات Azure Databricks أو مساحات العمل الخاصة بك، يمكنك استخدام أطر عمل وهمية مضمنة في Jest.

على سبيل المثال، بالنظر إلى الملف التالي المسمى helpers.js الذي يحتوي على getDBSQLClientWithPAT دالة تستخدم رمز وصول شخصي Azure Databricks لإرجاع اتصال بمساحة عمل Azure Databricks، getAllColumnsFromTable ودالة تستخدم الاتصال للحصول على العدد المحدد لصفوف البيانات من الجدول المحدد (على سبيل المثال، trips الجدول في samples مخطط الكتالوج nyctaxi 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();
    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
};

وبالنظر إلى الملف التالي المسمى main.js getDBSQLClientWithPATالذي يستدعي الدالات و getAllColumnsFromTableو printResults :

// main.js

const { getDBSQLClientWithPAT, getAllColumnsFromTable, printResult } = require('./helpers');

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

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

if (!tableSpec) {
  throw new Error("Cannot find table spec in the format catalog.schema.table. " +
    "Check the environment variable DATABRICKS_TABLE_SPEC."
  )
}

getDBSQLClientWithPAT(token, serverHostname, httpPath)
  .then(async client => {
    const result = await getAllColumnsFromTable(client, tableSpec, 2);
    printResult(result);
    await client.close();
  })
  .catch((error) => {
    console.error(error);
  });

يختبر الملف التالي المسمى helpers.test.js ما إذا كانت الدالة getAllColumnsFromTable ترجع الاستجابة المتوقعة. بدلا من إنشاء اتصال حقيقي بمساحة العمل الهدف، يقوم هذا الاختبار بالسخرية من كائن DBSQLClient . كما يسخر الاختبار من بعض البيانات التي تتوافق مع المخطط والقيم الموجودة في البيانات الحقيقية. يقوم الاختبار بإرجاع البيانات المقلدة من خلال الاتصال الوهمي ثم يتحقق مما إذا كانت إحدى قيم صفوف البيانات المقلدة تطابق القيمة المتوقعة.

// 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، تبدو التعليمات البرمجية السابقة مشابهة. لاختبار Jest مع TypeScript، استخدم ts-jest.

الموارد الإضافية

Databricks SQL Driver لمستودع Node.js على GitHub
بدء استخدام برنامج تشغيل Databricks SQL ل Node.js
استكشاف أخطاء برنامج تشغيل Databricks SQL وإصلاحها Node.js

مرجع واجهة برمجة التطبيقات

فئات

الفصول

`DBSQLClient` فصل

نقطة الإدخال الرئيسية للتفاعل مع قاعدة بيانات.

الأساليب

طريقة `connect`

فتح اتصال بقاعدة البيانات.

المعلمات
خيارات النوع: `ConnectionOptions` مجموعة الخيارات المستخدمة للاتصال بقاعدة البيانات. `hostpath`يجب ملء الحقول المطلوبة الأخرى و و. راجع المصادقة. مثال: `const client: DBSQLClient = new DBSQLClient();` `client.connect(` `{` `host: serverHostname,` `path: httpPath,` `// ...` `}` `)`

المرتجعات: Promise<IDBSQLClient>

طريقة `openSession`

يفتح جلسة العمل بين DBSQLClient وقاعدة البيانات.

المعلمات
طلب النوع: `OpenSessionRequest` مجموعة من المعلمات الاختيارية لتحديد المخطط الأولي والكتالوج الأولي مثال: `const session = await client.openSession(` `{initialCatalog: 'catalog'}` `);`

المرتجعات: Promise<IDBSQLSession>

طريقة `getClient`

إرجاع كائن TCLIService.Client الداخلي. يجب استدعاء بعد اتصال DBSQLClient.

لا توجد معلمات

رجوع TCLIService.Client

طريقة `close`

إغلاق الاتصال بقاعدة البيانات وإصدار كافة الموارد المقترنة على الخادم. أي استدعاءات إضافية لهذا العميل ستطرح خطأ.

لا توجد معلمات.

لا توجد قيمة إرجاع.

`DBSQLSession` فصل

يتم استخدام DBSQLSessions بشكل أساسي لتنفيذ عبارات مقابل databbase بالإضافة إلى عمليات جلب بيانات التعريف المختلفة.

الأساليب

طريقة `executeStatement`

تنفيذ عبارة مع الخيارات المتوفرة.

المعلمات

المعلمات
بيان النوع: `str` العبارة التي سيتم تنفيذها.
خيارات النوع: `ExecuteStatementOptions` مجموعة من المعلمات الاختيارية لتحديد مهلة الاستعلام، والحد الأقصى للصفوف للنتائج المباشرة، وما إذا كان سيتم تشغيل الاستعلام بشكل غير متزامن. يتم تعيين افتراضيا `maxRows` إلى 10000. إذا `maxRows` تم تعيين إلى null، تشغيل العملية مع إيقاف تشغيل ميزة النتائج المباشرة. مثال: `const session = await client.openSession(` `{initialCatalog: 'catalog'}` `);` `queryOperation = await session.executeStatement(` `'SELECT "Hello, World!"', { runAsync: true }` `);`

بيان

النوع: str

العبارة التي سيتم تنفيذها.

خيارات

النوع: ExecuteStatementOptions

مجموعة من المعلمات الاختيارية لتحديد مهلة الاستعلام، والحد الأقصى للصفوف للنتائج المباشرة، وما إذا كان سيتم تشغيل الاستعلام بشكل غير متزامن. يتم تعيين افتراضيا maxRows إلى 10000. إذا maxRows تم تعيين إلى null، تشغيل العملية مع إيقاف تشغيل ميزة النتائج المباشرة.

مثال:

const session = await client.openSession(
{initialCatalog: 'catalog'}
);

queryOperation = await session.executeStatement(
'SELECT "Hello, World!"', { runAsync: true }
);

المرتجعات: Promise<IOperation>

طريقة `close`

إغلاق جلسة العمل. يجب أن يتم ذلك بعد استخدام جلسة العمل.

لا توجد معلمات.

لا توجد قيمة إرجاع.

طريقة `getId`

إرجاع GUID لجلسة العمل.

لا توجد معلمات.

المرتجعات: str

طريقة `getTypeInfo`

إرجاع معلومات حول أنواع البيانات المدعومة.

المعلمات
طلب النوع: `TypeInfoRequest` معلمات الطلب.

المرتجعات: Promise<IOperation>

طريقة `getCatalogs`

يحصل على قائمة الكتالوجات.

المعلمات
طلب النوع: `CatalogsRequest` معلمات الطلب.

المرتجعات: Promise<IOperation>

طريقة `getSchemas`

يحصل على قائمة المخططات.

المعلمات
طلب النوع: `SchemasRequest` معلمات الطلب. يمكن استخدام الحقول `catalogName` و `schemaName` لأغراض التصفية.

المرتجعات: Promise<IOperation>

طريقة `getTables`

الحصول على قائمة الجداول.

المعلمات
طلب النوع: `TablesRequest` معلمات الطلب. الحقول `catalogName` و و `schemaName` `tableName` يمكن استخدامها للتصفية.

المرتجعات: Promise<IOperation>

طريقة `getFunctions`

الحصول على قائمة الجداول.

المعلمات
طلب النوع: `FunctionsRequest` معلمات الطلب. الحقل `functionName` مطلوب.

المرتجعات: Promise<IOperation>

طريقة `getPrimaryKeys`

الحصول على قائمة المفاتيح الأساسية.

المعلمات
طلب النوع: `PrimaryKeysRequest` معلمات الطلب. الحقول `schemaName` والمطلوبة `tableName` .

المرتجعات: Promise<IOperation>

طريقة `getCrossReference`

الحصول على معلومات حول المفاتيح الخارجية بين جدولين.

المعلمات
طلب النوع: `CrossReferenceRequest` معلمات الطلب. يجب تحديد اسم المخطط والأصل والكتالوج لكلا الجدولين.

المرتجعات: Promise<IOperation>

`DBSQLOperation` فصل

يتم إنشاء عمليات DBSQL بواسطة DBSQLSessions ويمكن استخدامها لجلب نتائج العبارات والتحقق من تنفيذها. يتم جلب البيانات من خلال وظائف إحضار المجموعة وجلب الكل.

الأساليب

طريقة `getId`

إرجاع GUID للعملية.

لا توجد معلمات.

المرتجعات: str

طريقة `fetchAll`

ينتظر اكتمال العملية، ثم يجلب جميع الصفوف من العملية.

المعلمات: بلا

المرتجعات: Promise<Array<object>>

طريقة `fetchChunk`

ينتظر اكتمال العملية، ثم يجلب ما يصل إلى عدد محدد من الصفوف من عملية.

المعلمات
خيارات النوع: `FetchOptions` الخيارات المستخدمة للإحضار. حاليا، الخيار الوحيد هو maxRows، والذي يتوافق مع الحد الأقصى لعدد كائنات البيانات التي سيتم إرجاعها في أي صفيف معين.

المرتجعات: Promise<Array<object>>

طريقة `close`

إغلاق العملية وإصدار كافة الموارد المقترنة. يجب أن يتم ذلك بعد عدم استخدام العملية.

لا توجد معلمات.

لا توجد قيمة إرجاع.

مشاركة عبر

Databricks SQL Driver for Node.js

المتطلبات

المصادقة

مصادقة رمز الوصول الشخصي ل Databricks

JavaScript

TypeScript

مصادقة OAuth من مستخدم إلى جهاز (U2M)

JavaScript

TypeScript

مصادقة OAuth من جهاز إلى جهاز (M2M)

JavaScript

TypeScript

مصادقة الرمز المميز لمعرف Microsoft Entra (المعروف سابقا ب Azure Active Directory)

JavaScript

TypeScript

بيانات الاستعلام

JavaScript

TypeScript

جلسات العمل

العمليات

إحضار مجموعات من البيانات

إدارة الملفات في وحدات تخزين كتالوج Unity

JavaScript

TypeScript

تكوين التسجيل

JavaScript

TypeScript

الاختبار

الموارد الإضافية

مرجع واجهة برمجة التطبيقات

الفصول

DBSQLClient فصل

الأساليب

طريقة connect

طريقة openSession

طريقة getClient

طريقة close

DBSQLSession فصل

الأساليب

طريقة executeStatement

طريقة close

طريقة getId

طريقة getTypeInfo

طريقة getCatalogs

طريقة getSchemas

طريقة getTables

طريقة getFunctions

طريقة getPrimaryKeys

طريقة getCrossReference

DBSQLOperation فصل

الأساليب

طريقة getId

طريقة fetchAll

طريقة fetchChunk

طريقة close

الملاحظات

الملاحظات

الموارد الإضافية

`DBSQLClient` فصل

طريقة `connect`

طريقة `openSession`

طريقة `getClient`

طريقة `close`

`DBSQLSession` فصل

طريقة `executeStatement`

طريقة `close`

طريقة `getId`

طريقة `getTypeInfo`

طريقة `getCatalogs`

طريقة `getSchemas`

طريقة `getTables`

طريقة `getFunctions`

طريقة `getPrimaryKeys`

طريقة `getCrossReference`

`DBSQLOperation` فصل

طريقة `getId`

طريقة `fetchAll`

طريقة `fetchChunk`

طريقة `close`