Node.js için Databricks SQL Sürücüsü

Node.js için Databricks SQL Sürücüsü, Azure Databricks işlem kaynaklarında SQL komutlarını çalıştırmak için JavaScript kodu kullanmanıza olanak tanıyan bir Node.js kitaplığıdır.

Gereksinimler

• Node.js, sürüm 14 veya üzerini çalıştıran bir geliştirme makinesi. Node.js yüklü sürümünü yazdırmak için komutunu node -vçalıştırın. farklı Node.js sürümlerini yüklemek ve kullanmak için Node Version Manager (nvm) gibi araçları kullanabilirsiniz.

• Düğüm Paket Yöneticisi (npm). Node.js'ın sonraki sürümleri zaten içerir npm. npm'ın yüklenip yüklenmediğini kontrol etmek için npm -v komutunu çalıştırın. Gerekirse npm öğesini yüklemek için npm indirme ve yükleme yönergeleri gibi talimatları izleyebilirsiniz.

• npm'den @databricks/sql paketi. Node.js projenize @databricks/sql paketini bağımlılık olarak yüklemek için, projenizle aynı dizinde aşağıdaki komutu çalıştırmak üzere npm kullanın:

  npm i @databricks/sql
  

• Node.js projenizde TypeScript'i yüklemek ve kullanmak istiyorsanız, olarak projenizin bulunduğu dizinden şu komutları çalıştırmak için devDependencies kullanın:

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

• Mevcut bir küme veya SQL ambarı.

• Mevcut küme veya SQL ambarı için Sunucu Ana Bilgisayar Adı ve HTTP Yolu değeri.

  • Küme için bu değerleri alın.
  • BIR SQL ambarı için bu değerleri alın.

Kimlik Doğrulaması

Node.js için Databricks SQL Sürücüsü aşağıdaki Azure Databricks kimlik doğrulama türlerini destekler:

• Databricks kişisel erişim belirteci kimlik doğrulaması
• Microsoft Entra Id belirteci kimlik doğrulaması
• OAuth makineden makineye (M2M) kimlik doğrulaması
• OAuth kullanıcıdan makineye (U2M) kimlik doğrulaması

Node.js için Databricks SQL Sürücüsü henüz aşağıdaki Azure Databricks kimlik doğrulama türlerini desteklemez:

• Azure yönetilen kimlikleriyle kimlik doğrulayın
• Microsoft Entra hizmet sorumlularıyla kimlik doğrulaması
• Azure CLI ile kimlik doğrulaması

Not

En iyi güvenlik uygulaması olarak, bağlantı değişkeni değerlerini kodunuza sabit kodlama yapmamalısınız. Bunun yerine, bu bağlantı değişkeni değerlerini güvenli bir konumdan almanız gerekir. Örneğin, bu makaledeki kod parçacıkları ve örnekler ortam değişkenlerini kullanır.

Databricks kişisel erişim belirteci kimlik doğrulaması

Kimlik doğrulamasıyla Node.js için Databricks SQL Sürücüsünü kullanmak için önce bir Azure Databricks kişisel erişim belirteci oluşturmanız gerekir. Bu adımla ilgili ayrıntılar için bkz. Çalışma alanı kullanıcıları için kişisel erişim belirteçleri oluşturma.

Node.js için Databricks SQL Sürücüsünün kimliğini doğrulamak için aşağıdaki kod parçacığını kullanın. Bu kod parçacığı, aşağıdaki ortam değişkenlerini ayarladığınızı varsayar:

• DATABRICKS_SERVER_HOSTNAMEkümeniz veya SQL ambarınız için Sunucu Host Adı değerine ayarlanır.
• DATABRICKS_HTTP_PATH, kümeniz veya SQL ambarınız için HTTP Yolu değerine ayarlanmıştır.
• DATABRICKS_TOKEN, Azure Databricks kişisel erişim belirteci olacak şekilde ayarlayın.

Ortam değişkenlerini ayarlamak için işletim sisteminizin belgelerine bakın.

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 kullanıcıdan makineye (U2M) kimlik doğrulaması

Node.js sürüm 1.8.0 ve üzeri için Databricks SQL Sürücüsü, OAuth kullanıcıdan makineye (U2M) kimlik doğrulamasını destekler.

OAuth U2M kimlik doğrulamasıyla Node.js için Databricks SQL Sürücüsünün kimliğini doğrulamak için aşağıdaki kod parçacığını kullanın. Bu kod parçacığı, aşağıdaki ortam değişkenlerini ayarladığınızı varsayar:

• DATABRICKS_SERVER_HOSTNAMEkümeniz veya SQL ambarınız için Sunucu Host Adı değerine ayarlanır.
• DATABRICKS_HTTP_PATH, kümeniz veya SQL ambarınız için HTTP Yolu değerine ayarlanmıştır.

Ortam değişkenlerini ayarlamak için işletim sisteminizin belgelerine bakın.

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

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

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

OAuth makineler arası (M2M) kimlik doğrulaması

Node.js sürüm 1.8.0 ve üzeri için Databricks SQL Sürücüsü, OAuth makineden makineye (U2M) kimlik doğrulamasını destekler.

OAuth M2M kimlik doğrulamasıyla Node.js için Databricks SQL Sürücüsünü kullanmak için aşağıdakileri yapmanız gerekir:

1. Azure Databricks çalışma alanınızda bir Azure Databricks hizmet sorumlusu oluşturun ve bu hizmet sorumlusu için bir OAuth gizli anahtarı oluşturun.

   Hizmet sorumlusunu ve OAuth gizli dizisini oluşturmak için bkz. OAuth ile Azure Databricks'e hizmet sorumlusu erişimi yetkilendirme. Hizmet prensibinin UUID veya Uygulama Kimliği değerini ve hizmet prensibinin OAuth gizli anahtarı için Gizli Anahtar değerini not edin.

2. Hizmet sorumlusuna kümenize veya ambarınıza erişim verin. Bkz. İşlem izinleri veya SQL ambarı yönetme.

Node.js için Databricks SQL Sürücüsünün kimliğini doğrulamak için aşağıdaki kod parçacığını kullanın. Bu kod parçacığı, aşağıdaki ortam değişkenlerini ayarladığınızı varsayar:

• DATABRICKS_SERVER_HOSTNAMEkümeniz veya SQL ambarınız için Sunucu Host Adı değerine ayarlanır.
• DATABRICKS_HTTP_PATH, kümeniz veya SQL ambarınız için HTTP Yolu değerine ayarlanmıştır.
• DATABRICKS_CLIENT_IDdeğerini hizmet sorumlusunun UUID veya Uygulama Kimliği değerine ayarlayın.
• DATABRICKS_CLIENT_SECRET, hizmet principal'inin OAuth gizli anahtarı için Gizli değerine ayarlayın.

Ortam değişkenlerini ayarlamak için işletim sisteminizin belgelerine bakın.

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

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

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

Microsoft Entra ID Belirteci Kimlik Doğrulaması

Node.js için Databricks SQL Sürücüsünü, Microsoft Entra ID belirteci kimlik doğrulamasıyla kullanabilmek için, Microsoft Entra ID belirtecini Node.js için Databricks SQL Sürücüsüne sağlamanız gerekir. Microsoft Entra ID erişim belirteci oluşturmak için aşağıdakileri yapın:

• Azure Databricks kullanıcısı için Azure CLI'yı kullanabilirsiniz. Bkz. Microsoft Entra Id belirteçlerini el ile alma.
• Microsoft Entra ID hizmet sorumlusu için bkz. Hizmet sorumluları için belirteçleri alma. Microsoft Entra ID yönetilen bir hizmet ilkesi oluşturmak için bkz. Hizmet ilkeleri.

Microsoft Entra Id belirteçlerinin varsayılan ömrü yaklaşık 1 saattir. Yeni bir Microsoft Entra Id belirteci oluşturmak için bu işlemi yineleyin.

Node.js için Databricks SQL Sürücüsünün kimliğini doğrulamak için aşağıdaki kod parçacığını kullanın. Bu kod parçacığı, aşağıdaki ortam değişkenlerini ayarladığınızı varsayar:

• DATABRICKS_SERVER_HOSTNAMEkümeniz veya SQL ambarınız için Sunucu Host Adı değerine ayarlanır.
• DATABRICKS_HTTP_PATH, kümeniz veya SQL ambarınız için HTTP Yolu değerine ayarlanmıştır.
• DATABRICKS_TOKEN, Microsoft Entra ID belirtecine ayarlanacak.

Ortam değişkenlerini ayarlamak için işletim sisteminizin belgelerine bakın.

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

User-Agent Ayarla

Aşağıdaki kod örneğinde, kullanım izleme için User-Agent uygulama product_name nasıl ayarlanacağı gösterilmektedir.

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

Verileri sorgulama

Aşağıdaki kod örneği, Azure Databricks işlem kaynağında temel bir SQL sorgusu çalıştırmak üzere Node.js için Databricks SQL Sürücüsünün nasıl çağrılduğunu gösterir. Bu komut, kataloğun trips şemasındaki tablodan samplesnyctaxi ilk iki satırı döndürür.

Not

Aşağıdaki kod örneği, kimlik doğrulaması için Azure Databricks kişisel erişim belirtecinin nasıl kullanılacağını gösterir. Bunun yerine diğer kullanılabilir Azure Databricks kimlik doğrulama türlerini kullanmak için bkz . Kimlik doğrulaması.

Bu kod örneği, bir dizi Azure Databricks ortam değişkeninden token, server_hostname ve http_path bağlantı değişkeni değerlerini alır. Bu ortam değişkenleri aşağıdaki ortam değişkeni adlarına sahiptir:

• DATABRICKS_TOKEN, gereksinimlerde belirtilen Azure Databricks kişisel erişim belirtecinizi temsil eder.
• DATABRICKS_SERVER_HOSTNAME, gereksinimlerden Sunucu Ana Bilgisayar Adı değerini temsil eder.
• DATABRICKS_HTTP_PATH, gereksinimlerden HTTP Yolu değerini temsil eder.

Bu bağlantı değişkeni değerlerini almak için diğer yaklaşımları kullanabilirsiniz. Ortam değişkenlerini kullanmak, birçok yaklaşım arasında yalnızca bir yaklaşımdır.

Aşağıdaki kod örneği, Node.js için Databricks SQL Bağlayıcısı'nı çağırarak bir kümede veya SQL ambarı üzerinde temel bir SQL komutunu çalıştırmayı gösterir. Bu komut, tablodan ilk iki satırı trips döndürür.

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

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

Sorgu etiketleri örneği

Önemli

Bu özellik, Özel Önizleme sürümündedir. Erişim istemek için hesap ekibinize başvurun.

Sorgu etiketleri, izleme ve analiz amacıyla SQL sorgularına eklenebilen anahtar-değer çiftleridir. Ayarlandığında, system.query.history tabloda görüntülenir ve böylece sorgu desenlerini ve kullanımını analiz edebilirsiniz.

Sorgu etiketlerini virgülle ayrılmış anahtar-değer çiftleri olarak tanımlayın; burada her anahtar ve değer iki nokta üst üste ile ayrılır; örneğin, key1:value1,key2:value2.

Aşağıdaki örnekte sorgu etiketlerinin oturum yapılandırmasıyla nasıl kullanılacağı gösterilmektedir:

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

TypeScript

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

Oturumlar

API Başvurusu'ndaki nesneleri döndüren IDBSQLSession tüm IOperation yöntemlerin davranışları etkileyen aşağıdaki ortak parametreleri vardır:

• runAsync ayarını true olarak ayarlamak eşzamansız modu başlatır. IDBSQLSession yöntemleri, işlemleri kuyruğa koyar ve mümkün olan en kısa sürede döndürür. Döndürülen IOperation nesnenin geçerli durumu farklılık gösterebilir ve istemci, döndürülen IOperationöğesini kullanmadan önce durumunu denetlemekle sorumludur. Bkz. İşlemler. runAsync ayarının false yapılması, IDBSQLSession yöntemlerin işlemlerin tamamlanmasını beklediği anlamına gelir. Databricks, runAsync her zaman true olarak ayarlanmasını önerir.
• Null olmayan bir değere ayar yapmak maxRows doğrudan sonuçları etkinleştirir. Doğrudan sonuçlarla, sunucu işlemlerin tamamlanmasını beklemeye çalışır ve ardından verilerin bir bölümünü getirir. Sunucunun tanımlanan süre içinde ne kadar işi tamamlayabildiğine bağlı olarak, IOperation nesneler bekleme konumunda değil, ara durumda geri döner. Çoğu zaman tüm meta veriler ve sorgu sonuçları sunucuya tek bir istek içinde döndürülür. Sunucu, hemen kaç kayıt döndürebileceğini belirlemek için kullanır maxRows . Ancak, gerçek öbek farklı bir boyutta olabilir; bkz IDBSQLSession.fetchChunk. . Doğrudan sonuçlar varsayılan olarak etkinleştirilir. Databricks, doğrudan sonuçları devre dışı bırakmamanızı önerir.

Oturum yapılandırması

yöntemindeki configuration nesnesini kullanarak openSession bir oturumu açarken oturum yapılandırma parametrelerini geçirebilirsiniz. Bu parametreler, bu oturumdaki tüm işlemlerin davranışını etkiler.

Yaygın oturum yapılandırma parametreleri şunlardır:

• query_tags: İzleme ve analiz için SQL sorgularına anahtar-değer etiketleri ekleyin. Daha fazla bilgi için bkz. Sorgu etiketleri örneği.
• ansi_mode: ANSI SQL uyumluluk modunu ('true' veya 'false') denetler
• timezone: Oturum saat dilimini ayarlar (örneğin, 'UTC', 'America/New_York')

Operasyonlar

Oturumlar'da açıklandığı gibi, oturum yöntemleri tarafından API Referansı'nda döndürülen IOperation nesneler tam olarak doldurulmamıştır. Databricks SQL ambarını başlatmayı bekleme, sorguyu çalıştırma veya verileri getirme gibi ilgili sunucu işlemi devam ediyor olabilir. sınıfı bu IOperation ayrıntıları kullanıcılardan gizler. Örneğin , ve gibi fetchAllfetchChunkgetSchema yöntemler, işlemlerin tamamlanmasını ve ardından sonuçların döndürülmesini dahili olarak bekler. İşlemlerin tamamlanmasını açıkça beklemek için bu IOperation.finished() yöntemini kullanabilirsiniz. Bu yöntemler, işlemlerin tamamlanmasını beklerken düzenli aralıklarla çağrılan bir geri çağırma alır. progress seçeneğinin true ayarlanması, sunucudan ek ilerleme verileri istemeye ve geri çağırma fonksiyonuna aktarmayı dener.

close ve cancel yöntemleri istediğiniz zaman çağrılabilir. Çağrıldığında, IOperation nesnesini hemen geçersiz kılar; fetchAll, fetchChunk ve getSchema gibi bekleyen tüm çağrılar hemen iptal edilir ve bir hata mesajı döndürülür. Bazı durumlarda sunucu işlemi zaten tamamlanmış olabilir ve cancel yöntem yalnızca istemciyi etkiler.

Yöntem fetchAll'yi dahili olarak çağırır ve tüm verileri bir dizide toplar. Bu kullanışlı olsa da, büyük veri kümelerinde kullanıldığında bellek yetersiz hatalarına neden olabilir. fetchAll seçenekleri genellikle öğesine fetchChunkgeçirilir.

Veri parçalarını getirme

Veri öbekleri getirilirken aşağıdaki kod deseni kullanılır:

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

fetchChunk API Başvurusu'ndaki yöntemi, bellek tüketimini azaltmak için verileri küçük bölümlerde işler. fetchChunk önce henüz tamamlanmamışsa işlemlerin tamamlanmasını bekler, ardından bekleme döngüsü sırasında bir geri çağırma çağırır ve sonraki veri öbeklerini getirir.

İstediğiniz öbek boyutunu belirtmek için seçeneğini kullanabilirsiniz maxRows . Ancak, döndürülen öbek farklı bir boyuta sahip olabilir, daha küçük, hatta bazen daha büyük olabilir. fetchChunk verileri istenen bölümlere bölmek için dahili olarak önceden işlemeye çalışmaz. Ardından sunucusuna maxRows seçeneğini gönderir ve sunucunun döndürdüğü her şeyi döndürür. Bu maxRows seçeneği içindekiyle IDBSQLSessionkarıştırmayın. maxRows ve fetchChunk her öbek boyutunu tanımlar ve başka bir işlevi yoktur.

Unity Kataloğu birimlerinde dosyaları yönetme

Databricks SQL Sürücüsü, aşağıdaki örnekte gösterildiği gibi Unity Kataloğu birimlerine yerel dosyalar yazmanızı, birimlerden dosya indirmenizi ve birimlerden dosya silmenizi sağlar:

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

Günlük kaydetmeyi yapılandırma

Günlükçü, bağlayıcıyla ilgili hata ayıklama sorunları için bilgi sağlar. Tüm DBSQLClient nesneler, bilgileri konsola yazdıran bir kayıt sistemi ile başlatılır, ancak özel bir kayıt sistemi geçirerek bu bilgileri bir dosyaya gönderebilirsiniz. Aşağıdaki örnek, bir kayıt aygıtının nasıl yapılandırılacağını ve düzeyinin nasıl değiştirileceğini göstermektedir.

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

Ek örnekler için GitHub'daki databricks/databricks-sql-nodejs deposundaki örnekler klasörüne bakın.

Test Etme

Kodunuzu test etmek için Jest gibi JavaScript test çerçevelerini kullanabilirsiniz. Azure Databricks REST API uç noktalarını çağırmadan veya Azure Databricks hesaplarınızın veya çalışma alanlarınızın durumunu değiştirmeden kodunuzu sanal koşullar altında test etmek için Jest'in yerleşik sahte çerçevelerini kullanabilirsiniz.

Örneğin, helpers.js adlı aşağıdaki dosya verildiğinde, bir Azure Databricks çalışma alanına bir bağlantı döndürmek için Azure Databricks kişisel erişim belirtecini kullanan bir getDBSQLClientWithPAT işlev, belirtilen tablodan belirtilen sayıda veri satırı almak için bu bağlantıyı kullanan bir getAllColumnsFromTable işlev (örneğin, trips tablosu,samples şeması içinde nyctaxi katalogda) ve veri satırlarının içeriğini yazdırmak için bir printResults işlev içerir:

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

Ve main.js adlı ve getDBSQLClientWithPAT, getAllColumnsFromTable, ve printResults işlevlerini çağıran aşağıdaki dosya göz önünde bulundurulduğunda:

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

Adlı aşağıdaki dosya helpers.test.js , işlevin getAllColumnsFromTable beklenen yanıtı döndürip döndürmediğini sınar. Bu test, hedef çalışma alanına gerçek bir bağlantı oluşturmak yerine bir DBSQLClient nesnesini taklit eder. Test ayrıca şemaya ve gerçek verilerdeki değerlere uyan bazı verileri taklit eder. Test, sahte bağlantı üzerinden sahte verileri döndürür ve ardından sahte veri satırlarından birinin değerlerinin beklenen değerle eşleşip eşleşmediğini denetler.

// 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 için, önceki kod benzer görünür. TypeScript ile Jest testi için ts-jest kullanın.

Ek kaynaklar

• GitHub'daki Node.js deposu için Databricks SQL Sürücüsü
• Node.js için Databricks SQL Sürücüsü ile çalışmaya başlama
• Node.js için Databricks SQL Sürücüsü sorunlarını giderme

API referansı

• Sınıflar
  • DBSQLClient sınıf
    • Yöntemler
      • connect yöntem
      • openSession yöntem
      • getClient yöntem
      • close yöntem
  • DBSQLSession sınıf
    • Yöntemler
      • executeStatement yöntem
      • close yöntem
      • getId yöntem
      • getTypeInfo yöntem
      • getCatalogs yöntem
      • getSchemas yöntem
      • getTables yöntem
      • getFunctions yöntem
      • getPrimaryKeys yöntem
      • getCrossReference yöntem
  • DBSQLOperation sınıf
    • Yöntemler
      • getId yöntem
      • fetchAll yöntem
      • fetchChunk yöntem
      • close yöntem

Sınıflar

DBSQLClient sınıfı

Veritabanıyla etkileşime girmek için ana giriş noktası.

Yöntemler

connect yöntem

Veritabanına bir bağlantı açar.

Parametreler
Seçenekler Tür: ConnectionOptions Veritabanına bağlanmak için kullanılan seçenekler kümesi. host, pathve diğer gerekli alanlar doldurulmalıdır. Bkz. Kimlik doğrulaması. userAgentEntry alanı, kullanım izleme için User-Agent’ı HTTP istek üst bilgisine eklemenize olanak tanır. Bkz. Kullanıcı Aracıyı Ayarlama.

Dönüşler: Promise<IDBSQLClient>

openSession yöntem

DBSQLClient ile veritabanı arasındaki oturumu açar.

Parametreler
istek Tür: OpenSessionRequest İlk şemayı ve ilk kataloğu belirtmek için isteğe bağlı parametreler kümesi Örnek: const session = await client.openSession({ initialCatalog: 'catalog' });

Dönüşler: Promise<IDBSQLSession>

getClient yöntem

İçsel thrift TCLIService.Client nesnesini döndürür. DBSQLClient bağlandıktan sonra çağrılmalıdır.

Parametre yok

Döndürür TCLIService.Client

close yöntem

Veritabanı bağlantısını kapatır ve ilişkili tüm kaynakları sunucuda serbest bırakır. Bu istemciye yapılan ek çağrılar hata oluşturur.

Parametre yoktur.

Dönüş değeri yok.

DBSQLSession sınıfı

DBSQLSessions öncelikle veritabanına karşı ifadelerin yürütülmesi ve çeşitli meta veri getirme işlemleri için kullanılır.

Yöntemler

executeStatement yöntem

Verilen seçeneklerle bir ifadeyi yürütür.

Parametreler

beyanat Tür: str Yürütülecek komut. Seçenekler Tür: ExecuteStatementOptions Sorgu zaman aşımını belirlemek için isteğe bağlı parametreler kümesi, doğrudan sonuçlar için en fazla satır sayısı ve sorgunun zaman uyumsuz olarak çalıştırılıp çalıştırılmayacağı. Varsayılan olarak maxRows 10000 olarak ayarlanır. maxRows null olarak ayarlandığında, işlem doğrudan sonuçlar özelliği kapalı şekilde çalıştırılır. Örnek: const session = await client.openSession({ initialCatalog: 'catalog' }); `` queryOperation = await session.executeStatement('SELECT "Hello, World!"', { runAsync: true });

Dönüşler: Promise<IOperation>

close yöntem

Oturumu kapatır. Oturum kullanıldıktan sonra yapılmalıdır.

Parametre yoktur.

Dönüş değeri yok.

getId yöntem

Oturumun GUID değerini döndürür.

Parametre yoktur.

Dönüşler: str

getTypeInfo yöntem

Desteklenen veri türleri hakkında bilgi döndürür.

Parametreler
istek Tür: TypeInfoRequest İstek parametreleri.

Dönüşler: Promise<IOperation>

getCatalogs yöntem

Katalog listesini alır.

Parametreler
istek Tür: CatalogsRequest İstek parametreleri.

Dönüşler: Promise<IOperation>

getSchemas yöntem

Şemaların listesini alır.

Parametreler
istek Tür: SchemasRequest İstek parametreleri. catalogName ve schemaName alanları filtreleme amacıyla kullanılabilir.

Dönüşler: Promise<IOperation>

getTables yöntem

Tabloların listesini alır.

Parametreler
istek Tür: TablesRequest İstek parametreleri. Alanlar catalogName, schemaName ve tableName filtreleme için kullanılabilir.

Dönüşler: Promise<IOperation>

getFunctions yöntem

Tabloların listesini alır.

Parametreler
istek Tür: FunctionsRequest İstek parametreleri. Alan functionName gereklidir.

Dönüşler: Promise<IOperation>

getPrimaryKeys yöntem

Birincil anahtarların listesini alır.

Parametreler
istek Tür: PrimaryKeysRequest İstek parametreleri. Alanlar schemaName ve tableName gereklidir.

Dönüşler: Promise<IOperation>

getCrossReference yöntem

İki tablo arasındaki yabancı anahtarlar hakkında bilgi alır.

Parametreler
istek Tür: CrossReferenceRequest İstek parametreleri. Her iki tablo için de Şema, Üst ve Katalog adı belirtilmelidir.

Dönüşler: Promise<IOperation>

DBSQLOperation sınıfı

DBSQLOperations, DBSQLSessions tarafından oluşturulur ve deyimlerin sonuçlarını getirmek ve yürütümünü kontrol etmek için kullanılabilir. Veriler fetchChunk ve fetchAll işlevleri aracılığıyla getirilir.

Yöntemler

getId yöntem

İşlemin GUID değerini döndürür.

Parametre yoktur.

Dönüşler: str

fetchAll yöntem

İşlemin tamamlanmasını bekler ve ardından işlemden tüm satırları alır.

Parametreler: Yok

Dönüşler: Promise<Array<object>>

fetchChunk yöntem

İşlemin tamamlanmasını bekler, ardından bir işlemden belirtilen sayıda satır getirir.

Parametreler
Seçenekler Tür: FetchOptions Getirme için kullanılan seçenekler. Şu anda tek seçenek, herhangi bir dizide döndürülecek en fazla veri nesnesi sayısına karşılık gelen maxRows'tır.

Dönüşler: Promise<Array<object>>

close yöntem

İşlemi kapatır ve ilişkili tüm kaynakları serbest bırakır. artık işlem kullanılmadıktan sonra yapılmalıdır.

Parametre yoktur.

Dönüş değeri yok.