Partilhar via

Databricks SQL Connector para Python

  • Artigo

O Databricks SQL Connector for Python é uma biblioteca Python que permite usar o código Python para executar comandos SQL em clusters do Azure Databricks e armazéns SQL Databricks. 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.

Nota

O Databricks SQL Connector para Python também inclui um dialeto SQLAlchemy para Azure Databricks. Consulte Usar SQLAlchemy com o Azure Databricks.

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 a biblioteca Databricks SQL Connector for Python em sua máquina de desenvolvimento executando pip install databricks-sql-connector ou python -m pip install 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 Databricks SQL Connector for Python suporta os seguintes tipos de autenticação do Azure Databricks:

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

Autenticação de token de acesso pessoal Databricks

Para usar o Databricks SQL Connector for Python com a autenticação de token de acesso pessoal do Azure Databricks, você deve primeiro criar um token de acesso pessoal do Azure Databricks, da seguinte maneira:

  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 o seguinte:

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 seu cluster ou SQL warehouse.
  • DATABRICKS_HTTP_PATH, definido como o valor Caminho HTTP para seu cluster 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 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 versões 2.7.0 e superiores suporta autenticação OAuth máquina-a-máquina (M2M). 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:

  1. 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 a entidade de serviço e seu segredo OAuth, consulte Usar uma entidade de serviço para autenticar com o Azure Databricks. 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.

  2. Dê a essa entidade de serviço acesso ao seu cluster ou depósito.

    Para conceder à entidade de serviço acesso ao cluster ou depósito, consulte Permissões de computação ou Gerenciar um depósito 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_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_CLIENT_ID, definido como o valor UUID ou ID do aplicativo da entidade de serviço.
  • DATABRICKS_CLIENT_SECRET, definido como o valor Secret para o 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 Microsoft Entra ID (anteriormente Azure Ative Directory)

Para usar o Databricks SQL Connector for Python com autenticação de token do Microsoft Entra ID (anteriormente Azure Ative Directory), 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:

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 seu cluster ou SQL warehouse.
  • Defina DATABRICKS_HTTP_PATH como Valor de caminho HTTP para seu cluster ou SQL warehouse.
  • Defina DATABRICKS_TOKEN como 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 user-to-machine (U2M)

O Databricks SQL Connector para Python versões 2.7.0 e superiores 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 seu cluster ou SQL warehouse.
  • Defina DATABRICKS_HTTP_PATH como Valor de caminho HTTP para seu cluster ou SQL warehouse.

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 e configurar o 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 outros tipos de autenticação disponíveis do Azure Databricks, consulte Autenticação.

Estes exemplos de código recuperam seus server_hostnamevalores de variável , http_pathe connection access_token destas variáveis de ambiente:

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

Você pode usar outras abordagens para recuperar esses valores de variáveis de conexão. O uso de variáveis de ambiente é apenas uma abordagem entre muitas.

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 um cluster ou armazém SQL. Este comando retorna as duas primeiras linhas da trips tabela no samples esquema do nyctaxi catálogo.

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)

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)]
    values = ",".join([f"({x}, {y})" for (x, y) in squares])

    cursor.execute(f"INSERT INTO squares VALUES {values}")

    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 .

Metadados de consulta

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 em clusters do Azure Databricks e 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 em volumes do Unity Catalog, 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_allows_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_allows_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 '/temp/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

O Databricks SQL Connector usa o módulo de log padrão do Python. Você pode configurar o nível de log semelhante ao seguinte:

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()

Testar

Para testar seu código, use estruturas de teste Python como pytest. Para testar seu código em condições simuladas sem chamar pontos de extremidade da API REST do Azure Databricks ou alterar o estado de suas contas ou espaços de trabalho do Azure Databricks, você pode usar bibliotecas simuladas do 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(f"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 get_connection_personal_access_token funções 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 select_nyctaxi_trips função contém uma SELECT instrução e, portanto, não altera o estado da tabela, a trips 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

Pacote

databricks-sql-connector

Utilização: pip install databricks-sql-connector

Consulte também databricks-sql-connector no Python Package Index (PyPI).

Módulo

databricks.sql

Utilização: from databricks import sql

Classes

As classes selecionadas incluem o seguinte:

Classes
Connection

Uma sessão em um recurso de computação do Azure Databricks.
Cursor

Um mecanismo para percorrer registos de dados.
Row

Uma linha de dados em um resultado de consulta SQL.

Connection Classe

Para criar um Connection objeto, chame o databricks.sql.connect método com os seguintes parâmetros:

Parâmetros
server_hostname

Tipo: str

O nome do host do servidor para o cluster ou SQL warehouse. Para obter o nome de host do servidor, consulte as instruções anteriormente neste artigo.

Este parâmetro é obrigatório.

Exemplo: adb-1234567890123456.7.azuredatabricks.net
http_path

Tipo: str

O caminho HTTP do cluster ou do SQL warehouse. Para obter o caminho HTTP, consulte as instruções anteriormente neste artigo.

Este parâmetro é obrigatório.

Exemplo:
sql/protocolv1/o/1234567890123456/1234-567890-test123 para um cluster.
/sql/1.0/warehouses/a1b234c567d8e9fa para um armazém SQL.
access_token, auth_type

Tipo: str

Informações sobre as configurações de autenticação do Azure Databricks. Para obter detalhes, consulte Autenticação.
session_configuration

Tipo: 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 SET -v SQL para obter uma lista completa das configurações disponíveis.

O padrão é None.

Este parâmetro é opcional.

Exemplo: {"spark.sql.variable.substitute": True}
http_headers

Tipo: List[Tuple[str, str]]]

Pares adicionais (chave, valor) para definir em cabeçalhos HTTP em cada solicitação RPC feita pelo cliente. O uso típico não definirá cabeçalhos HTTP extras. O padrão é None.

Este parâmetro é opcional.

Desde a versão 2.0
catalog

Tipo: str

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).

Este parâmetro é opcional.

Desde a versão 2.0
schema

Tipo: str

Esquema inicial a ser usado para a conexão. O padrão é ( None nesse caso, o esquema default padrão será usado).

Este parâmetro é opcional.

Desde a versão 2.0
use_cloud_fetch

Tipo: bool

True para enviar solicitações de busca diretamente para o armazenamento de objetos na nuvem para baixar partes de dados. False (o padrão) 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

Os métodos selecionados Connection incluem o seguinte:

Métodos
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 um Errorarquivo .

Sem parâmetros.

Sem valor de retorno.
cursor

Retorna um novo Cursor objeto que permite a travessia sobre os registros em um banco de dados.

Sem parâmetros.

Cursor Classe

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

Os atributos selecionados Cursor incluem o seguinte:

Atributos
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-gravação.
description

Contém um Python list de tuple objetos. Cada um desses tuple objetos contém 7 valores, com os primeiros 2 itens de cada tuple objeto contendo informações descrevendo 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 inttipo de .

Os 5 itens restantes de cada objeto de 7 itens tuple não são implementados e seus valores não são definidos. Eles normalmente serão devolvidos como 4
None valores seguidos de um único True valor.

Acesso somente leitura.

Os métodos selecionados Cursor incluem o seguinte:

Métodos
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 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.

Sem valor de retorno.

Parâmetros:

operation

Tipo: str

A consulta ou comando a ser preparado e executado.

Este parâmetro é obrigatório.

Exemplo sem o parameters parâmetro:


cursor.execute(
'SELECT * FROM samples.nyctaxi.trips WHERE pickup_zip="10019" LIMIT 2'
)

Exemplo com o parameters parâmetro:


cursor.execute(
'SELECT * FROM samples.nyctaxi.trips WHERE zip=%(pickup_zip)s LIMIT 2',
{ 'pickup_zip': '10019' }
)

parameters

Tipo: dicionário

Uma sequência de parâmetros para usar com o operation parâmetro.

Este parâmetro é opcional. A predefinição é None.
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.

Sem valor de retorno.

Parâmetros:

operation

Tipo: str

A consulta ou comando a ser preparado e executado.

Este parâmetro é obrigatório.

seq_of_parameters

Tipo: list de dict

Uma sequência de muitos conjuntos de valores de parâmetros para usar com o
operation parâmetro.

Este parâmetro é obrigatório.
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. Tipo: str. O nome do catálogo.

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. Tipo: str. O nome do esquema.
* Nome do campo: TABLE_CATALOG. Tipo: str. O catálogo ao qual o esquema pertence.

Sem valor de retorno.

Desde a versão 1.0

Parâmetros:

catalog_name

Tipo: str

Um nome de catálogo sobre o qual recuperar informações. O % personagem é interpretado como um curinga.

Este parâmetro é opcional.

schema_name

Tipo: str

Um nome de esquema para recuperar informações sobre. O % personagem é interpretado como um curinga.

Este parâmetro é opcional.
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. Tipo: str. O catálogo ao qual a tabela pertence.
* Nome do campo: TABLE_SCHEM. Tipo: str. O esquema ao qual a tabela pertence.
* Nome do campo: TABLE_NAME. Tipo: str. O nome da tabela.
* Nome do campo: TABLE_TYPE. Tipo: str. 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).

Sem valor de retorno.

Desde a versão 1.0

Parâmetros

catalog_name

Tipo: str

Um nome de catálogo sobre o qual recuperar informações. O % personagem é interpretado como um curinga.

Este parâmetro é opcional.

schema_name

Tipo: str

Um nome de esquema para recuperar informações sobre. O % personagem é interpretado como um curinga.

Este parâmetro é opcional.

table_name

Tipo: str

Um nome de tabela para recuperar informações sobre. O % personagem é interpretado como um curinga.

Este parâmetro é opcional.

table_types

Tipo: List[str]

Uma lista de tipos de tabela a serem correspondidos, por exemplo TABLE ou VIEW.

Este parâmetro é opcional.
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. Tipo: str. O catálogo ao qual a coluna pertence.
* Nome do campo: TABLE_SCHEM. Tipo: str. O esquema ao qual a coluna pertence.
* Nome do campo: TABLE_NAME. Tipo: str. O nome da tabela à qual a coluna pertence.
* Nome do campo: COLUMN_NAME. Tipo: str. O nome da coluna.

Sem valor de retorno.

Desde a versão 1.0

Parâmetros:

catalog_name

Tipo: str

Um nome de catálogo sobre o qual recuperar informações. O % personagem é interpretado como um curinga.

Este parâmetro é opcional.

schema_name

Tipo: str

Um nome de esquema para recuperar informações sobre. O % personagem é interpretado como um curinga.

Este parâmetro é opcional.

table_name

Tipo: str

Um nome de tabela para recuperar informações sobre. O % personagem é interpretado como um curinga.

Este parâmetro é opcional.

column_name

Tipo: str

Um nome de coluna sobre o qual recuperar informações. O % personagem é interpretado como um curinga.

Este parâmetro é opcional.
fetchall

Obtém todas (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.

Retorna até size (ou o arraysize atributo se size não for especificado) das próximas linhas de uma consulta como um Python list de Row objetos.

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.

Parâmetros:

size

Tipo: int

O número de próximas linhas a obter.

Este parâmetro é opcional. Se não for especificado, o valor do arraysize atributo será usado.

Exemplo: cursor.fetchmany(10)
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 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 . As consultas que retornam grandes quantidades de dados devem ser usadas 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 .

Retorna até o size argumento (ou o arraysize atributo se size não for especificado) das próximas linhas de uma consulta como um Python PyArrow
Table objeto.

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

Parâmetros:

size

Tipo: int

O número de próximas linhas a obter.

Este parâmetro é opcional. Se não for especificado, o valor do arraysize atributo será usado.

Exemplo: cursor.fetchmany_arrow(10)

Row Classe

A classe row é uma estrutura de dados semelhante a uma tupla que representa uma linha de resultado individual. Se a linha contiver uma coluna com o nome "my_column", você pode acessar o "my_column" campo de row via 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:

| 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.

Sem parâmetros.

Devolve um dict dos campos. |

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

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 você executa seu código, vê a mensagem Error during request to server: IpAclValidation quando tenta usar o conector em um bloco de anotações 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 listagem de permissões de IP, as conexões dos clusters do Spark de volta ao 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: