Compartir a través de

Conexión de Python y pyodbc a Azure Databricks

  • Artículo

Puede conectarse desde el código local de Python, a través de ODBC, a los datos de un clúster de Azure Databricks o de un almacén de SQL. Para ello, puede usar el módulo de código abierto de Python pyodbc.

Siga estas instrucciones para instalar, configurar y usar pyodbc.

Para más información sobre pyodbc, consulte la Wiki de pyodbc.

Nota:

Databricks ofrece Databricks SQL Connector para Python, como alternativa a pyodbc. Databricks SQL Connector para Python es más fácil de configurar, de usar, y tiene un conjunto más sólido de construcciones de codificación que pyodbc. Sin embargo, pyodbc puede tener un mejor rendimiento al capturar resultados de consultas por encima de 10 MB.

Estas instrucciones se probaron con el controlador ODBC de Databricks 2.7.5, pyodbc 5.0.1 y unixODBC 2.3.12.

Requisitos

  • Una máquina de desarrollo local que ejecute uno de los siguientes elementos:
    • macOS
    • Windows
    • Una distribución de Unix o Linux que admita archivos .rpm o .deb
  • pip.
  • Para Unix, Linux o macOS, Homebrew.
  • Un clúster de Azure Databricks, un almacén de Databricks SQL o ambos. Para más información, consulte Referencia de configuración de proceso y Conexión a sql Warehouse.

Paso 1: Descarga, instalación y configuración del software

En este paso, descargará e instalará el controlador ODBC de Databricks, el paquete unixodbc y el módulo pyodbc. (El módulo pyodbc requiere el paquete unixodbc en Unix, Linux y macOS). También configurará un nombre de origen de datos ODBC (DSN) para autenticarse y conectarse al clúster o al almacenamiento de SQL.

  1. Descargar e instalar el controlador ODBC de Databricks y , y configurar un DSN ODBC para el sistema operativo.
  2. Para Unix, Linux y macOS, instale el paquete unixodbc: desde el terminal, use Homebrew para ejecutar el comando brew install unixodbc. Para más información, consulte unixodbc en el sitio web de Homebrew.
  3. Instale el módulo pyodbc: desde el terminal o el símbolo del sistema, use pip para ejecutar el comando pip install pyodbc. Para más información, consulte pyodbc en el sitio web de PyPI e Instalación en la Wiki de pyodbc.

Paso 2: Prueba de la configuración

En este paso, escribirá y ejecutará código de Python para usar el clúster de Azure Databricks o el almacén de Databricks SQL para consultar la tabla trips en el esquema nyctrips del catálogo samples y mostrar los resultados.

  1. Cree un archivo llamado pyodbc-demo.py con el siguiente contenido. Reemplace <dsn-name> por el nombre del DSN ODBC que creó anteriormente, guarde el archivo y, a continuación, ejecute el archivo con el intérprete de Python.

    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. Para acelerar la ejecución del código, inicie el clúster correspondiente a la configuración de HTTPPath del DSN.

  3. Ejecute el archivo pyodbc-demo.py con el intérprete de Python. Se muestra información sobre las filas de la tabla.

Pasos siguientes

  • Para ejecutar el código de prueba de Python en un clúster diferente o en SQL Warehouse, cree un DSN diferente y cambie <dsn-name> al nombre del DSN.
  • Para ejecutar el código de prueba de Python con una consulta SQL diferente, cambie la cadena de comando execute.

Uso de una conexión sin DSN

Como alternativa al uso de un nombre de DSN, puede especificar la configuración de conexión insertada. En el ejemplo siguiente se muestra cómo usar una cadena de conexión sin DSN para la autenticación de tokens de acceso personal de Azure Databricks. En este ejemplo se supone que se han establecido las siguientes variables de entorno:

Para establecer las variables de entorno, consulte la documentación del sistema operativo.

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)

En el ejemplo siguiente se usa la autenticación basada en explorador de OAuth 2.0 o de usuario a máquina (U2M) de OAuth en lugar de un token de acceso personal de Azure Databricks. En este ejemplo se supone que las variables de entorno DATABRICKS_SERVER_HOSTNAME y DATABRICKS_HTTP_PATH anteriores ya se han establecido.

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)

En el siguiente ejemplo se utiliza la autenticación de credenciales de cliente de OAuth 2.0 o de máquina a máquina (M2M) de OAuth. En este ejemplo se supone que las variables de entorno DATABRICKS_SERVER_HOSTNAME y DATABRICKS_HTTP_PATH anteriores ya se han establecido, así como las siguientes variables de entorno:

  • ARM_CLIENT_ID, establecido en el valor del identificador de aplicación (cliente) de la entidad de servicio.
  • DATABRICKS_OAUTH_SECRET, establecido en el valor Secreto de OAuth de la entidad de servicio. (Los secretos de Microsoft Entra ID no se admiten para la autenticación de credenciales de cliente de OAuth M2M o OAuth 2.0 con el controlador ODBC de Databricks).

Para obtener más información, consulte Autenticación de máquina a máquina (M2M) de 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)

Solución de problemas

En esta sección se abordan los problemas comunes al usar pyodbc con Databricks.

Error de descodificación Unicode

Problema: recibe un mensaje de error similar al siguiente:

<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

Causa: existe un problema en pyodbc versión 4.0.31 o anterior, que podría manifestarse con estos síntomas al ejecutar consultas, que devuelven columnas con nombres largos o un mensaje de error largo. El problema se ha corregido mediante una versión más reciente de pyodbc.

Solución: actualice la instalación de pyodbc a la versión 4.0.32 o posterior.

Solución general de problemas

Consulte Problemas, en el repositorio mkleehammer/pyodbc de GitHub.