Connettore SQL di Databricks per Python

Articolo
11/14/2024

Il connettore SQL di Databricks per Python è una libreria Python che consente di usare il codice Python per eseguire comandi SQL nei cluster di Azure Databricks e nei databricks SQL Warehouse. Il connettore SQL di Databricks per Python è più semplice da configurare e usare rispetto a librerie Python simili, ad esempio pyodbc. Questa libreria segue PEP 249 - Specifica API Database Python v2.0.

Nota

Il connettore SQL di Databricks per Python include anche un dialetto SQLAlchemy per Azure Databricks. Consultare Usare SQLAlchemy con Azure Databricks.

Requisiti

Un computer di sviluppo che esegue Python >=3.8 e <=3.11.
Databricks consiglia di usare ambienti virtuali Python, ad esempio quelli forniti da venv inclusi in Python. Gli ambienti virtuali consentono di assicurarsi di usare insieme le versioni corrette di Python e il connettore SQL di Databricks per Python. La configurazione e l'uso di ambienti virtuali non rientra nell'ambito di questo articolo. Per altre informazioni, consultare Creare ambienti virtuali.
Un cluster esistente o SQL warehouse.

Introduzione

Installare il connettore SQL databricks per la libreria Python nel computer di sviluppo eseguendo pip install databricks-sql-connector o python -m pip install databricks-sql-connector.
Raccogliere le informazioni seguenti per il cluster o SQL Warehouse da usare:

Cluster
- Nome host del server del cluster. È possibile ottenere questo valore dal valore Nome host server nella scheda Opzioni avanzate > JDBC/ODBC per il cluster.
- Percorso HTTP del cluster. È possibile ottenere questo dal valore Percorso HTTP nella scheda Opzioni avanzate > JDBC/ODBC per il cluster.
Warehouse SQL
- Nome host del server di SQL Warehouse. È possibile ottenere questo valore dal valore Nome host server nella scheda Dettagli connessione per SQL warehouse.
- Percorso HTTP del warehouse SQL. È possibile ottenere questo valore dal valore Percorso HTTP nella scheda Dettagli connessione per SQL warehouse.

Autenticazione

Il connettore del database SQL per Python supporta i seguenti tipi di autenticazione di Azure Databricks:

Autenticazione con token di accesso personale di Databricks
Autenticazione con token di Microsoft Entra ID
Autenticazione OAuth da computer a computer (M2M)
Autenticazione da utente a computer (U2M) OAuth

Il connettore SQL di Databricks per Python non supporta ancora i tipi di autenticazione di Azure Databricks seguenti:

Autenticazione con token di accesso personale di Databricks

Per usare il connettore SQL di Databricks per Python con l'autenticazione del token di accesso personale di Azure Databricks, è prima necessario creare un token di accesso personale di Azure Databricks. A tale scopo, seguire la procedura descritta in Token di accesso personale di Azure Databricks per gli utenti dell'area di lavoro.

Per autenticare il connettore SQL di Databricks per Python, usare il frammento di codice seguente. Questo frammento presuppone che sono state impostate le variabili di ambiente seguenti:

DATABRICKS_SERVER_HOSTNAMEimpostato sul valore Nome host server per il cluster o SQL Warehouse.
DATABRICKS_HTTP_PATH, impostato sul valore percorso HTTP per il cluster o SQL Warehouse.
DATABRICKS_TOKEN, impostato sul token di accesso personale di Azure Databricks.

Per impostare le variabili di ambiente, si veda la documentazione relativa al sistema operativo Windows utilizzato.

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

Autenticazione OAuth da computer a computer (M2M)

Databricks SQL Connector for Go versioni 2.7.0 e successive supportano l'autenticazione da computer a computer (M2M) OAuth. È anche necessario installare Databricks SDK per Python 0.18.0 o versione successiva, ad esempio eseguendo pip install databricks-sdk o python -m pip install databricks-sdk.

Per usare il connettore SQL di Databricks per Python con l'autenticazione OAuth M2M, è necessario eseguire le operazioni seguenti:

Creare un'entità servizio di Azure Databricks nell'area di lavoro di Azure Databricks e creare un segreto OAuth per tale entità servizio.

Per creare l'entità servizio e il relativo segreto OAuth, consultare Autenticare l'accesso ad Azure Databricks con un'entità servizio usando OAuth (OAuth M2M). Prendere nota del valore UUID o ID applicazione dell'entità servizio e del valore Secret per il segreto OAuth dell'entità servizio.
Concedere a quell’entità servizio l'accesso al cluster o al warehouse.

Per concedere all'entità servizio l'accesso al cluster o al warehouse, consultare Autorizzazioni di calcolo o Gestire un data warehouse SQL.

Per autenticare il connettore SQL di Databricks per Python, usare il frammento di codice seguente. Questo frammento presuppone che sono state impostate le variabili di ambiente seguenti:

DATABRICKS_SERVER_HOSTNAME impostato sul valore Nome host server per il cluster o SQL Warehouse.
DATABRICKS_HTTP_PATH, impostato sul valore percorso HTTP per il cluster o SQL Warehouse.
DATABRICKS_CLIENT_ID, impostato sul valore dell'ID applicazione e UUID dell'entità servizio.
DATABRICKS_CLIENT_SECRET, impostato sul valore del segreto OAuth dell'entità servizio.

Per impostare le variabili di ambiente, si veda la documentazione relativa al sistema operativo Windows utilizzato.

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

Autenticazione con token di Microsoft Entra ID

Per usare il connettore SQL di Databricks per Python con l'autenticazione del token ID Microsoft Entra, è necessario fornire il connettore SQL databricks per Python con il token ID Microsoft Entra. Per creare un token di accesso di Microsoft Entra ID, eseguire le operazioni seguenti:

Per un utente di Azure Databricks, è possibile usare l'interfaccia della riga di comando di Azure. Consultare Ottenere i token Microsoft Entra ID per gli utenti utilizzando l’interfaccia della riga di comando di Azure.
Per un'entità servizio Microsoft Entra ID, consultare Ottenere un token di accesso microsoft Entra ID con l'interfaccia della riga di comando di Azure. Per creare un'entità servizio gestita di Microsoft Entra ID, consultare Gestire le entità servizio.

I token ID Microsoft Entra hanno una durata predefinita di circa 1 ora. Per creare un nuovo token ID Microsoft Entra, ripetere questo processo.

Per autenticare il connettore SQL di Databricks per Python, usare il frammento di codice seguente. Questo frammento presuppone che sono state impostate le variabili di ambiente seguenti:

Impostato DATABRICKS_SERVER_HOSTNAME sul valore Nome host server per il cluster o SQL Warehouse.
Impostato DATABRICKS_HTTP_PATH sul valore percorso HTTP per il cluster o SQL Warehouse.
Impostare DATABRICKS_TOKEN sul token Microsoft Entra ID.

Per impostare le variabili di ambiente, si veda la documentazione relativa al sistema operativo Windows utilizzato.

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

Autenticazione da utente a computer (U2M) OAuth

Databricks SQL Driver for Python versioni 2.7.0 e successive supportano l'autenticazione da utente a computer (U2M) OAuth. È anche necessario installare Databricks SDK per Python 0.19.0 o versione successiva, ad esempio eseguendo pip install databricks-sdk o python -m pip install databricks-sdk.

Per autenticare il connettore SQL di Databricks per Python con l’autenticazione OAuth U2M, usare il frammento di codice seguente. L'autenticazione U2M OAuth usa l'accesso umano in tempo reale e il consenso per autenticare l'account utente di Azure Databricks di destinazione. Questo frammento presuppone che sono state impostate le variabili di ambiente seguenti:

Impostato DATABRICKS_SERVER_HOSTNAME sul valore Nome host server per il cluster o SQL Warehouse.
Impostato DATABRICKS_HTTP_PATH sul valore percorso HTTP per il cluster o SQL Warehouse.

Per impostare le variabili di ambiente, si veda la documentazione relativa al sistema operativo Windows utilizzato.

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

Esempi

Gli esempi di codice seguenti illustrano come usare databricks SQL Connector per Python per eseguire query e inserire dati, eseguire query sui metadati, gestire cursori e connessioni e configurare la registrazione.

Nota

Gli esempi di codice seguenti illustrano come usare un token di accesso personale di Azure Databricks per l'autenticazione. Per usare altri tipi di autenticazione di Azure Databricks disponibili, consultare Autenticazione.

Questo esempio di codice recupera i valori delle variabili di connessione server_hostname, http_pathe access_token da queste variabili di ambiente:

DATABRICKS_SERVER_HOSTNAME: che rappresenta il valore Server Hostname in base ai requisiti.
DATABRICKS_HTTP_PATH: che rappresenta il valore Percorso HTTP in base ai requisiti.
DATABRICKS_TOKEN, che rappresenta il token di accesso dai requisiti.

È possibile usare altri approcci per recuperare questi valori delle variabili di connessione. L'uso delle variabili di ambiente è solo un approccio tra molti.

Eseguire query sui dati
Inserire i dati
Metadati delle query
Gestire cursori e connessioni
Gestisce i file nei volumi nel catalogo Unity
Configurare la registrazione

Eseguire query sui dati

L'esempio di codice seguente illustra come chiamare il connettore SQL di Databricks per Python per eseguire un comando SQL di base in un cluster o in un SQL warehouse. Questo comando restituisce le prime due righe della tabella trips nello schema samples del catalogo nyctaxi.

from databricks import sql
import os

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

  with connection.cursor() as cursor:
    cursor.execute("SELECT * FROM samples.nyctaxi.trips LIMIT 2")
    result = cursor.fetchall()

    for row in result:
      print(row)

Inserire i dati

Nell'esempio seguente viene illustrato come inserire piccole quantità di dati (migliaia di righe):

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)

Per grandi quantità di dati, è necessario prima caricare i dati nell'archiviazione cloud e quindi eseguire il comando COPY INTO.

Metadati delle query

Sono disponibili metodi dedicati per il recupero dei metadati. Nell'esempio seguente vengono recuperati i metadati relativi alle colonne in una tabella di esempio:

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

Gestire cursori e connessioni

È consigliabile chiudere tutte le connessioni e i cursori che non sono più in uso. In questo modo vengono liberate le risorse nei cluster di Azure Databricks e nei data warehouse SQL di Databricks.

È possibile usare un gestore di contesto (la sintassi with usata negli esempi precedenti) per gestire le risorse o chiamare close in modo esplicito:

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

Gestisce i file nei volumi nel catalogo Unity

Il connettore SQL di Databricks consente di scrivere file locali in volumi del catalogo Unity, scaricare file dai volumi ed eliminare file dai volumi, come illustrato nell'esempio seguente:

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'"
    )

Configurare la registrazione

Il connettore SQL di Databricks usa il modulo di registrazione standard di Python. È possibile configurare il livello di registrazione simile al seguente:

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

Test

Per testare il codice, usare framework di test Python come pytest. Per testare il codice in condizioni simulate senza chiamare gli endpoint dell'API REST di Azure Databricks o modificare lo stato degli account o delle aree di lavoro di Azure Databricks, è possibile usare librerie di simulazione di Python, ad esempio le unittest.mock.

Ad esempio, dato il file seguente denominato helpers.py contenente una funzione get_connection_personal_access_token che usa un token di accesso personale di Azure Databricks per restituire una connessione a un'area di lavoro di Azure Databricks e una funzione select_nyctaxi_trips che usa la connessione per ottenere il numero specificato di righe di dati dalla tabella trips nello schema nyctaxi del catalogo 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 dato il file seguente denominato main.py che chiama la funzione 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)

Il file seguente denominato test_helpers.py verifica se la funzione select_nyctaxi_trips restituisce la risposta prevista. Anziché creare una connessione reale all'area di lavoro di destinazione, questo test simula un oggetto Connection. Il test simula anche alcuni dati conformi allo schema e ai valori presenti nei dati reali. Il test restituisce i dati fittizi tramite la connessione fittizia e quindi controlla se uno dei valori delle righe di dati fittizi corrisponde al valore previsto.

# 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

Poiché la funzione select_nyctaxi_trips contiene un'istruzione SELECT e pertanto non modifica lo stato della tabella trips, la simulazione non è assolutamente necessaria in questo esempio. Tuttavia, la simulazione consente di eseguire rapidamente i test senza attendere che venga stabilita una connessione effettiva con l'area di lavoro. Inoltre, la simulazione consente di eseguire test simulati più volte per le funzioni che potrebbero modificare lo stato di una tabella, ad esempio INSERT INTO, UPDATE e DELETE FROM.

Pacchetto

databricks-sql-connector

Sintassi: pip install databricks-sql-connector

Consultare anche databricks-sql-connector nell'indice dei pacchetti Python (PyPI).

Modulo

databricks.sql

Sintassi: from databricks import sql

Classi

Le classi selezionate includono quanto segue:

Classi
`Connection` Una sessione in una risorsa di calcolo di Azure Databricks.
`Cursor` Meccanismo per l'attraversamento dei record di dati.
`Row` Riga di dati in un risultato della query SQL.

Classe `Connection`

Per creare un oggetto Connection, chiamare il metodo databricks.sql.connect con i parametri seguenti:

Parametri
`server_hostname` Tipo: `str` Il server hostname per il cluster o SQL Warehouse. Per ottenere il nome host del server, consultare le istruzioni riportate in precedenza in questo articolo. Questo parametro è obbligatorio. Esempio: `adb-1234567890123456.7.azuredatabricks.net`
`http_path` Tipo: `str` Percorso HTTP del cluster o SQL warehouse. Per ottenere il percorso HTTP, consultare le istruzioni riportate in precedenza in questo articolo. Questo parametro è obbligatorio. Esempio: `sql/protocolv1/o/1234567890123456/1234-567890-test123` per un cluster. `/sql/1.0/warehouses/a1b234c567d8e9fa` per SQL warehouse:
`access_token`, `auth_type` Tipo: `str` Informazioni sulle impostazioni di autenticazione di Azure Databricks. Per informazioni dettagliate, consultare Autenticazione.
`session_configuration` Tipo: `dict[str, Any]` Dizionario dei parametri di configurazione della sessione Spark. L'impostazione di una configurazione equivale all'uso del comando SQL `SET key=val`. Eseguire il comando SQL `SET -v` per ottenere un elenco completo delle configurazioni disponibili. Il valore predefinito è `None`. Il parametro è facoltativo. Esempio: `{"spark.sql.variable.substitute": True}`
`http_headers` Tipo: `List[Tuple[str, str]]]` Coppie aggiuntive (chiave, valore) da impostare nelle intestazioni HTTP in ogni richiesta RPC eseguita dal client. L'utilizzo tipico non imposta intestazioni HTTP aggiuntive. Il valore predefinito è `None`. Il parametro è facoltativo. A partire dalla versione 2.0
`catalog` Tipo: `str` Catalogo iniziale da usare per la connessione. L'impostazione predefinita è `None` (nel qual caso verrà usato il catalogo predefinito, in genere `hive_metastore`). Il parametro è facoltativo. A partire dalla versione 2.0
`schema` Tipo: `str` Schema iniziale da usare per la connessione. L'impostazione predefinita è `None` (nel qual caso verrà usato lo schema `default` predefinito). Il parametro è facoltativo. A partire dalla versione 2.0
`use_cloud_fetch` Tipo: `bool` `True` per inviare richieste di recupero direttamente all'archivio oggetti cloud per scaricare blocchi di dati. `False` (impostazione predefinita) per inviare richieste di recupero direttamente ad Azure Databricks. Se `use_cloud_fetch` è impostato su `True` ma l'accesso alla rete è bloccato, le richieste di recupero avranno esito negativo. A partire dalla versione 2.8

I metodi Connection selezionati includono i seguenti:

Metodi
`close` Chiude la connessione al database e rilascia tutte le risorse associate nel server. Eventuali chiamate aggiuntive a questa connessione genereranno un'eccezione `Error`. Nessun parametro. Nessun valore restituito.
`cursor` Restituisce un nuovo `Cursor` oggetto che abilita l'attraversamento dei record in un database. Nessun parametro.

Classe `Cursor`

Per creare un oggetto Cursor, chiamare il metodo Connection della classe cursor.

Gli attributi selezionati Cursor includono quanto segue:

Attributi

Attributi
`arraysize` Usato con il metodo `fetchmany`, specifica la dimensione interna del buffer, ovvero il numero di righe effettivamente recuperate dal server alla volta. Il valore predefinito è `10000`. Per risultati limitati (risultati in cui ogni riga non contiene molti dati), è consigliabile aumentare questo valore per ottenere prestazioni migliori. Accesso in lettura e scrittura.
`description` Contiene un python degli oggetti `list` di `tuple`. Ognuno di questi oggetti `tuple` contiene 7 valori, con i primi 2 elementi di ogni oggetto `tuple` contenente informazioni che descrivono una singola colonna di risultato come indicato di seguito: - `name`: il nome della colonna. - `type_code`: una stringa che rappresenta il tipo di colonna. Ad esempio, una colonna integer avrà un codice di tipo `int`. Gli altri 5 elementi di ogni oggetto a 7 elementi `tuple` non vengono implementati e i relativi valori non sono definiti. In genere verranno restituiti come 4 I valori `None` seguiti da un singolo valore `True`. Accesso di sola lettura.

arraysize

Usato con il metodo fetchmany, specifica la dimensione interna del buffer, ovvero il numero di righe effettivamente recuperate dal server alla volta. Il valore predefinito è 10000. Per risultati limitati (risultati in cui ogni riga non contiene molti dati), è consigliabile aumentare questo valore per ottenere prestazioni migliori.

Accesso in lettura e scrittura.

description

Contiene un python degli oggetti list di tuple. Ognuno di questi oggetti tuple contiene 7 valori, con i primi 2 elementi di ogni oggetto tuple contenente informazioni che descrivono una singola colonna di risultato come indicato di seguito:

- name: il nome della colonna.
- type_code: una stringa che rappresenta il tipo di colonna. Ad esempio, una colonna integer avrà un codice di tipo int.

Gli altri 5 elementi di ogni oggetto a 7 elementi tuple non vengono implementati e i relativi valori non sono definiti. In genere verranno restituiti come 4
I valori None seguiti da un singolo valore True.

Accesso di sola lettura.

I metodi Cursor selezionati includono i seguenti:

Metodi
`cancel` Interrompe l'esecuzione di qualsiasi query o comando di database avviato dal cursore. Per rilasciare le risorse associate nel server, chiamare il metodo `close` dopo aver chiamato il metodo `cancel`. Nessun parametro. Nessun valore restituito.
`close` Chiude il cursore e rilascia le risorse associate nel server. La chiusura di un cursore già chiuso potrebbe generare un errore. Nessun parametro. Nessun valore restituito.
`execute` Prepara e quindi esegue una query o un comando di database. Nessun valore restituito. Parametri: `operation` Tipo: `str` Query o comando da preparare e quindi eseguire. Questo parametro è obbligatorio. Esempio senza il parametro `parameters`: `cursor.execute(` `'SELECT * FROM samples.nyctaxi.trips WHERE pickup_zip="10019" LIMIT 2'` `)` Esempio con il parametro `parameters`: `cursor.execute(` `'SELECT * FROM samples.nyctaxi.trips WHERE zip=%(pickup_zip)s LIMIT 2',` `{ 'pickup_zip': '10019' }` `)` `parameters` Tipo: dizionario Sequenza di parametri da usare con il parametro `operation`. Il parametro è facoltativo. Il valore predefinito è `None`.
`executemany` Prepara e quindi esegue una query o un comando di database usando tutte le sequenze di parametri nell'argomento `seq_of_parameters`. Viene mantenuto solo il set di risultati finale. Nessun valore restituito. Parametri: `operation` Tipo: `str` Query o comando da preparare e quindi eseguire. Questo parametro è obbligatorio. `seq_of_parameters` Tipo: `list` di `dict` Sequenza di molti set di valori dei parametri da usare con il `operation` parametro. Questo parametro è obbligatorio.
`catalogs` Eseguire una query di metadati sui cataloghi. I risultati effettivi devono quindi essere recuperati usando `fetchmany` o `fetchall`. I campi importanti nel set di risultati includono: - Nome campo: `TABLE_CAT`. Digitare `str`. Nome del catalogo. Nessun parametro. Nessun valore restituito. A partire dalla versione 1.0
`schemas` Eseguire una query di metadati sugli schemi. I risultati effettivi devono quindi essere recuperati usando `fetchmany` o `fetchall`. I campi importanti nel set di risultati includono: - Nome campo: `TABLE_SCHEM`. Digitare `str`. Nome dello schema. - Nome campo: `TABLE_CATALOG`. Digitare `str`. Il catalogo a cui appartiene lo schema. Nessun valore restituito. A partire dalla versione 1.0 Parametri: `catalog_name` Tipo: `str` Nome del catalogo per recuperare informazioni a riguardo. Il carattere `%` viene interpretato come carattere jolly. Il parametro è facoltativo. `schema_name` Tipo: `str` Un nome dello schema per recuperare informazioni a riguardo. Il carattere `%` viene interpretato come carattere jolly. Il parametro è facoltativo.
`tables` Eseguire una query di metadati sulle tabelle e le viste. I risultati effettivi devono quindi essere recuperati usando `fetchmany` o `fetchall`. I campi importanti nel set di risultati includono: - Nome campo: `TABLE_CAT`. Digitare `str`. Il catalogo a cui appartiene la tabella. - Nome campo: `TABLE_SCHEM`. Digitare `str`. Nome dello schema a cui appartiene la tabella. - Nome campo: `TABLE_NAME`. Digitare `str`. Nome della tabella. - Nome campo: `TABLE_TYPE`. Digitare `str`. Il tipo di relazione, ad esempio `VIEW` o `TABLE` (si applica a Databricks Runtime 10.4 LTS e versioni successive, nonché a Databricks SQL; le versioni precedenti di Databricks Runtime restituiscono una stringa vuota). Nessun valore restituito. A partire dalla versione 1.0 Parametri `catalog_name` Tipo: `str` Nome del catalogo per recuperare informazioni a riguardo. Il carattere `%` viene interpretato come carattere jolly. Il parametro è facoltativo. `schema_name` Tipo: `str` Un nome dello schema per recuperare informazioni a riguardo. Il carattere `%` viene interpretato come carattere jolly. Il parametro è facoltativo. `table_name` Tipo: `str` Un nome della tabella per recuperare informazioni a riguardo. Il carattere `%` viene interpretato come carattere jolly. Il parametro è facoltativo. `table_types` Tipo: `List[str]` Elenco di tipi di tabella da trovare, ad esempio `TABLE` o `VIEW`. Il parametro è facoltativo.
`columns` Eseguire una query di metadati sulle colonne. I risultati effettivi devono quindi essere recuperati usando `fetchmany` o `fetchall`. I campi importanti nel set di risultati includono: - Nome campo: `TABLE_CAT`. Digitare `str`. Catalogo a cui appartiene la colonna. - Nome campo: `TABLE_SCHEM`. Digitare `str`. Lo schema a cui appartiene la colonna. - Nome campo: `TABLE_NAME`. Digitare `str`. Il nome della tabella a cui appartiene la colonna. - Nome campo: `COLUMN_NAME`. Digitare `str`. Nome della colonna. Nessun valore restituito. A partire dalla versione 1.0 Parametri: `catalog_name` Tipo: `str` Nome del catalogo per recuperare informazioni a riguardo. Il carattere `%` viene interpretato come carattere jolly. Il parametro è facoltativo. `schema_name` Tipo: `str` Un nome dello schema per recuperare informazioni a riguardo. Il carattere `%` viene interpretato come carattere jolly. Il parametro è facoltativo. `table_name` Tipo: `str` Un nome della tabella per recuperare informazioni a riguardo. Il carattere `%` viene interpretato come carattere jolly. Il parametro è facoltativo. `column_name` Tipo: `str` Un nome della colonna per recuperare informazioni a riguardo. Il carattere `%` viene interpretato come carattere jolly. Il parametro è facoltativo.
`fetchall` Ottiene tutte le righe (o tutte le righe rimanenti) di una query. Nessun parametro. Restituisce tutte le righe rimanenti della query come Python `list` degli oggetti `Row`. Genera una `Error` se la chiamata precedente al metodo `execute` non ha restituito dati o non è stata ancora effettuata alcuna chiamata `execute`.
`fetchmany` Ottiene le righe successive di una query. Restituisce fino a `size` (o all'attributo `arraysize` se `size` non è specificato) delle righe successive di una query come oggetti Python `list` di `Row`. Se sono presenti meno righe `size` da recuperare, verranno restituite tutte le righe rimanenti. Genera una `Error` se la chiamata precedente al metodo `execute` non ha restituito dati o non è stata ancora effettuata alcuna chiamata `execute`. Parametri: `size` Tipo: `int` Numero di righe successive da ottenere. Il parametro è facoltativo. Se non specificato, viene usato il valore dell’attributo `arraysize`. Esempio: `cursor.fetchmany(10)`
`fetchone` Ottiene la riga successiva del set di dati. Nessun parametro. Restituisce la riga successiva del set di dati come una singola sequenza come oggetto Python `tuple` oppure restituisce `None` se non sono presenti altri dati disponibili. Genera una `Error` se la chiamata precedente al metodo `execute` non ha restituito dati o non è stata ancora effettuata alcuna chiamata `execute`.
`fetchall_arrow` Ottiene tutte (o tutte le righe rimanenti) di una query, come oggetto PyArrow `Table`. Le query che restituiscono grandi quantità di dati devono invece usare `fetchmany_arrow` per ridurre il consumo di memoria. Nessun parametro. Restituisce tutte le righe (o tutte le righe rimanenti) della query come tabella PyArrow. Genera una `Error` se la chiamata precedente al metodo `execute` non ha restituito dati o non è stata ancora effettuata alcuna chiamata `execute`. A partire dalla versione 2.0
`fetchmany_arrow` Ottiene le righe successive di una query come oggetto PyArrow `Table`. Restituisce fino a `size` (o all'attributo `arraysize` se`size` non è specificato) delle righe successive di una query come Python PyArrow Oggetto `Table`. Genera una `Error` se la chiamata precedente al metodo `execute` non ha restituito dati o non è stata ancora effettuata alcuna chiamata `execute`. A partire dalla versione 2.0 Parametri: `size` Tipo: `int` Numero di righe successive da ottenere. Il parametro è facoltativo. Se non specificato, viene usato il valore dell’attributo `arraysize`. Esempio: `cursor.fetchmany_arrow(10)`

Classe `Row`

La classe row è una struttura di dati simile ad una tupla che rappresenta una singola riga di risultato. Se la riga contiene una colonna con il nome "my_column", è possibile accedere al campo "my_column" di row tramite row.my_column. È anche possibile usare indici numerici per accedere ai campi, ad esempio row[0]. Se il nome della colonna non è consentito come nome del metodo di attributo (ad esempio, inizia con una cifra), è possibile accedere al campo come row["1_my_column"].

A partire dalla versione 1.0

I metodi Row selezionati includono:

| asDict

Restituisce una rappresentazione del dizionario della riga, indicizzata in base ai nomi dei campi. Se sono presenti nomi di campo duplicati, uno dei campi duplicati (ma solo uno) verrà restituito nel dizionario. Il campo duplicato restituito non è definito.

Nessun parametro.

Restituisce un dict dei campi. |

Conversioni di tipi

La tabella seguente esegue il mapping dei tipi di dati SQL di Apache Spark agli equivalenti del tipo di dati Python.

Tipo di dati SQL di Apache Spark	Tipo di dati 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`

Risoluzione dei problemi

`tokenAuthWrapperInvalidAccessToken: Invalid access token` messaggio

Problema: quando si esegue il codice, viene visualizzato un messaggio simile a Error during request to server: tokenAuthWrapperInvalidAccessToken: Invalid access token.

Possibile causa: il valore passato a access_token non è un token di accesso personale di Azure Databricks valido.

Correzione consigliata: verificare che il valore passato a access_token sia corretto e riprovare.

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

Problema: quando si esegue il codice, viene visualizzato un messaggio simile a Error during request to server: gaierror(8, 'nodename nor servname provided, or not known').

Possibile causa: il valore passato a server_hostname non è il nome host corretto.

Correzione consigliata: verificare che il valore passato a server_hostname sia corretto e riprovare.

Per altre informazioni su come trovare il nome host del server, consultare Ottenere i dettagli della connessione per una risorsa di calcolo di Azure Databricks.

`IpAclError` messaggio

Problema: quando si esegue il codice, viene visualizzato il messaggio Error during request to server: IpAclValidation quando si tenta di usare il connettore in un notebook di Azure Databricks.

Possibile causa: è possibile che l'elenco indirizzi IP consentiti sia abilitato per l'area di lavoro di Azure Databricks. Con l'elenco degli indirizzi IP consentiti, le connessioni dai cluster Spark al piano di controllo non sono consentite per impostazione predefinita.

Correzione consigliata: chiedere all'amministratore di aggiungere la subnet del piano di calcolo all'elenco indirizzi IP consentiti.

Risorse aggiuntive

Per altre informazioni, vedi:

Il repository del connettore SQL di Databricks per Python in GitHub
Tipo di dati
Tipi predefiniti (per bool, bytearray, float, int e str) nel sito Web Python
datetime (per datetime.date e datatime.datetime) nel sito Web Python
decimal (per decimal.Decimal) nel sito Web Python
Costanti predefinite (per NoneType) nel sito Web Python

Condividi tramite

Connettore SQL di Databricks per Python

Requisiti

Introduzione

Cluster

Warehouse SQL

Autenticazione

Autenticazione con token di accesso personale di Databricks

Autenticazione OAuth da computer a computer (M2M)

Autenticazione con token di Microsoft Entra ID

Autenticazione da utente a computer (U2M) OAuth

Esempi

Eseguire query sui dati

Inserire i dati

Metadati delle query

Gestire cursori e connessioni

Gestisce i file nei volumi nel catalogo Unity

Configurare la registrazione

Test

Informazioni di riferimento sulle API

Pacchetto

Modulo

Classi

Classe `Connection`

Classe `Cursor`

Classe `Row`

Conversioni di tipi

Risoluzione dei problemi

`tokenAuthWrapperInvalidAccessToken: Invalid access token` messaggio

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

`IpAclError` messaggio

Risorse aggiuntive

Commenti e suggerimenti

Risorse aggiuntive

Condividi tramite

Connettore SQL di Databricks per Python

Requisiti

Introduzione

Cluster

Warehouse SQL

Autenticazione

Autenticazione con token di accesso personale di Databricks

Autenticazione OAuth da computer a computer (M2M)

Autenticazione con token di Microsoft Entra ID

Autenticazione da utente a computer (U2M) OAuth

Esempi

Eseguire query sui dati

Inserire i dati

Metadati delle query

Gestire cursori e connessioni

Gestisce i file nei volumi nel catalogo Unity

Configurare la registrazione

Test

Informazioni di riferimento sulle API

Pacchetto

Modulo

Classi

Classe Connection

Classe Cursor

Classe Row

Conversioni di tipi

Risoluzione dei problemi

tokenAuthWrapperInvalidAccessToken: Invalid access token messaggio

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

IpAclError messaggio

Risorse aggiuntive

Commenti e suggerimenti

Risorse aggiuntive

Classe `Connection`

Classe `Cursor`

Classe `Row`

`tokenAuthWrapperInvalidAccessToken: Invalid access token` messaggio

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

`IpAclError` messaggio