Драйвер SQL Databricks для Node.js

Драйвер SQL Databricks для Node.js — это библиотека Node.js, которая позволяет использовать код JavaScript для выполнения команд SQL в вычислительных ресурсах Azure Databricks.

Требования

Компьютер разработки с Node.js версии 14 или более поздней. Чтобы вывести на экран установленную версию Node.js, выполните команду node -v. Чтобы установить другие версии Node.js, можно использовать такие средства, как Node Version Manager (nvm).
Диспетчер пакетов Node.js (npm). В новых версиях Node.js npm уже включен. Чтобы проверить, установлена ли 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.
Значения имени узла сервера и пути HTTP для существующего кластера или хранилища SQL.
- Получите эти значения для кластера.
- Получите эти значения для хранилища SQL.

Проверка подлинности

Драйвер SQL Databricks для Node.js поддерживает следующие типы проверки подлинности Azure Databricks:

Аутентификация с помощью личного токена доступа Databricks
Аутентификация токена идентификации Microsoft Entra
Аутентификация машина-машине (M2M) OAuth
Проверка подлинности пользователей и компьютеров OAuth (U2M)

Драйвер SQL Databricks для Node.js пока не поддерживает следующие типы проверки подлинности Azure Databricks:

Примечание.

В рамках лучших практик безопасности не следует жёстко задавать значения переменных подключения в коде. Вместо этого следует извлекать значения переменных соединения из безопасного расположения. Например, фрагменты кода и примеры в этой статье используют переменные среды.

Проверка подлинности токена личного доступа Databricks

Чтобы использовать драйвер SQL Databricks для Node.js с проверкой подлинности, необходимо сначала создать личный маркер доступа Azure Databricks. Дополнительные сведения об этом шаге см. в разделе "Создание личных маркеров доступа для пользователей рабочей области".

Чтобы проверить подлинность драйвера SQL Databricks для Node.js, используйте следующий фрагмент кода. В этом фрагменте предполагается, что вы установили следующие переменные среды:

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

Машинописный текст

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 for Node.js версии 1.8.0 и более поздних поддерживают аутентификацию OAuth между пользователями и компьютерами (U2M).

Чтобы аутентифицировать драйвер SQL Databricks для Node.js с помощью аутентификации OAuth U2M, используйте следующий пример кода. В этом фрагменте предполагается, что вы установили следующие переменные среды:

DATABRICKS_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',
  azureTenantId: '<tenant-id>',
  useDatabricksOAuthInAzure: true,
  host: serverHostname,
  path: httpPath,
};

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

Машинописный текст

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

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

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

const client: DBSQLClient = new DBSQLClient();
const connectOptions = {
  authType: 'databricks-oauth',
  azureTenantId: '<tenant-id>',
  useDatabricksOAuthInAzure: true,
  host: serverHostname,
  path: httpPath,
};

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

Проверка подлинности для машинного взаимодействия (M2M) по протоколу OAuth

Databricks SQL Driver for Node.js версии 1.8.0 и выше поддерживает проверку подлинности OAuth на компьютере (U2M).

Чтобы использовать драйвер SQL Databricks для Node.js с проверкой подлинности OAuth M2M, необходимо выполнить следующее:

Создайте основной идентификатор службы Azure Databricks в рабочей области Azure Databricks и создайте секрет аутентификации OAuth для этого идентификатора.

Сведения о создании субъекта-службы и его секрета OAuth см. в статье "Авторизация доступа субъекта-службы к Azure Databricks с помощью OAuth". Запишите значение UUID или идентификатора приложения принципала службы и значение секрета для OAuth-ключа принципала службы.
Предоставьте субъекту-службе доступ к кластеру или хранилищу. Смотрите разрешения на вычисления или управление складом данных SQL.

DATABRICKS_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',
  azureTenantId: '<tenant-id>',
  useDatabricksOAuthInAzure: true,
  host: serverHostname,
  path: httpPath,
  oauthClientId: clientId,
  oauthClientSecret: clientSecret,
};

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

Машинописный текст

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

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

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

const client: DBSQLClient = new DBSQLClient();
const connectOptions = {
  authType: 'databricks-oauth',
  azureTenantId: '<tenant-id>',
  useDatabricksOAuthInAzure: true,
  host: serverHostname,
  path: httpPath,
  oauthClientId: clientId,
  oauthClientSecret: clientSecret,
};

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

Аутентификация по токену Microsoft Entra ID

Чтобы использовать драйвер SQL Databricks для Node.js с аутентификацией с помощью токена Microsoft Entra ID, необходимо предоставить этому драйверу токен Microsoft Entra ID. Чтобы создать токен доступа Microsoft Entra ID, сделайте следующее:

Для пользователя Azure Databricks можно использовать Azure CLI. См. Получение токенов Microsoft Entra ID вручную.
Сведения о субъекте-службе идентификатора Microsoft Entra см. в разделе "Получение маркеров для субъектов-служб". Чтобы создать управляемый принципал службы Microsoft Entra ID, см. раздел Субъекты-службы.

Токены идентификации Microsoft Entra имеют время существования по умолчанию около 1 часа. Чтобы создать новый маркер идентификатора Microsoft Entra, повторите этот процесс.

DATABRICKS_SERVER_HOSTNAMEУстановите значение Имени узла сервера для вашего кластера или SQL-хранилища.
DATABRICKS_HTTP_PATH, установите параметр HTTP-пути для кластера или хранилища SQL.
DATABRICKS_TOKEN, установите в маркер токена Microsoft Entra ID.

Чтобы задать переменные среды, ознакомьтесь с документацией операционной системы.

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

Машинописный текст

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

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

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

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

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

Набор User-Agent

Следующий пример кода демонстрирует, как настроить приложение User-Agent product_name для мониторинга использования.

JavaScript

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

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

Запрос данных

В следующем примере кода демонстрируется вызов драйвера Databricks SQL для Node.js с целью выполнения простого SQL-запроса к вычислительному ресурсу Azure Databricks. Эта команда возвращает первые две строки из таблицы trips в схеме samples каталога nyctaxi.

Примечание.

В следующем примере кода показано, как использовать личный маркер доступа Azure Databricks для проверки подлинности. Чтобы использовать другие доступные типы проверки подлинности Azure Databricks, см. статью "Проверка подлинности".

В этом примере кода извлекаются значения переменных подключения token, server_hostname и http_path из набора переменных окружения Azure Databricks. Эти переменные среды имеют следующие имена:

DATABRICKS_TOKEN представляет ваш личный токен доступа Azure Databricks в соответствии с требованиями.
DATABRICKS_SERVER_HOSTNAME, которая предоставляет значение Имени узла сервера в соответствии с требованиями.
DATABRICKS_HTTP_PATH, которое представляет значение HTTP-пути из требований.

Вы можете использовать другие подходы для получения значений этих переменных подключения. Использование переменных среды — это лишь один из многих подходов.

В следующем примере кода показано, как вызвать соединитель SQL Databricks для 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 ?', {
      runAsync: true,
      maxRows: 10000, // This option enables the direct results feature.
      ordinalParameters: [2],
    });

    const result = await queryOperation.fetchAll();

    await queryOperation.close();

    console.table(result);

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

Машинописный текст

import { DBSQLClient } from '@databricks/sql';
import IDBSQLSession from '@databricks/sql/dist/contracts/IDBSQLSession';
import IOperation from '@databricks/sql/dist/contracts/IOperation';

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

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

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

client
  .connect(connectOptions)
  .then(async (client) => {
    const session: IDBSQLSession = await client.openSession();

    const queryOperation: IOperation = await session.executeStatement('SELECT * FROM samples.nyctaxi.trips LIMIT ?', {
      runAsync: true,
      maxRows: 10000, // This option enables the direct results feature.
      ordinalParameters: [2],
    });

    const result = await queryOperation.fetchAll();

    await queryOperation.close();

    console.table(result);

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

Пример тегов запросов

Это важно

Эта функция доступна в закрытой предварительной версии. Чтобы запросить доступ, обратитесь в вашу команду поддержки аккаунтов.

Теги запросов — это пары "ключ-значение", которые можно подключить к запросам SQL для отслеживания и аналитических целей. При установке они отображаются в system.query.history таблице, что позволяет анализировать шаблоны запросов и использование.

Определите теги запросов как пары "ключ-значение", разделенные запятыми, где каждый ключ и значение разделены двоеточием, например key1:value1,key2:value2.

В следующем примере показано, как использовать теги запросов с конфигурацией сеанса:

JavaScript

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

const client = new DBSQLClient();

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

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

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

Машинописный текст

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

const client: DBSQLClient = new DBSQLClient();

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

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

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

Сеансы

Все IDBSQLSession методы, возвращающие IOperation объекты в справочнике по API, имеют следующие общие параметры, влияющие на их поведение:

Установка runAsync в true запускает асинхронный режим. IDBSQLSession Методы помещают операции в очередь и возвращаются как можно быстрее. Текущее состояние возвращаемого объекта может отличаться, и клиент отвечает за проверку состояния перед использованием возвращаемого IOperationIOperationобъекта. См . статью "Операции". Значение параметра runAsyncfalse означает, что IDBSQLSession методы ожидают завершения операций. Databricks рекомендует всегда задавать значение runAsynctrue.
Если задать maxRows значение, отличное от NULL, можно получить прямые результаты. Когда используются прямые результаты, сервер ожидает завершения операций, а затем забирает часть данных. В зависимости от того, сколько работы сервера удалось выполнить в течение определенного времени, IOperation объекты возвращаются в некотором промежуточном состоянии вместо некоторого ожидающего состояния. Часто все метаданные и результаты запроса возвращаются в рамках одного запроса на сервер. Сервер использует maxRows для определения количества записей, которые он может возвращать немедленно. Однако фактический блок может иметь другой размер; см. раздел IDBSQLSession.fetchChunk. Прямые результаты включены по умолчанию. Databricks не рекомендует отключать прямые результаты.

Конфигурация сеанса

Параметры конфигурации можно передать при открытии сеанса с помощью объекта configuration в методе openSession. Эти параметры влияют на поведение всех операций в этом сеансе.

К общим параметрам конфигурации сеанса относятся:

query_tags: присоединение тегов key-value к запросам SQL для отслеживания и аналитики. Дополнительные сведения см. в примере тегов запросов.
ansi_mode: управляет режимом соответствия ANSI SQL ('true' или 'false')
timezone: задает часовой пояс сеанса (например, 'UTC', ) 'America/New_York'

Операции

Как описано в Sessions, объекты, возвращаемые методами сессии в IOperation, не полностью заполнены. Связанная операция сервера может по-прежнему выполняться, например ожидание запуска хранилища SQL Databricks, выполнение запроса или получение данных. Класс IOperation скрывает эти сведения от пользователей. Например, такие методы, как fetchAll, fetchChunk и getSchema, ожидают завершения операций, а затем возвращают результаты. Метод IOperation.finished() можно использовать для явного ожидания завершения операций. Эти методы принимают обратный вызов, который периодически вызывается во время ожидания завершения операций. Установка параметра progress в true пытается запросить дополнительные данные хода выполнения с сервера и передать их в этот обратный вызов.

Методы close и cancel можно вызывать в любое время. При вызове они немедленно отменяют IOperation объект; все ожидающие вызовы, такие как fetchAll, fetchChunk, и getSchema, немедленно отменяются, и возвращается ошибка. В некоторых случаях операция сервера, возможно, уже завершена, и cancel метод влияет только на клиента.

Метод fetchAll вызывает fetchChunk внутренним образом и собирает все данные в массив. Хотя это удобно, это может привести к ошибкам памяти при использовании в больших наборах данных. fetchAll Параметры обычно передаются в fetchChunk.

Извлечение блоков данных

Получение блоков данных использует следующий шаблон кода:

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

Метод fetchChunk в справочнике по API обрабатывает данные в небольших порциях для уменьшения потребления памяти. fetchChunk сначала ожидает завершения операций, если они еще не завершены, а затем вызывает обратный вызов во время цикла ожидания, а затем извлекает следующий блок данных.

Можно использовать параметр maxRows для указания требуемого размера блока. Однако возвращаемый фрагмент может иметь другой размер, меньший или даже иногда больший. fetchChunk не пытается внутренне предварительно загружать данные, чтобы разрезать их на запрошенные части. Он отправляет maxRows параметр на сервер и возвращает все, что возвращает сервер. Не путайте этот maxRows параметр с одним из IDBSQLSessionних. maxRows передается в fetchChunk для определения размера каждого блока и не делает ничего другого.

Управление файлами в томах каталога Unity

Драйвер SQL Databricks позволяет записывать локальные файлы в тома каталога 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);
  });

Машинописный текст

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

Машинописный текст

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

Дополнительные примеры см. в папке examples в репозитории databricks/databricks-sql-nodejs на сайте GitHub.

Тестирование

Для тестирования кода можно использовать платформы тестирования JavaScript, такие как Jest. Чтобы протестировать код в имитированных условиях без вызова конечных точек REST API Azure Databricks или изменения состояния учетных записей Или рабочих областей 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();
    // Note: Table names cannot be parameterized; validate tableSpec against allowed values
    queryOperation = await session.executeStatement(`SELECT * FROM ${tableSpec} LIMIT ?`, {
      runAsync: true,
      maxRows: 10000, // This option enables the direct results feature.
      ordinalParameters: [rowCount],
    });
  } catch (error) {
    console.error(error);
    throw error;
  }
  let result;
  try {
    result = await queryOperation.fetchAll();
  } catch (error) {
    console.error(error);
    throw error;
  } finally {
    if (queryOperation) {
      await queryOperation.close();
    }
    if (session) {
      await session.close();
    }
  }
  return result;
}

function printResult(result) {
  console.table(result);
}

module.exports = {
  getDBSQLClientWithPAT,
  getAllColumnsFromTable,
  printResult,
};

И учитывая следующий файл с именем 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(() => {
      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 для Node.js на GitHub
Начало работы с драйвером Databricks SQL для Node.js
Устранение неполадок драйвера Databricks SQL для Node.js

Справочник по API

Классы

Классы

Класс `DBSQLClient`

Основная точка входа для взаимодействия с базой данных.

Методы

`connect`Метод

Открывает подключение к базе данных.

Параметры

Параметры
параметры Тип: `ConnectionOptions` Набор параметров, используемых для подключения к базе данных. Поля `host`, `path`и другие обязательные поля должны быть заполнены. См. раздел Аутентификация. Поле `userAgentEntry` позволяет предоставить User-Agent, чтобы включить в заголовок HTTP-запроса для отслеживания использования. См. раздел "Настройка агента пользователя".

параметры
Тип: ConnectionOptions
Набор параметров, используемых для подключения к базе данных.
Поля host, pathи другие обязательные поля должны быть заполнены. См. раздел Аутентификация.
Поле userAgentEntry позволяет предоставить User-Agent, чтобы включить в заголовок HTTP-запроса для отслеживания использования. См. раздел "Настройка агента пользователя".

Возврат: Promise<IDBSQLClient>

`openSession`Метод

Открывает сеанс между DBSQLClient и базой данных.

Параметры
просьба Тип: `OpenSessionRequest` Набор необязательных параметров для указания начальной схемы и начального каталога Пример: `const session = await client.openSession({ initialCatalog: 'catalog' });`

Возврат: Promise<IDBSQLSession>

`getClient`Метод

Возвращает внутренний объект TCLIService.Client. Необходимо вызвать после подключения DBSQLClient.

Нет параметров

Возвращает TCLIService.Client.

`close`Метод

Закрывает соединение с базой данных и освобождает все связанные ресурсы на сервере. Любые дополнительные вызовы этого клиента будут вызывать ошибку.

Без параметров.

Нет возвращаемого значения.

Класс `DBSQLSession`

DBSQLSessions в основном используются для выполнения инструкций в базе данных, а также для различных операций извлечения метаданных.

Методы

`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` и `schemaNametableName` можно использовать для фильтрации.

Возврат: Promise<IOperation>

`getFunctions`Метод

Возвращает список таблиц.

Параметры
просьба Тип: `FunctionsRequest` Параметры запроса. Поле `functionName` является обязательным.

Возврат: Promise<IOperation>

`getPrimaryKeys`Метод

Возвращает список первичных ключей.

Параметры
просьба Тип: `PrimaryKeysRequest` Параметры запроса. Поля `schemaName` и `tableName` обязательные.

Возврат: Promise<IOperation>

`getCrossReference`Метод

Получает сведения о внешних ключах между двумя таблицами.

Параметры
просьба Тип: `CrossReferenceRequest` Параметры запроса. Для обеих таблиц необходимо указать имя схемы, родителя и каталога.

Возврат: Promise<IOperation>

Класс `DBSQLOperation`

DBSQLOperations создаются DBSQLSessions и могут использоваться для получения результатов инструкций и проверки их выполнения. Данные извлекаются с помощью функций fetchChunk и fetchAll.

Методы

`getId`Метод

Возвращает идентификатор GUID операции.

Без параметров.

Возврат: str

`fetchAll`Метод

Ожидает завершения операции и затем извлекает из неё все строки.

Параметры: нет

Возврат: Promise<Array<object>>

`fetchChunk`Метод

Ожидает завершения операции, а затем извлекает до указанного количества строк из операции.

Параметры

Параметры
параметры Тип: `FetchOptions` Параметры, используемые для получения. В настоящее время единственным вариантом является maxRows, который соответствует максимальному количеству объектов данных, возвращаемых в любом заданном массиве.

параметры
Тип: FetchOptions
Параметры, используемые для получения. В настоящее время единственным вариантом является maxRows, который соответствует максимальному количеству объектов данных, возвращаемых в любом заданном массиве.

Возврат: Promise<Array<object>>

`close`Метод

Закрывает операцию и освобождает все связанные ресурсы. Необходимо выполнить после прекращения использования операции.

Без параметров.

Нет возвращаемого значения.

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2026-01-16

Поделиться через

Драйвер SQL Databricks для Node.js

Требования

Проверка подлинности

Проверка подлинности токена личного доступа Databricks

JavaScript

Машинописный текст

Проверка подлинности пользователей и компьютеров OAuth (U2M)

JavaScript

Машинописный текст

Проверка подлинности для машинного взаимодействия (M2M) по протоколу OAuth

JavaScript

Машинописный текст

Аутентификация по токену Microsoft Entra ID

JavaScript

Машинописный текст

Набор User-Agent

JavaScript

Запрос данных

JavaScript

Машинописный текст

Пример тегов запросов

JavaScript

Машинописный текст

Сеансы

Конфигурация сеанса

Операции

Извлечение блоков данных

Управление файлами в томах каталога Unity

JavaScript

Машинописный текст

Настройка журналирования

JavaScript

Машинописный текст

Тестирование

Дополнительные ресурсы

Справочник по API

Классы

Класс 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`Метод