Databricks CLI: usa Databricks dalla riga di comando

La Command Line Interface (CLI) di Databricks è uno strumento potente che ti consente di automatizzare attività sulla piattaforma Databricks direttamente dal terminale o dal prompt dei comandi. Con la CLI puoi eseguire comandi per gestire cluster, job e notebook senza dover passare dall’interfaccia grafica, aumentando l’efficienza e l’integrazione nei workflow automatizzati.

Al momento, la Databricks CLI è in Public Preview per le versioni 0.205 e successive. Gli utenti che utilizzano versioni precedenti dovrebbero considerarle legacy: potrebbero non supportare le funzionalità o i miglioramenti più recenti disponibili nelle versioni nuove.

In questo tutorial ti mostrerò come installare la CLI e come orientarti tra i comandi principali per automatizzare i tuoi workflow. Prima di iniziare, ti consiglio vivamente di leggere il post sul blog di DataCamp How to Learn Databricks: A Beginner’s Guide to the Unified Data Platform, che ti aiuterà a capire le funzionalità chiave e le applicazioni di Databricks e ti fornirà un percorso strutturato per cominciare a imparare. 

Perché usare la Databricks CLI

Da utilizzatore assiduo, ecco i motivi per cui dovresti usare la Databricks CLI.

• Automazione: la CLI ti permette di scriptare operazioni come la creazione di cluster, l’invio di job e la gestione dei notebook. Questa automazione fa risparmiare tempo e riduce la probabilità di errori. Per esempio, puoi creare ed eseguire job con un unico comando.
• Integrazione: la Databricks CLI si integra senza problemi con pipeline DevOps e processi CI/CD. Grazie a questa funzionalità, puoi configurare facilmente gli ambienti per automatizzare deployment e aggiornamenti dei workflow Databricks senza interventi manuali. Ad esempio, puoi attivare job automatici direttamente da strumenti come Jenkins, GitHub Actions o Azure DevOps.
• Semplicità: puoi eseguire attività direttamente dalla tua macchina locale, evitando di navigare nella web UI per le operazioni di routine. Questo rende più semplice gestire i workflow eseguendo comandi per operazioni come il caricamento di notebook o la gestione dei cluster, senza il peso di un’interfaccia grafica.
• Flessibilità: la Databricks CLI supporta un’ampia gamma di sistemi operativi e ambienti, come Windows, macOS e Linux, rendendola accessibile a team eterogenei. La CLI supporta anche l’autenticazione multi-profile, permettendoti di gestire in modo efficiente più account o workspace Databricks. 

Installare e aggiornare la Databricks CLI

Per iniziare con la Databricks CLI, devi soddisfare i prerequisiti dell’ambiente e seguire le istruzioni di installazione specifiche per il tuo sistema operativo. Ti mostrerò come configurare l’ambiente e aggiornare la CLI su Linux, macOS e Windows.

Prerequisiti dell’ambiente

Prima di installare la Databricks CLI, assicurati che il tuo sistema soddisfi questi requisiti di base:

• Un gestore di pacchetti: anche se un gestore di pacchetti come Homebrew (per macOS) o WinGet (per Windows) può semplificare l’installazione, puoi anche installare direttamente usando binari o codice sorgente.
• Python: la CLI richiede Python 3.6 o successivo.
• Accesso di rete al workspace Databricks.
• Curl: per alcuni metodi di installazione su Linux e macOS, assicurati che curl sia installato.
• Privilegi di amministratore (per alcuni metodi di installazione).

Installazione su Linux

Esistono diversi modi per installare la Databricks CLI su Linux, tra cui i seguenti:

Con Homebrew

Se hai Homebrew installato, esegui:

brew install databricks-cli

Con curl

Puoi scaricare e installare la Databricks CLI usando curl eseguendo il seguente comando:

curl -Lo databricks-cli.tar.gz https://github.com/databricks/databricks-cli/releases/latest/download/databricks-cli.tar.gz
tar -xzf databricks-cli.tar.gz -C /usr/local/bin

Download manuale

In alternativa, puoi scaricare il binario della CLI dall’repository GitHub di Databricks CLI ufficiale e spostarlo in una directory presente nel tuo PATH.

Installazione su macOS

Se usi macOS, puoi installare la Databricks CLI con i seguenti comandi.

Con Homebrew

Esegui il comando qui sotto per installare la Databricks CLI;

brew install databricks-cli

Installazione diretta del binario

Scarica l’ultimo binario dalle release su GitHub, estrailo e posizionalo nel tuo PATH locale. Rendilo eseguibile con il comando seguente:

chmod +x /usr/local/bin/databricks

Download manuale

Allo stesso modo, puoi scaricare il binario della CLI dall’repository GitHub di Databricks CLI ufficiale e spostarlo in una directory presente nel tuo PATH.

Installazione su Windows

Se utilizzi Windows, puoi scegliere di installare la Databricks CLI con uno dei seguenti metodi:

Con WinGet

Esegui il seguente comando nel prompt dei comandi:

winget install Databricks.DatabricksCLI

Con Chocolatey

Se hai installato Chocolatey, usa:

choco install databricks-cli

Con Windows Subsystem for Linux (WSL)

Se WSL è configurato, segui i passaggi di installazione per Linux.

Installazione diretta del binario

Scarica il file .exe da la repository GitHub di Databricks CLI.

Aggiungi la directory che contiene il file al PATH di sistema per un accesso rapido.

Verifica dell’installazione

Dopo l’installazione, verifica che la Databricks CLI sia stata installata correttamente. Apri un terminale o prompt dei comandi ed esegui:

databricks --version

Autenticazione e configurazione della Databricks CLI

Per usare efficacemente la Databricks CLI, devi autenticarti con il tuo workspace Databricks. In questa sezione vedremo come configurare l’autenticazione e gestire le configurazioni.

Generare un personal access token

Per autenticarsi con la Databricks CLI è necessario un personal access token (PAT). Segui questi passaggi per generarne uno:

Passaggio 1: accedi alle impostazioni utente 

Accedi al tuo workspace Databricks e fai clic sul tuo nome utente nella barra in alto. Seleziona Settings dal menu a discesa.

Impostazioni utente del workspace Databricks. Immagine dell’autore.

Passaggio 2: vai alle impostazioni per sviluppatori 

Fai clic su Developer.

Impostazioni Developer di Databricks. Immagine dell’autore.

Passaggio 3: gestisci gli access token

Accanto a Access tokens, fai clic su Manage.

Access token di Databricks. Immagine dell’autore

Passaggio 4: genera un nuovo token

Fai clic su Generate new token.

Generazione di un nuovo Access token di Databricks. Immagine dell’autore.

Passaggio 5: inserisci i dettagli e salva il token

Aggiungi un commento per identificare il token e imposta la durata in giorni. Se lasci vuoto, verrà applicata la durata massima (in genere 730 giorni). Fai clic su Generate, copia il token in modo sicuro e poi su Done.

Generazione di un nuovo Access token di Databricks. Immagine dell’autore.

Configurare i profili

Una volta ottenuto il token, configura la CLI per comunicare con il tuo workspace. Questo processo prevede la creazione di un profilo che includa l’URL del workspace e il token.

Configurazione di base

Esegui il seguente comando per impostare il profilo predefinito:

databricks configure --token

Ti verrà chiesto di inserire:

L’URL host di Databricks (ad es., https://<databricks-instance>.cloud.databricks.com).

Il Personal Access Token che hai generato in precedenza.

Configurazione del profilo Databricks CLI. Immagine dell’autore.

Profili multipli

Puoi configurare più profili per ambienti diversi (ad es., dev, staging, production):

databricks configure --profile <profile-name> --token

Per usare un profilo specifico, includi il flag --profile nei comandi CLI:

databricks clusters list --profile staging

Autenticazione avanzata

La Databricks CLI supporta la Databricks Unified Authentication, che si integra con sistemi enterprise di gestione delle identità come Single Sign-On (SSO) e OAuth. Ciò consente un’autenticazione sicura e scalabile su tutte le API di Databricks. L’autenticazione unificata semplifica la gestione degli utenti consentendo una singola configurazione SSO per più workspace, rendendo più semplice gestire gli accessi e automatizzare le attività usando i service principal.

I principali comandi della Databricks CLI

La Databricks CLI organizza le sue funzionalità in categorie di alto livello, ciascuna con sottocomandi pensati per compiti specifici. Di seguito trovi una panoramica delle principali categorie e alcuni esempi pratici per iniziare. Se vuoi ripassare le funzionalità principali di Databricks, ti consiglio il nostro tutorial su 7 concetti da conoscere per ogni specialista dei dati.

Clusters

I comandi clusters servono a gestire i cluster Databricks, inclusi creazione, elenco, avvio ed eliminazione. I sottocomandi comuni includono:

• create: crea un nuovo cluster.

• list: elenca tutti i cluster nel workspace.

• start e delete: avvia o elimina un cluster.

Ad esempio, il seguente comando crea un nuovo cluster chiamato my-cluster con 4 worker di tipo Standard_D2_v2.

databricks clusters create --cluster-name my-cluster --node-type-id Standard_D2_v2 --num-workers 4

Puoi anche usare il seguente comando per elencare tutti i cluster nel tuo workspace Databricks.

databricks clusters list

Jobs

Questi comandi servono a gestire i job di Databricks, inclusi creazione, esecuzione e elenco. I sottocomandi comuni includono:

• create: crea un nuovo job.

• run-now: avvia immediatamente un job esistente.

• list: elenca tutti i job disponibili.

Ad esempio, puoi creare un nuovo job chiamato my-job che esegue un task notebook.

databricks jobs create --job-name my-job --notebook-task /path/to/notebook

Puoi anche avviare un job esistente tramite il suo ID usando il comando qui sotto.

databricks jobs run-now --job-id 12345

Workspace

Questi comandi servono a gestire le risorse del workspace, come importare ed esportare notebook. I sottocomandi comuni includono:

• import: importa un notebook o una libreria.

• export: esporta un notebook sulla tua macchina locale.

• list: elenca il contenuto di una directory del workspace.

Ad esempio, puoi esportare un notebook in un file locale con il seguente comando.

databricks workspace export /Users/username/notebook /local/path/notebook.py

Allo stesso modo, puoi importare un notebook con il comando seguente.

databricks workspace import /local/path/notebook.py /Users/username/notebook

File system (DBFS)

Questi comandi servono a interagire con il Databricks File System (DBFS), inclusi caricamento e download dei file. I sottocomandi comuni includono:

• cp: copia file da o verso DBFS.

• ls: elenca i file in una directory DBFS.

• rm: rimuove file o directory da DBFS.

Ad esempio, puoi usare il comando qui sotto per caricare un file locale su DBFS.

databricks fs cp /local/path/file.txt dbfs:/path/in/dbfs/

Allo stesso modo, il seguente comando ti consente di scaricare un file da DBFS in un percorso locale.

databricks fs cp dbfs:/path/in/dbfs/file.txt /local/path/

Repos

I comandi repos ti permettono di gestire repository all’interno di Databricks, abilitando il controllo di versione. I sottocomandi comuni includono:

• list: elenca tutti i repository.

• create: aggiunge un nuovo repository.

Ad esempio, il seguente comando elenca tutti i Databricks Repos nel tuo workspace.

databricks repos list

Permissions

Puoi usare questi comandi per impostare e gestire i permessi per workspace, job e cluster. I sottocomandi comuni includono:

• get: visualizza i permessi correnti.

• update: modifica i permessi.

Ad esempio, il comando seguente ti permette di visualizzare i permessi per una specifica risorsa.

databricks permissions get --type cluster --id 12345

Comandi Databricks SQL

Questi comandi ti consentono di interagire con Databricks SQL per interrogare database e gestire i SQL warehouse.

La query seguente recupera e visualizza le prime 10 righe di sales_table.

databricks sql query --query "SELECT * FROM sales_table LIMIT 10;"

Se vuoi ripassare Databricks SQL, ti consiglio il nostro tutorial Databricks SQL per imparare a usare SQL per interrogare i dati dal Databricks SQL Warehouse.

Casi d’uso comuni e scenari di esempio

La Databricks CLI offre soluzioni pratiche per automatizzare le attività di routine. Di seguito trovi esempi dettagliati di scenari comuni che ne dimostrano la versatilità.

Creare o modificare un cluster

Per creare un cluster, usa un file di configurazione JSON, ad esempio cluster-config.json, che specifica le impostazioni del cluster.

{
  "cluster_name": "example-cluster",
  "spark_version": "11.3.x-scala2.12",
  "node_type_id": "Standard_DS3_v2",
  "num_workers": 2
}

Quindi esegui il seguente comando per creare il cluster:

databricks clusters create --json-file cluster-config.json

Per aggiornare la configurazione di un cluster esistente, prima esporta le impostazioni correnti del cluster usando il comando seguente:

databricks clusters get --cluster-id <cluster-id> > cluster-config.json

Poi modifica il file cluster-config.json come necessario e applica le modifiche al cluster.

databricks clusters edit --json-file cluster-config.json

Gestire i notebook

In alcuni scenari potresti voler esportare un notebook da Databricks in una directory locale e poi importarlo di nuovo. Usa il seguente comando per importare esportare il notebook:

databricks workspace export /path/to/notebook.ipynb /local/path/notebook.ipynb

Il comando qui sotto serve per caricare nuovamente il notebook su Databricks.

databricks workspace import /local/path/notebook.ipynb /path/to/notebook.ipynb

Attivare job

Quando vuoi creare attività automatizzate, potresti dover creare un job che esegue un notebook o uno script e programmarlo per essere eseguito ogni giorno. Per prima cosa, usa un file JSON come job-config.json per definire un job che esegue un notebook specifico.

{
  "name": "example-job",
  "new_cluster": {
    "spark_version": "11.3.x-scala2.12",
    "node_type_id": "Standard_DS3_v2",
    "num_workers": 1
  },
  "notebook_task": {
    "notebook_path": "/Users/username/my-notebook"
  },
  "schedule": {
    "quartz_cron_expression": "0 0 * * * ?",
    "timezone_id": "UTC"
  }
}

Crea il job con il comando seguente:

databricks jobs create --json-file job-config.json

Puoi quindi eseguire il job tramite il suo job ID.

databricks jobs run-now --job-id <job-id>

Operazioni su file in DBFS

Se devi elencare, copiare o rimuovere file in DBFS, usa i seguenti comandi.

Per visualizzare i file in una directory:

databricks fs ls dbfs:/path/to/directory

Carica un file locale su DBFS:

databricks fs cp /local/path/file.txt dbfs:/path/to/remote-file.txt

Elimina un file o una directory:

databricks fs rm dbfs:/path/to/file.txt

Best practice e consigli

Per massimizzare efficienza, sicurezza e affidabilità della Databricks CLI, considera di adottare le seguenti best practice.

• Rimani aggiornato sulle versioni: assicurati di usare la Databricks CLI versione 0.200 o successiva per beneficiare dello sviluppo attivo e delle nuove funzionalità. Le versioni precedenti sono considerate legacy e potrebbero non supportare le funzionalità più recenti.
• Sicurezza: evita di archiviare i personal access token in chiaro. Usa invece variabili d’ambiente o metodi di archiviazione sicura come file cifrati o strumenti di gestione dei secret.
• Script: usa script Bash o Python per automatizzare le attività concatenando più comandi CLI. Questo approccio semplifica i workflow complessi e migliora la riproducibilità.
• Logging/Debug: usa il flag --debug per abilitare un output dettagliato per il debug. Può aiutarti a diagnosticare i problemi fornendo messaggi di errore dettagliati.

databricks --debug clusters create --cluster-name my-cluster --node-type-id Standard_D2_v2 --num-workers 4

Confronto tra Databricks CLI e altri approcci

Quando lavori con Databricks, hai diverse opzioni per interagire con la piattaforma, tra cui Databricks CLI, REST API, Databricks Python SDK e web UI. Ogni metodo ha vantaggi e svantaggi, a seconda delle esigenze e preferenze dell’utente o dell’organizzazione.

REST API

Le REST API di Databricks forniscono accesso diretto e di basso livello alle funzionalità di Databricks, offrendo la massima flessibilità per integrazioni indipendenti dal linguaggio.

Databricks Python SDK

Il Databricks Python SDK offre un’interfaccia “pythonic” per interagire con Databricks, fornendo astrazioni di alto livello sopra le REST API.

Web UI

La Web UI di Databricks offre un’interfaccia grafica interattiva per gestire cluster, job, notebook e altro.

Riassumo vantaggi, punti deboli e casi d’uso dei metodi sopra nella seguente tabella:

Risoluzione dei problemi e issue note

Usando la Databricks CLI, potresti incontrare errori e difficoltà comuni. Di seguito trovi un riepilogo dei problemi più frequenti e delle soluzioni pratiche, insieme a consigli per diagnosticare i problemi di rete.

Errori frequenti

Gli errori frequenti quando si usa la Databricks CLI includono:

• Authorization Failed: l’errore può essere causato da un personal access token errato o scaduto. Per risolvere, assicurati che il token sia valido e correttamente configurato nelle impostazioni della CLI. Se necessario, genera un nuovo token.
• CLI Not Found in PATH: questo errore si verifica quando l’eseguibile della Databricks CLI non è nel PATH di sistema. Per risolvere, aggiungi sempre la directory contenente l’eseguibile della CLI alla variabile d’ambiente PATH del sistema.
• Scadenza del token: i token hanno una durata limitata e scadono dopo un periodo definito. Per evitare l’errore, rinnova periodicamente il token o imposta un meccanismo per aggiornarlo automaticamente.

Diagnosticare i problemi di rete

In ambienti con reti ristrette o allowlist di IP, potresti riscontrare problemi nel connetterti a Databricks. Ecco alcuni passaggi per diagnosticare e risolvere questi problemi:

• Verifica la configurazione di rete: assicurati che la tua rete consenta connessioni in uscita all’URL del workspace Databricks. Verifica che eventuali firewall o proxy siano configurati correttamente.

• IP Allowlists: se il tuo workspace richiede un’allowlist di IP, assicurati che il tuo indirizzo IP sia incluso nell’elenco. Usa strumenti come curl per testare la connettività dalla tua macchina alle API di Databricks.

• Verifica SSL: se riscontri errori di verifica SSL, prova a disabilitare temporaneamente la verifica SSL usando l’opzione —k con curl per isolare il problema.

Conclusione e risorse utili

Spero di averti convinto che vale la pena esercitarsi con la Databricks CLI. Come hai visto, la Databricks CLI consente un’automazione rapida e scriptabile di attività come gestione dei cluster, avvio dei job e operazioni sui file, riducendo la dipendenza dalla web UI e facendo risparmiare tempo. Mi ha colpito la sua flessibilità e il fatto che si integri con le pipeline DevOps.

Ci sono sicuramente molti dettagli specifici che non ho potuto trattare in un solo articolo, quindi prova a consultare la documentazione ufficiale di Databricks o la pagina GitHub della CLI se stai cercando la risposta a una domanda specifica. Per approfondire i concetti fondamentali più importanti, prova il nostro corso Introduction to Databricks. Questo corso ti insegna Databricks come soluzione di data warehousing per la Business Intelligence. Ti consiglio anche, se stai intraprendendo il percorso di apprendimento di Databricks, di leggere la nostra guida sulle certificazioni Databricks, in modo da non solo imparare Databricks ma anche posizionarti al meglio nel mercato del lavoro.