Conecte Python e pyodbc ao Databricks

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

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

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

Observação

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

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

Requisitos

Uma máquina de desenvolvimento local executando um dos seguintes:
- Mac OS
- janelas
- Uma distribuição Unix ou Linux compatível com arquivos .rpm ou .deb
pip.
Para Unix, Linux ou macOS, Homebrew.
Um cluster do Databricks, um warehouse do Databricks SQL ou ambos. Para obter mais informações, consulte Referência de configuração do Compute e Criar um SQL warehouse.

o passo 1: downloads, instalar e configurar software

Nesta etapa, você downloads e instala 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 nome de fonte de dados (DSN) ODBC para autenticar e conectar-se aos seus clusters ou SQL warehouse.

downloads e instala o driver ODBC do Databricks e configura um DSN ODBC para seu sistema operacional.
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.
Instale o módulo pyodbc : no 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 instale no pyodbc Wiki.

o passo 2: Teste sua configuração

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

Crie um arquivo chamado pyodbc-demo.py com o conteúdo a seguir. Substitua <dsn-name> pelo nome do DSN ODBC criado anteriormente, salve o arquivo e execute-o 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, comece o cluster que corresponde à configuração HTTPPath no seu DSN.
execute o arquivo pyodbc-demo.py com seu interpretador Python. informações sobre as linhas da tabela são exibidas.

Próximos passos

Para executar o código de teste Python em clusters ou SQL warehouse diferentes, crie um DSN diferente e altere <dsn-name> para o nome do DSN.
Para executar o código de teste Python com uma query SQL diferente, altere as strings de 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 em linha. O exemplo a seguir mostra como usar strings de conexão sem DSN para autenticação access token pessoal do Databricks. Este exemplo pressupõe que você tenha a seguinte variável de ambiente:

Configure DATABRICKS_SERVER_HOSTNAME como o nome da instância do espaço de trabalho, por exemplo dbc-a1b2345c-d6e7.cloud.databricks.com.
Defina DATABRICKS_HTTP_PATH como o valor do Caminho HTTP para os clusters de destino ou SQL warehouse no workspace. Para obter o valor do Caminho HTTP , consulte Obter detalhes de conexão para um recurso de computação do Databricks.
Defina DATABRICKS_TOKEN como o access token pessoal do Databricks para o usuário de destino. Para criar um access token pessoal, consulte access token pessoal do Databricks para usuários do workspace.

Para definir variáveis de ambiente, consulte 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 autenticação baseada em navegador OAuth usuário-máquina (U2M) ou OAuth 2.0 em vez de um access token pessoal do 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 máquina a máquina (M2M) ou OAuth 2.0. Este exemplo pressupõe que você já tenha definido a variável de ambiente DATABRICKS_SERVER_HOSTNAME e DATABRICKS_HTTP_PATH anteriores, bem como a seguinte variável de ambiente:

Defina DATABRICKS_CLIENT_ID como o valor UUID/ID do aplicativo da entidade de serviço.
Defina DATABRICKS_OAUTH_SECRET como o valor do segredo OAuth da entidade de serviço.

Para obter mais informações, consulte Autenticação máquina a máquina (M2M) 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('DATABRICKS_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 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 abaixo que pode se manifestar com tais sintomas ao executar query 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ções: Atualize sua instalação do pyodbc para a versão 4.0.32 ouacima.

Solução de problemas geral

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