Menyambungkan Python dan pyodbc ke Azure Databricks

Anda dapat terhubung dari kode Python lokal Anda melalui ODBC ke data di kluster Azure Databricks atau gudang SQL. Untuk melakukan ini, Anda dapat menggunakan modul pyodbc kode Python sumber terbuka.

Ikuti petunjuk berikut untuk menginstal, mengonfigurasi, dan menggunakan pyodbc.

Untuk informasi selengkapnya tentang pyodbc, lihat Wiki pyodbc.

Persyaratan

• Komputer pengembangan lokal yang menjalankan salah satu hal berikut:
  • macOS
  • Windows
  • Distribusi Unix atau Linux yang mendukung file .rpm atau .deb
• pip.
• Untuk Unix, Linux, atau macOS, Homebrew.
• Kluster Azure Databricks, gudang SQL Databricks, ataupun keduanya. Untuk informasi selengkapnya, lihat Referensi konfigurasi komputasi dan Menyambungkan ke gudang SQL.

Langkah 1: Mengunduh, menginstal, dan mengonfigurasi perangkat lunak

Pada langkah ini, Anda mengunduh dan menginstal driver Databricks ODBC, paket unixodbc, dan modul pyodbc. (Modul pyodbc ini memerlukan unixodbc paket di Unix, Linux, dan macOS.) Anda juga mengonfigurasi Nama Sumber Data (DSN) ODBC untuk mengautentikasi dengan dan menyambungkan ke kluster atau gudang SQL Anda.

1. Unduh dan instal driver Databricks ODBC dan konfigurasikan ODBC DSN untuk sistem operasi Anda.
2. Untuk Unix, Linux, dan macOS, instal unixodbc paket: dari terminal, gunakan Homebrew untuk menjalankan perintah brew install unixodbc. Untuk informasi lebih lanjut, lihat unixodbc di situs web Homebrew.
3. pyodbc Instal modul: dari terminal atau prompt perintah, gunakan pip untuk menjalankan perintah pip install pyodbc. Untuk informasi lebih lanjut, lihat pyodbc di situs web PyPI dan Instal di Wiki pyodbc.

Langkah 2: Uji konfigurasi Anda

Dalam langkah ini, Anda menulis dan menjalankan kode Python untuk menggunakan kluster Azure Databricks atau gudang Databricks SQL Anda untuk mengkueri tabel trips dalam skema nyctrips katalog samples dan menampilkan hasilnya.

1. Buat file bernama pyodbc-demo.py dengan konten berikut. Ganti dengan nama ODBC DSN yang Anda buat sebelumnya, simpan file, lalu jalankan <dsn-name> file dengan interpreter Python Anda.

   import pyodbc
   
   # Connect to the Databricks cluster by using the
   # Data Source Name (DSN) that you created earlier.
   conn = pyodbc.connect("DSN=<dsn-name>", autocommit=True)
   
   # Run a SQL query by using the preceding connection.
   cursor = conn.cursor()
   cursor.execute(f"SELECT * FROM samples.nyctaxi.trips")
   
   # Print the rows retrieved from the query.
   for row in cursor.fetchall():
     print(row)
   

2. Untuk mempercepat menjalankan kode, mulai kluster yang sesuai dengan HTTPPath pengaturan di DSN Anda.

3. Jalankan file pyodbc-demo.py dengan interpreter Python Anda. Informasi tentang baris tabel akan ditampilkan.

Langkah berikutnya

• Untuk menjalankan kode pengujian Python terhadap kluster atau gudang SQL yang berbeda, buat DSN yang berbeda dan ubah <dsn-name> ke nama DSN.
• Untuk menjalankan kode uji Python dengan kueri SQL yang berbeda, ubah string perintah execute.

Menggunakan koneksi DSN-less

Sebagai alternatif untuk menggunakan nama DSN, Anda dapat menentukan pengaturan koneksi sebaris. Contoh berikut menunjukkan cara menggunakan string koneksi tanpa DSN untuk autentikasi token akses pribadi Azure Databricks. Contoh ini mengasumsikan bahwa Anda memiliki variabel lingkungan berikut:

• Atur DATABRICKS_SERVER_HOSTNAME ke nama instans ruang kerja , misalnya adb-1234567890123456.7.azuredatabricks.net.
• Atur ke nilai Jalur HTTP untuk kluster target atau gudang SQL di ruang kerja. Untuk mendapatkan nilai Jalur HTTP, lihat Dapatkan detail koneksi untuk sumber daya komputasi Azure Databricks.
• Atur DATABRICKS_TOKEN ke token akses pribadi Azure Databricks untuk pengguna target. Untuk membuat token akses pribadi, lihat Token akses pribadi Azure Databricks untuk pengguna ruang kerja.

Untuk mengatur variabel lingkungan, lihat dokumentasi sistem operasi Anda.

import pyodbc
import os

conn = pyodbc.connect(
  "Driver=/Library/simba/spark/lib/libsparkodbc_sb64-universal.dylib;" +
  f"Host={os.getenv('DATABRICKS_HOST')};" +
  "Port=443;" +
  f"HTTPPath={os.getenv('DATABRICKS_HTTP_PATH')};" +
  "SSL=1;" +
  "ThriftTransport=2;" +
  "AuthMech=3;" +
  "UID=token;" +
  f"PWD={os.getenv('DATABRICKS_TOKEN')}",
  autocommit = True
)

# Run a SQL query by using the preceding connection.
cursor = conn.cursor()
cursor.execute("SELECT * FROM samples.nyctaxi.trips")

# Print the rows retrieved from the query.
for row in cursor.fetchall():
  print(row)

Contoh berikut menggunakan autentikasi berbasis browser OAuth user-to-machine (U2M) atau OAuth 2.0 alih-alih token akses pribadi Azure Databricks. Contoh ini mengasumsikan bahwa Anda telah mengatur variabel lingkungan DATABRICKS_SERVER_HOSTNAME dan DATABRICKS_HTTP_PATH sebelumnya.

import pyodbc
import os

conn = pyodbc.connect(
  "Driver=/Library/simba/spark/lib/libsparkodbc_sb64-universal.dylib;" +
  f"Host={os.getenv('DATABRICKS_HOST')};" +
  "Port=443;" +
  f"HTTPPath={os.getenv('DATABRICKS_HTTP_PATH')};" +
  "SSL=1;" +
  "ThriftTransport=2;" +
  "AuthMech=11;" +
  "Auth_Flow=2;" +
  "PWD=1234567",
  autocommit = True
)

# Run a SQL query by using the preceding connection.
cursor = conn.cursor()
cursor.execute("SELECT * FROM samples.nyctaxi.trips")

# Print the rows retrieved from the query.
for row in cursor.fetchall():
  print(row)

Contoh berikut menggunakan autentikasi kredensial klien OAuth machine-to-machine (M2M) atau OAuth 2.0. Contoh ini mengasumsikan bahwa Anda telah mengatur variabel lingkungan DATABRICKS_SERVER_HOSTNAME dan DATABRICKS_HTTP_PATH sebelumnya serta variabel lingkungan berikut:

• Atur ke nilai ID Aplikasi (klien) dari Prinsipal Layanan .
• Atur ke nilai Rahasia OAuth dari perwakilan layanan . (Rahasia ID Microsoft Entra tidak didukung untuk autentikasi kredensial klien OAuth M2M atau OAuth 2.0 dengan Driver Databricks ODBC.)

Untuk informasi selengkapnya, lihat Autentikasi mesin-ke-mesin (M2M) OAuth.

import pyodbc
import os

conn = pyodbc.connect(
  "Driver=/Library/simba/spark/lib/libsparkodbc_sb64-universal.dylib;" +
  f"Host={os.getenv('DATABRICKS_HOST')};" +
  "Port=443;" +
  f"HTTPPath={os.getenv('DATABRICKS_HTTP_PATH')};" +
  "SSL=1;" +
  "ThriftTransport=2;" +
  "AuthMech=11;" +
  "Auth_Flow=1;" +
  f"Auth_Client_ID={os.getenv('ARM_CLIENT_ID')};" +
  f"Auth_Client_Secret={os.getenv('DATABRICKS_OAUTH_SECRET')}",
  autocommit = True
)

# Run a SQL query by using the preceding connection.
cursor = conn.cursor()
cursor.execute("SELECT * FROM samples.nyctaxi.trips")

# Print the rows retrieved from the query.
for row in cursor.fetchall():
  print(row)

Pemecahan Masalah

Bagian ini membahas masalah umum yang terjadi ketika menggunakan pyodbc dengan Databricks.

Kesalahan dekode Unicode

Masalah: Anda menerima pesan kesalahan yang serupa dengan hal berikut:

<class 'pyodbc.Error'> returned a result with an error set
Traceback (most recent call last):
File "/Users/user/.pyenv/versions/3.7.5/lib/python3.7/encodings/utf_16_le.py", line 16, in decode
return codecs.utf_16_le_decode(input, errors, True)
UnicodeDecodeError: 'utf-16-le' codec can't decode bytes in position 2112-2113: illegal UTF-16 surrogate

Penyebab: Masalah ada di pyodbc versi 4.0.31 atau di bawahnya yang dapat bermanifestasi dengan gejala seperti itu saat menjalankan kueri yang mengembalikan kolom dengan nama panjang atau pesan kesalahan panjang. Masalah ini telah diperbaiki oleh versi yang lebih baru dari pyodbc.

Solusi: Tingkatkan penginstalan pyodbc Anda ke versi 4.0.32 atau lebih tinggi.

Pemecahan Masalah Umum

Lihat Masalah di repositori mkleehammer/pyodbc di GitHub.