Partilhar via

Conectar Python e pyodbc ao Azure Databricks

  • Artigo

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.

  1. Baixe e instale o driver ODBC Databricks e configure um DSN ODBC para seu sistema operacional.
  2. 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.
  3. 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 tabela trips no esquema nyctrips do catálogo samples e exibir os resultados.

  1. 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)

  2. Para acelerar a execução do código, inicie o cluster que corresponde à HTTPPath configuração no seu DSN.

  3. 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:

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 de ambiente DATABRICKS_SERVER_HOSTNAME e DATABRICKS_HTTP_PATH anteriores.

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 de ambiente DATABRICKS_SERVER_HOSTNAME e DATABRICKS_HTTP_PATH anteriores, bem como as seguintes variáveis de ambiente:

  • Defina para o valor ID do aplicativo (cliente) da entidade de serviço .
  • Defina DATABRICKS_OAUTH_SECRET para o valor do segredo OAuth 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 versão 4.0.31 ou inferior pyodbc 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.