Conector do Databricks SQL para Python

O Conector SQL do Databricks para Python é uma biblioteca Python que permite que você use o código Python para executar comandos SQL na computação de uso geral do Azure Databricks e nos armazéns SQL do Databricks. O Conector SQL Databricks para Python é mais fácil de configurar e usar do que bibliotecas do Python semelhantes, como pyodbc. Essa biblioteca segue PEP 249 – Especificação da API do Banco de Dados Python v2.0.

Importante

O Conector do SQL do Databricks para Python versão 3.0.0 e superior dá suporte à execução de consulta parametrizada nativa, o que impede a injeção de SQL e pode melhorar o desempenho da consulta. As versões anteriores usavam a execução parametrizada embutida, que não é segura contra injeção de SQL e tem outras desvantagens. Para obter mais informações, consulte Como usar parâmetros nativos.

O Databricks SQL Conector para Python também dá suporte ao dialeto SQLAlchemy para o Azure Databricks, mas precisa ser instalado para que esses recursos possam ser utilizados. Confira Usar SQLAlchemy com o Azure Databricks.

Requisitos

Um computador de desenvolvimento executando o Python 3.8 e superior.
O Databricks recomenda que você use ambientes virtuais Python, como os fornecidos por 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 Conector SQL do Databricks para Python. A configuração e o uso de ambientes virtuais estão fora do escopo deste artigo. Para obter mais informações, confira Criando ambientes virtuais.
Uma computação de todos os fins existente ou um SQL Warehouse.

Introdução

Instale o Conector SQL do Databricks para o Python. O PyArrow é uma dependência opcional do Conector SQL do Databricks para Python e não é instalado por padrão na versão 4.0.0 e posteriores do conector. Se o PyArrow não estiver instalado, recursos como CloudFetch e outras funcionalidades do Apache Arrow não estarão disponíveis, o que pode afetar o desempenho de grandes volumes de dados.
- Para instalar o conector lean, use:
```
pip install databricks-sql-connector
```
- Para instalar o conector completo, incluindo PyArrow, use:
```
pip install databricks-sql-connector[pyarrow]
```
Reúna as seguintes informações para a computação de uso geral ou o armazém de dados SQL que você pretende utilizar.

Computação para todos os fins
- O nome do host do servidor da computação para todas as finalidades. Você pode obter isso do valor do nome do host do servidor na guia Opções Avançadas > JDBC/ODBC para sua computação de uso geral.
- O caminho HTTP do computador de uso geral. Você pode obter isso no valor de Caminho HTTP na guia Opções avançadas > JDBC/ODBC para a sua computação para todas as finalidades
Observação

O conector do SQL não dá suporte à conexão com a computação de trabalhos.

SQL Warehouse
- O nome de host do servidor do SQL warehouse. É possível obtê-lo no valor do Nome do host do servidor na guia Detalhes da conexão do SQL warehouse.
- O caminho HTTP do SQL warehouse. É possível obtê-lo no valor de Caminho HTTP na guia Detalhes da conexão do SQL warehouse.

Autenticação

O Conector do SQL do Databricks para Python dá suporte para os seguintes tipos de autenticação do Azure Databricks:

Autenticação de token de acesso pessoal do Databricks
Autenticação de token do Microsoft Entra ID
Autenticação OAuth entre máquinas (M2M)
Autenticação U2M (usuário para computador) do OAuth

O Conector SQL do Databricks para Python ainda não suporta os seguintes tipos de autenticação do Azure Databricks:

Autenticação de token de acesso pessoal do Databricks

Para usar o Conector do SQL do Databricks para Python com a autenticação de token de acesso pessoal do Azure Databricks, você precisa primeiro criar um token de acesso pessoal do Azure Databricks. Para fazer isso, siga as etapas em Criar tokens de acesso pessoal para usuários do workspace.

Para autenticar o Databricks SQL Connector for Python, use o seguinte trecho de código. Esse snippet de código pressupõe que você tenha definido as seguintes variáveis de ambiente:

DATABRICKS_SERVER_HOSTNAMEdefinido como o valor do nome do host do servidor para sua computação para todas as finalidades ou SQL warehouse.
DATABRICKS_HTTP_PATH, definido como o valor Caminho HTTP para sua computação para todas as finalidades ou SQL warehouse.
DATABRICKS_TOKEN, definido como o token de acesso pessoal do Azure Databricks.

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

from databricks import sql
import os

with sql.connect(server_hostname = os.getenv("DATABRICKS_SERVER_HOSTNAME"),
                 http_path       = os.getenv("DATABRICKS_HTTP_PATH"),
                 access_token    = os.getenv("DATABRICKS_TOKEN")) as connection:
# ...

Autenticação M2M (de computador para computador) do OAuth

O Conector do Databricks SQL para Python versões 2.7.0 e superior suportam autenticação OAuth máquina a máquina (M2M). Você também precisa instalar o SDK do Databricks para Python 0.18.0 ou superior, por exemplo, executando pip install databricks-sdk ou python -m pip install databricks-sdk.

Para usar o Conector do Databricks SQL para Python com autenticação OAuth M2M, faça o seguinte:

Crie um principal de serviço do Azure Databricks em seu espaço de trabalho do Azure Databricks e crie um segredo OAuth para esse principal de serviço.

Para criar a entidade de serviço e seu segredo de OAuth, consulte Autorizar o acesso da entidade de serviço ao Azure Databricks com OAuth. Anote o valor do UUID ou do ID do aplicativo da entidade de serviço e o valor de Segredo para o segredo de OAuth da entidade de serviço.
Dê a essa entidade de serviço acesso à sua computação para todas as finalidades ou warehouse.

Para conceder à entidade de serviço acesso ao seu warehouse ou à computação para todas as finalidades, consulte Permissões de computação ou Gerenciar um SQL warehouse.

Para autenticar o Databricks SQL Connector for Python, use o seguinte trecho de código. Esse snippet de código pressupõe que você tenha definido as seguintes variáveis de ambiente:

DATABRICKS_SERVER_HOSTNAMEdefinido como o valor do nome do host do servidor para sua computação para todas as finalidades ou SQL warehouse.
DATABRICKS_HTTP_PATH, definido como o valor Caminho HTTP para sua computação para todas as finalidades ou SQL warehouse.
DATABRICKS_CLIENT_ID, definido como o valor do UUID ou da ID do aplicativo da entidade de serviço.
DATABRICKS_CLIENT_SECRET, defina como Segredo para o segredo de OAuth da entidade de serviço.

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

from databricks.sdk.core import Config, oauth_service_principal
from databricks import sql
import os

server_hostname = os.getenv("DATABRICKS_SERVER_HOSTNAME")

def credential_provider():
  config = Config(
    host          = f"https://{server_hostname}",
    client_id     = os.getenv("DATABRICKS_CLIENT_ID"),
    client_secret = os.getenv("DATABRICKS_CLIENT_SECRET"))
  return oauth_service_principal(config)

with sql.connect(server_hostname      = server_hostname,
                 http_path            = os.getenv("DATABRICKS_HTTP_PATH"),
                 credentials_provider = credential_provider) as connection:
# ...

Autenticação de token do Microsoft Entra ID

Para usar o Conector do SQL do Databricks para Python com a autenticação de token do Microsoft Entra ID, você deve fornecer ao Conector do SQL do Databricks para Python o token do Microsoft Entra ID. Para criar um token de acesso do Microsoft Entra ID, faça o seguinte:

Para um usuário do Azure Databricks, você pode usar a CLI do Azure. Consulte Como obter manualmente tokens de ID do Microsoft Entra.
Para um principal de serviço do Microsoft Entra ID, consulte Obter tokens para principais de serviço. Para criar uma entidade de serviço gerenciada do Microsoft Entra ID, veja Entidades de serviço.

Os tokens do Microsoft Entra ID têm um tempo de vida padrão de cerca de 1 hora. Para criar um novo token do Microsoft Entra ID, repita esse processo.

Para autenticar o Databricks SQL Connector for Python, use o seguinte trecho de código. Esse snippet de código pressupõe que você tenha definido as seguintes variáveis de ambiente:

Defina DATABRICKS_SERVER_HOSTNAME como o valor do nome do host do servidor para sua computação para todas as finalidades ou SQL warehouse.
Defina DATABRICKS_HTTP_PATH como o valor de Caminho HTTP para sua computação para todas as finalidades ou SQL warehouse.
Defina DATABRICKS_TOKEN como o token do Microsoft Entra ID.

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

from databricks import sql
import os

with sql.connect(server_hostname = os.getenv("DATABRICKS_SERVER_HOSTNAME"),
                 http_path       = os.getenv("DATABRICKS_HTTP_PATH"),
                 access_token    = os.getenv("DATABRICKS_TOKEN")) as connection:
# ...

Autenticação U2M (usuário para computador) do OAuth

As versões 2.7.0 e posteriores do Conector SQL do Databricks para Python suportam a autenticação usuário para computador (U2M) do OAuth. Você também precisa instalar o SDK do Databricks para Python 0.19.0 ou superior, por exemplo, executando pip install databricks-sdk ou python -m pip install databricks-sdk.

Para autenticar o Conector SQL do Databricks para Python com a autenticação OAuth U2M, use o seguinte trecho de código. A autenticação OAuth U2M usa a entrada e consentimento humano em tempo real para autenticar a conta de usuário do Azure Databricks de destino. Esse snippet de código pressupõe que você tenha definido as seguintes variáveis de ambiente:

Defina DATABRICKS_SERVER_HOSTNAME como o valor do nome do host do servidor para sua computação para todas as finalidades ou SQL warehouse.
Defina DATABRICKS_HTTP_PATH como o valor de Caminho HTTP para sua computação para todas as finalidades ou SQL warehouse.

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

from databricks import sql
import os

with sql.connect(server_hostname = os.getenv("DATABRICKS_SERVER_HOSTNAME"),
                 http_path       = os.getenv("DATABRICKS_HTTP_PATH"),
                 auth_type       = "databricks-oauth") as connection:
# ...

Exemplos

Os exemplos de código a seguir demonstram como usar o Conector do SQL do Databricks para Python para consultar e inserir dados, consultar metadados, gerenciar cursores e conexões, gerenciar arquivos no Catálogo do Unity e configurar o registro em log.

Observação

Os exemplos de código a seguir demonstram como usar um token de acesso pessoal do Azure Databricks para a autenticação. Para usar um tipo de autenticação diferente, consulte Autenticação.

Esses exemplos de código recuperam os valores de variável de conexão server_hostname, http_path e access_token destas variáveis de ambiente:

DATABRICKS_SERVER_HOSTNAME, que representa o valor do Nome do host do servidor nos requisitos.
DATABRICKS_HTTP_PATH, que representa o valor do Caminho HTTP obtido nos requisitos.
DATABRICKS_TOKEN, que representa seu token de acesso dos requisitos.

Definir agente do usuário

O exemplo de código a seguir demonstra como definir o aplicativo User-Agent product_name para acompanhamento de uso.

from databricks import sql
import os

with sql.connect(server_hostname   = os.getenv("DATABRICKS_SERVER_HOSTNAME"),
                 http_path         = os.getenv("DATABRICKS_HTTP_PATH"),
                 access_token      = os.getenv("DATABRICKS_TOKEN"),
                 user_agent_entry = "product_name") as connection:
  with connection.cursor() as cursor:
    cursor.execute("SELECT 1 + 1")
    result = cursor.fetchall()

    for row in result:
      print(row)

Consultar dados

O exemplo de código a seguir demonstra como chamar o Databricks SQL Connector para Python para executar um comando SQL básico em uma instância de computação genérica ou em um armazém de dados SQL. Esse comando retorna as duas primeiras linhas da tabela trips no esquema samples do catálogo nyctaxi.

from databricks import sql
import os

with sql.connect(server_hostname = os.getenv("DATABRICKS_SERVER_HOSTNAME"),
                 http_path       = os.getenv("DATABRICKS_HTTP_PATH"),
                 access_token    = os.getenv("DATABRICKS_TOKEN")) as connection:

  with connection.cursor() as cursor:
    cursor.execute("SELECT * FROM samples.nyctaxi.trips LIMIT ?", [2])
    result = cursor.fetchall()

    for row in result:
      print(row)

Marcas de consulta

Importante

Este recurso está em Versão prévia privada. Para solicitar acesso, entre em contato com sua equipe de conta.

O exemplo a seguir mostra como anexar marcas chave-valor às consultas SQL para fins de acompanhamento e análise. As marcas de consulta aparecem na tabela system.query.history.

from databricks import sql
import os

with sql.connect(
    server_hostname = os.getenv("DATABRICKS_SERVER_HOSTNAME"),
    http_path       = os.getenv("DATABRICKS_HTTP_PATH"),
    access_token    = os.getenv("DATABRICKS_TOKEN"),
    session_configuration = {
        'query_tags': 'team:engineering,dashboard:abc123,env:prod'
    }
) as connection:
    with connection.cursor() as cursor:
        cursor.execute("SELECT * FROM samples.nyctaxi.trips LIMIT ?", [2])
        result = cursor.fetchall()
        # Query is now tagged and trackable in system.query.history
        for row in result:
            print(row)

Inserir dados

O exemplo a seguir demonstra como inserir pequenas quantidades de dados (milhares de linhas):

from databricks import sql
import os

with sql.connect(server_hostname = os.getenv("DATABRICKS_SERVER_HOSTNAME"),
                 http_path       = os.getenv("DATABRICKS_HTTP_PATH"),
                 access_token    = os.getenv("DATABRICKS_TOKEN")) as connection:

  with connection.cursor() as cursor:
    cursor.execute("CREATE TABLE IF NOT EXISTS squares (x int, x_squared int)")

    squares = [(i, i * i) for i in range(100)]

    cursor.executemany("INSERT INTO squares VALUES (?, ?)", squares)

    cursor.execute("SELECT * FROM squares LIMIT ?", [10])

    result = cursor.fetchall()

    for row in result:
      print(row)

Para grandes quantidades de dados, você deve primeiro carregar os dados no armazenamento em nuvem e, em seguida, executar o comando COPY INTO.

Consultar metadados

Há métodos dedicados para recuperar metadados. O exemplo a seguir recupera metadados sobre colunas em uma tabela de exemplo:

from databricks import sql
import os

with sql.connect(server_hostname = os.getenv("DATABRICKS_SERVER_HOSTNAME"),
                 http_path       = os.getenv("DATABRICKS_HTTP_PATH"),
                 access_token    = os.getenv("DATABRICKS_TOKEN")) as connection:

  with connection.cursor() as cursor:
    cursor.columns(schema_name="default", table_name="squares")
    print(cursor.fetchall())

Gerenciar cursores e conexões

É uma melhor prática fechar todas as conexões e cursores que não estão mais em uso. Isso libera recursos na computação de uso geral do Azure Databricks e nos warehouses SQL do Databricks.

Você pode usar um gerenciador de contexto ( a sintaxe with usada nos exemplos anteriores) para gerenciar os recursos ou chamar explicitamente close:

from databricks import sql
import os

connection = sql.connect(server_hostname = os.getenv("DATABRICKS_SERVER_HOSTNAME"),
                         http_path       = os.getenv("DATABRICKS_HTTP_PATH"),
                         access_token    = os.getenv("DATABRICKS_TOKEN"))

cursor = connection.cursor()

cursor.execute("SELECT * from range(10)")
print(cursor.fetchall())

cursor.close()
connection.close()

Gerenciar arquivos em volumes do Catálogo do Unity

O Conector do SQL do Databricks permite que você grave arquivos locais em volumes do Catálogo do Unity, baixe arquivos de volumes e exclua arquivos de volumes, conforme mostrado no exemplo a seguir:

from databricks import sql
import os

# For writing local files to volumes and downloading files from volumes,
# you must set the staging_allowed_local_path argument to the path to the
# local folder that contains the files to be written or downloaded.
# For deleting files in volumes, you must also specify the
# staging_allowed_local_path argument, but its value is ignored,
# so in that case its value can be set for example to an empty string.
with sql.connect(server_hostname            = os.getenv("DATABRICKS_SERVER_HOSTNAME"),
                 http_path                  = os.getenv("DATABRICKS_HTTP_PATH"),
                 access_token               = os.getenv("DATABRICKS_TOKEN"),
                 staging_allowed_local_path = "/tmp/") as connection:

  with connection.cursor() as cursor:

    # Write a local file to the specified path in a volume.
    # Specify OVERWRITE to overwrite any existing file in that path.
    cursor.execute(
      "PUT '/tmp/my-data.csv' INTO '/Volumes/main/default/my-volume/my-data.csv' OVERWRITE"
    )

    # Download a file from the specified path in a volume.
    cursor.execute(
      "GET '/Volumes/main/default/my-volume/my-data.csv' TO '/tmp/my-downloaded-data.csv'"
    )

    # Delete a file from the specified path in a volume.
    cursor.execute(
      "REMOVE '/Volumes/main/default/my-volume/my-data.csv'"
    )

Configurar o registro em log

O Conector do SQL do Databricks usa o módulo de log padrão do Python. O exemplo a seguir configura o nível de registro e gera um log de depuração:

from databricks import sql
import os, logging

logging.getLogger("databricks.sql").setLevel(logging.DEBUG)
logging.basicConfig(filename = "results.log",
                    level    = logging.DEBUG)

connection = sql.connect(server_hostname = os.getenv("DATABRICKS_SERVER_HOSTNAME"),
                         http_path       = os.getenv("DATABRICKS_HTTP_PATH"),
                         access_token    = os.getenv("DATABRICKS_TOKEN"))

cursor = connection.cursor()

cursor.execute("SELECT * from range(10)")

result = cursor.fetchall()

for row in result:
   logging.debug(row)

cursor.close()
connection.close()

Testando

Para testar seu código, use estruturas de teste do Python, como pytest. Para testar seu código em condições simuladas sem chamar endpoints da API REST do Azure Databricks ou alterar o estado das suas contas ou espaços de trabalho do Azure Databricks, você pode usar bibliotecas de simulação do Python, como unittest.mock.

Por exemplo, dado o seguinte arquivo chamado helpers.py contendo uma função get_connection_personal_access_token que usa um token de acesso pessoal do Azure Databricks para retornar uma conexão a um workspace do Azure Databricks e uma função select_nyctaxi_trips que usa a conexão para obter o número especificado de linhas de dados da tabela trips no esquema samples do catálogo nyctaxi:

# helpers.py

from databricks import sql
from databricks.sql.client import Connection, List, Row, Cursor

def get_connection_personal_access_token(
  server_hostname: str,
  http_path: str,
  access_token: str
) -> Connection:
  return sql.connect(
    server_hostname = server_hostname,
    http_path = http_path,
    access_token = access_token
  )

def select_nyctaxi_trips(
  connection: Connection,
  num_rows: int
) -> List[Row]:
  cursor: Cursor = connection.cursor()
  cursor.execute("SELECT * FROM samples.nyctaxi.trips LIMIT ?", [num_rows])
  result: List[Row] = cursor.fetchall()
  return result

E dado o seguinte arquivo chamado main.py que chama as funções get_connection_personal_access_token e select_nyctaxi_trips:

# main.py

from databricks.sql.client import Connection, List, Row
import os
from helpers import get_connection_personal_access_token, select_nyctaxi_trips

connection: Connection = get_connection_personal_access_token(
  server_hostname = os.getenv("DATABRICKS_SERVER_HOSTNAME"),
  http_path = os.getenv("DATABRICKS_HTTP_PATH"),
  access_token = os.getenv("DATABRICKS_TOKEN")
)

rows: List[Row] = select_nyctaxi_trips(
  connection = connection,
  num_rows = 2
)

for row in rows:
  print(row)

O arquivo nomeado test_helpers.py a seguir testa se a função select_nyctaxi_trips retorna a resposta esperada. Em vez de criar uma conexão real com o workspace de destino, esse teste simula um objeto Connection. O teste também simula alguns dados que estão em conformidade com o esquema e os valores que estão nos dados reais. O teste retorna os dados simulados por meio da conexão simulada e verifica se um dos valores das linhas de dados simuladas corresponde ao valor esperado.

# test_helpers.py

import pytest
from databricks.sql.client import Connection, List, Row
from datetime import datetime
from helpers import select_nyctaxi_trips
from unittest.mock import create_autospec

@pytest.fixture
def mock_data() -> List[Row]:
  return [
    Row(
      tpep_pickup_datetime = datetime(2016, 2, 14, 16, 52, 13),
      tpep_dropoff_datetime = datetime(2016, 2, 14, 17, 16, 4),
      trip_distance = 4.94,
      fare_amount = 19.0,
      pickup_zip = 10282,
      dropoff_zip = 10171
    ),
    Row(
      tpep_pickup_datetime = datetime(2016, 2, 4, 18, 44, 19),
      tpep_dropoff_datetime = datetime(2016, 2, 4, 18, 46),
      trip_distance = 0.28,
      fare_amount = 3.5,
      pickup_zip = 10110,
      dropoff_zip = 10110
    )
  ]

def test_select_nyctaxi_trips(mock_data: List[Row]):
  # Create a mock Connection.
  mock_connection = create_autospec(Connection)

  # Set the mock Connection's cursor().fetchall() to the mock data.
  mock_connection.cursor().fetchall.return_value = mock_data

  # Call the real function with the mock Connection.
  response: List[Row] = select_nyctaxi_trips(
    connection = mock_connection,
    num_rows = 2)

  # Check the value of one of the mocked data row's columns.
  assert response[1].fare_amount == 3.5

Como a função select_nyctaxi_trips contém uma instrução SELECT e, portanto, não altera o estado da tabela trips, a simulação não é absolutamente necessária neste exemplo. No entanto, a simulação permite que você execute rapidamente seus testes sem esperar que uma conexão real seja feita com o workspace. Além disso, a simulação permite executar testes simulados várias vezes para funções que podem alterar o estado de uma tabela, como INSERT INTO, UPDATE e DELETE FROM.

Referência da API

Esta seção contém referência de API para o databricks-sql-connector pacote. Consulte databricks-sql-connector no PyPI (Índice de Pacotes do Python).

Módulo

O databricks.sql módulo do databricks-sql-connector pacote contém o método para inicializar uma conexão com um sql warehouse.

método de conexão

Inicializa uma conexão com um SQL Warehouse. Retorna um objeto "Connection".

Parâmetro	Tipo	Description
`server_hostname`	`str`	Obrigatório O nome do host do servidor para a computação de uso geral ou o Armazém SQL, por exemplo `adb-1234567890123456.7.azuredatabricks.net`. Para obter o nome do host do servidor, consulte as instruções em Introdução.
`http_path`	`str`	Obrigatório O caminho HTTP da computação geral ou do SQL warehouse, por exemplo `sql/protocolv1/o/1234567890123456/1234-567890-test123` para computação geral ou `/sql/1.0/warehouses/a1b234c567d8e9fa` para um SQL warehouse. Para obter o caminho HTTP, consulte as instruções em Introdução.
`access_token`, `auth_type`, `credentials_provider`, , `passwordusername`	`str`	Informações sobre as configurações de autenticação do Azure Databricks. Para obter detalhes, confira Autenticação.
`session_configuration`	`dict[str, Any]`	Um dicionário de parâmetros de configuração de sessão do Spark. Definir uma configuração é equivalente a usar o comando `SET key=val` SQL. Execute o comando `SET -v` SQL para obter uma lista completa das configurações disponíveis. Usa `None` como padrão. Exemplo: `{"spark.sql.variable.substitute": True}`
`http_headers`	`List[Tuple[str, str]]]`	Optional. Pares adicionais (chave, valor) a serem definidos em cabeçalhos HTTP em cada solicitação RPC que o cliente faz. O uso típico não definirá nenhum cabeçalho HTTP extra. Usa `None` como padrão.
`catalog`	`str`	Optional. O catálogo inicial a ser usado para a conexão. O padrão é `None` (nesse caso, o catálogo padrão, normalmente `hive_metastore`, será usado).
`schema`	`str`	Optional. Esquema inicial a ser usado para a conexão. O padrão é `None` (nesse caso, o esquema `default` padrão será usado). Desde a versão 2.0
`use_cloud_fetch`	`bool`	Optional. Se deseja enviar solicitações de busca diretamente para o repositório de objetos de nuvem para baixar partes de dados. Usa `True` como padrão. Configure para `False` enviar solicitações de busca diretamente para o Azure Databricks. Se `use_cloud_fetch` estiver definido como `True`, mas o acesso à rede estiver bloqueado, ocorrerá uma falha nas solicitações de busca. Desde a versão 2.8
`user_agent_entry`	`str`	Optional. A entrada User-Agent a ser incluída no cabeçalho de solicitação HTTP para acompanhamento de uso. Usa `PyDatabricksSqlConnector` como padrão.

`Connection` classe

Representa uma conexão com um sistema computacional ou um SQL Warehouse.

Métodos

A Connection classe fornece os métodos a seguir.

Método	Description
`close`	Fecha a conexão com o banco de dados e libera todos os recursos associados no servidor. Qualquer chamada adicional para essa conexão gerará um `Error`. Sem parâmetros. Sem valor de retorno.
`cursor`	Retorna um novo objeto Cursor que permite a passagem sobre os registros em um banco de dados. Sem parâmetros.

`Cursor` classe

Representa um mecanismo para percorrer registros de dados.

Para criar um Cursor objeto, chame o cursor método da classe Connection.

Atributos

Os atributos Cursor selecionados incluem o seguinte:

Attribute Description

arraysize Usado com o método fetchmany, especifica o tamanho do buffer interno, que também é o número de linhas que são de fato buscadas do servidor por vez. O valor padrão é 10000. Para obter resultados estreitos (os resultados em que cada linha não contém muitos dados), você deve aumentar esse valor para melhorar o desempenho. Acesso de leitura-gravação.

Attribute	Description
`arraysize`	Usado com o método `fetchmany`, especifica o tamanho do buffer interno, que também é o número de linhas que são de fato buscadas do servidor por vez. O valor padrão é `10000`. Para obter resultados estreitos (os resultados em que cada linha não contém muitos dados), você deve aumentar esse valor para melhorar o desempenho. Acesso de leitura-gravação.
`description`	Contém um Python `list` de objetos `tuple`. Cada um desses objetos `tuple` contém 7 valores, com os primeiros 2 itens de cada objeto `tuple` contendo informações que descrevem uma única coluna de resultado da seguinte maneira: `name`: o nome da coluna. `type_code`: uma cadeia de caracteres que representa o tipo da coluna. Por exemplo, uma coluna de inteiros terá um código de tipo de `int`. Os cinco itens restantes de cada objeto `tuple` de sete itens não são implementados e seus valores não são definidos. Normalmente, eles serão retornados como 4 `None` valores seguidos por um único `True` valor. Acesso somente leitura.

description

Contém um Python list de objetos tuple. Cada um desses objetos tuple contém 7 valores, com os primeiros 2 itens de cada objeto tuple contendo informações que descrevem uma única coluna de resultado da seguinte maneira:

name: o nome da coluna.
type_code: uma cadeia de caracteres que representa o tipo da coluna. Por exemplo, uma coluna de inteiros terá um código de tipo de int. Os cinco itens restantes de cada objeto tuple de sete itens não são implementados e seus valores não são definidos. Normalmente, eles serão retornados como 4 None valores seguidos por um único True valor. Acesso somente leitura.

Métodos

Os métodos Cursor selecionados incluem o seguinte:

Método	Description
`cancel`	Interrompe a execução de qualquer consulta ou comando de banco de dados que o cursor tenha iniciado. Para liberar os recursos associados no servidor, chame o `close` método depois de chamar o `cancel` método. Sem parâmetros. Sem valor de retorno.
`close`	Fecha o cursor e libera os recursos associados no servidor. Fechar um cursor já fechado pode gerar um erro. Sem parâmetros. Sem valor de retorno.
`execute`	Prepara e executa uma consulta ou comando de banco de dados. Parâmetros: `operation`:Necessário. A consulta ou o comando a ser preparado e executado. Tipo: `str` exemplo sem o `parameters` parâmetro: `cursor.execute('SELECT * FROM samples.nyctaxi.trips LIMIT 2')` Exemplo com o `parameters` parâmetro (usando parâmetros posicionais nativos): `cursor.execute('SELECT * FROM samples.nyctaxi.trips WHERE pickup_zip = ? LIMIT ?', ['10019', 2])` `parameters`: opcional. Uma sequência de parâmetros a ser usada com o parâmetro `operation`. O padrão é `None`. Digite: `dictionary` Sem valor de retorno.
`executemany`	Prepara e executa uma consulta ou comando de banco de dados usando todas as sequências de parâmetro no argumento `seq_of_parameters`. Somente o conjunto de resultados final é retido. Parâmetros: `operation`:Necessário. A consulta ou o comando a ser preparado e executado. Digite: `str` `seq_of_parameters`:Necessário. Uma sequência de muitos conjuntos de valores de parâmetro a serem usados com o `operation` parâmetro. Tipo: `list` de `dict` Sem valor de retorno.
`catalogs`	Execute uma consulta de metadados sobre os catálogos. Os resultados reais devem ser buscados usando `fetchmany` ou `fetchall`. Os campos importantes no conjunto de resultados incluem: Nome do campo: `TABLE_CAT`. O nome do catálogo. Digite: `str` Sem parâmetros. Sem valor de retorno. Desde a versão 1.0
`schemas`	Execute uma consulta de metadados sobre os esquemas. Os resultados reais devem ser buscados usando `fetchmany` ou `fetchall`. Os campos importantes no conjunto de resultados incluem: Nome do campo: `TABLE_SCHEM`. O nome do esquema. Digite: `str` Nome do campo: `TABLE_CATALOG`. O catálogo ao qual o esquema pertence. Digite: `str` Parâmetros: `catalog_name`: opcional. Um nome de catálogo sobre o que recuperar informações. O caractere `%` é interpretado como um curinga. Digite: `str` `schema_name`: opcional. Um nome de esquema sobre o que recuperar informações. O caractere `%` é interpretado como um curinga. Digite: `str` Sem valor de retorno. Desde a versão 1.0
`tables`	Execute uma consulta de metadados sobre tabelas e exibições. Os resultados reais devem ser buscados usando `fetchmany` ou `fetchall`. Os campos importantes no conjunto de resultados incluem: Nome do campo: `TABLE_CAT`. O catálogo ao qual a tabela pertence. Digite: `str` Nome do campo: `TABLE_SCHEM`. O esquema ao qual a tabela pertence. Digite: `str` Nome do campo: `TABLE_NAME`. O nome da tabela. Digite: `str` Nome do campo: `TABLE_TYPE`. O tipo de relação, por exemplo, `VIEW` ou `TABLE` (aplica-se ao Databricks Runtime 10.4 LTS e superior, bem como ao Databricks SQL; versões anteriores do Databricks Runtime retornam uma cadeia de caracteres vazia). Digite: `str` Parâmetros: `catalog_name`: opcional. Um nome de catálogo sobre o que recuperar informações. O caractere `%` é interpretado como um curinga. Digite: `str` `schema_name`: opcional. Um nome de esquema sobre o que recuperar informações. O caractere `%` é interpretado como um curinga. Digite: `str` `table_name`: opcional. Um nome de tabela do qual recuperar informações. O caractere `%` é interpretado como um curinga. Digite: `str` `table_types`: opcional. Uma lista de tipos de tabela a corresponder, por exemplo `TABLE` ou `VIEW`. Digite: `List[str]` Sem valor de retorno. Desde a versão 1.0
`columns`	Execute uma consulta de metadados sobre as colunas. Os resultados reais devem ser buscados usando `fetchmany` ou `fetchall`. Os campos importantes no conjunto de resultados incluem: Nome do campo: `TABLE_CAT`. O catálogo ao qual a coluna pertence. Digite: `str` Nome do campo: `TABLE_SCHEM`. O esquema ao qual a coluna pertence. Digite: `str` Nome do campo: `TABLE_NAME`. O nome da tabela à qual a coluna pertence. Digite: `str` Nome do campo: `COLUMN_NAME`. O nome da coluna. Digite: `str` Parâmetros: `catalog_name`: opcional. Um nome de catálogo sobre o que recuperar informações. O caractere `%` é interpretado como um curinga. Digite: `str` `schema_name`: opcional. Um nome de esquema sobre o que recuperar informações. O caractere `%` é interpretado como um curinga. Digite: `str` `table_name`: opcional. Um nome de tabela do qual recuperar informações. O caractere `%` é interpretado como um curinga. Digite: `str` `column_name`: opcional. Um nome de coluna sobre o que recuperar informações. O caractere `%` é interpretado como um curinga. Digite: `str` Sem valor de retorno. Desde a versão 1.0
`fetchall`	Obtém todas as linhas (ou todas as restantes) de uma consulta. Sem parâmetros. Retorna todas as linhas (ou as restantes) da consulta como uma coleção Python `list` de objetos `Row`. Lança um `Error` se a chamada anterior para o método `execute` não retornou nenhum dado ou nenhuma chamada `execute` ainda foi feita.
`fetchmany`	Obtém as próximas linhas de uma consulta. Parâmetros: `size`: opcional. O número de próximas linhas a obter. Se não for especificado, o valor do atributo `arraysize` será usado. Digite: `int`. Exemplo: `cursor.fetchmany(10)` Retorna até `size` (ou o atributo `arraysize`, se `size` não for especificado) as próximas linhas de uma consulta como um `list` Python de objetos `Row`. Se houver menos de `size` linhas a serem buscadas, todas as linhas restantes serão retornadas. Lança um `Error` se a chamada anterior para o método `execute` não retornou nenhum dado ou nenhuma chamada `execute` ainda foi feita.
`fetchone`	Obtém a próxima linha do conjunto de dados. Sem parâmetros. Retorna a próxima linha do conjunto de dados como uma única sequência como um objeto Python `tuple` ou retorna `None` se não houver mais dados disponíveis. Lança um `Error` se a chamada anterior para o método `execute` não retornou nenhum dado ou nenhuma chamada `execute` ainda foi feita.
`fetchall_arrow`	Obtém todas as linhas (ou todas as restantes) de uma consulta, como um objeto PyArrow `Table`. As consultas que retornam quantidades muito grandes de dados devem usar `fetchmany_arrow` para reduzir o consumo de memória. Sem parâmetros. Retorna todas as linhas (ou todas as restantes) da consulta como uma tabela PyArrow. Lança um `Error` se a chamada anterior para o método `execute` não retornou nenhum dado ou nenhuma chamada `execute` ainda foi feita. Desde a versão 2.0
`fetchmany_arrow`	Obtém as próximas linhas de uma consulta como um objeto PyArrow `Table`. Parâmetros: `size`: opcional. O número de próximas linhas a obter. Se não for especificado, o valor do atributo `arraysize` será usado. Digite: `int`. Exemplo: `cursor.fetchmany_arrow(10)` Retorna até o `size` argumento (ou o `arraysize` atributo, se `size` não for especificado) das próximas linhas de uma consulta como um objeto PyArrow `Table` do Python. Lança um `Error` se a chamada anterior para o método `execute` não retornou nenhum dado ou nenhuma chamada `execute` ainda foi feita. Desde a versão 2.0

`Row` classe

A classe de linha é uma estrutura de dados semelhante a tupla que representa uma linha de resultado individual em um resultado de consulta SQL. Se a linha contiver uma coluna com o nome "my_column", você poderá acessar o campo "my_column" de row via row.my_column. Você também pode usar indicies numéricos para acessar campos, por exemplo row[0]. Se o nome da coluna não for permitido como um nome de método de atributo (por exemplo, ele começa com um dígito), você poderá acessar o campo como row["1_my_column"].

Desde a versão 1.0

Os métodos Row selecionados incluem:

Métodos

Método	Description
`asDict`	Retorna uma representação de dicionário da linha, que é indexada por nomes de campo. Se houver nomes de campo duplicados, um dos campos duplicados (mas apenas um) será retornado no dicionário. Qual campo duplicado é retornado não está definido.

Conversões de tipo

A tabela a seguir mapeia os tipos de dados de SQL do Apache Spark para seus equivalentes de tipo de dados Python.

Tipos de dados de SQL do Apache Spark	Tipo de dados do Python
`array`	`numpy.ndarray`
`bigint`	`int`
`binary`	`bytearray`
`boolean`	`bool`
`date`	`datetime.date`
`decimal`	`decimal.Decimal`
`double`	`float`
`int`	`int`
`map`	`str`
`null`	`NoneType`
`smallint`	`int`
`string`	`str`
`struct`	`str`
`timestamp`	`datetime.datetime`
`tinyint`	`int`

Coleção de telemetria

O Conector do SQL do Databricks para Python coleta dados de telemetria para ajudar o Azure Databricks a melhorar a confiabilidade e solucionar problemas. A telemetria é habilitada por padrão e coleta os seguintes dados operacionais:

Detalhes do ambiente do cliente, como versão do driver, runtime do Python e sistema operacional
Configurações de conexão do driver (excluindo qualquer informação de identificação pessoal)
Medidas de latência da operação
Formatos de resultado de execução, como JSON em linha ou Apache Arrow
Tipos de operação, como execução de consulta, consultas de metadados ou operações de volume
Dados de classificação de erro
Contagens de repetição

Importante

O Azure Databricks não coleta conteúdo de consulta, resultados de consulta ou qualquer PII (informações de identificação pessoal) por meio da telemetria.

Para desabilitar a coleta de telemetria, defina o parâmetro enable_telemetry como 0 ao criar uma conexão.

Solução de problemas

`tokenAuthWrapperInvalidAccessToken: Invalid access token` mensagem

Problema: ao executar seu código, você vê uma mensagem semelhante a Error during request to server: tokenAuthWrapperInvalidAccessToken: Invalid access token.

Causa possível: o valor passado para access_token não é um token de acesso pessoal válido do Azure Databricks.

Correção recomendada: verifique se o valor passado para access_token está correto e tente novamente.

`gaierror(8, 'nodename nor servname provided, or not known')` mensagem

Problema: ao executar seu código, você vê uma mensagem semelhante a Error during request to server: gaierror(8, 'nodename nor servname provided, or not known').

Causa possível: o valor passado para server_hostname não é o nome do host correto.

Correção recomendada: verifique se o valor passado para server_hostname está correto e tente novamente.

Para obter mais informações sobre como localizar o nome do host do servidor, confira Obter detalhes de conexão para um recurso de computação do Azure Databricks.

`IpAclError` mensagem

Problema: quando você executar seu código, verá a mensagem Error during request to server: IpAclValidation ao tentar usar o conector em um notebook do Azure Databricks.

Causa possível: você pode ter a listagem de permitir IP habilitada para o workspace do Azure Databricks. Com a listagem de permissão de IP, as conexões de clusters Spark de volta para o plano de controle não são permitidas por padrão.

Correção recomendada: peça ao administrador para adicionar a sub-rede do plano de computação à lista de permissões de IP.

Recursos adicionais

Para obter mais informações, consulte:

O repositório do Conector do Databricks SQL para Python no GitHub
Tipos de dados
Tipos integrados (para bool, bytearray, float, int, e str) no site do Python
datetime (para datetime.date e datatime.datetime) no site do Python
decimal (para decimal.Decimal) no site do Python
Constantes integrados (para NoneType) no site do Python

Comentários

Esta página foi útil?

Last updated on 2025-10-31

Compartilhar via

Conector do Databricks SQL para Python

Requisitos

Introdução

Computação para todos os fins

SQL Warehouse

Autenticação

Autenticação de token de acesso pessoal do Databricks

Autenticação M2M (de computador para computador) do OAuth

Autenticação de token do Microsoft Entra ID

Autenticação U2M (usuário para computador) do OAuth

Exemplos

Definir agente do usuário

Consultar dados

Marcas de consulta

Inserir dados

Consultar metadados

Gerenciar cursores e conexões

Gerenciar arquivos em volumes do Catálogo do Unity

Configurar o registro em log

Testando

Referência da API

Módulo

método de conexão

Connection classe

Métodos

Cursor classe

Atributos

Métodos

Row classe

Métodos

Conversões de tipo

Coleção de telemetria

Solução de problemas

tokenAuthWrapperInvalidAccessToken: Invalid access token mensagem

gaierror(8, 'nodename nor servname provided, or not known') mensagem

IpAclError mensagem

Recursos adicionais

Comentários

Recursos adicionais

`Connection` classe

`Cursor` classe

`Row` classe

`tokenAuthWrapperInvalidAccessToken: Invalid access token` mensagem

`gaierror(8, 'nodename nor servname provided, or not known')` mensagem

`IpAclError` mensagem