Conectar Python e pyodbc ao Azure Databricks

Artigo
08/29/2024

Você pode se conectar de seu código Python local por meio de ODBC a dados em um cluster do Azure Databricks ou SQL warehouse. Para fazer isso, você pode usar o módulo pyodbcde código Python de código aberto.

Siga estas instruções para instalar, configurar e usar pyodbco .

Para obter mais informações sobre pyodbco , consulte o Wiki pyodbc.

Nota

O Databricks oferece o Databricks SQL Connector for Python como uma alternativa ao pyodbc. O Databricks SQL Connector for Python é mais fácil de configurar e usar, e tem um conjunto mais robusto de construções de codificação, do que pyodbc. pyodbc No entanto, pode ter melhor desempenho ao buscar resultados de consultas acima de 10 MB.

Essas instruções foram testadas com o driver ODBC Databricks 2.7.5, pyodbc 5.0.1 e unixODBC 2.3.12.

Requisitos

Uma máquina de desenvolvimento local executando um dos seguintes:
- macOS
- Windows
- Uma distribuição Unix ou Linux que suporta .rpm ou .deb arquivos
pip.
Para Unix, Linux ou macOS, Homebrew.
Um cluster do Azure Databricks, um armazém SQL do Databricks ou ambos. Para obter mais informações, consulte Referência de configuração de computação e Conectar-se a um SQL warehouse.

Etapa 1: Baixar, instalar e configurar o software

Nesta etapa, você baixa e instala o driver ODBC Databricks, o unixodbc pacote e o pyodbc módulo. (O pyodbc módulo requer o unixodbc pacote em Unix, Linux e macOS.) Você também configura um DSN (Nome da Fonte de Dados) ODBC para autenticar e se conectar ao cluster ou ao SQL warehouse.

Baixe e instale o driver ODBC Databricks e configure um DSN ODBC para seu sistema operacional.
Para Unix, Linux e macOS, instale o unixodbc pacote: a partir do terminal, use Homebrew para executar o comando brew install unixodbc. Para obter mais informações, consulte unixodbc no site Homebrew.
Instale o pyodbc módulo: a partir do terminal ou prompt de comando, use pip para executar o comando pip install pyodbc. Para obter mais informações, consulte pyodbc no site do PyPI e Instalar no wiki do pyodbc.

Etapa 2: Testar sua configuração

Nesta etapa, você escreve e executa código Python para usar seu cluster do Azure Databricks ou o armazém SQL do Databricks para consultar a trips tabela no samples esquema do nyctrips catálogo e exibir os resultados.

Crie um arquivo nomeado pyodbc-demo.py com o seguinte conteúdo. Substitua <dsn-name> pelo nome do DSN ODBC que você criou anteriormente, salve o arquivo e execute o arquivo com seu interpretador 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)

Para acelerar a execução do código, inicie o cluster que corresponde à HTTPPath configuração no seu DSN.
Execute o pyodbc-demo.py arquivo com seu interpretador Python. São apresentadas informações sobre as linhas da tabela.

Próximos passos

Para executar o código de teste Python em um cluster ou armazém SQL diferente, crie um DSN diferente e altere <dsn-name> para o nome do DSN.
Para executar o código de teste Python com uma consulta SQL diferente, altere a cadeia de execute comando.

Usando uma conexão sem DSN

Como alternativa ao uso de um nome DSN, você pode especificar as configurações de conexão embutidas. O exemplo a seguir mostra como usar uma cadeia de conexão sem DSN para autenticação de token de acesso pessoal do Azure Databricks. Este exemplo pressupõe que você tenha as seguintes variáveis de ambiente:

Defina DATABRICKS_SERVER_HOSTNAME como o nome da instância do espaço de trabalho, por exemploadb-1234567890123456.7.azuredatabricks.net.
Defina DATABRICKS_HTTP_PATH como o valor Caminho HTTP para o cluster de destino ou o SQL warehouse no espaço de trabalho. Para obter o valor de Caminho HTTP, consulte Obter detalhes de conexão para um recurso de computação do Azure Databricks.
Defina DATABRICKS_TOKEN como o token de acesso pessoal do Azure Databricks para o usuário de destino. Para criar um token de acesso pessoal, consulte Tokens de acesso pessoal do Azure Databricks para usuários do espaço de trabalho.

Para definir variáveis de ambiente, consulte a documentação do seu sistema operacional.

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)

O exemplo a seguir usa a autenticação baseada em navegador OAuth user-to-machine (U2M) ou OAuth 2.0 em vez de um token de acesso pessoal do Azure Databricks. Este exemplo pressupõe que você já tenha definido as variáveis anterior DATABRICKS_SERVER_HOSTNAME e DATABRICKS_HTTP_PATH de ambiente.

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)

O exemplo a seguir usa autenticação de credenciais de cliente OAuth machine-to-machine (M2M) ou OAuth 2.0. Este exemplo pressupõe que você já tenha definido as variáveis anterior DATABRICKS_SERVER_HOSTNAME e DATABRICKS_HTTP_PATH de ambiente, bem como as seguintes variáveis de ambiente:

Defina ARM_CLIENT_ID o valor de ID do aplicativo (cliente) da entidade de serviço.
Defina DATABRICKS_OAUTH_SECRET como o valor OAuth Secret da entidade de serviço. (Os segredos de ID do Microsoft Entra não são suportados para autenticação de credenciais de cliente OAuth M2M ou OAuth 2.0 com o driver ODBC Databricks.)

Para obter mais informações, consulte Autenticação OAuth máquina-a-máquina (M2M).

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)

Resolução de Problemas

Esta seção aborda problemas comuns ao usar pyodbc com Databricks.

Erro de decodificação Unicode

Problema: Você recebe uma mensagem de erro semelhante à seguinte:

<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 um problema na pyodbc versão 4.0.31 ou inferior que pode se manifestar com esses sintomas ao executar consultas que retornam colunas com nomes longos ou uma mensagem de erro longa. O problema foi corrigido por uma versão mais recente do pyodbc.

Solução: Atualize a instalação para pyodbc a versão 4.0.32 ou superior.

Resolução de problemas gerais

Consulte Problemas no repositório mkleehammer/pyodbc no GitHub.

Partilhar via