Controlador de Databricks SQL para Node.js

Databricks SQL Driver for Node.js es una biblioteca deNode.js que permite usar código JavaScript para ejecutar comandos SQL en recursos de proceso de Azure Databricks.

Requisitos

• Una máquina de desarrollo que ejecute Node.js versión 14 o posterior. Para imprimir la versión instalada de Node.js, ejecute el comando node -v. Para instalar y usar diferentes versiones de Node.js, puede usar herramientas como Node Version Manager (nvm).

• Administrador de paquetes de Node (npm). Las versiones posteriores de Node.js ya incluyen npm. Para comprobar si npm está instalado, ejecute el comando npm -v. Para instalar npm si es necesario, puede seguir instrucciones como las que se indican en Descargar e instalar npm.

• Paquete @databricks/sql de npm. Para instalar el paquete @databricks/sql en el proyecto de Node.js como una dependencia, use npm para ejecutar el siguiente comando desde el mismo directorio que el proyecto:

  npm i @databricks/sql
  

• Si desea instalar y usar TypeScript en el proyecto de Node.js como devDependencies, use npm para ejecutar los siguientes comandos desde el mismo directorio que el proyecto:

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

• Un clúster existente o almacén de datos SQL.

• El nombre del host del servidor y el valor de la ruta de acceso HTTP para el clúster existente o el almacén SQL.

  • Obtenga estos valores para un clúster.
  • Obtenga estos valores para una instancia de SQL Warehouse.

Autenticación

El controlador Databricks SQL para Node.js admite los siguientes tipos de autenticación de Azure Databricks:

• Autenticación de token de acceso personal de Databricks
• Autenticación de tokens de Microsoft Entra ID
• Autenticación de máquina a máquina (M2M) de OAuth
• Autenticación de usuario a máquina (U2M) de OAuth

Databricks SQL Driver for Node.js aún no admite los siguientes tipos de autenticación de Azure Databricks:

• Autenticación con identidades administradas de Azure
• Autenticación con entidades de servicio de Microsoft Entra
• Autenticación con la CLI de Azure

Nota:

Como procedimiento recomendado de seguridad, no debe codificar de forma rígida los valores de variable de conexión en el código. En su lugar, recupere estos valores de variable de conexión de una ubicación segura. Por ejemplo, los fragmentos de código y ejemplos de este artículo usan variables de entorno.

Autenticación de token de acceso personal de Databricks

Para usar databricks SQL Driver for Node.js con autenticación, primero debe crear un token de acceso personal de Azure Databricks. Para más información sobre este paso, consulte Creación de tokens de acceso personal para usuarios del área de trabajo.

Para autenticar el controlador Databricks SQL para Node.js, use el siguiente fragmento de código. En este fragmento, se da por supuesto que ha establecido las siguientes variables de entorno:

• DATABRICKS_SERVER_HOSTNAMEestablecido en el valor de Nombre de host del servidor del clúster o almacén de SQL.
• DATABRICKS_HTTP_PATH, establecido en el valor de Ruta de acceso HTTP del clúster o almacén del SQL.
• DATABRICKS_TOKEN, establecido en el token de acceso personal de Azure Databricks.

Para establecer variables de entorno, consulte la documentación del sistema operativo.

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

Mecanografiado

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

Autenticación de usuario a máquina (U2M) de OAuth

Databricks SQL Driver for Node.js versiones 1.8.0 y posteriores admiten la autenticación de usuario a máquina (U2M) de OAuth.

Para autenticar el controlador SQL de Databricks para Node.js con la autenticación U2M de OAuth, use el siguiente fragmento de código. En este fragmento, se da por supuesto que ha establecido las siguientes variables de entorno:

• DATABRICKS_SERVER_HOSTNAMEestablecido en el valor de Nombre de host del servidor del clúster o almacén de SQL.
• DATABRICKS_HTTP_PATH, establecido en el valor de Ruta de acceso HTTP del clúster o almacén del SQL.

Para establecer variables de entorno, consulte la documentación del sistema operativo.

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

Mecanografiado

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

Autenticación de máquina a máquina (M2M) de OAuth

Databricks SQL Driver for Node.js versiones 1.8.0 y posteriores admiten la autenticación de máquina a máquina (U2M) de OAuth.

Para usar el controlador SQL de Databricks para Node.js con la autenticación de OAuth M2M, debe hacer lo siguiente:

1. Cree una entidad de servicio de Azure Databricks en el área de trabajo de Azure Databricks y cree un secreto de OAuth para esa entidad de servicio.

   Para crear la entidad de servicio y su secreto de OAuth, consulte Autorización del acceso de la entidad de servicio a Azure Databricks con OAuth. Anote el valor UUID o ID de Aplicación de la entidad de servicio y el valor Secreto para el secreto OAuth de la entidad de servicio.

2. Proporcione a la entidad de servicio acceso al clúster o al almacenamiento. Consulte Permisos de proceso o Administración de un almacenamiento de SQL.

Para autenticar el controlador Databricks SQL para Node.js, use el siguiente fragmento de código. En este fragmento, se da por supuesto que ha establecido las siguientes variables de entorno:

• DATABRICKS_SERVER_HOSTNAMEestablecido en el valor de Nombre de host del servidor del clúster o almacén de SQL.
• DATABRICKS_HTTP_PATH, establecido en el valor de Ruta de acceso HTTP del clúster o almacén del SQL.
• DATABRICKS_CLIENT_ID, se establece en el UUID de la entidad de servicio o en el valor ID de Aplicación.
• DATABRICKS_CLIENT_SECRET, configurado al valor secreto para el secreto OAuth del principal de servicio.

Para establecer variables de entorno, consulte la documentación del sistema operativo.

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

Mecanografiado

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

Autenticación de token de Microsoft Entra ID

Para usar el controlador Databricks SQL para Node.js con la autenticación de token de Microsoft Entra ID, debe proporcionar el controlador Databricks SQL para Node.js con el token de Microsoft Entra ID. Para crear un token de acceso de Microsoft Entra ID, haga lo siguiente:

• Para un usuario de Azure Databricks, puede usar la CLI de Azure. Ver Obtener manualmente tokens de ID de Microsoft Entra.
• Para un principal de servicio de Microsoft Entra ID, consulte Obtención de tokens para principales de servicio. Para crear una entidad de servicio administrada de Microsoft Entra ID, consulte Entidades de servicio.

Los tokens de Microsoft Entra ID tienen una duración predeterminada de aproximadamente 1 hora. Para crear un nuevo token de Microsoft Entra ID, repita este proceso.

Para autenticar el controlador Databricks SQL para Node.js, use el siguiente fragmento de código. En este fragmento, se da por supuesto que ha establecido las siguientes variables de entorno:

• DATABRICKS_SERVER_HOSTNAMEestablecido en el valor de Nombre de host del servidor del clúster o almacén de SQL.
• DATABRICKS_HTTP_PATH, establecido en el valor de Ruta de acceso HTTP del clúster o almacén del SQL.
• DATABRICKS_TOKEN, establecido en el token de Microsoft Entra ID.

Para establecer variables de entorno, consulte la documentación del sistema operativo.

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

Mecanografiado

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

Establecer User-Agent

En el ejemplo de código siguiente se muestra cómo establecer la aplicación product_name User-Agent para el seguimiento de uso.

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

Consultar datos

En el ejemplo de código siguiente se muestra cómo llamar al Controlador de Databricks SQL para Node.js para ejecutar una consulta SQL básica en un recurso de proceso de Azure Databricks. Este comando devuelve las dos primeras filas de la trips tabla en el samples esquema del nyctaxi catálogo.

Nota:

En el ejemplos de código siguiente se muestra cómo usar un token de acceso personal de Azure Databricks para la autenticación. Para usar otros tipos de autenticación de Azure Databricks disponibles en su lugar, consulte Autenticación.

En este ejemplo de código se recuperan los valores de variable de conexión token, server_hostname y http_path de un conjunto de variables de entorno de Azure Databricks. Estas variables de entorno tienen los siguientes nombres de variable de entorno:

• DATABRICKS_TOKEN, que representa el token de acceso personal de Azure Databricks de los requisitos.
• DATABRICKS_SERVER_HOSTNAME, que representa el valor nombre de host del servidor de los requisitos.
• DATABRICKS_HTTP_PATH, que representa el valor de ruta de acceso HTTP de los requisitos.

Puede usar otros enfoques para recuperar estos valores de variable de conexión. El uso de variables de entorno es solo un enfoque entre muchos.

En el ejemplo de código siguiente, se muestra cómo llamar a Databricks SQL Connector para Node.js para ejecutar un comando SQL básico en un clúster o un almacenamiento SQL. Este comando devuelve las dos primeras filas de la tabla 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);
  });

Mecanografiado

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

Ejemplo de etiquetas de consulta

Importante

** Esta característica está disponible en versión preliminar privada. Para solicitar acceso, póngase en contacto con el equipo de su cuenta.

Las etiquetas de consulta son pares clave-valor que se pueden adjuntar a consultas SQL con fines analíticos y de seguimiento. Cuando se configura, aparecen en la tabla system.query.history, lo que le permite analizar los patrones de consulta y el uso.

Defina etiquetas de consulta como pares clave-valor separados por comas, donde cada clave y valor están separados por dos puntos, por ejemplo, key1:value1,key2:value2.

En el ejemplo siguiente se muestra cómo usar etiquetas de consulta con configuración de sesión:

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

Mecanografiado

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

Sesiones

Todos los IDBSQLSession métodos que devuelven IOperation objetos en la referencia de API tienen los siguientes parámetros comunes que afectan a su comportamiento:

• Configurando runAsync a true inicia el modo asíncrono. IDBSQLSession métodos colocan las operaciones en la cola y devuelven lo más rápido posible. El estado actual del objeto devuelto IOperation puede variar y el cliente es responsable de comprobar su estado antes de usar el devuelto IOperation. Consulte Operaciones. Configurar runAsync en false significa que los métodos esperan a que IDBSQLSession se completen las operaciones. Databricks recomienda configurar siempre runAsync entrue.
• Si se establece maxRows en un valor distinto de NULL, se habilitan los resultados directos. Con los resultados directos, el servidor intenta esperar a que se completen las operaciones y a continuación, capture una parte de los datos. Dependiendo de cuánto trabajo pudo completar el servidor dentro del tiempo definido, los objetos IOperation devuelven en algún estado intermedio en lugar de en algún estado pendiente. A menudo, todos los metadatos y los resultados de la consulta se devuelven dentro de una sola solicitud al servidor. El servidor usa maxRows para determinar cuántos registros puede devolver inmediatamente. Sin embargo, el fragmento real puede tener un tamaño diferente; consulte IDBSQLSession.fetchChunk. Los resultados directos están habilitados de manera predeterminada. Databricks recomienda deshabilitar los resultados directos.

Configuración de sesión

Puede pasar parámetros de configuración de sesión al abrir una sesión mediante el objeto configuration en el método openSession. Estos parámetros afectan al comportamiento de todas las operaciones dentro de esa sesión.

Entre los parámetros de configuración de sesión comunes se incluyen:

• query_tags: adjunte etiquetas clave-valor a consultas SQL para el seguimiento y el análisis. Para obtener más información, vea Ejemplo de etiquetas de consulta.
• ansi_mode: controla el modo de cumplimiento de ANSI SQL ('true' o 'false')
• timezone: establece la zona horaria de la sesión (por ejemplo, 'UTC', 'America/New_York')

Operaciones

Como se describe en Sesiones, los objetos que los métodos de sesión devuelven en la IOperation no están completamente rellenados. La operación del servidor relacionada podría estar aún en curso, como esperar a que se inicie el almacén SQL de Databricks, ejecutar la consulta o recuperar los datos. La clase IOperation oculta estos detalles de los usuarios. Por ejemplo, los métodos como fetchAll, fetchChunky getSchema esperan internamente para que las operaciones se completen y a continuación, devuelvan resultados. Puede usar el método IOperation.finished() para esperar explícitamente a que se completen las operaciones. Estos métodos toman una devolución de llamada que se llama periódicamente mientras espera a que se completen las operaciones. Establecer la opción progress para true intentar solicitar datos de progreso adicionales desde el servidor y pasarlos a esa devolución de llamada.

Los métodosclose y cancel se pueden llamar en cualquier momento. Cuando se llama, invalidan inmediatamente el objetoIOperation; todas las llamadas pendientes como fetchAll, fetchChunky getSchema, se cancelan inmediatamente y se devuelve un error. En algunos casos, es posible que la operación del servidor ya se haya completado y el método cancel solo afecta al cliente.

El métodofetchAll llama a fetchChunk internamente y recopila todos los datos en una matriz. Aunque esto es conveniente, puede provocar errores de memoria insuficiente cuando se usan en grandes conjuntos de datos. Normalmente, las opciones fetchAll se pasan a fetchChunk.

Capturar fragmentos de datos

La captura de fragmentos de datos usa el siguiente patrón de código:

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

El fetchChunk método de la referencia de API procesa los datos en pequeñas partes para reducir el consumo de memoria. fetchChunk primero espera a que las operaciones se completen si aún no se han completado, llama a una devolución de llamada durante el ciclo de espera y despúes captura el siguiente fragmento de datos.

Puede usar la opción maxRows para especificar el tamaño de fragmento deseado. Sin embargo, el fragmento devuelto puede tener un tamaño diferente, más pequeño o incluso a veces mayor. fetchChunk no intenta capturar previamente los datos internamente, con el fin de segmentarlos en las partes solicitadas. Envía la opción maxRows al servidor y le devuelve lo que el servidor le devuelva. No confunda esta opción maxRows con la de IDBSQLSession. maxRowspasado a fetchChunk define el tamaño de cada fragmento y no hace nada más.

Administrar archivos en volúmenes del catálogo de Unity

El controlador SQL de Databricks permite escribir archivos locales en volúmenes del catálogo de Unity, descargar archivos de volúmenes y eliminar archivos de volúmenes, como se muestra en el ejemplo siguiente:

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

Mecanografiado

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

registro

El registrador proporciona información para depurar problemas con el conector. Se crean instancias de todos los objetos DBSQLClient con un registrador que se imprime en la consola, pero pasando un registrador personalizado, puede enviar esta información a un archivo. En el ejemplo siguiente se muestra cómo configurar un registrador y cambiar su nivel.

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

Mecanografiado

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

Para obtener ejemplos adicionales, consulte la carpeta examples del repositorio databricks/databricks-sql-nodejs en GitHub.

Prueba

Para probar el código, puede usar marcos de prueba de JavaScript como Jest. Para probar el código en condiciones simuladas sin llamar a los puntos de conexión de la API REST de Azure Databricks ni cambiar el estado de las cuentas o áreas de trabajo de Azure Databricks, puede usar los frameworks de simulación integrados de Jest.

Por ejemplo, dado el siguiente archivo denominado helpers.js que contiene una función que usa un getDBSQLClientWithPAT token de acceso personal de Azure Databricks para devolver una conexión a un área de trabajo de Azure Databricks, una getAllColumnsFromTable función que usa la conexión para obtener el número especificado de filas de datos de la tabla especificada (por ejemplo, la trips tabla del samples esquema del nyctaxi catálogo) y una printResults función para imprimir el contenido de las filas de datos:

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

Y dado el siguiente archivo denominado main.js que llama a las funciones getDBSQLClientWithPAT, getAllColumnsFromTable, y 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);
  });

El siguiente archivo denominado helpers.test.js comprueba si la función getAllColumnsFromTable devuelve la respuesta esperada. En lugar de crear una conexión real al área de trabajo de destino, esta prueba simula un objeto DBSQLClient. La prueba también simula algunos datos que se ajustan al esquema y los valores que se encuentran en los datos reales. La prueba devuelve los datos ficticios a través de la conexión simulada y, a continuación, comprueba si uno de los valores de las filas de datos simuladas coincide con el valor esperado.

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

En TypeScript, el código anterior tiene un aspecto similar. Para las pruebas de Jest con TypeScript, use ts-jest.

Recursos adicionales

• Repositorio del controlador SQL de Databricks para Node.js en GitHub
• Introducción al Controlador de Databricks SQL para Node.js
• Solución de problemas del controlador SQL de Databricks para Node.js

Referencia de API

• Clases
  • DBSQLClient clase
    • Métodos
      • connect método
      • openSession método
      • getClient método
      • close método
  • DBSQLSession clase
    • Métodos
      • executeStatement método
      • close método
      • getId método
      • getTypeInfo método
      • getCatalogs método
      • getSchemas método
      • getTables método
      • getFunctions método
      • getPrimaryKeys método
      • getCrossReference método
  • DBSQLOperation clase
    • Métodos
      • getId método
      • fetchAll método
      • fetchChunk método
      • close método

Clases

Clase DBSQLClient

Punto de entrada principal para interactuar con una base de datos.

Métodos

Método connect

Abre una conexión a la base de datos.

Parámetros
Opciones Escriba: ConnectionOptions Conjunto de opciones usadas para conectarse a la base de datos. Los campos host, path y otros obligatorios deben rellenarse. Consulte Autenticación. El campo userAgentEntry permite proporcionar el User-Agent para incluir en el encabezado de solicitud HTTP para el seguimiento del uso. Consulte Set User-Agent (Establecer agente de usuario).

Devuelve: Promise<IDBSQLClient>

Método openSession

Abre la sesión entre DBSQLClient y la base de datos.

Parámetros
pedir Escriba: OpenSessionRequest Conjunto de parámetros opcionales para especificar el esquema y el catálogo iniciales. Ejemplo: const session = await client.openSession({ initialCatalog: 'catalog' });

Devuelve: Promise<IDBSQLSession>

Método getClient

Devuelve el objeto TCLIService.Client interno de Thrift. Se debe llamar después de que DBSQLClient se haya conectado.

Sin parámetros

Devuelve TCLIService.Client

Método close

Cierra la conexión a la base de datos y libera todos los recursos asociados en el servidor. Las llamadas adicionales a esta conexión generarán un error.

No hay parámetros.

No devuelve ningún valor.

Clase DBSQLSession

DBSQLSessions se usa principalmente para la ejecución de instrucciones en la base de datos, así como para varias operaciones de captura de metadatos.

Métodos

Método executeStatement

Ejecuta una instrucción con las opciones proporcionadas.

Parámetros

declaración Escriba: str La instrucción que se va a ejecutar. Opciones Escriba: ExecuteStatementOptions Conjunto de parámetros opcionales para determinar el tiempo de espera de la consulta, el número máximo de filas para los resultados directos y si se va a ejecutar la consulta de forma asincrónica. De forma predeterminada, maxRows se estable en 10000. Si maxRows se establece en null, la operación se ejecutará con la característica de resultados directos desactivada. Ejemplo: const session = await client.openSession({ initialCatalog: 'catalog' }); `` queryOperation = await session.executeStatement('SELECT "Hello, World!"', { runAsync: true });

Devuelve: Promise<IOperation>

Método close

Cierra la sesión. Debe realizarse después de usar la sesión.

No hay parámetros.

No devuelve ningún valor.

Método getId

Devuelve el GUID de la sesión.

No hay parámetros.

Devuelve: str

Método getTypeInfo

Devuelve información sobre los tipos de datos admitidos.

Parámetros
pedir Escriba: TypeInfoRequest Parámetros de solicitud.

Devuelve: Promise<IOperation>

Método getCatalogs

Obtiene la lista de catálogos.

Parámetros
pedir Escriba: CatalogsRequest Parámetros de solicitud.

Devuelve: Promise<IOperation>

Método getSchemas

Obtiene la lista de esquemas.

Parámetros
pedir Escriba: SchemasRequest Parámetros de solicitud. Los campos catalogName y schemaName se pueden usar para el filtrado.

Devuelve: Promise<IOperation>

Método getTables

Obtiene la lista de tablas.

Parámetros
pedir Escriba: TablesRequest Parámetros de solicitud. Campos catalogName y y schemaNametableName se pueden usar para filtrar.

Devuelve: Promise<IOperation>

Método getFunctions

Obtiene la lista de tablas.

Parámetros
pedir Escriba: FunctionsRequest Parámetros de solicitud. El campo functionName es obligatorio.

Devuelve: Promise<IOperation>

Método getPrimaryKeys

Obtiene la lista de claves principales.

Parámetros
pedir Escriba: PrimaryKeysRequest Parámetros de solicitud. Los campos schemaName y tableName son obligatorios.

Devuelve: Promise<IOperation>

Método getCrossReference

Obtiene información sobre las claves externas entre dos tablas.

Parámetros
pedir Escriba: CrossReferenceRequest Parámetros de solicitud. El esquema, el elemento principal y el nombre del catálogo deben especificarse para ambas tablas.

Devuelve: Promise<IOperation>

Clase DBSQLOperation

DBSQLOperations se crea mediante DBSQLSessions y se puede usar para capturar los resultados de las instrucciones y comprobar su ejecución. Los datos se capturan a través de las funciones fetchChunk y fetchAll.

Métodos

Método getId

Devuelve el GUID de la operación.

No hay parámetros.

Devuelve: str

Método fetchAll

Espera a que finalice la operación y, luego, captura todas las filas de la operación.

Parámetros: None

Devuelve: Promise<Array<object>>

Método fetchChunk

Espera a que finalice la operación y, luego, captura hasta un número especificado de filas de una operación.

Parámetros
Opciones Escriba: FetchOptions Opciones usadas para la captura. Actualmente, la única opción es maxRows, que corresponde al número máximo de objetos de datos que se van a devolver en cualquier matriz determinada.

Devuelve: Promise<Array<object>>

Método close

Cierra la operación y libera todos los recursos asociados. Debe realizarse después de dejar de usar la operación.

No hay parámetros.

No devuelve ningún valor.