Connettore SQL di Databricks per Python

Il connettore SQL di Databricks per Python è una libreria Python che consente di usare il codice Python per eseguire i comandi SQL su Azure Databricks per il calcolo all-purpose e 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 la Specifica dell'API di Database di Python PEP 249 v2.0.

Importante

Databricks SQL Connector per Python versione 3.0.0 e successive supporta l'esecuzione di query con parametri nativa, che impedisce l'inserimento di SQL e può migliorare le prestazioni delle query. Le versioni precedenti usano l'esecuzione con parametri inline, che non è sicura da SQL injection e presenta altri svantaggi. Per altre informazioni, vedere Uso di parametri nativi.

Il connettore SQL di Databricks per Python supporta anche il sqlAlchemy dialetto per Azure Databricks, ma deve essere installato per usare queste funzionalità. Vedi Usare SQLAlchemy con Azure Databricks.

Requisiti

Un computer di sviluppo che esegue Python 3.8 e versioni successive.
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 ambiente di calcolo all-purpose esistente o SQL Warehouse.

Inizia

Installare il connettore SQL di Databricks per Python. PyArrow è una dipendenza facoltativa del connettore SQL di Databricks per Python e non è installata per impostazione predefinita nella versione 4.0.0 e successive del connettore. Se PyArrow non è installato, le funzionalità come CloudFetch e altre funzionalità di Apache Arrow non sono disponibili, che potrebbero influire sulle prestazioni per grandi volumi di dati.
- Per installare il lean connector, usare:
```
pip install databricks-sql-connector
```
- Per installare il connettore completo, incluso PyArrow, usare:
```
pip install databricks-sql-connector[pyarrow]
```
Raccogli le seguenti informazioni per il calcolo generico o il magazzino SQL che desideri usare:

Calcolo multiuso
- Nome host del server di calcolo multiuso. È possibile ottenere questo valore dal valore Server Hostname nella scheda Opzioni Avanzate > JDBC/ODBC per il calcolo generico.
- Percorso HTTP della computazione multiuso. È possibile ottenerlo dal valore percorso HTTP nella scheda Opzioni > avanzate JDBC/ODBC per il calcolo all-purpose.
Nota

Il connettore SQL non supporta la connessione alla computazione dei job.

Magazzino SQL
- Nome host del server di SQL Warehouse. È possibile ottenere questo dal valore nome host del server nella scheda Dettagli della connessione per il magazzino SQL.
- Percorso HTTP del warehouse SQL. È possibile ottenerlo dal valore percorso HTTP nella scheda Dettagli connessione per il 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 macchina (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 Creare token di accesso personali 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 siano state impostate le variabili di ambiente seguenti:

DATABRICKS_SERVER_HOSTNAMEimpostare sul valore Nome host server per il calcolo all-purpose o SQL Warehouse.
DATABRICKS_HTTP_PATH, impostato al valore percorso HTTP per il calcolo all-purpose o SQL Warehouse.
DATABRICKS_TOKEN, impostato sul token di accesso personale di Azure Databricks.

Per impostare le variabili di ambiente, vedere la documentazione del sistema operativo.

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 Python versioni 2.7.0 e successive supporta 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 primario di servizio di Azure Databricks nell'area di lavoro di Azure Databricks e creare un segreto OAuth per tale primario di servizio.

Per creare l'entità servizio e il relativo segreto OAuth, vedere Autorizzare l'accesso dell'entità servizio ad Azure Databricks con OAuth. Prendere nota del valore UUID o ID applicazione dell'entità servizio e del valore Secret per il segreto OAuth dell'entità servizio.
Concedere al principal di servizio l'accesso alle risorse di calcolo o al magazzino dati all-purpose.

Per concedere al principale di servizio l'accesso al calcolo di uso generale o al data warehouse, vedere 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 siano state impostate le variabili di ambiente seguenti:

DATABRICKS_SERVER_HOSTNAME impostato sul valore Nome host del server per il calcolo generico o magazzino SQL.
DATABRICKS_HTTP_PATH, impostato al valore percorso HTTP per il calcolo all-purpose o SQL Warehouse.
DATABRICKS_CLIENT_ID, impostato sul valore UUID o ID applicazione del principale del servizio.
DATABRICKS_CLIENT_SECRET, impostato al valore Secret per il segreto OAuth del principale del servizio.

Per impostare le variabili di ambiente, vedere la documentazione del sistema operativo.

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. Consulta Ottenere manualmente i token ID di Microsoft Entra.
Per un'entità servizio Microsoft Entra ID, vedere Ottenere i token per le entità servizio. Per creare un service principal gestito di Microsoft Entra ID, vedere Service principals.

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 siano state impostate le variabili di ambiente seguenti:

Imposta DATABRICKS_SERVER_HOSTNAME sul valore Nome host del server per il tuo ambiente computazionale generico o magazzino SQL.
Impostare DATABRICKS_HTTP_PATH sul valore per Percorso HTTP per il calcolo all-purpose o SQL Warehouse.
Impostare DATABRICKS_TOKEN sul token di Entra ID di Microsoft.

Per impostare le variabili di ambiente, vedere la documentazione del sistema operativo.

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 utente-macchina (U2M)

Databricks SQL Connector per Python versioni 2.7.0 e successive supportano l'autenticazione OAuth da utente a macchina (U2M). È 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 utilizza l'accesso umano in tempo reale e il consenso per autenticare l'account utente di Azure Databricks di destinazione. Questo frammento presuppone che siano state impostate le variabili di ambiente seguenti:

Imposta DATABRICKS_SERVER_HOSTNAME sul valore Nome host del server per il tuo ambiente computazionale generico o magazzino SQL.
Impostare DATABRICKS_HTTP_PATH sul valore per Percorso HTTP per il calcolo all-purpose o SQL Warehouse.

Per impostare le variabili di ambiente, vedere la documentazione del sistema operativo.

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, gestire i file nel catalogo di Unity 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 un tipo di autenticazione diverso, vedere 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 secondo i requisiti.

Imposta User-Agent

Nell'esempio di codice seguente viene illustrato come impostare l'applicazione User-Agent per il monitoraggio dell'utilizzo product_name.

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)

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 ambiente di calcolo all-purpose o in SQL Warehouse. Questo comando restituisce le prime due righe della trips tabella nello samples schema del nyctaxi catalogo.

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)

Tag di query

Importante

Questa funzionalità si trova in anteprima privata. Per richiedere l'accesso, contattare il team di account.

L'esempio seguente illustra come collegare tag chiave-valore alle query SQL per scopi di rilevamento e analisi. I tag di query vengono visualizzati nella system.query.history tabella.

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"),
    session_configuration = {
        'query_tags': 'team:engineering,dashboard:abc123,env:prod'
    }
) as connection:
    with connection.cursor() as cursor:
        cursor.execute("SELECT * FROM samples.nyctaxi.trips LIMIT ?", [2])
        result = cursor.fetchall()
        # Query is now tagged and trackable in system.query.history
        for row in result:
            print(row)

Inserire 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)]

    cursor.executemany("INSERT INTO squares VALUES (?, ?)", squares)

    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. Le risorse vengono liberate sui calcoli generici di Azure Databricks e sui magazzini 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()

Gestire i file nei volumi del catalogo di Unity

Il connettore SQL di Databricks consente di scrivere file locali in volumi di Unity Catalog , 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_allowed_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_allowed_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 '/tmp/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. L'esempio seguente configura il livello di registrazione e genera un log di debug:

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

Collaudo

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 get_connection_personal_access_token funzione che usa un token di accesso personale di Azure Databricks per restituire una connessione a un'area di lavoro di Azure Databricks e una select_nyctaxi_trips funzione che usa la connessione per ottenere il numero specificato di righe di dati dalla trips tabella nello samples schema del nyctaxi catalogo:

# 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("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, il mocking non è necessario in questo esempio. Tuttavia, il mocking consente di eseguire rapidamente i tuoi 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, UPDATEe DELETE FROM.

Informazioni di riferimento sulle API

Questa sezione contiene informazioni di riferimento sulle API per il databricks-sql-connector pacchetto. Vedere databricks-sql-connector nell'indice dei pacchetti Python (PyPI).

Modulo

Il databricks.sql modulo del databricks-sql-connector pacchetto contiene il metodo per inizializzare una connessione a un magazzino SQL.

metodo di connessione

Inizializza una connessione a un magazzino dati SQL. Restituisce un oggetto Connection.

Parametro	TIPO	Description
`server_hostname`	`str`	Obbligatorio. Nome host del server per il calcolo universale o il magazzino SQL, ad esempio `adb-1234567890123456.7.azuredatabricks.net`. Per ottenere il nome host del server, vedere le istruzioni in Introduzione.
`http_path`	`str`	Obbligatorio. Percorso HTTP del calcolo generale o SQL Warehouse, ad esempio `sql/protocolv1/o/1234567890123456/1234-567890-test123` per il calcolo generale o `/sql/1.0/warehouses/a1b234c567d8e9fa` per un'istanza di SQL Warehouse. Per ottenere il percorso HTTP, vedere le istruzioni in Introduzione.
`access_token`, `auth_type`, `credentials_provider`, , `password`, `username`	`str`	Informazioni sulle impostazioni di autenticazione di Azure Databricks. Per informazioni dettagliate, consultare Autenticazione.
`session_configuration`	`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`. Esempio: `{"spark.sql.variable.substitute": True}`
`http_headers`	`List[Tuple[str, str]]]`	Optional. 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`.
`catalog`	`str`	Optional. Catalogo iniziale da utilizzare per la connessione. L'impostazione predefinita è `None` (nel qual caso verrà utilizzato il catalogo predefinito, tipicamente `hive_metastore`).
`schema`	`str`	Optional. Schema iniziale da usare per la connessione. L'impostazione predefinita è `None` (nel qual caso verrà usato lo schema predefinito `default`). A partire dalla versione 2.0
`use_cloud_fetch`	`bool`	Optional. Se inviare richieste di recupero direttamente all'archivio oggetti cloud per scaricare blocchi di dati. Il valore predefinito è `True`. Impostare su `False` 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
`user_agent_entry`	`str`	Optional. Voce User-Agent da includere nell'intestazione della richiesta HTTP per il rilevamento dell'utilizzo. Il valore predefinito è `PyDatabricksSqlConnector`.

`Connection` classe

Rappresenta una connessione alle risorse di calcolo o a un magazzino SQL.

Metodi

La Connection classe fornisce i metodi seguenti.

Metodo	Description
`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 oggetto Cursor che abilita l'attraversamento dei record in un database. Nessun parametro.

`Cursor` classe

Rappresenta un meccanismo per l'attraversamento dei record di dati.

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

Attributi

Gli attributi selezionati Cursor includono quanto segue:

Attribute Description

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.

Attribute	Description
`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 oggetti `list` di `tuple` in Python. 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 risultati come indicato di seguito: `name`: nome della colonna. `type_code`: stringa che rappresenta il tipo della colonna. Ad esempio, una colonna integer avrà un codice di tipo di `int`. Gli altri 5 elementi di ogni oggetto `tuple` 7 elementi non vengono implementati e i relativi valori non sono definiti. In genere verranno restituiti come 4 `None` valori seguiti da un singolo `True` valore. Accesso di sola lettura.

description

Contiene oggetti list di tuple in Python. 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 risultati come indicato di seguito:

name: nome della colonna.
type_code: stringa che rappresenta il tipo della colonna. Ad esempio, una colonna integer avrà un codice di tipo di int. Gli altri 5 elementi di ogni oggetto tuple 7 elementi non vengono implementati e i relativi valori non sono definiti. In genere verranno restituiti come 4 None valori seguiti da un singolo True valore. Accesso di sola lettura.

Metodi

I metodi Cursor selezionati includono i seguenti:

Metodo	Description
`cancel`	Interrompe l'esecuzione di qualsiasi query o comando di database avviato dal cursore. Per rilasciare le risorse associate nel server, chiamare il `close` metodo dopo aver chiamato il `cancel` metodo . 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 successivamente esegue una query o un comando di database. Parametri: `operation`:Obbligatorio. Query o comando da preparare e quindi eseguire. Tipo: `str` Esempio senza il `parameters` parametro : `cursor.execute('SELECT * FROM samples.nyctaxi.trips LIMIT 2')` Esempio con il `parameters` parametro (usando parametri posizionali nativi): `cursor.execute('SELECT * FROM samples.nyctaxi.trips WHERE pickup_zip = ? LIMIT ?', ['10019', 2])` `parameters`: facoltativo. Sequenza di parametri da usare con il parametro `operation`. Il valore predefinito è `None`. Tipo: `dictionary` Nessun valore restituito.
`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. Parametri: `operation`:Obbligatorio. Query o comando da preparare e quindi eseguire. Tipo: `str` `seq_of_parameters`:Obbligatorio. Sequenza di molti set di valori di parametro da usare con il `operation` parametro . Tipo: `list` di `dict` Nessun valore restituito.
`catalogs`	Effettuare una interrogazione 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`. Nome del catalogo. Tipo: `str` 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`. Nome dello schema. Tipo: `str` Nome campo: `TABLE_CATALOG`. Catalogo a cui appartiene lo schema. Tipo: `str` Parametri: `catalog_name`: facoltativo. Nome di un catalogo da cui recuperare informazioni. Il carattere `%` viene interpretato come simbolo jolly. Tipo: `str` `schema_name`: facoltativo. Nome dello schema da cui recuperare informazioni. Il carattere `%` viene interpretato come simbolo jolly. Tipo: `str` Nessun valore restituito. A partire dalla versione 1.0
`tables`	Eseguire una query sui metadati riguardante tabelle e viste. I risultati effettivi devono quindi essere recuperati usando `fetchmany` o `fetchall`. I campi importanti nel set di risultati includono: Nome campo: `TABLE_CAT`. Catalogo a cui appartiene la tabella. Tipo: `str` Nome campo: `TABLE_SCHEM`. Schema a cui appartiene la tabella. Tipo: `str` Nome campo: `TABLE_NAME`. Nome della tabella. Tipo: `str` Nome campo: `TABLE_TYPE`. 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). Tipo: `str` Parametri: `catalog_name`: facoltativo. Nome di un catalogo da cui recuperare informazioni. Il carattere `%` viene interpretato come simbolo jolly. Tipo: `str` `schema_name`: facoltativo. Nome dello schema da cui recuperare informazioni. Il carattere `%` viene interpretato come simbolo jolly. Tipo: `str` `table_name`: facoltativo. Nome della tabella da cui recuperare informazioni. Il carattere `%` viene interpretato come simbolo jolly. Tipo: `str` `table_types`: facoltativo. Elenco di tipi di tabella da abbinare, ad esempio `TABLE` o `VIEW`. Tipo: `List[str]` Nessun valore restituito. A partire dalla versione 1.0
`columns`	Eseguire una query di metadati relative alle colonne. I risultati effettivi devono quindi essere recuperati usando `fetchmany` o `fetchall`. I campi importanti nel set di risultati includono: Nome campo: `TABLE_CAT`. Catalogo a cui appartiene la colonna. Tipo: `str` Nome campo: `TABLE_SCHEM`. Schema a cui appartiene la colonna. Tipo: `str` Nome campo: `TABLE_NAME`. Nome della tabella a cui appartiene la colonna. Tipo: `str` Nome campo: `COLUMN_NAME`. Nome della colonna. Tipo: `str` Parametri: `catalog_name`: facoltativo. Nome di un catalogo da cui recuperare informazioni. Il carattere `%` viene interpretato come simbolo jolly. Tipo: `str` `schema_name`: facoltativo. Nome dello schema da cui recuperare informazioni. Il carattere `%` viene interpretato come simbolo jolly. Tipo: `str` `table_name`: facoltativo. Nome della tabella da cui recuperare informazioni. Il carattere `%` viene interpretato come simbolo jolly. Tipo: `str` `column_name`: facoltativo. Nome di colonna su cui recuperare informazioni. Il carattere `%` viene interpretato come simbolo jolly. Tipo: `str` Nessun valore restituito. A partire dalla versione 1.0
`fetchall`	Ottiene tutte le righe (o tutte le righe rimanenti) di una query. Nessun parametro. Restituisce tutte le righe (o tutte le righe rimanenti) della query come un `list` di oggetti `Row` in Python. 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. Parametri: `size`: facoltativo. Numero di righe successive da ottenere. Se non specificato, viene usato il valore dell’attributo `arraysize`. Digitare `int`. Esempio: `cursor.fetchmany(10)` 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`.
`fetchone`	Ottiene la riga successiva del set di dati. Nessun parametro. Restituisce la riga successiva del set di dati come singola sequenza come oggetto Python `tuple` o 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 quelle rimanenti) della query come una 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`. Parametri: `size`: facoltativo. Numero di righe successive da ottenere. Se non specificato, viene usato il valore dell’attributo `arraysize`. Digitare `int`. Esempio: `cursor.fetchmany_arrow(10)` Restituisce fino all'argomento `size` (o all'attributo `arraysize` se `size` non è specificato) delle righe seguenti di una query come oggetto Python PyArrow `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

`Row` classe

La classe row è una struttura di dati simile a una tupla che rappresenta una singola riga di risultato in un risultato della query SQL. 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:

Metodi

Metodo	Description
`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.

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, vedere 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

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2025-10-31

Condividi tramite

Connettore SQL di Databricks per Python

Requisiti

Inizia

Calcolo multiuso

Magazzino 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 OAuth utente-macchina (U2M)

Esempi

Imposta User-Agent

Eseguire query sui dati

Tag di query

Inserire dati

Metadati delle query

Gestire cursori e connessioni

Gestire i file nei volumi del catalogo di Unity

Configurare la registrazione

Collaudo

Informazioni di riferimento sulle API

Modulo

metodo di connessione

Connection classe

Metodi

Cursor classe

Attributi

Metodi

Row classe

Metodi

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

`Connection` classe

`Cursor` classe

`Row` classe

`tokenAuthWrapperInvalidAccessToken: Invalid access token` messaggio

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

`IpAclError` messaggio