Databricks SQL Connector para Python

O Databricks SQL Connector for Python é uma biblioteca Python que permite usar o código Python para executar comandos SQL no Azure Databricks all-purpose compute e Databricks SQL warehouses. O Databricks SQL Connector for Python é mais fácil de configurar e usar do que bibliotecas Python semelhantes, como pyodbc. Esta biblioteca segue PEP 249 – Python Database API Specification v2.0.

Importante

O Databricks SQL Connector para Python versão 3.0.0 e superior suporta a execução de consultas parametrizadas nativas, o que impede a injeção de SQL e pode melhorar o desempenho da consulta. As versões anteriores usavam execução parametrizada em linha, que não é segura contra injeção de SQL e tem outras desvantagens. Para obter mais informações, consulte Usando parâmetros nativos.

O Databricks SQL Connector for Python também dá suporte ao dialeto SQLAlchemy para Azure Databricks, mas deve ser instalado para usar esses recursos. Consulte Utilizar SQLAlchemy com Azure Databricks.

Requisitos

Uma máquina de desenvolvimento executando Python 3.8 e superior.
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 armazém SQL ou computação multiusos existente.

Introdução

Instale o Databricks SQL Connector para Python. PyArrow é uma dependência opcional do Databricks SQL Connector para Python e não é instalado por padrão na versão 4.0.0 e superior do conector. Se o PyArrow não estiver instalado, recursos como o 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", utilize:
```
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 multiuso ou o SQL warehouse que você deseja usar:

Computação polivalente
- O nome do anfitrião do servidor de computação geral. Você pode obtê-lo a partir do valor Nome do host do servidor na guia Opções > avançadas JDBC/ODBC para sua computação para todos os fins.
- O caminho HTTP da computação multiuso. Este valor pode ser encontrado no HTTP Path na aba Advanced Options > JDBC/ODBC para o seu ambiente de computação geral.
Nota

O conector SQL não suporta a conexão com a computação de trabalhos.

Armazém SQL
- O nome de host do servidor do SQL warehouse. Você pode obter isso a partir do valor de Hostname do Servidor no separador Detalhes da Conexão para o seu armazen de dados SQL.
- O caminho HTTP do SQL warehouse. Você pode obter isto a partir do valor Caminho HTTP na aba Detalhes da Conexão para o seu armazém de dados SQL.

Autenticação

O Databricks SQL Connector for Python suporta os seguintes tipos de autenticação do Azure Databricks:

Autenticação com token de acesso pessoal do Databricks
Autenticação de token do Microsoft Entra ID
Autenticação máquina a máquina (M2M) OAuth
Autenticação OAuth utilizador-para-máquina (U2M)

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

Autenticação de token pessoal de acesso do Databricks

Para usar o Databricks SQL Connector for Python com a autenticação de token de acesso pessoal do Azure Databricks, deverá 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 espaço de trabalho.

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

DATABRICKS_SERVER_HOSTNAMEdefinido como o valor Nome do host do servidor para a sua computação multiuso ou armazém de dados SQL.
DATABRICKS_HTTP_PATH, definido como o valor de caminho HTTP para a sua computação geral ou armazém de dados SQL.
DATABRICKS_TOKEN, definido como o token de acesso pessoal do Azure Databricks.

Para definir variáveis de ambiente, consulte a documentação do seu 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 OAuth máquina-a-máquina (M2M)

O Databricks SQL Connector para Python da versão 2.7.0 em diante suporta a autenticação máquina-a-máquina (M2M) OAuth. Você também deve 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 Databricks SQL Connector para Python com autenticação OAuth M2M, você deve fazer o seguinte:

Crie uma entidade de serviço do Azure Databricks em seu espaço de trabalho do Azure Databricks e crie um segredo OAuth para essa entidade de serviço.

Para criar o principal de serviço e o respetivo segredo OAuth, consulte Autorizar o acesso do principal de serviço ao Azure Databricks com OAuth. Anote o valor UUID ou ID do aplicativo da entidade de serviço e o valor Secret do segredo OAuth da entidade de serviço.
Dê a essa entidade de serviço acesso à sua infraestrutura multiuso ou armazém de dados.

Para dar à entidade de serviço acesso à sua computação ou armazém para todos os fins, consulte Permissões de computação ou Gerir um armazém SQL.

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

DATABRICKS_SERVER_HOSTNAME definido como o valor Nome do host do servidor para sua computação multiuso ou SQL warehouse.
DATABRICKS_HTTP_PATH, definido como o valor de caminho HTTP para a sua computação geral ou armazém de dados SQL.
DATABRICKS_CLIENT_ID, definido como o UUID ou o ID da aplicação da entidade de serviço.
DATABRICKS_CLIENT_SECRET, definido para o valor Secret do segredo OAuth da entidade de serviço.

Para definir variáveis de ambiente, consulte a documentação do seu 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 Databricks SQL Connector for Python com autenticação de token de ID do Microsoft Entra, você deve fornecer o Databricks SQL Connector for Python com o token de ID do Microsoft Entra. Para criar um token de acesso do Microsoft Entra ID, faça o seguinte:

Para um utilizador do Azure Databricks, pode usar a CLI do Azure. Consulte Obter tokens de ID do Microsoft Entra manualmente.
Para uma entidade de serviço do Microsoft Entra ID, consulte Obter tokens para entidades de serviço. Para criar um principal de serviço gerido pelo Microsoft Entra ID, consulte Principais de serviço.

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

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

Defina DATABRICKS_SERVER_HOSTNAME como o valor Nome do host do servidor para sua computação geral ou armazém SQL.
Defina o valor de DATABRICKS_HTTP_PATH para a sua computação de uso geral ou armazém de dados SQL.
Defina DATABRICKS_TOKEN para o token de ID do Microsoft Entra.

Para definir variáveis de ambiente, consulte a documentação do seu 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 OAuth de utilizador para máquina (U2M)

O Databricks SQL Connector para Python a partir da versão 2.7.0 suporta autenticação OAuth user-to-machine (U2M). Você também deve 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 Databricks SQL Connector for Python com autenticação OAuth U2M, use o seguinte trecho de código. A autenticação OAuth U2M usa o logon humano em tempo real e o consentimento para autenticar a conta de usuário de destino do Azure Databricks. Este trecho pressupõe que você tenha definido as seguintes variáveis de ambiente:

Defina DATABRICKS_SERVER_HOSTNAME como o valor Nome do host do servidor para sua computação geral ou armazém SQL.
Defina o valor de DATABRICKS_HTTP_PATH para a sua computação de uso geral ou armazém de dados SQL.

Para definir variáveis de ambiente, consulte a documentação do seu 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 Databricks SQL Connector for Python para consultar e inserir dados, consultar metadados, gerenciar cursores e conexões, gerenciar arquivos no Unity Catalog e configurar o registro em log.

Nota

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

Estes exemplos de código recuperam seus valores de variáveis de conexão server_hostname, http_pathe access_token destas variáveis de ambiente:

DATABRICKS_SERVER_HOSTNAME, que representa o valor do Server Hostname a partir dos requisitos.
DATABRICKS_HTTP_PATH, que representa o valor de caminho HTTP dos requisitos.
DATABRICKS_TOKEN, que representa o seu token de acesso nos requisitos.

Definir User-Agent

O exemplo de código a seguir demonstra como definir o User-Agent aplicativo product_name para controle 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 os dados

O exemplo de código a seguir demonstra como chamar o Databricks SQL Connector for Python para executar um comando SQL básico em computação multiuso ou SQL warehouse. Este 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)

Tags de consulta

Importante

Esta funcionalidade está em Pré-visualização Privada. Para solicitar acesso, entre em contato com a equipe da sua conta.

O exemplo a seguir mostra como anexar tags de chave-valor às suas consultas SQL para fins de controle e análise. As tags 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 para o armazenamento em nuvem e, em seguida, executar o comando COPY INTO.

Consultar metadados

Existem 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 prática recomendada fechar quaisquer conexões e cursores que não estejam mais em uso. Isso libera recursos na computação multiuso do Azure Databricks e nos armazéns SQL do Databricks.

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

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 Unity

O Databricks SQL Connector permite gravar arquivos locais no Unity Catalog volumes, baixar arquivos de volumes e excluir 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 registo de logs

O Databricks SQL Connector usa o módulo de log padrão do Python. O exemplo a seguir configura o nível de log 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()

Testes

Para testar seu código, use estruturas de teste Python como pytest. Para testar o 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, pode utilizar bibliotecas de simulação Python como unittest.mock.

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

# 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 ficheiro 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 a seguir chamado test_helpers.py testa se a select_nyctaxi_trips função retorna a resposta esperada. Em vez de criar uma conexão real com o espaço de trabalho de destino, esse teste simula um Connection objeto. 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, em seguida, 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 espaço de trabalho. Além disso, a simulação permite que você execute testes simulados várias vezes para funções que podem alterar o estado de uma tabela, como INSERT INTO, UPDATEe DELETE FROM.

Referência da API

Esta seção contém referência de API para o databricks-sql-connector pacote. Veja databricks-sql-connector no Python Package Index (PyPI).

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 Ligação

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

Parâmetro	Tipo	Description
`server_hostname`	`str`	Required. O nome de host do servidor para a computação multiuso ou SQL warehouse, por exemplo `adb-1234567890123456.7.azuredatabricks.net`. Para obter o nome de host do servidor, consulte as instruções em Introdução.
`http_path`	`str`	Required. O caminho HTTP da computação geral ou do armazém de dados SQL, por exemplo `sql/protocolv1/o/1234567890123456/1234-567890-test123` para computação geral ou `/sql/1.0/warehouses/a1b234c567d8e9fa` para um armazém de dados SQL. Para obter o caminho HTTP, consulte as instruções em Introdução.
`access_token`, `auth_type`, `credentials_provider`, `password`, `username`	`str`	Informações sobre as configurações de autenticação do Azure Databricks. Para obter detalhes, consulte 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 `SET key=val` comando SQL. Execute o comando SQL `SET -v` para obter uma lista completa das configurações disponíveis. O padrão é `None`. Exemplo: `{"spark.sql.variable.substitute": True}`
`http_headers`	`List[Tuple[str, str]]]`	Opcional. Pares adicionais (chave, valor) para definir em cabeçalhos HTTP em cada solicitação RPC feita pelo cliente. O uso típico não irá definir cabeçalhos HTTP adicionais. O padrão é `None`.
`catalog`	`str`	Opcional. 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`	Opcional. Esquema inicial a ser usado para a conexão. O padrão é `None` (caso em que o esquema predefinido `default` será usado). Desde a versão 2.0
`use_cloud_fetch`	`bool`	Opcional. Se deseja enviar solicitações de busca diretamente para o armazenamento de objetos na nuvem para baixar partes de dados. O padrão é `True`. Defina como `False` para enviar solicitações de busca diretamente para o Azure Databricks. Se `use_cloud_fetch` estiver definido como `True` mas o acesso à rede estiver bloqueado, as solicitações de busca falharão. Desde a versão 2.8
`user_agent_entry`	`str`	Opcional. A entrada User-Agent a ser incluída no cabeçalho da solicitação HTTP para controle de uso. O padrão é `PyDatabricksSqlConnector`.

`Connection` Classe

Representa uma conexão com computação ou um SQL warehouse.

Métodos

A Connection classe fornece os seguintes métodos.

Método	Description
`close`	Fecha a conexão com o banco de dados e libera todos os recursos associados no servidor. Quaisquer chamadas adicionais para esta conexão lançarão uma exceção `Error`. Sem parâmetros. Sem valor de retorno.
`cursor`	Retorna um novo objeto Cursor que permite percorrer os registos em um banco de dados. Sem parâmetros.

`Cursor` Classe

Representa um mecanismo para percorrer registos de dados.

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

Atributos

Os atributos selecionados Cursor incluem o seguinte:

Attribute Description

arraysize Usado com o fetchmany método, especifica o tamanho do buffer interno, que também é quantas linhas são realmente buscadas do servidor de cada vez. O valor predefinido é 10000. Para resultados estreitos (resultados em que cada linha não contém muitos dados), você deve aumentar esse valor para obter um melhor desempenho. Acesso de leitura e gravação.

Attribute	Description
`arraysize`	Usado com o `fetchmany` método, especifica o tamanho do buffer interno, que também é quantas linhas são realmente buscadas do servidor de cada vez. O valor predefinido é `10000`. Para resultados estreitos (resultados em que cada linha não contém muitos dados), você deve aumentar esse valor para obter um melhor desempenho. Acesso de leitura e gravação.
`description`	Contém objetos Python `list` de `tuple`. Cada um desses objetos `tuple` contém 7 valores, com os 2 primeiros 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 inteira terá um código de tipo de `int`. Os 5 itens restantes de cada objeto de `tuple` de 7 itens não são implementados e seus valores não são definidos. Eles normalmente serão retornados como 4 `None` valores seguidos por um único `True` valor. Acesso somente leitura.

description

Contém objetos Python list de tuple. Cada um desses objetos tuple contém 7 valores, com os 2 primeiros 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 inteira terá um código de tipo de int. Os 5 itens restantes de cada objeto de tuple de 7 itens não são implementados e seus valores não são definidos. Eles normalmente serão retornados como 4 None valores seguidos por um único True valor. Acesso somente leitura.

Métodos

Os métodos selecionados Cursor incluem o seguinte:

Método	Description
`cancel`	Interrompe a execução de qualquer consulta ou comando de banco de dados iniciado pelo cursor. 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 comando que deve 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 para usar com o parâmetro `operation`. A predefinição é `None`. Tipo: `dictionary` Sem valor de retorno.
`executemany`	Prepara e executa uma consulta ou comando de banco de dados usando todas as sequências de parâmetros no `seq_of_parameters` argumento. Apenas o conjunto de resultados finais é mantido. Parâmetros: `operation`:Necessário. A consulta ou comando que deve ser preparado e executado. Tipo: `str` `seq_of_parameters`:Necessário. Uma sequência de muitos conjuntos de valores de parâmetros para usar 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 então ser obtidos usando `fetchmany` ou `fetchall`. Os campos importantes no conjunto de resultados incluem: Nome do campo: `TABLE_CAT`. O nome do catálogo. Tipo: `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 então ser obtidos usando `fetchmany` ou `fetchall`. Os campos importantes no conjunto de resultados incluem: Nome do campo: `TABLE_SCHEM`. O nome do esquema. Tipo: `str` Nome do campo: `TABLE_CATALOG`. O catálogo ao qual o esquema pertence. Tipo: `str` Parâmetros: `catalog_name`: Opcional. Um nome de catálogo sobre o qual recuperar informações. O `%` carácter é interpretado como um curinga. Tipo: `str` `schema_name`: Opcional. Um nome de esquema para recuperar informações sobre. O `%` carácter é interpretado como um curinga. Tipo: `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 então ser obtidos 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. Tipo: `str` Nome do campo: `TABLE_SCHEM`. O esquema ao qual a tabela pertence. Tipo: `str` Nome do campo: `TABLE_NAME`. O nome da tabela. Tipo: `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). Tipo: `str` Parâmetros: `catalog_name`: Opcional. Um nome de catálogo sobre o qual recuperar informações. O `%` carácter é interpretado como um curinga. Tipo: `str` `schema_name`: Opcional. Um nome de esquema para recuperar informações sobre. O `%` carácter é interpretado como um curinga. Tipo: `str` `table_name`: Opcional. Um nome de tabela para obter informações sobre. O `%` carácter é interpretado como um curinga. Tipo: `str` `table_types`: Opcional. Uma lista de tipos de tabela a serem correspondentes, por exemplo, `TABLE` ou `VIEW`. Tipo: `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 então ser obtidos 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. Tipo: `str` Nome do campo: `TABLE_SCHEM`. O esquema ao qual a coluna pertence. Tipo: `str` Nome do campo: `TABLE_NAME`. O nome da tabela à qual a coluna pertence. Tipo: `str` Nome do campo: `COLUMN_NAME`. O nome da coluna. Tipo: `str` Parâmetros: `catalog_name`: Opcional. Um nome de catálogo sobre o qual recuperar informações. O `%` carácter é interpretado como um curinga. Tipo: `str` `schema_name`: Opcional. Um nome de esquema para recuperar informações sobre. O `%` carácter é interpretado como um curinga. Tipo: `str` `table_name`: Opcional. Um nome de tabela para obter informações sobre. O `%` carácter é interpretado como um curinga. Tipo: `str` `column_name`: Opcional. Um nome de coluna sobre o qual recuperar informações. O `%` carácter é interpretado como um curinga. Tipo: `str` Sem valor de retorno. Desde a versão 1.0
`fetchall`	Obtém todas as linhas (ou todas as linhas restantes) de uma consulta. Sem parâmetros. Retorna todas (ou todas as linhas restantes) da consulta como um Python `list` de `Row` objetos. Lança um `Error` se a chamada anterior para o `execute` método não retornou nenhum dado ou nenhuma `execute` chamada ainda foi feita.
`fetchmany`	Obtém as próximas linhas de uma consulta. Parâmetros: `size`: Opcional. O número de linhas seguintes a obter. Se não for especificado, o valor do `arraysize` atributo será usado. Tipo: `int`. Exemplo: `cursor.fetchmany(10)` Retorna até `size` (ou o atributo `arraysize` se `size` não for especificado) das linhas seguintes 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 `execute` método não retornou nenhum dado ou nenhuma `execute` chamada 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 `execute` método não retornou nenhum dado ou nenhuma `execute` chamada ainda foi feita.
`fetchall_arrow`	Obtém todas (ou todas as linhas restantes) de uma consulta, como um objeto PyArrow `Table` . No caso de consultas que retornam grandes quantidades de dados, deve-se utilizar `fetchmany_arrow` para reduzir o consumo de memória. Sem parâmetros. Retorna todas (ou todas as linhas restantes) da consulta como uma tabela PyArrow. Lança um `Error` se a chamada anterior para o `execute` método não retornou nenhum dado ou nenhuma `execute` chamada 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 linhas seguintes a obter. Se não for especificado, o valor do `arraysize` atributo será usado. Tipo: `int`. Exemplo: `cursor.fetchmany_arrow(10)` Retorna até ao `size` argumento (ou o `arraysize` atributo se `size` não for especificado) das próximas linhas de uma consulta como um objeto Python PyArrow `Table`. Lança um `Error` se a chamada anterior para o `execute` método não retornou nenhum dado ou nenhuma `execute` chamada ainda foi feita. Desde a versão 2.0

`Row` Classe

A classe row é uma estrutura de dados semelhante a uma 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", pode aceder ao campo "my_column" de row através de row.my_column. Você também pode usar índices 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 selecionados Row 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 campos duplicados, um dos campos duplicados (mas apenas um) será retornado no dicionário. O campo duplicado retornado não está definido.

Conversões de tipos

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

Tipo de dados Apache Spark SQL	Tipo de dados 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`

Recolha de telemetria

O Databricks SQL Connector para Python recolhe dados de telemetria para ajudar o Azure Databricks a melhorar a fiabilidade e a resolver problemas. A telemetria está ativada por defeito e recolhe os seguintes dados operacionais:

Detalhes do ambiente cliente, como versão do driver, runtime em Python e sistema operativo
Configurações de ligação do driver (excluindo qualquer informação pessoalmente identificável)
Medições de latência de operação
Formatos de resultados de execução, como JSON inline ou Apache Arrow
Tipos de operações, como execução de consultas, consultas de metadados ou operações de volume
Dados de classificação de erros
Contagem de repetições

Importante

O Azure Databricks não recolhe conteúdo de consultas, resultados de consulta ou qualquer informação pessoal identificável (PII) através de telemetria.

Para desativar a recolha de telemetria, defina o enable_telemetry parâmetro para 0 ao criar uma ligação.

Resolução de Problemas

`tokenAuthWrapperInvalidAccessToken: Invalid access token` Mensagem

Problema: quando executa o código, vê uma mensagem semelhante a Error during request to server: tokenAuthWrapperInvalidAccessToken: Invalid access token.

Possível causa: 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: quando executa o código, 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 de 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 de host do servidor, consulte Obter detalhes de conexão para um recurso de computação do Azure Databricks.

`IpAclError` Mensagem

Problema: quando executas o teu código, vês a mensagem Error during request to server: IpAclValidation quando tentas usar o conector num bloco de notas do Azure Databricks.

Possível causa: você pode ter a listagem de permissões de IP habilitada para o espaço de trabalho do Azure Databricks. Com a lista de permissões de IP, as conexões dos clusters Spark de volta ao plano de controlo 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 Databricks SQL Connector 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 (relativo a ) no site do Python
Constantes incorporadas (para NoneType) no site da Python

Comentários

Esta página foi útil?

Last updated on 2025-10-31

Partilhar via

Databricks SQL Connector para Python

Requisitos

Introdução

Computação polivalente

Armazém SQL

Autenticação

Autenticação de token pessoal de acesso do Databricks

Autenticação OAuth máquina-a-máquina (M2M)

Autenticação de token do Microsoft Entra ID

Autenticação OAuth de utilizador para máquina (U2M)

Exemplos

Definir User-Agent

Consultar os dados

Tags de consulta

Inserir dados

Consultar metadados

Gerenciar cursores e conexões

Gerenciar arquivos em volumes do catálogo Unity

Configurar registo de logs

Testes

Referência da API

Módulo

Método de Ligação

Connection Classe

Métodos

Cursor Classe

Atributos

Métodos

Row Classe

Métodos

Conversões de tipos

Recolha de telemetria

Resoluçã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