Conectar o Python e o pyodbc ao Azure Databricks

Você pode conectar-se a partir do seu código Python local por meio de ODBC aos dados em um cluster do Azure Databricks ou em um SQL Warehouse. Para fazer isso, você pode usar o módulo de código Python de software livre pyodbc.

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

Para obter mais informações sobre pyodbc, confira a Wiki do pyodbc.

Requisitos

• Um computador de desenvolvimento local executando um dos seguintes sistemas:
  • macOS
  • Windows
  • Uma distribuição Unix ou Linux que dê suporte a arquivos .rpm ou .deb
• pip.
• No caso de Unix, Linux ou macOS, Homebrew.
• Um cluster do Azure Databricks, um SQL warehouse 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 software

Nesta etapa, você baixará e instalará o driver ODBC do Databricks, o pacote unixodbc e o módulo pyodbc. (O módulo pyodbc requer o pacote unixodbc no Unix, Linux e macOS.) Você também configura um DSN (Nome da Fonte de Dados) ODBC para autenticar e conectar-se ao cluster ou ao SQL Warehouse.

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

Etapa 2: testar a configuração

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

1. Crie um arquivo chamado pyodbc-demo.py com o conteúdo a seguir. Substitua <dsn-name> pelo nome do DSN ODBC que você criou anteriormente, salve o arquivo e execute o arquivo com o interpretador do 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 à configuração HTTPPath em seu DSN.

3. Execute o arquivo pyodbc-demo.py com o interpretador de Python. São exibidas informações sobre as linhas da tabela.

Próximas etapas

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

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 pelo nome da instância do espaço de trabalho, por exemplo, adb-1234567890123456.7.azuredatabricks.net.
• Defina DATABRICKS_HTTP_PATH pelo valor do Caminho HTTP do cluster de destino ou o SQL Warehouse no espaço de trabalho. Para obter o valor do Caminho HTTP, confira Obter detalhes de conexão para um recurso de computação do Azure Databricks.
• Defina DATABRICKS_TOKEN pelo 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 os usuários do espaço de trabalho.

Para definir variáveis de ambiente, confira a documentação do 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 no navegador de usuário para máquina (U2M) OAuth ou a autenticação baseada no navegador 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 anteriores 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 a autenticação das credenciais do cliente de máquina para máquina OAuth (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, assim como as seguintes variáveis de ambiente:

• Defina ARM_CLIENT_ID pelo valor da ID do aplicativo (cliente) da entidade de serviço.
• Defina DATABRICKS_OAUTH_SECRET pelo valo Segredo do OAuth da entidade de serviço. (Não há suporte para os segredos do Microsoft Entra ID para a autenticação das credenciais do cliente OAuth M2M ou OAuth 2.0 com o Driver ODBC do Databricks.)

Para obter mais informações, consulte Autenticação de máquina para máquina (M2M) do 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)

Solução de problemas

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

Erro de decodificação de Unicode

Problema: você recebe uma mensagem de erro similar à 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 do pyodbc, que pode manifestar esses sintomas ao executar consultas que retornam colunas com nomes longos ou uma mensagem de erro longa. O problema foi corrigido em uma versão mais recente do pyodbc.

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

Solução de problemas gerais

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