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

  • Makale

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. Yüklenip yüklenmediğini npm denetlemek için komutunu npm -vçalıştırın. Gerekirse yüklemek npm için npm'yi indirme ve yükleme başlığındakiler gibi yönergeleri izleyebilirsiniz.

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

    npm i @databricks/sql

  • Node.js projenizde TypeScript'i olarak yüklemek ve kullanmak istiyorsanız, aşağıdaki komutları projenizle aynı dizinde çalıştırmak için kullanınnpm:devDependencies

    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.

Kimlik Doğrulaması

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

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

Not

En iyi güvenlik uygulaması olarak, bağlantı değişkeni değerlerini kodunuzla sabit kodla dönüştürmemelisiniz. 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ı

Azure Databricks kişisel erişim belirteci kimlik doğrulamasıyla Node.js için Databricks SQL Sürücüsünü kullanmak için önce aşağıdaki gibi bir Azure Databricks kişisel erişim belirteci oluşturmanız gerekir:

  1. Azure Databricks çalışma alanınızda üst çubukta Azure Databricks kullanıcı adınıza tıklayın ve açılan listeden Ayarlar'ı seçin.
  2. Geliştirici'ye tıklayın.
  3. Erişim belirteçleri'nin yanındaki Yönet'e tıklayın.
  4. Yeni belirteç oluştur'a tıklayın.
  5. (İsteğe bağlı) Gelecekte bu belirteci tanımlamanıza yardımcı olacak bir açıklama girin ve belirtecin varsayılan 90 günlük ömrünü değiştirin. Yaşam süresi olmayan bir belirteç oluşturmak için (önerilmez), Yaşam Süresi (gün) kutusunu boş (boş) bırakın.
  6. Generate (Oluştur) düğmesine tıklayın.
  7. Görüntülenen belirteci güvenli bir konuma kopyalayın ve bitti'ye tıklayın.

Not

Kopyalanan belirteci güvenli bir konuma kaydettiğinizden emin olun. Kopyalanan belirtecinizi başkalarıyla paylaşmayın. Kopyalanan belirteci kaybederseniz, tam olarak aynı belirteci yeniden oluşturamazsınız. Bunun yerine, yeni bir belirteç oluşturmak için bu yordamı yinelemeniz gerekir. Kopyalanan belirteci kaybederseniz veya belirtecin gizliliğinin ihlal edildiğini düşünüyorsanız Databricks, Erişim belirteçleri sayfasındaki belirtecin yanındaki çöp kutusu (İptal Et) simgesine tıklayarak bu belirteci çalışma alanınızdan hemen silmenizi kesinlikle önerir.

Çalışma alanınızda belirteç oluşturamıyor veya kullanamıyorsanız, bunun nedeni çalışma alanı yöneticinizin belirteçleri devre dışı bırakmış olması veya size belirteç oluşturma veya kullanma izni vermemiş olması olabilir. Çalışma alanı yöneticinize veya aşağıdaki konulara bakın:

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_HOSTNAMEdeğerini kümenizin veya SQL ambarınızın Sunucu Ana Bilgisayar Adı değerine ayarlayın.
  • DATABRICKS_HTTP_PATH, kümeniz veya SQL ambarınız için HTTP Yolu değeri olarak ayarlayın.
  • DATABRICKS_TOKEN, Azure Databricks kişisel erişim belirtecine 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_HOSTNAMEdeğerini kümenizin veya SQL ambarınızın Sunucu Ana Bilgisayar Adı değerine ayarlayın.
  • DATABRICKS_HTTP_PATH, kümeniz veya SQL ambarınız için HTTP Yolu değeri olarak 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;

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

  const client = new DBSQLClient();
  const connectOptions = {
    authType:                  "databricks-oauth",
    useDatabricksOAuthInAzure: true,
    host:                      serverHostname,
    path:                      httpPath
  };

  client.connect(connectOptions)
  // ...

TypeScript

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

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

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

  const client: DBSQLClient = new DBSQLClient();
  const connectOptions = {
    authType:                  "databricks-oauth",
    useDatabricksOAuthInAzure: true,
    host:                      serverHostname,
    path:                      httpPath
  };

  client.connect(connectOptions)
  // ...

OAuth makineden makineye (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 dizisi oluşturun.

    Hizmet sorumlusunu ve OAuth gizli dizisini oluşturmak için bkz . OAuth (OAuth M2M) kullanarak hizmet sorumlusuyla Azure Databricks'e erişimin kimliğini doğrulama. Hizmet sorumlusunun UUID veya Uygulama Kimliği değerini ve hizmet sorumlusunun OAuth gizli dizisi için Gizli dizi 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_HOSTNAMEdeğerini kümenizin veya SQL ambarınızın Sunucu Ana Bilgisayar Adı değerine ayarlayın.
  • DATABRICKS_HTTP_PATH, kümeniz veya SQL ambarınız için HTTP Yolu değeri olarak ayarlayın.
  • DATABRICKS_CLIENT_IDdeğerini hizmet sorumlusunun UUID veya Uygulama Kimliği değerine ayarlayın.
  • DATABRICKS_CLIENT_SECRET, hizmet sorumlusunun OAuth gizli dizisi için Gizli dizi 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",
    useDatabricksOAuthInAzure: true,
    host:                      serverHostname,
    path:                      httpPath,
    oauthClientId:             clientId,
    oauthClientSecret:         clientSecret
  };

  client.connect(connectOptions)
  // ...

TypeScript

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

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

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

  const client: DBSQLClient = new DBSQLClient();
  const connectOptions = {
    authType:                  "databricks-oauth",
    useDatabricksOAuthInAzure: true,
    host:                      serverHostname,
    path:                      httpPath,
    oauthClientId:             clientId,
    oauthClientSecret:         clientSecret
  };

  client.connect(connectOptions)
  // ...

Microsoft Entra Id belirteci kimlik doğrulaması

Node.js için Databricks SQL Sürücüsünü Microsoft Entra Id belirteci kimlik doğrulamasıyla kullanmak için Microsoft Entra Id belirteciyle Node.js için Databricks SQL Sürücüsü 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 . Azure CLI kullanarak kullanıcılar için Microsoft Entra ID belirteçlerini alma.
  • Microsoft Entra ID hizmet sorumlusu için bkz . Azure CLI ile Microsoft Entra ID erişim belirteci alma. Microsoft Entra Id yönetilen hizmet sorumlusu oluşturmak için bkz . Hizmet sorumlularını yönetme.

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_HOSTNAMEdeğerini kümenizin veya SQL ambarınızın Sunucu Ana Bilgisayar Adı değerine ayarlayın.
  • DATABRICKS_HTTP_PATH, kümeniz veya SQL ambarınız için HTTP Yolu değeri olarak ayarlayın.
  • DATABRICKS_TOKEN, Microsoft Entra ID belirtecine 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 " +
                    "<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)
  // ...

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 nyctaxi şemasındaki tablodan trips samples 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 ve server_hostname http_path bağlantı değişkeni değerlerini alırtoken. Bu ortam değişkenleri aşağıdaki ortam değişkeni adlarına sahiptir:

  • DATABRICKS_TOKEN, gereksinimlerden 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 2',
      {
        runAsync: true,
        maxRows:  10000 // This option enables the direct results feature.
      }
    );

    const result = await queryOperation.fetchAll();

    await queryOperation.close();

    console.table(result);

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

TypeScript

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

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

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

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

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

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

    const result = await queryOperation.fetchAll();

    await queryOperation.close();

    console.table(result);

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

Çıktı:

┌─────────┬─────┬────────┬───────────┬───────┬─────────┬────────┬───────┬───────┬────────┬────────┬────────┐
│ (index) │ _c0 │ carat  │    cut    │ color │ clarity │ depth  │ table │ price │   x    │   y    │   z    │
├─────────┼─────┼────────┼───────────┼───────┼─────────┼────────┼───────┼───────┼────────┼────────┼────────┤
│    0    │ '1' │ '0.23' │  'Ideal'  │  'E'  │  'SI2'  │ '61.5' │ '55'  │ '326' │ '3.95' │ '3.98' │ '2.43' │
│    1    │ '2' │ '0.21' │ 'Premium' │  'E'  │  'SI1'  │ '59.8' │ '61'  │ '326' │ '3.89' │ '3.84' │ '2.31' │
└─────────┴─────┴────────┴───────────┴───────┴─────────┴────────┴───────┴───────┴────────┴────────┴────────┘

Oturumlar

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

  • Zaman uyumsuz modu başlatacak true ayarrunAsync. 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. ayarı runAsync , false yöntemlerin işlemlerin IDBSQLSession tamamlanmasını beklediği anlamına gelir. Databricks her zaman olarak ayarlanmasını runAsync trueö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 durumunda değil, ara bir durumda döndürür. Ç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.

Operations

Oturumlar'da açıklandığı gibi, IOperation API Başvurusundaki oturum yöntemleri tarafından IDBSQLSession döndürülen nesneler tam olarak doldurulmaz. 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 IOperation.finished() tamamlanmasını açıkça beklemek için 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 bu geri çağırmaya geçirmeye çalışır.

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

yöntemi dahili fetchAll olarak çağırır fetchChunk 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 öbeklerini 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 , fetchChunk her öbek boyutunu tanımlar ve başka bir şey yapmaz.

Unity Kataloğu birimlerindeki 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 konsola yazdırılan bir günlükçü ile oluşturulur, ancak özel bir günlükçü geçirerek bu bilgileri bir dosyaya gönderebilirsiniz. Aşağıdaki örnekte günlükçü yapılandırma ve düzeyini değiştirme gösterilmektedir.

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, Azure Databricks çalışma alanına bağlantı döndürmek için Azure Databricks kişisel erişim belirtecini kullanan bir işlev içeren aşağıdaki dosyahelpers.js, belirtilen tablodan belirtilen sayıda veri satırı almak için bağlantıyı kullanan bir getAllColumnsFromTable işlev (örneğin, trips kataloğun nyctaxi şemasındaki samples tablo) ve veri satırlarının içeriğini yazdırmak için bir printResults işlev verilmiştir:getDBSQLClientWithPAT

// helpers.js

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

async function getDBSQLClientWithPAT(token, serverHostname, httpPath) {
  const client = new DBSQLClient();
  const connectOptions = {
    token: token,
    host: serverHostname,
    path: httpPath
  };
  try {
    return await client.connect(connectOptions);
  } catch (error) {
    console.error(error);
    throw error;
  }
}

async function getAllColumnsFromTable(client, tableSpec, rowCount) {
  let session;
  let queryOperation;
  try {
    session = await client.openSession();
    queryOperation = await session.executeStatement(
      `SELECT * FROM ${tableSpec} LIMIT ${rowCount}`,
      {
        runAsync: true,
        maxRows: 10000 // This option enables the direct results feature.
      }
    );
  } catch (error) {
    console.error(error);
    throw error;
  }
  let result;
  try {
    result = await queryOperation.fetchAll();
  } catch (error) {
    console.error(error);
    throw error;
  } finally {
    if (queryOperation) {
      await queryOperation.close();
    }
    if (session) {
      await session.close();
    }
  }
  return result;
}

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

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

Ve , ve printResults işlevlerini çağıran getAllColumnsFromTablegetDBSQLClientWithPATadlı main.js 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 nesneyle dalga geçer. Test ayrıca şemaya ve gerçek verilerdeki değerlere uyan bazı verilerle dalga geçer. 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().mockImplementation(() => {
      return {
        connect: jest.fn().mockResolvedValue({ mock: 'DBSQLClient'})
      };
    }),
  };
});

test('getDBSQLClientWithPAT returns mocked Promise<DBSQLClient> object', async() => {
  const result = await getDBSQLClientWithPAT(
    token = 'my-token',
    serverHostname = 'mock-server-hostname',
    httpPath = 'mock-http-path'
  );

  expect(result).toEqual({ mock: 'DBSQLClient' });
});

const data = [
  {
    tpep_pickup_datetime: new Date(2016, 1, 13, 15, 51, 12),
    tpep_dropoff_datetime: new Date(2016, 1, 13, 16, 15, 3),
    trip_distance: 4.94,
    fare_amount: 19.0,
    pickup_zip: 10282,
    dropoff_zip: 10171
  },
  {
    tpep_pickup_datetime: new Date(2016, 1, 3, 17, 43, 18),
    tpep_dropoff_datetime: new Date(2016, 1, 3, 17, 45),
    trip_distance: 0.28,
    fare_amount: 3.5,
    pickup_zip: 10110,
    dropoff_zip: 10110
  }
];

const mockDBSQLClientForSession = {
  openSession: jest.fn().mockResolvedValue({
    executeStatement: jest.fn().mockResolvedValue({
      fetchAll: jest.fn().mockResolvedValue(data),
      close: jest.fn().mockResolvedValue(null)
    }),
    close: jest.fn().mockResolvedValue(null)
  })
};

test('getAllColumnsFromTable returns the correct fare_amount for the second mocked data row', async () => {
  const result = await getAllColumnsFromTable(
    client    = mockDBSQLClientForSession,
    tableSpec = 'mock-table-spec',
    rowCount  = 2);
  expect(result[1].fare_amount).toEqual(3.5);
});

global.console.table = jest.fn();

test('printResult mock prints the correct fare_amount for the second mocked data row', () => {
  printResult(data);
  expect(console.table).toHaveBeenCalledWith(data);
  expect(data[1].fare_amount).toBe(3.5);
});

TypeScript için, önceki kod benzer görünür. TypeScript ile Jest testi için ts-jest kullanın.

Ek kaynaklar

API başvurusu

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ı.

Örnek:


const client: DBSQLClient = new DBSQLClient();

client.connect(
{
host: serverHostname,
path: httpPath,
// ...
}
)

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

İç 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 databbase'e karşı deyimlerin yürütülmesi ve çeşitli meta veri getirme işlemleri için kullanılır.

Yöntemler
executeStatement yöntem

Sağlanan seçeneklerle bir deyimi yürütür.

Parametreler
beyanat

Tür: str

Yürütülecek deyim.
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. null olarak ayarlanırsa maxRows , işlem doğrudan sonuçlar özelliği kapalı olarak ç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. schemaName ve alanları catalogName 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 ve ve schemaName
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. ve tableName alanları schemaName 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ütmelerini denetlemek 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, ardından işlemden tüm satırları getirir.

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

Getirmek 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.