Pular para o conteúdo principal

Databricks SQL Conector para Python

O Databricks SQL Connector for Python é uma Python biblioteca que permite que o senhor use o código Python para executar o SQL comando em Databricks armazéns de uso geral compute e Databricks SQL. O conector Databricks SQL para Python é mais fácil de configurar e usar do que uma biblioteca Python semelhante, como pyodbc. Essa biblioteca segue a PEP 249 - Python Database API Specification v2.0.

important

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

O conector Databricks SQL para Python também é compatível com o dialeto SQLAlchemy para Databricks, mas deve ser instalado para usar esses recursos. Consulte Usar o SQLAlchemy com Databricks.

Requisitos​

  • Uma máquina de desenvolvimento executando Python >=3.8 e <=3.11.
  • A Databricks recomenda que o senhor use ambientes virtuais Python, como os fornecidos pelo venv que estão incluídos no Python. Os ambientes virtuais ajudam a garantir que o senhor 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 Criação de ambientes virtuais.
  • Um site existente para todos os fins compute ou SQL warehouse.

Começar​

  • Instale o Databricks SQL Connector for Python. O PyArrow é uma dependência opcional do Databricks SQL Connector for Python e não é instalado pelo default na versão 4.0.0 e acima do conector. Se o PyArrow não estiver instalado, recursos como o CloudFetch e outras funcionalidades do Apache Arrow não estarão disponíveis, o que pode afetar o desempenho de grandes volumes de dados.

    • Para instalar o conector lean, use pip install databricks-sql-connector.
    • Para instalar o conector completo, incluindo o PyArrow, use pip install databricks-sql-connector[pyarrow].

  • Reúna as seguintes informações sobre o site compute ou SQL warehouse que o senhor deseja usar:

nota

The SQL connector does not support connecting to jobs compute.

Autenticação​

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

nota

A autenticação básica usando um nome de usuário e senha da Databricks chegou ao fim da vida útil em 10 de julho de 2024. Consulte End of life para Databricks-gerenciar senhas.

Databricks autenticação de tokens de acesso pessoal​

Para usar o Databricks SQL Conector para Python com Databricks autenticação de tokens de acesso pessoal, o senhor deve primeiro criar um Databricks tokens de acesso pessoal. Para fazer isso, siga as etapas em Databricks personal access tokens for workspace users.

Para autenticar o Databricks SQL Connector for Python, use o seguinte trecho de código. Esse snippet pressupõe que o senhor tenha definido a seguinte variável de ambiente:

  • DATABRICKS_SERVER_HOSTNAMEDefina o valor do Server Hostname para o seu site compute ou SQL warehouse.
  • DATABRICKS_HTTP_PATHDefina o valor do caminho HTTP para seu site compute ou SQL warehouse.
  • DATABRICKS_TOKEN, definido como os tokens de acesso pessoal Databricks.

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

Python
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)​

Databricks SQL Connector for Python versões 2.5.0 e acima suportam autenticação máquina a máquina (M2M)OAuth. O senhor também deve instalar o Databricks SDK para Python (por exemplo, executando pip install databricks-sdk ou python -m pip install databricks-sdk).

Para usar o Databricks SQL Connector for Python com a autenticação OAuth M2M, o senhor deve fazer o seguinte:

  1. Crie uma Databricks entidade de serviço em seu Databricks workspace e crie um OAuth secret para essa entidade de serviço.

    Para criar a entidade de serviço e seu segredo OAuth, consulte Autorizar o acesso da entidade de serviço ao Databricks com OAuth. 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 ao seu compute ou armazém para todos os fins.

    Para conceder à entidade de serviço acesso ao seu compute ou armazém para todos os fins, consulte computar permissões ou gerenciar a SQL warehouse.

Para autenticar o Databricks SQL Connector for Python, use o seguinte trecho de código. Esse snippet pressupõe que o senhor tenha definido a seguinte variável de ambiente:

  • DATABRICKS_SERVER_HOSTNAME Defina o valor do Server Hostname para o seu site compute ou SQL warehouse.
  • DATABRICKS_HTTP_PATHDefina o valor do caminho HTTP para seu site compute ou SQL warehouse.
  • DATABRICKS_CLIENT_IDdefinido como o valor do UUID da entidade de serviço ou do ID do aplicativo .
  • DATABRICKS_CLIENT_SECRETdefinido como o valor Secret do segredo OAuth da entidade de serviço.

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

Python
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 OAuth de usuário para máquina (U2M)​

Databricks SQL Connector for Python versões 2.1.0 e acima suportam a autenticaçãoOAuth user-to-machine (U2M).

Para autenticar o Databricks SQL Connector for Python com a autenticação OAuth U2M, use o seguinte trecho de código. OAuth A autenticação U2M usa o tempo de login humano real e o consentimento para autenticar o usuário de destino 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 o seu compute ou SQL warehouse multifuncional.
  • Defina DATABRICKS_HTTP_PATH como o valor do caminho HTTP para o seu compute ou SQL warehouse multifuncional.

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

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

nota

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

Esses exemplos de código recuperam os valores das variáveis de conexão server_hostname, http_path e access_token a partir dessas variáveis de ambiente:

  • DATABRICKS_SERVER_HOSTNAME, que representa o valor do nome do host do servidor a partir dos requisitos.
  • DATABRICKS_HTTP_PATH, que representa o valor do caminho HTTP dos requisitos.
  • DATABRICKS_TOKENque representa seus tokens de acesso dos requisitos.

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

Definir agente de usuário​

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

Python
from databricks import sql
import os

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

    for row in result:
      print(row)

Dados de consulta​

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

Python
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):

Python
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, o senhor deve primeiro fazer upload dos dados para o armazenamento em nuvem e, em seguida, executar o comando COPY INTO.

Metadados da consulta​

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

Python
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 recurso em Databricks armazéns de uso geral compute e Databricks SQL.

O senhor pode usar um gerenciador de contexto (a sintaxe with usada nos exemplos anteriores) para gerenciar o recurso ou chamar explicitamente close:

Python
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:

Python
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 registro padrão do Python. Você pode configurar o nível de registro semelhante ao seguinte:

Python
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 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, que contém uma função get_connection_personal_access_token que usa tokens de acesso pessoal Databricks 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:

Python
# 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:

Python
# 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 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 simuladas corresponde ao valor esperado.

Python
# 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 Python pacote Index (PyPI).

Módulo​

databricks.sql

Uso: from databricks import sql

Aulas​

As aulas selecionadas incluem o seguinte:

Aulas

Connection Uma sessão em um recurso Databricks compute .

Cursor Um mecanismo para percorrer registros de dados.

Row Uma linha de dados em um resultado de consulta SQL.

ClasseConnection​

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

Parâmetros

server_hostname Tipo: str O nome do host do servidor para o site multifuncional compute ou SQL warehouse. Para obter o nome do host do servidor, consulte as instruções anteriores neste artigo. Este parâmetro é necessário. Exemplo: dbc-a1b2345c-d6e7.cloud.databricks.com

http_path Tipo: str O caminho HTTP do site multifuncional compute ou SQL warehouse. Para obter o caminho HTTP, consulte as instruções anteriores neste artigo. Este parâmetro é necessário. Exemplo: sql/protocolv1/o/1234567890123456/1234-567890-test123 para todos os fins compute. /sql/1.0/warehouses/a1b234c567d8e9fa para um SQL warehouse.

access_token, auth_type, credentials_provider, password, username Tipo: str Informações sobre as configurações de autenticação do 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 comando SET key=val SQL. Execute o SQL comando SET -v para obter uma lista completa das configurações disponíveis. padrão para None. Este parâmetro é opcional. Exemplo: {"spark.sql.variable.substitute": True}

http_headers Tipo: List[Tuple[str, str]]] Valor adicional (par key) a ser definido nos cabeçalhos HTTP em cada solicitação de RPC feita pelo cliente. O uso típico não definirá nenhum cabeçalho HTTP extra. padrão 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. tem como padrão None (nesse caso, será usado o catálogo default, normalmente hive_metastore). Este parâmetro é opcional. Desde a versão 2.0

schema Tipo: str Esquema inicial a ser usado para a conexão. tem como padrão None (nesse caso, será usado o esquema default default). 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 na nuvem para fazer download de partes de dados. False (o default) para enviar solicitações de busca diretamente para Databricks. Se use_cloud_fetch estiver definido como True, mas o acesso à rede estiver bloqueado, as solicitações de busca falharão. Desde a versão 2.8

user_agent_entry Tipo: str A entrada User-Agent a ser incluída no cabeçalho da solicitação HTTP para acompanhamento do uso. padrão para PyDatabricksSqlConnector. Este parâmetro é opcional. Desde a versão 4.0.1

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.

ClasseCursor​

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 é quantas linhas são realmente buscadas 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, sendo que os 2 primeiros itens de cada objeto tuple contêm informações que descrevem uma única coluna de resultados, como segue: - name: O nome da coluna. - type_code: Uma cadeia de caracteres que representa o tipo da coluna. Por exemplo, uma coluna de números inteiros terá um código de tipo int. Os 5 itens restantes de cada objeto tuple de 7 itens não são implementados e seus valores não estão definidos. Eles normalmente serão devolvidos como 4 None valores seguidos por um único valor True. Acesso somente para leitura.

Os métodos Cursor selecionados incluem o seguinte:

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 comando close método depois de chamar o método cancel. Sem parâmetros. Sem valor de retorno.

close Fecha o cursor e libera o recurso associado 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 para preparar e depois executar. Este parâmetro é necessá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 para usar com o parâmetro operation. Este 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âmetros no argumento seq_of_parameters. Somente o conjunto de resultados final é mantido. Sem valor de retorno. Parâmetros: operation Tipo: str A consulta ou comando para preparar e depois executar. Este parâmetro é necessário. seq_of_parameters Tipo: list de dict Uma sequência de vários conjuntos de valores de parâmetros para usar com o operation parâmetro. Este parâmetro é necessá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 para recuperar informações sobre o senhor. O caractere % é interpretado como um curinga. Este parâmetro é opcional. schema_name Tipo: str Um nome de esquema para recuperar informações sobre o senhor. 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 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 a Databricks Runtime 10.4 LTS e acima, bem como a 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 para recuperar informações sobre o senhor. O caractere % é interpretado como um curinga. Este parâmetro é opcional. schema_name Tipo: str Um nome de esquema para recuperar informações sobre o senhor. O caractere % é interpretado como um curinga. Este parâmetro é opcional. table_name Tipo: str Um nome de tabela para recuperar informações sobre o senhor. O caractere % é interpretado como um curinga. Este parâmetro é opcional. table_types Tipo: List[str] Uma lista de tipos de tabela a serem combinados, 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 para recuperar informações sobre o senhor. O caractere % é interpretado como um curinga. Este parâmetro é opcional. schema_name Tipo: str Um nome de esquema para recuperar informações sobre o senhor. O caractere % é interpretado como um curinga. Este parâmetro é opcional. table_name Tipo: str Um nome de tabela para recuperar informações sobre o senhor. O caractere % é interpretado como um curinga. Este parâmetro é opcional. column_name Tipo: str Um nome de coluna para recuperar informações sobre o senhor. O caractere % é 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 as linhas (ou todas as linhas restantes) da consulta como um Python list de Row objetos. Lança um Error se a chamada anterior para o método execute não retornar nenhum dado ou se nenhuma chamada execute ainda tiver sido feita.

fetchmany Obtém as próximas linhas de uma consulta. 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 para serem buscadas, todas as linhas restantes serão retornadas. Lança um Error se a chamada anterior para o método execute não retornar nenhum dado ou se nenhuma chamada execute ainda tiver sido feita. Parâmetros: size Tipo: int O número das próximas linhas a serem obtidas. 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 site dataset. Sem parâmetros. Retorna a próxima linha do site dataset como uma única sequência como um Python tuple object 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 retornar nenhum dado ou se nenhuma chamada execute ainda tiver sido feita.

fetchall_arrow Obtém todas (ou todas as linhas restantes) de uma consulta, como um objeto PyArrow Table. Em vez disso, as consultas que retornam grandes quantidades de dados devem usar 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 método execute não retornar nenhum dado ou se nenhuma chamada execute ainda tiver sido 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 uma PyArrow Python Table objeto. Lança um Error se a chamada anterior para o método execute não retornar nenhum dado ou se nenhuma chamada execute ainda tiver sido feita. Desde a versão 2.0 Parâmetros: size Tipo: int O número das próximas linhas a serem obtidas. Esse parâmetro é opcional. Se não for especificado, o valor do atributo arraysize será usado. Exemplo: cursor.fetchmany_arrow(10)

ClasseRow​

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ê 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, ele começa com um dígito), então você pode 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 somente um) será retornado no dicionário. O 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 SQL do Apache Spark para seus equivalentes em Python.

Tipo de dados SQL do Apache Spark

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​

MensagemtokenAuthWrapperInvalidAccessToken: Invalid access token​

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

Possible cause : O valor passado para access_token não é um Databricks válido de tokens de acesso pessoal.

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

Mensagemgaierror(8, 'nodename nor servname provided, or not known')​

Problema : Ao executar o código, o senhor 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 encontrar o nome do host do servidor, consulte Obter detalhes da conexão para um recurso Databricks compute.

MensagemIpAclError​

Problema : Ao executar o código, o senhor vê a mensagem Error during request to server: IpAclValidation quando tenta usar o conector em um notebook Databricks.

Possível causa : O senhor pode ter habilitado a listagem de permissão de IP para o site Databricks workspace. Com a listagem de permissão de IP, as conexões do Spark clustering de volta ao plano de controle não são permitidas pelo default.

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

Recurso adicional​

Para saber mais, consulte:

Última atualização em