Databricks SQL para Python

O Databricks SQL Connector para Python é uma biblioteca Python que permite que você use o código Python para executar comandos SQL em clusters Databricks e Databricks SQL warehouse. O Databricks SQL Connector for Python é mais fácil de configurar e usar do que bibliotecas Python semelhantes, como pyodbc. Esta biblioteca segue a PEP 249 – Python Database API Specification v2.0.

Observação

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

Requisitos

  • Uma máquina de desenvolvimento executando Python >=3.8 e <=3.11.

  • A Databricks recomenda que utilize ambientes virtuais Python, como os fornecidos pela venv que estão incluídos no Python. Os ambientes virtuais ajudam a garantir que você está usando as versões corretas do Python e do Databricks SQL Connector para Python juntos. Configurar e usar ambientes virtuais está fora do escopo deste artigo. Para mais informações, consulte Criando ambientes virtuais.

  • Uma empresa existente cluster ou SQL warehouse.

Comece a começar

  • Instale a biblioteca Databricks SQL Connector para 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 os clusters ou SQL warehouse que você deseja usar:

    • O hostname do servidor do SQL warehouse. Você pode obter isso no valor do servidor hostname na Detalhes da conexão tab do seu SQL warehouse.

    • O caminho HTTP do SQL warehouse. Você pode obter isso no valor HTTP Path na Connection Details tab do SQL warehouse seu .

Autenticação

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

O Databricks SQL Connector for Python ainda não é compatível com os seguintes tipos de autenticação do Databricks:

Autenticação de token de acesso pessoal do Databricks

Para usar o Databricks SQL Conector para Python com Databricks access token autenticação pessoal, o senhor deve primeiro criar um Databricks access tokenpessoal. Para isso, siga os passos em Databricks access tokens pessoal para usuários de workspace .

Para autenticar o Conector Databricks SQL para Python, use o trecho de código a seguir. Este trecho pressupõe que você definiu a seguinte variável de ambiente:

  • DATABRICKS_SERVER_HOSTNAMEdefinido como o valor hostnamedo servidor para seus clusters ou SQL warehouse.

  • DATABRICKS_HTTP_PATH, defina o valor do Caminho HTTP para seus clusters ou SQL warehouse.

  • DATABRICKS_TOKEN, defina como o access token pessoal do Databricks.

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

from databricks import sql
import os

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

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

O Databricks SQL Connector for Python versões 2.7.0 e acima suportam a autenticação OAuth máquina a máquina (M2M). O senhor também deve instalar o Databricks SDK for 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 Databricks em seu workspace do Databricks e crie um segredo OAuth para essa entidade de serviço.

    Para criar a entidade de serviço e seu segredo OAuth, consulte Autenticar o acesso ao Databricks com uma entidade de serviço usando OAuth (OAuth M2M). Anote o valor do UUID da entidade de serviço ou do ID do aplicativo e o valor do segredo do OAuth da entidade de serviço.

  2. Dê a essa entidade de serviço acesso aos seus clusters ou armazém.

    Para conceder à entidade de serviço acesso ao seu cluster ou depósito, consulte compute permissions ou gerenciar a SQL warehouse.

Para autenticar o Conector Databricks SQL para Python, use o trecho de código a seguir. Este trecho pressupõe que você definiu a seguinte variável de ambiente:

  • DATABRICKS_SERVER_HOSTNAME definido como o valor hostnamedo servidor para seus clusters ou SQL warehouse.

  • DATABRICKS_HTTP_PATH, defina o valor do Caminho HTTP para seus clusters ou SQL warehouse.

  • DATABRICKS_CLIENT_ID, defina como o valor UUID ou ID do aplicativo da entidade de serviço.

  • DATABRICKS_CLIENT_SECRET, definido como o valor Secreto para o segredo OAuth da entidade de serviço.

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

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

server_hostname = os.getenv("DATABRICKS_SERVER_HOSTNAME")

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

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

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

Databricks SQL Connector para Python versões 3.0.3 e acima suportam a autenticação OAuth de usuário para máquina (U2M). O senhor também deve instalar o Databricks SDK for 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 a autenticação OAuth U2M, use o seguinte trecho de código. A autenticação OAuth U2M usa login e consentimento humano em tempo real para autenticar o usuário alvo da Databricks account. Esse snippet pressupõe que o senhor tenha definido a seguinte variável de ambiente:

  • Defina DATABRICKS_SERVER_HOSTNAME como o valor do Server hostname para seus clusters ou SQL warehouse.

  • Defina DATABRICKS_HTTP_PATH como o valor do caminho HTTP para seus clusters ou SQL warehouse.

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

from databricks import sql
import os

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

Exemplos

Os exemplos de código a seguir demonstram como usar o Databricks SQL Connector para Python para query e inserir dados, query metadados, gerenciar cursores e conexões e configurar o log.

Observação

Os exemplos de código a seguir demonstram como usar um access token pessoal do Databricks para autenticação. Para usar outros tipos de autenticação do Databricks disponíveis, consulte Autenticação.

Este exemplo de código recupera seus valores de variável de conexão server_hostname, http_path e access_token a partir desta variável de ambiente:

  • DATABRICKS_SERVER_HOSTNAME, que representa o valor hostnamedo servidor dos requisitos.

  • DATABRICKS_HTTP_PATH, que representa o valor do Caminho HTTP dos requisitos.

  • DATABRICKS_TOKEN, que representa seus access tokens dos requisitos.

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

Consultar dados

O exemplo de código a seguir demonstra como chamar o Databricks SQL Connector para Python para executar um comando SQL básico em clusters ou SQL warehouse. Este 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, você deve primeiro upload os dados para o armazenamento cloud 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 amostra:

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 todas as conexões e cursores que não estejam mais em uso. Isso libera recursos nos clusters do Databricks e nos warehouses do Databricks SQL.

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

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 Unity Catalog volumes

O Databricks SQL conector permite que o senhor grave arquivos locais em Unity Catalog volumes, download 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

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

Testes

Para testar seu código, use estruturas de teste Python, como o pytest. Para testar seu código em condições simuladas sem chamar o endpoint Databricks REST API ou alterar o estado de sua conta ou espaço de trabalho Databricks, o senhor pode usar a biblioteca de simulação Python, como unittest.mock.

Por exemplo, dado o seguinte arquivo denominado helpers.py contendo uma função get_connection_personal_access_token que usa um Databricks pessoal access token para retornar uma conexão a um Databricks workspace 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 nyctaxi do catálogo samples:

# 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 a seguir, denominado test_helpers.py, testa se a função select_nyctaxi_trips retorna a resposta esperada. Em vez de criar uma conexão real com o destino workspace, 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, em seguida, verifica se um dos valores das linhas de dados simulados 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, o mocking permite que o senhor execute rapidamente seus testes sem esperar que seja feita uma conexão real com o site workspace. Além disso, o mocking permite que o senhor execute testes simulados várias vezes para funções que possam 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 Índice do pacote Python (PyPI).

Módulo

databricks.sql

Uso: from databricks import sql

Classes

As aulas selecionadas incluem o seguinte:

Aulas

Connection

Uma sessão em um recurso Databricks compute .

Cursor

Um mecanismo para percorrer os registros de dados.

Row

Uma linha de dados em um resultado de consulta SQL.

Connection classe

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

Parâmetros

server_hostname

Tipo: str

O hostname do servidor para os clusters. Para obter o hostname do servidor, consulte as instruções anteriores neste artigo.

Este parâmetro é obrigatório.

Exemplo: 1234567890123456.7.gcp.databricks.com

http_path

Tipo: str

O caminho HTTP dos clusters. Para obter o caminho HTTP, consulte as instruções anteriores neste artigo.

Este parâmetro é obrigatório.

sql/protocolv1/o/1234567890123456/1234-567890-test123 para um cluster. /sql/1.0/warehouses/a1b234c567d8e9fa para um SQL warehouse.

access_token

Tipo: str

Seu access token pessoal do Databricks para o espaço de trabalho dos clusters. Para criar tokens, consulte as instruções anteriores neste artigo.

Este parâmetro é obrigatório.

Exemplo: dapi...<the-remaining-portion-of-your-token>

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 comando SQL SET key=val . execução do comando SQL SET -v para obter uma lista completa das configurações disponíveis.

default para None.

Este parâmetro é opcional.

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

http_headers

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

Adicional (par valor- keypara definir nos cabeçalhos HTTP em cada solicitação RPC que o cliente faz. O uso típico não definirá nenhum cabeçalho HTTP extra. default para None.

Este parâmetro é opcional.

Desde a versão 2.0

catalog

Tipo: str

Catálogo inicial a ser usado para a conexão. default para None (nesse caso, o catálogo default , 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. default para None (nesse caso, o esquema default default 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 ao armazenamento de objetos clouds para downloads blocos de dados. False (o default) para enviar solicitações de busca diretamente ao 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 Connection selecionados incluem os seguintes:

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

Cursor classe

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 obtidas do servidor por vez. O valor de default é 10000. Para resultados estreitos (resultados em que cada linha não contém muitos dados), o senhor deve aumentar esse valor para melhorar o desempenho.

Acesso de leitura e gravação.

description

Contém um Python list de objetos 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 como a seguir:

  • name: O nome da coluna.

  • type_code: Uma strings 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 tuple de 7 itens não são implementados e seus valores não são definidos. Eles normalmente serão retornados como 4 valores None seguidos por um único valor True .

Acesso somente leitura.

Os métodos Cursor selecionados incluem os seguintes:

Métodos

cancel

Interrompe a execução de qualquer consulta ao banco de dados ou comando que o cursor tenha começado. Para liberar o recurso associado 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, em seguida, executa uma query ou comando de banco de dados.

Sem valor de retorno.

Parâmetros:

operation

Tipo: str

A query ou comando para preparar e depois executar.

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 serem usados com o parâmetro operation .

Este parâmetro é opcional. O default é None.

executemany

Prepara e, em seguida, executa uma query ou comando de banco de dados usando todas as sequências de parâmetros no argumento seq_of_parameters. Apenas o conjunto de resultados final é retido.

Sem valor de retorno.

Parâmetros:

operation

Tipo: str

A query ou comando para preparar e depois executar.

Este parâmetro é obrigatório.

seq_of_parameters

Tipo: list de dict

Uma sequência de muitos conjuntos de valores de parâmetros a serem usados com o parâmetro operation .

Este parâmetro é obrigatório.

catalogs

Executar uma consulta de metadados sobre os catálogos. Os resultados reais devem ser obtidos 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.

Sem valor de retorno.

Desde a versão 1.0

schemas

Executar uma consulta de metadados sobre os esquemas. Os resultados reais devem ser obtidos 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.

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 caractere % é interpretado como um curinga.

Este parâmetro é opcional.

schema_name

Tipo: str

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

Este parâmetro é opcional.

tables

Executar uma consulta de metadados sobre tabelas e exibições. Os resultados reais devem ser obtidos 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 mesa.

  • Nome do campo: TABLE_TYPE. Tipo: str. O tipo de relação, por exemplo, VIEW ou TABLE (aplica-se a Databricks Runtime 10.4 LTS e acima; 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 caractere % é interpretado como um curinga.

Este parâmetro é opcional.

schema_name

Tipo: str

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

Este parâmetro é opcional.

table_name

Tipo: str

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

Este parâmetro é opcional.

table_types

Tipo: List[str]

Uma lista de tipos de tabela para correspondência, por exemplo TABLE ou VIEW.

Este parâmetro é opcional.

columns

Executar uma consulta de metadados sobre as colunas. Os resultados reais devem ser obtidos 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.

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 caractere % é interpretado como um curinga.

Este parâmetro é opcional.

schema_name

Tipo: str

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

Este parâmetro é opcional.

table_name

Tipo: str

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

Este parâmetro é opcional.

column_name

Tipo: str

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

Este parâmetro é opcional.

fetchall

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

Sem parâmetros.

Retorna todas (ou todas as linhas restantes) da query como um Python list de objetos Row.

Lança um Error se a chamada anterior ao método execute não tiver retornado nenhum dado ou se nenhuma chamada execute tiver sido feita.

fetchmany

Obtém as próximas linhas de uma query.

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

Se restarem menos de size linhas a serem buscadas, todas as linhas restantes serão retornadas.

Lança um Error se a chamada anterior ao método execute não tiver retornado nenhum dado ou se nenhuma chamada execute tiver sido feita.

Parâmetros:

size

Tipo: int

O número de próximas linhas a serem obtidas.

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

Sem parâmetros.

Retorna a próxima linha do conjunto de dataset 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 ao método execute não tiver retornado nenhum dado ou se nenhuma chamada execute tiver sido feita.

fetchall_arrow

Obtém todas (ou todas as linhas restantes) de uma query, como um objeto PyArrow Table. query que retorna quantidades muito grandes de dados deve usar fetchmany_arrow em vez disso para reduzir o consumo de memória.

Sem parâmetros.

Retorna todas (ou todas as restantes) linhas da query como uma tabela PyArrow.

Lança um Error se a chamada anterior ao método execute não tiver retornado nenhum dado ou se nenhuma chamada execute tiver sido feita.

Desde a versão 2.0

fetchmany_arrow

Obtém as próximas linhas de uma query 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 objeto Python PyArrow Table.

Lança um Error se a chamada anterior ao método execute não tiver retornado nenhum dado ou se nenhuma chamada execute tiver sido feita.

Desde a versão 2.0

Parâmetros:

size

Tipo: int

O número de próximas linhas a serem obtidas.

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

Exemplo: cursor.fetchmany_arrow(10)

Row classe

A classe de linha é 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ê poderá acessar o campo "my_column" 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, 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 campos. Se houver nomes de campos duplicados, um dos campos duplicados (mas apenas um) será retornado no dicionário. Não está definido qual campo duplicado é retornado.

Sem parâmetros.

Retorna um dict de campos.

Conversões de tipo

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

Solução de problemas

tokenAuthWrapperInvalidAccessToken: Invalid access token mensagem

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

Possível causa: o valor passado para access_token não é um access tokens pessoal Databricks válido.

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

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

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

Possível causa: 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 encontrar o hostname do servidor, consulte Obter detalhes de conexão para um recurso de computação do Databricks.

IpAclError mensagem

Problema: ao executar seu código, você vê a mensagem Error during request to server: IpAclValidation ao tentar usar o conector em um Databricks Notebook.

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

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

Recursos adicionais

Para mais informações, consulte: