Python en pyodbc verbinden met Azure Databricks

U kunt verbinding maken vanuit uw lokale Python-code via ODBC met gegevens in een Azure Databricks-cluster of SQL Warehouse. Hiervoor kunt u de opensource Python-codemodule pyodbcgebruiken.

Volg deze instructies voor het installeren, configureren en gebruiken pyodbcvan .

Zie de pyodbc voor meer informatie.

Notitie

Databricks biedt de Databricks SQL Connector voor Python als alternatief voor pyodbc. De Databricks SQL Connector voor Python is eenvoudiger in te stellen en te gebruiken en heeft een robuustere set coderingsconstructies dan pyodbc. Het kan echter pyodbc betere prestaties hebben bij het ophalen van queryresultaten van meer dan 10 MB.

Deze instructies zijn getest met Databricks ODBC-stuurprogramma 2.7.5, pyodbc 5.0.1 en unixODBC 2.3.12.

Vereisten

• Een lokale ontwikkelcomputer met een van de volgende opties:
  • macOS
  • Windows
  • Een Unix- of Linux-distributie die ondersteuning biedt .rpm voor of .deb bestanden
• pip.
• Voor Unix, Linux of macOS, Homebrew.
• Een Azure Databricks-cluster, een Databricks SQL-warehouse of beide. Zie Referentie voor compute-configuratie en verbinding maken met een SQL-warehouse voor meer informatie.

Stap 1: Software downloaden, installeren en configureren

In deze stap downloadt en installeert u het ODBC-stuurprogramma van Databricks, het unixodbc pakket en de pyodbc module. (De pyodbc module vereist het unixodbc pakket op Unix, Linux en macOS.) U configureert ook een ODBC-gegevensbronnaam (DSN) om te verifiëren met en verbinding te maken met uw cluster of SQL Warehouse.

1. Download en installeer het ODBC-stuurprogramma van Databricks en configureer een ODBC-DSN voor uw besturingssysteem.
2. Installeer voor Unix, Linux en macOS het unixodbc pakket: gebruik Homebrew vanuit de terminal om de opdracht brew install unixodbcuit te voeren. Zie unixodbc op de homebrew-website voor meer informatie.
3. Installeer de pyodbc module: vanuit de terminal of opdrachtprompt gebruikt pip u om de opdracht pip install pyodbcuit te voeren. Zie pyodbc op de PyPI-website en installeren in de pyodbc-wiki voor meer informatie.

Stap 2: Uw configuratie testen

In deze stap schrijft en voert u Python-code uit om uw Azure Databricks-cluster of Databricks SQL Warehouse te gebruiken om een query uit te voeren op de trips tabel in het schema van samples de nyctrips catalogus en de resultaten weer te geven.

1. Maak een bestand met de naam pyodbc-demo.py met de volgende inhoud. Vervang <dsn-name> door de naam van de ODBC-DSN die u eerder hebt gemaakt, sla het bestand op en voer het bestand uit met uw Python-interpreter.

   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. Als u de code sneller wilt uitvoeren, start u het cluster dat overeenkomt met de HTTPPath instelling in uw DSN.

3. Voer het pyodbc-demo.py bestand uit met uw Python-interpreter. Informatie over de rijen van de tabel wordt weergegeven.

Volgende stappen

• Als u de Python-testcode wilt uitvoeren voor een ander cluster of SQL Warehouse, maakt u een andere DSN en wijzigt <dsn-name> u de naam van de DSN.
• Als u de Python-testcode wilt uitvoeren met een andere SQL-query, wijzigt u de execute opdrachtreeks.

Een DSN-less-verbinding gebruiken

Als alternatief voor het gebruik van een DSN-naam kunt u de verbindingsinstellingen inline opgeven. In het volgende voorbeeld ziet u hoe u een DSN-less-verbindingsreeks gebruikt voor verificatie van persoonlijke toegangstokens van Azure Databricks. In dit voorbeeld wordt ervan uitgegaan dat u de volgende omgevingsvariabelen hebt:

• Stel DATABRICKS_SERVER_HOSTNAME deze in op de naam van het werkruimte-exemplaar, bijvoorbeeldadb-1234567890123456.7.azuredatabricks.net.
• Stel DATABRICKS_HTTP_PATH deze waarde in op de HTTP-padwaarde voor het doelcluster of SQL-warehouse in de werkruimte. Zie Verbindingsgegevens ophalen voor een Azure Databricks-rekenresource om de waarde voor het HTTP-pad op te halen.
• Ingesteld DATABRICKS_TOKEN op het persoonlijke toegangstoken van Azure Databricks voor de doelgebruiker. Als u een persoonlijk toegangstoken wilt maken, raadpleegt u persoonlijke toegangstokens van Azure Databricks voor werkruimtegebruikers.

Als u omgevingsvariabelen wilt instellen, raadpleegt u de documentatie van uw besturingssysteem.

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)

In het volgende voorbeeld wordt OAuth-gebruiker-naar-machine (U2M) of OAuth 2.0-browserverificatie gebruikt in plaats van een persoonlijk toegangstoken van Azure Databricks. In dit voorbeeld wordt ervan uitgegaan dat u de voorgaande DATABRICKS_SERVER_HOSTNAME en DATABRICKS_HTTP_PATH omgevingsvariabelen al hebt ingesteld.

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)

In het volgende voorbeeld wordt verificatie van OAuth-computer-naar-machine (M2M) of OAuth 2.0-clientreferenties gebruikt. In dit voorbeeld wordt ervan uitgegaan dat u de voorgaande DATABRICKS_SERVER_HOSTNAME en DATABRICKS_HTTP_PATH omgevingsvariabelen al hebt ingesteld, evenals de volgende omgevingsvariabelen:

• Stel ARM_CLIENT_ID deze waarde in op de waarde van de toepassings-id (client) van de service-principal.
• Ingesteld DATABRICKS_OAUTH_SECRET op de OAuth Secret-waarde van de service-principal. (Microsoft Entra ID-geheimen worden niet ondersteund voor verificatie van OAuth M2M- of OAuth 2.0-clientreferenties met het Databricks ODBC-stuurprogramma.)

Zie OAuth M2M-verificatie (machine-to-machine) voor meer informatie.

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)

Probleemoplossing

In deze sectie worden veelvoorkomende problemen opgelost bij gebruik pyodbc met Databricks.

Unicode-decodefout

Probleem: Er wordt een foutbericht weergegeven dat er ongeveer als volgt uitziet:

<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

Oorzaak: Er bestaat een probleem in pyodbc versie 4.0.31 of lager dat kan optreden met dergelijke symptomen bij het uitvoeren van query's die kolommen met lange namen of een lang foutbericht retourneren. Het probleem is opgelost door een nieuwere versie van pyodbc.

Oplossing: Voer een upgrade uit van de installatie van pyodbc versie 4.0.32 of hoger.

Algemene probleemoplossing

Zie Problemen in de mkleehammer/pyodbc-opslagplaats op GitHub.