Menyambungkan Python dan pyodbc ke Azure Databricks

Artikel
05/14/2024

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.

Catatan

Databricks menawarkan Databricks SQL Connector untuk Python sebagai alternatif untuk pyodbc. Databricks SQL Connector untuk Python lebih mudah disiapkan dan digunakan, serta memiliki serangkaian konstruksi pengkodean yang lebih kuat daripada pyodbc. Namun, pyodbc mungkin memiliki performa yang lebih baik saat mengambil hasil kueri di atas 10 MB.

Instruksi ini diuji dengan driver Databricks ODBC 2.7.5, pyodbc 5.0.1, dan unixODBC 2.3.12.

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 Apa itu 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.

Unduh dan instal driver Databricks ODBC dan konfigurasikan ODBC DSN untuk sistem operasi Anda.
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.
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 trips tabel dalam samples skema nyctrips katalog dan menampilkan hasilnya.

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)

Untuk mempercepat menjalankan kode, mulai kluster yang sesuai dengan HTTPPath pengaturan di DSN Anda.
Jalankan file pyodbc-demo.py dengan interpreter Python Anda. Informasi tentang baris tabel 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 DATABRICKS_HTTP_PATH ke nilai Jalur HTTP untuk kluster target atau gudang SQL di ruang kerja. Untuk mendapatkan nilai Jalur HTTP, lihat Mendapatkan 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 sebelumnya DATABRICKS_SERVER_HOSTNAME dan DATABRICKS_HTTP_PATH lingkungan.

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 sebelumnya DATABRICKS_SERVER_HOSTNAME dan DATABRICKS_HTTP_PATH lingkungan serta variabel lingkungan berikut:

Atur ARM_CLIENT_ID ke nilai ID Aplikasi (klien) perwakilan layanan.
Atur DATABRICKS_OAUTH_SECRET ke nilai Rahasia OAuth perwakilan layanan. (Rahasia ID Microsoft Entra (sebelumnya Azure Active Directory) tidak didukung untuk autentikasi kredensial klien OAuth M2M atau OAuth 2.0 dengan Driver ODBC Databricks.)

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 muncul di pyodbc versi 4.0.31 atau di bawahnya yang dapat bermanifestasi dengan gejala semacam itu saat menjalankan kueri yang mengembalikan kolom dengan nama atau pesan kesalahan yang 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.

Bagikan melalui