Condividi tramite

Databricks SQL Connessione or per Python

  • Articolo

Databricks SQL Connessione or 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. Databricks SQL Connessione or 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

Databricks SQL Connessione or per Python include anche un dialetto SQLAlchemy per Azure Databricks. Vedere 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 databricks SQL Connessione or per Python. La configurazione e l'uso di ambienti virtuali non rientra nell'ambito di questo articolo. Per altre informazioni, vedere Creazione di ambienti virtuali.
  • Un cluster esistente o sql warehouse.

Operazioni preliminari

  • Installare il Connessione or SQL di Databricks per 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

    Sql Warehouse

    • Nome host del server di SQL Warehouse. È possibile ottenere questo valore dal valore Nome host server nella scheda Dettagli Connessione ion per sql warehouse.
    • Percorso HTTP del warehouse SQL. È possibile ottenerlo dal valore Percorso HTTP nella scheda Dettagli Connessione ion per sql warehouse.

Autenticazione

Databricks SQL Connessione or per Python supporta i tipi di autenticazione di Azure Databricks seguenti:

Databricks SQL Connessione or per Python non supporta ancora i tipi di autenticazione di Azure Databricks seguenti:

Autenticazione del token di accesso personale di Databricks

Per usare databricks SQL Connessione or per Python con l'autenticazione del token di accesso personale di Azure Databricks, è prima necessario creare un token di accesso personale di Azure Databricks, come indicato di seguito:

  1. Nell'area di lavoro di Azure Databricks fare clic sul nome utente di Azure Databricks nella barra superiore e quindi selezionare Impostazioni dall'elenco a discesa.
  2. Fare clic su Sviluppatore.
  3. Accanto a Token di accesso fare clic su Gestisci.
  4. Fare clic su Genera nuovo token.
  5. (Facoltativo) Immettere un commento che consente di identificare questo token in futuro e modificare la durata predefinita del token di 90 giorni. Per creare un token senza durata (scelta non consigliata), lasciare vuota la casella Durata (giorni) (vuota).
  6. Fare clic su Genera.
  7. Copiare il token visualizzato in un percorso sicuro e quindi fare clic su Fine.

Nota

Assicurarsi di salvare il token copiato in un percorso sicuro. Non condividere il token copiato con altri utenti. Se si perde il token copiato, non è possibile rigenerare lo stesso token esatto. È invece necessario ripetere questa procedura per creare un nuovo token. Se si perde il token copiato o si ritiene che il token sia stato compromesso, Databricks consiglia vivamente di eliminare immediatamente il token dall'area di lavoro facendo clic sull'icona del cestino (Revoca) accanto al token nella pagina Token di accesso.

Se non è possibile creare o usare token nell'area di lavoro, questo potrebbe essere dovuto al fatto che l'amministratore dell'area di lavoro ha disabilitato i token o non ha concesso l'autorizzazione per creare o usare token. Vedere l'amministratore dell'area di lavoro o quanto segue:

Per autenticare databricks SQL Connessione or 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 cluster o SQL Warehouse.
  • DATABRICKS_HTTP_PATH, impostato sul valore percorso HTTP per il cluster o SQL Warehouse.
  • DATABRICKS_TOKEN, impostare 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 da computer a computer OAuth (M2M)

Databricks SQL Connessione or per Python versioni 2.7.0 e successive supportano l'autenticazione da computer a computer OAuth (M2M). È 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 databricks SQL Connessione or per Python con l'autenticazione OAuth M2M, è necessario eseguire le operazioni seguenti:

  1. 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, vedere Autenticazione da computer a computer (M2M) OAuth. Prendere nota del valore UUID o ID applicazione dell'entità servizio e del valore Secret per il segreto OAuth dell'entità servizio.

  2. Concedere all'entità servizio l'accesso al cluster o al warehouse.

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

Per autenticare databricks SQL Connessione or per Python, usare il frammento di codice seguente. Questo frammento presuppone che siano state impostate le variabili di ambiente seguenti:

  • DATABRICKS_SERVER_HOSTNAME impostare 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 UUID o ID applicazione dell'entità servizio.
  • DATABRICKS_CLIENT_SECRET, impostare sul valore Secret (Segreto ) per il segreto OAuth dell'entità 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 del token di Microsoft Entra ID (in precedenza Azure Active Directory)

Per usare l'Connessione or sql di Databricks per Python con l'autenticazione del token Microsoft Entra ID (in precedenza Azure Active Directory), è necessario fornire il databricks SQL Connessione or per Python con il token ID Microsoft Entra. Per creare un token di accesso di Microsoft Entra ID, eseguire le operazioni seguenti:

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 databricks SQL Connessione or per Python, usare il frammento di codice seguente. Questo frammento presuppone che siano state impostate le variabili di ambiente seguenti:

  • Impostare DATABRICKS_SERVER_HOSTNAME sul valore Server Hostname per il cluster o SQL Warehouse.
  • Impostare su DATABRICKS_HTTP_PATHPercorso HTTP per il cluster o SQL Warehouse.
  • Impostare DATABRICKS_TOKEN sul token MICROSOFT Entra ID.

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 da utente a computer (U2M) OAuth

Databricks SQL Connessione or per 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 databricks SQL Connessione or per Python con l'autenticazione U2M OAuth, 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 siano state impostate le variabili di ambiente seguenti:

  • Impostare DATABRICKS_SERVER_HOSTNAME sul valore Server Hostname per il cluster o SQL Warehouse.
  • Impostare su DATABRICKS_HTTP_PATHPercorso HTTP per il cluster 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 Connessione or 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, vedere Autenticazione.

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

  • DATABRICKS_SERVER_HOSTNAME, che rappresenta il valore Nome host server dai requisiti.
  • DATABRICKS_HTTP_PATH, che rappresenta il valore del percorso HTTP dai 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

L'esempio di codice seguente illustra come chiamare databricks SQL Connessione or 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 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)

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 with sintassi usata negli esempi precedenti) per gestire le risorse o chiamare closein 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()

Configurare la registrazione

Databricks SQL Connessione or 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 in corso

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 Python, ad esempio 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(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 le get_connection_personal_access_token funzioni 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 select_nyctaxi_trips funzione restituisce la risposta prevista. Anziché creare una connessione reale all'area di lavoro di destinazione, questo test simula un Connection oggetto. 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 select_nyctaxi_trips funzione contiene un'istruzione SELECT e pertanto non modifica lo stato della trips tabella, 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, UPDATEe DELETE FROM.

Informazioni di riferimento sulle API

Pacchetto

databricks-sql-connector

Sintassi: pip install databricks-sql-connector

Vedere 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

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 Connection oggetto, chiamare il databricks.sql.connect metodo con i parametri seguenti:

Parametri
server_hostname

Tipo: str

Nome host del server per il cluster o SQL Warehouse. Per ottenere il nome host del server, vedere 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, vedere 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 un'istanza di SQL Warehouse.
access_token, auth_type

Tipo: str

Informazioni sulle impostazioni di autenticazione di Azure Databricks. Per informazioni dettagliate, vedere Autenticazione.
session_configuration

Tipo: dict[str, Any]

Dizionario dei parametri di configurazione della sessione Spark. L'impostazione di una configurazione equivale all'uso del SET key=val comando SQL. Eseguire il comando SET -v SQL 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.

Dalla versione 2.0
catalog

Tipo: str

Catalogo iniziale da utilizzare per la connessione. L'impostazione predefinita è None (nel qual caso verrà usato il catalogo predefinito, in hive_metastoregenere , ).

Il parametro è facoltativo.

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.

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.

Dalla versione 2.8

I metodi selezionati Connection includono quanto segue:

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 Cursor oggetto, chiamare il Connection metodo della cursor classe.

Gli attributi selezionati Cursor includono quanto segue:

Attributi
arraysize

Usato con il fetchmany metodo , 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/scrittura.
description

Contiene un python list di tuple oggetti. Ognuno di questi tuple oggetti contiene 7 valori, con i primi 2 elementi di ogni tuple oggetto contenente informazioni che descrivono una singola colonna di risultato 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 .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
None valori seguiti da un singolo True valore.

Accesso in sola lettura.

I metodi selezionati Cursor includono quanto segue:

Metodi
cancel

Interrompe l'esecuzione di qualsiasi query o comando di database avviato dal cursore. Per rilasciare le risorse associate nel server, chiamare
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 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 parameters parametro :


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

Esempio con il parameters parametro :


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

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

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. Catalogo a cui appartiene lo schema.

Nessun valore restituito.

Dalla versione 1.0

Parametri:

catalog_name

Tipo: str

Nome del catalogo per recuperare informazioni su . Il % carattere viene interpretato come carattere jolly.

Il parametro è facoltativo.

schema_name

Tipo: str

Nome dello schema per recuperare informazioni su . 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. Catalogo a cui appartiene la tabella.
* Nome campo: TABLE_SCHEM. Digitare str. 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.

Dalla versione 1.0

Parametri

catalog_name

Tipo: str

Nome del catalogo per recuperare informazioni su . Il % carattere viene interpretato come carattere jolly.

Il parametro è facoltativo.

schema_name

Tipo: str

Nome dello schema per recuperare informazioni su . Il % carattere viene interpretato come carattere jolly.

Il parametro è facoltativo.

table_name

Tipo: str

Nome di tabella per recuperare informazioni su . 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. Schema a cui appartiene la colonna.
* Nome campo: TABLE_NAME. Digitare str. Nome della tabella a cui appartiene la colonna.
* Nome campo: COLUMN_NAME. Digitare str. Nome della colonna.

Nessun valore restituito.

Dalla versione 1.0

Parametri:

catalog_name

Tipo: str

Nome del catalogo per recuperare informazioni su . Il % carattere viene interpretato come carattere jolly.

Il parametro è facoltativo.

schema_name

Tipo: str

Nome dello schema per recuperare informazioni su . Il % carattere viene interpretato come carattere jolly.

Il parametro è facoltativo.

table_name

Tipo: str

Nome di tabella per recuperare informazioni su . Il % carattere viene interpretato come carattere jolly.

Il parametro è facoltativo.

column_name

Tipo: str

Nome di colonna per recuperare informazioni su . Il % carattere viene interpretato come carattere jolly.

Il parametro è facoltativo.
fetchall

Ottiene tutte o tutte le righe rimanenti di una query.

Nessun parametro.

Restituisce tutte le righe rimanenti della query come Python list di
Row Oggetti.

Genera un'eccezione Error se la chiamata precedente al execute metodo non ha restituito dati o non è stata ancora effettuata alcuna execute chiamata.
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 Python list di Row oggetti.

Se sono presenti meno righe size da recuperare, verranno restituite tutte le righe rimanenti.

Genera un'eccezione Error se la chiamata precedente al execute metodo non ha restituito dati o non è stata ancora effettuata alcuna execute chiamata.

Parametri:

size

Tipo: int

Numero di righe successive da ottenere.

Il parametro è facoltativo. Se non specificato, viene utilizzato 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 Python
tuple oppure restituisce None se non sono presenti altri dati disponibili.

Genera un'eccezione Error se la chiamata precedente al execute metodo non ha restituito dati o non è stata ancora effettuata alcuna execute chiamata.
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 rimanenti della query come tabella PyArrow.

Genera un'eccezione Error se la chiamata precedente al execute metodo non ha restituito dati o non è stata ancora effettuata alcuna execute chiamata.

Dalla versione 2.0
fetchmany_arrow

Ottiene le righe successive di una query come oggetto PyArrow Table .

Restituisce fino all'argomento size (o all'attributo arraysize se size non è specificato) delle righe successive di una query come Python PyArrow
Oggetto Table.

Genera un'eccezione Error se la chiamata precedente al execute metodo non ha restituito dati o non è stata ancora effettuata alcuna execute chiamata.

Dalla versione 2.0

Parametri:

size

Tipo: int

Numero di righe successive da ottenere.

Il parametro è facoltativo. Se non specificato, viene utilizzato il valore dell'attributo arraysize .

Esempio: cursor.fetchmany_arrow(10)

Classe Row

La classe row è una struttura di dati simile a una tupla che rappresenta una singola riga di risultato. Se la riga contiene una colonna con il nome "my_column", è possibile accedere al "my_column" campo 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"].

Dalla versione 1.0

I metodi selezionati Row 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 oggetto di 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, 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: