Compartilhar via

Conector do Databricks SQL para Python

  • Artigo

O Conector do Databricks SQL para Python é uma biblioteca Python que permite a você usar o código Python para executar comandos SQL em clusters do Azure Databricks e em warehouses do Databricks SQL. 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.

Observação

O Conector do SQL do Databricks para Python também inclui um dialeto SQLAlchemy para o Azure Databricks. Confira Usar SQLAlchemy com o Azure Databricks.

Requisitos

  • Um computador de desenvolvimento executando Python >=3.8 e <=3.11.
  • 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 do SQL do Databricks para Python juntos. 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.
  • Um cluster ou SQL warehouse existente.

Introdução

  • Instale a biblioteca do Conector do SQL do Databricks para Python em seu computador de desenvolvimento, executando pip install databricks-sql-connector ou python -m pip install databricks-sql-connector.

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

    Cluster

    SQL warehouse

    • O nome do 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:

O Conector do SQL do Databricks para Python ainda não suporte para 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ê deve primeiro criar um token de acesso pessoal do Azure Databricks, da seguinte maneira:

  1. No workspace do Azure Databricks, clique no nome de usuário do Azure Databricks na barra superior e selecione Configurações na lista suspensa.
  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 ajude você 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 Gerar.
  7. Copie o token exibido para um local seguro e clique em Concluído.

Observação

Lembre-se de salvar o token copiado em um local seguro. Não compartilhe seu token copiado com outras pessoas. Se você perder o token copiado, não poderá regenerar exatamente aquele mesmo token. Em vez disso, será necessário repetir esse procedimento para criar um novo token. Caso você tenha perdido o token copiado ou acredite que ele tenha sido comprometido, o Databricks recomenda que você exclua imediatamente esse token do seu workspace clicando no ícone de lixeira (Revogar) ao lado do token na página de Tokens de acesso.

Se você não conseguir criar ou usar tokens em seu workspace, isso pode ocorrer porque o administrador do workspace desabilitou tokens ou não deu permissão para criar ou usar tokens. Veja o administrador do workspace ou o seguinte:

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 Nome do Host do Servidor do seu cluster ou SQL Warehouse.
  • DATABRICKS_HTTP_PATH, definido para o valor do 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, confira 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:

  1. Crie uma entidade de serviço do Azure Databricks em seu workspace 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 Use uma entidade de serviço para autenticar com o Azure Databricks. Anote o valor do UUID ou da ID do aplicativo da entidade de serviço e o valor do Segredo do segredo OAuth da entidade de serviço.

  2. Dê a essa entidade de serviço acesso ao cluster ou ao warehouse.

    Para conceder acesso à entidade de serviço no seu cluster ou warehouse, confira 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_HOSTNAME definido como o valor Nome do Host do Servidor do seu cluster ou SQL Warehouse.
  • DATABRICKS_HTTP_PATH, definido para o valor do Caminho HTTP para seu cluster 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, definido como o valor do Segredo para o segredo OAuth da entidade de serviço.

Para definir variáveis de ambiente, confira 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 (antigo Azure Active Directory)

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

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 Nome do host de Servidor do seu cluster ou SQL Warehouse.
  • Defina DATABRICKS_HTTP_PATH para Caminho HTTP o valor do seu cluster ou SQL Warehouse.
  • Defina DATABRICKS_TOKEN como o token do Microsoft Entra ID.

Para definir variáveis de ambiente, confira 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 do SQL do Databricks para Python são compatíveis com a autenticação U2M (usuário para computador) 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 do SQL do Databricks para Python com a autenticação U2M do OAuth, 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 Nome do host de Servidor do seu cluster ou SQL Warehouse.
  • Defina DATABRICKS_HTTP_PATH para Caminho HTTP o valor do seu cluster ou SQL Warehouse.

Para definir variáveis de ambiente, confira 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 de SQL do Databricks para Python para consultar e inserir dados, consultar metadados, gerenciar cursores e conexões e configurar o 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 outros tipos de autenticação disponíveis do Azure Databricks, confira Autenticação.

Esses exemplos de código recuperam os valores de variável de conexão server_hostname, http_path e access_tokendestas 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.

Você pode usar outras abordagens para recuperar os valores dessa variável de conexão. Usar variáveis de ambiente é apenas uma abordagem entre muitas.

Consultar dados

O exemplo de código a seguir demonstra como chamar o Conector para Python do SQL do Databricks a fim de executar um comando SQL básico em um cluster ou SQL warehouse. Esse comando retorna as duas primeiras linhas da tabela trips no esquema nyctaxi do catálogo samples.

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, primeiro você deve 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 em clusters do Azure Databricks e em SQL warehouses 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_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 o registro em log

O Conector de SQL Databricks usa o módulo de registro em log padrão do Python. Você pode configurar o nível de registros em log de modo 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()

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 pontos de extremidade da API REST do Azure Databricks ou alterar o estado de suas contas ou workspaces 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(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 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

Pacote

databricks-sql-connector

Uso: pip install databricks-sql-connector

Consulte também databricks-sql-connector no PyPI (Índice de Pacotes Python).

Módulo

databricks.sql

Uso: 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 os registros de dados.
Row

Uma linha de dados em um resultado de consulta SQL.

Classe Connection

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

Parâmetros
server_hostname

Digite: str

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

Este parâmetro é obrigatório.

Exemplo: adb-1234567890123456.7.azuredatabricks.net
http_path

Digite: str

O caminho HTTP do cluster ou do SQL warehouse. Para obter o caminho HTTP, consulte as instruções anteriores 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 SQL warehouse.
access_token, auth_type

Digite: str

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

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

Esse parâmetro é opcional.

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

Digite: List[Tuple[str, str]]]

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.

Esse parâmetro é opcional.

Desde a versão 2.0
catalog

Digite: str

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

Esse parâmetro é opcional.

Desde a versão 2.0
schema

Digite: str

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

Esse parâmetro é opcional.

Desde a versão 2.0
use_cloud_fetch

Digite: bool

True para enviar solicitações de busca diretamente para o repositório de objetos de 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, ocorrerá uma falha nas solicitações de busca.

Desde a versão 2.8

Os métodos Connection selecionados incluem o seguinte:

Métodos
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 percorrer os registros em um banco de dados.

Sem parâmetros.

Classe Cursor

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

Os atributos Cursor selecionados incluem o seguinte:

Atributos
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. Elas normalmente serão retornadas como 4
Valores None seguidos por um único valor True.

Acesso somente leitura.

Os métodos Cursor selecionados incluem o seguinte:

Métodos
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
método close depois de chamar o método cancel.

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.

Nenhum valor retornado.

Parâmetros:

operation

Digite: str

A consulta ou o comando a ser preparado e executado.

Este parâmetro é obrigatório.

Exemplo sem o parâmetro parameters:


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

Exemplo com o parâmetro parameters:


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 a ser usada com o parâmetro operation.

Esse parâmetro é opcional. O padrão é None.
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.

Nenhum valor retornado.

Parâmetros:

operation

Digite: str

A consulta ou o 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âmetro a serem usados com o
Parâmetro operation.

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

Sem parâmetros.

Nenhum valor retornado.

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

Nenhum valor retornado.

Desde a versão 1.0

Parâmetros:

catalog_name

Digite: str

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

Esse parâmetro é opcional.

schema_name

Digite: str

Um nome de esquema sobre o que recuperar informações. O caractere % é interpretado como um curinga.

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

Nenhum valor retornado.

Desde a versão 1.0

Parâmetros

catalog_name

Digite: str

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

Esse parâmetro é opcional.

schema_name

Digite: str

Um nome de esquema sobre o que recuperar informações. O caractere % é interpretado como um curinga.

Esse parâmetro é opcional.

table_name

Digite: str

Um nome de tabela sobre o que recuperar informações. O caractere % é interpretado como um curinga.

Esse parâmetro é opcional.

table_types

Digite: List[str]

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

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

Nenhum valor retornado.

Desde a versão 1.0

Parâmetros:

catalog_name

Digite: str

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

Esse parâmetro é opcional.

schema_name

Digite: str

Um nome de esquema sobre o que recuperar informações. O caractere % é interpretado como um curinga.

Esse parâmetro é opcional.

table_name

Digite: str

Um nome de tabela sobre o que recuperar informações. O caractere % é interpretado como um curinga.

Esse parâmetro é opcional.

column_name

Digite: str

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

Esse parâmetro é opcional.
fetchall

Obtém todas as linhas (ou todas as restantes) de uma consulta.

Sem parâmetros.

Retorna todas (ou todas as linhas restantes) da consulta como um list Python 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.

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.

Parâmetros:

size

Digite: int

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

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

Exemplo: cursor.fetchmany(10)
fetchone

Obtém a próxima linha do conjuntos de dados.

Sem parâmetros.

Retorna a próxima linha do conjunto de dados como uma única sequência como um
objeto tuple do Python 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.

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

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

Parâmetros:

size

Digite: int

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

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

Exemplo: cursor.fetchmany_arrow(10)

Classe Row

A classe de linha é uma estrutura de dados do tipo tupla que representa uma linha de resultado individual. 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:

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

Sem parâmetros.

Retorna um dict de campos. |

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

Solução de problemas

mensagem tokenAuthWrapperInvalidAccessToken: Invalid access token

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.

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

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.

mensagem IpAclError

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

Recursos adicionais

Para obter mais informações, consulte: