Partilhar via

Usar SQLAlchemy com o Azure Databricks

  • Artigo

O Azure Databricks fornece um dialeto SQLAlchemy (o sistema que o SQLAlchemy usa para se comunicar com vários tipos de implementações de API de banco de dados e bancos de dados) para o Azure Databricks. SQLAlchemy é um kit de ferramentas Python SQL e Object Relational Mapper (ORM). SQLAlchemy fornece um conjunto de padrões de persistência de nível empresarial bem conhecidos, projetados para acesso eficiente e de alto desempenho ao banco de dados, adaptado em uma linguagem de domínio simples e pythonic. Ver Características e Filosofia.

O dialeto SQLAlchemy para Azure Databricks está incluído no Databricks SQL Connector for Python. Este artigo aborda o dialeto SQLAlchemy para Azure Databricks versão 2.0, que requer o Databricks SQL Connector para Python versão 3.0.0 ou superior.

Requisitos

  • Uma máquina de desenvolvimento executando Python >=3.8 e <=3.11.
  • O Databricks recomenda que você use ambientes virtuais Python, como aqueles fornecidos pelo venv que estão incluídos no Python. Os ambientes virtuais ajudam a garantir que você esteja usando as versões corretas do Python e do Databricks SQL Connector for Python juntos. A configuração e o uso de ambientes virtuais estão fora do escopo deste artigo. Para obter mais informações, consulte Criando ambientes virtuais.
  • Um cluster ou armazém SQL existente.

Começar agora

  • Instale o Databricks SQL Connector para biblioteca Python versão 3.0.0 ou superior em sua máquina de desenvolvimento executando pip install "databricks-sql-connector[sqlalchemy]" ou python -m pip install "databricks-sql-connector[sqlalchemy]". Para obter informações sobre a versão, consulte o histórico de lançamento do databricks-sql-connector.

  • Reúna as seguintes informações para o cluster ou SQL warehouse que você deseja usar:

    Cluster

    Armazém SQL

    • O nome de host do servidor do SQL warehouse. Você pode obter isso do valor Nome do host do servidor na guia Detalhes da conexão do seu SQL warehouse.
    • O caminho HTTP do SQL warehouse. Você pode obter isso do valor Caminho HTTP na guia Detalhes da Conexão do seu SQL warehouse.

Autenticação

O dialeto SQLAlchemy para Azure Databricks dá suporte à autenticação de token de acesso pessoal do Azure Databricks.

Para criar um token de acesso pessoal do Azure Databricks, faça o seguinte:

  1. No seu espaço de trabalho do Azure Databricks, clique no seu nome de utilizador do Azure Databricks na barra superior e, em seguida, selecione Definições na lista pendente.
  2. Clique em Desenvolvedor.
  3. Ao lado de Tokens de acesso, clique em Gerenciar.
  4. Clique em Gerar novo token.
  5. (Opcional) Insira um comentário que o ajude a identificar esse token no futuro e altere o tempo de vida padrão do token de 90 dias. Para criar um token sem tempo de vida (não recomendado), deixe a caixa Tempo de vida (dias) vazia (em branco).
  6. Clique em Generate (Gerar).
  7. Copie o token exibido para um local seguro e clique em Concluído.

Nota

Certifique-se de salvar o token copiado em um local seguro. Não partilhe o seu token copiado com outras pessoas. Se você perder o token copiado, não poderá regenerar exatamente o mesmo token. Em vez disso, você deve repetir esse procedimento para criar um novo token. Se você perder o token copiado ou acreditar que o token foi comprometido, o Databricks recomenda que você exclua imediatamente esse token do seu espaço de trabalho clicando no ícone da lixeira (Revogar) ao lado do token na página de tokens do Access.

Se você não conseguir criar ou usar tokens em seu espaço de trabalho, isso pode ser porque o administrador do espaço de trabalho desabilitou tokens ou não lhe deu permissão para criar ou usar tokens. Consulte o administrador do espaço de trabalho ou os seguintes tópicos:

Para autenticar o dialeto SQLAlchemy, use o seguinte trecho de código. Este trecho pressupõe que você tenha definido as seguintes variáveis de ambiente:

  • DATABRICKS_TOKEN, definido como o token de acesso pessoal do Azure Databricks.
  • DATABRICKS_SERVER_HOSTNAMEdefinido como o valor Nome do host do servidor para seu cluster ou SQL warehouse.
  • DATABRICKS_HTTP_PATH, definido como o valor Caminho HTTP para seu cluster ou SQL warehouse.
  • DATABRICKS_CATALOG, definido para o catálogo de destino no Unity Catalog.
  • DATABRICKS_SCHEMA, definido como o esquema de destino (também conhecido como banco de dados) no Unity Catalog.

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

import os
from sqlalchemy import create_engine

access_token    = os.getenv("DATABRICKS_TOKEN")
server_hostname = os.getenv("DATABRICKS_SERVER_HOSTNAME")
http_path       = os.getenv("DATABRICKS_HTTP_PATH")
catalog         = os.getenv("DATABRICKS_CATALOG")
schema          = os.getenv("DATABRICKS_SCHEMA")

engine = create_engine(
  url = f"databricks://token:{access_token}@{server_hostname}?" +
        f"http_path={http_path}&catalog={catalog}&schema={schema}"
)

# ...

Você usa a variável anterior engine para se conectar ao catálogo e ao esquema especificados por meio do recurso de computação do Azure Databricks. Para obter exemplos de conexão, consulte a seção a seguir e o arquivo sqlalchemy.py no GitHub.

Exemplo

Consulte o arquivo sqlalchemy.py no GitHub.

Referência DBAPI

Recursos adicionais