Databricks CLI: Gebruik Databricks vanaf de commandoregel

De Databricks Command Line Interface (CLI) is een krachtige tool waarmee je taken op het Databricks-platform rechtstreeks vanuit de terminal of de opdrachtprompt kunt automatiseren. Met de CLI kun je opdrachten uitvoeren voor het beheren van clusters, jobs en notebooks zonder door de grafische interface te hoeven navigeren, wat de efficiëntie verhoogt en de integratie in geautomatiseerde workflows verbetert.

Op dit moment is de Databricks CLI in Public Preview voor versies 0.205 en hoger. Gebruikers met oudere versies moeten weten dat deze als legacy worden beschouwd en mogelijk niet de nieuwste functies of verbeteringen ondersteunen die in de nieuwere versies beschikbaar zijn.

In deze tutorial laat ik je zien hoe je de CLI installeert en hoe je met de belangrijkste commando's door de CLI navigeert om je workflows te automatiseren. Als startpunt raad ik je aan om DataCamps blogpost How to Learn Databricks: A Beginner’s Guide to the Unified Data Platform te lezen, zodat je de kernfuncties en toepassingen van Databricks begrijpt en een gestructureerd pad krijgt om te beginnen met leren. 

Waarom we de Databricks CLI gebruiken

Als veelgebruiker zie ik de volgende redenen waarom je de Databricks CLI zou moeten gebruiken.

• Automatisering: Met de CLI kun je handelingen scripten zoals het aanmaken van clusters, het indienen van jobs en het beheren van notebooks. Deze automatisering bespaart tijd en verkleint de kans op fouten. Zo kun je bijvoorbeeld met één opdracht jobs aanmaken en uitvoeren.
• Integratie: De Databricks CLI integreert naadloos met DevOps-pijplijnen en CI/CD-processen. Met deze functionaliteit kun je eenvoudig je omgevingen configureren om implementaties en updates van Databricks-workflows te automatiseren zonder handmatige tussenkomst. Je kunt bijvoorbeeld geautomatiseerde jobs direct triggeren vanuit tools als Jenkins, GitHub Actions of Azure DevOps.
• Eenvoud: Je kunt taken rechtstreeks vanaf je lokale machine uitvoeren, zonder voor routinetaken door de web-UI te hoeven klikken. Dit maakt het beheren van je workflows gemakkelijker doordat je met commando's handelingen kunt uitvoeren zoals het uploaden van notebooks of het beheren van clusters, zonder de overhead van een grafische interface.
• Flexibiliteit: De Databricks CLI ondersteunt een breed scala aan besturingssystemen en omgevingen, zoals Windows, macOS en Linux, waardoor het toegankelijk is voor diverse teams. De CLI ondersteunt ook authenticatie met meerdere profielen, zodat je efficiënt meerdere Databricks-accounts of -workspaces kunt beheren. 

De Databricks CLI installeren en updaten

Om aan de slag te gaan met de Databricks CLI, moet je aan de omgevingsvereisten voldoen en de installatie-instructies volgen die specifiek zijn voor jouw besturingssysteem. Ik laat je zien hoe je de omgeving instelt en de CLI bijwerkt op Linux, macOS en Windows.

Omgevingsvereisten

Controleer vóór de installatie van de Databricks CLI of je systeem aan deze basisvereisten voldoet:

• Een pakketbeheerder: Hoewel een pakketbeheerder zoals Homebrew (voor macOS) of WinGet (voor Windows) de installatie kan vereenvoudigen, kun je ook direct installeren met binaries of broncode.
• Python: De CLI vereist Python 3.6 of later.
• Netwerktoegang tot de Databricks-workspace.
• Curl: Zorg ervoor dat curl is geïnstalleerd voor sommige installatiemethoden op Linux en macOS.
• Beheerdersrechten (voor sommige installatiemethoden).

Installeren op Linux

Er zijn verschillende manieren om de Databricks CLI op Linux te installeren, waaronder de volgende:

Met Homebrew

Als je Homebrew hebt geïnstalleerd, voer dan uit:

brew install databricks-cli

Met curl

Je kunt de Databricks CLI downloaden en installeren met curl door het volgende commando uit te voeren:

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

Handmatig downloaden

Je kunt het CLI-binary ook downloaden uit de officiële Databricks CLI GitHub-repository en het verplaatsen naar een map in je PATH.

Installeren op macOS

Als je macOS gebruikt, kun je de Databricks CLI installeren met de volgende commando's.

Met Homebrew

Voer het onderstaande commando uit om de Databricks CLI te installeren:

brew install databricks-cli

Directe installatie via binary

Download de nieuwste binary van GitHub-releases, pak deze uit en plaats hem in je lokale PATH. Maak hem uitvoerbaar met het onderstaande commando:

chmod +x /usr/local/bin/databricks

Handmatig downloaden

Je kunt het CLI-binary ook downloaden uit de officiële Databricks CLI GitHub-repository en het verplaatsen naar een map in je PATH.

Installeren op Windows

Als je Windows gebruikt, kun je kiezen uit de volgende installatiemethoden voor de Databricks CLI:

Met WinGet

Voer het volgende commando uit in de opdrachtprompt:

winget install Databricks.DatabricksCLI

Met Chocolatey

Als je Chocolatey hebt geïnstalleerd, gebruik dan:

choco install databricks-cli

Met Windows Subsystem for Linux (WSL)

Als WSL is ingesteld, volg dan de Linux-installatiestappen.

Directe installatie via binary

Download het .exe-bestand van de Databricks CLI GitHub-repository.

Voeg de map met het bestand toe aan de PATH van je systeem voor eenvoudige toegang.

Installatie verifiëren

Na de installatie controleer je of de Databricks CLI correct is geïnstalleerd. Open een terminal of opdrachtprompt en voer uit:

databricks --version

Authenticatie en configuratie van de Databricks CLI

Om de Databricks CLI effectief te gebruiken, moet je authenticeren bij je Databricks-workspace. In deze sectie behandel ik hoe je authenticatie instelt en configuraties beheert.

Een persoonlijk toegangstoken genereren

Een persoonlijk toegangstoken (PAT) is vereist om te authenticeren met de Databricks CLI. Volg deze stappen om er een te genereren:

Stap 1: Ga naar je gebruikersinstellingen 

Log in op je Databricks-workspace en klik op je gebruikersnaam in de bovenbalk. Kies Instellingen in het dropdownmenu.

Gebruikersinstellingen in Databricks-workspace. Afbeelding door de auteur.

Stap 2: Ga naar ontwikkelaarsinstellingen 

Klik op Developer.

Databricks Developer-instellingen. Afbeelding door de auteur.

Stap 3: Toegangstokens beheren

Klik naast Access tokens op Manage.

Databricks-toegangstokens. Afbeelding door de auteur

Stap 4: Nieuw token genereren

Klik op Generate new token.

Een nieuw Databricks-toegangstoken genereren. Afbeelding door de auteur.

Stap 5: Details invoeren en token opslaan

Geef een opmerking op om het token te identificeren en stel de levensduur in dagen in. Als je dit leeg laat, wordt de maximale levensduur gebruikt (meestal 730 dagen). Klik op Generate, kopieer het token veilig en klik vervolgens op Done.

Nieuw Databricks-toegangstoken genereren. Afbeelding door de auteur.

Profielen configureren

Zodra je je token hebt, configureer je de CLI om met je workspace te communiceren. Dit houdt in dat je een profiel instelt met je workspace-URL en token.

Basisconfiguratie

Voer het volgende commando uit om je standaardprofiel in te stellen:

databricks configure --token

Je wordt gevraagd om in te voeren:

De Databricks host-URL (bijv. https://<databricks-instance>.cloud.databricks.com).

Het Personal Access Token dat je eerder hebt gegenereerd.

Databricks CLI-profiel configureren. Afbeelding door de auteur.

Meerdere profielen

Je kunt meerdere profielen configureren voor verschillende omgevingen (bijv. dev, staging, productie):

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

Om een specifiek profiel te gebruiken, voeg je de vlag --profile toe aan je CLI-commando's:

databricks clusters list --profile staging

Geavanceerde authenticatie

De Databricks CLI ondersteunt Databricks Unified Authentication, dat integreert met enterprise identity management-systemen zoals Single Sign-On (SSO) en OAuth. Dit zorgt voor veilige en schaalbare authenticatie over alle Databricks-API's. Unified authentication vereenvoudigt gebruikersbeheer door één SSO-configuratie mogelijk te maken voor meerdere workspaces, waardoor het beheren van toegang en het automatiseren van taken met service-principals eenvoudiger wordt.

De belangrijkste Databricks CLI-commando's

De Databricks CLI organiseert functionaliteit in hoofdcategorieën, elk met subcommando's voor specifieke taken. Hieronder vind je een overzicht van de belangrijkste categorieën en praktische voorbeelden om te starten. Als je je kennis over de belangrijkste functies van Databricks wilt opfrissen, raad ik onze tutorial 7 Must-know Concepts For Any Data Specialist aan.

Clusters

De clusters-commando's zijn voor het beheren van Databricks-clusters, waaronder aanmaken, tonen, starten en verwijderen. Veelgebruikte subcommando's zijn onder meer:

• create: Maak een nieuw cluster.

• list: Toon alle clusters in de workspace.

• start en delete: Start of verwijder een cluster.

Het volgende commando maakt bijvoorbeeld een nieuw cluster met de naam my-cluster met 4 workers van het type Standard_D2_v2.

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

Je kunt ook het volgende commando gebruiken om alle clusters in je Databricks-workspace te tonen.

databricks clusters list

Jobs

Dit zijn commando's voor het beheren van Databricks-jobs, waaronder aanmaken, uitvoeren en tonen. Veelgebruikte subcommando's voor jobs zijn onder meer:

• create: Maak een nieuwe job.

• run-now: Start een bestaande job direct.

• list: Toon alle beschikbare jobs.

Zo kun je bijvoorbeeld een nieuwe job aanmaken met de naam my-job die een notebook-taak uitvoert.

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

Je kunt ook een bestaande job triggeren op basis van zijn ID met het onderstaande commando.

databricks jobs run-now --job-id 12345

Workspace

Dit zijn commando's voor het beheren van workspace-resources, zoals het importeren en exporteren van notebooks. Veelgebruikte subcommando's in deze categorie zijn onder meer:

• import: Importeer een notebook of bibliotheek.

• export: Exporteer een notebook naar je lokale machine.

• list: Toon de inhoud van een workspace-map.

Je kunt bijvoorbeeld een notebook exporteren naar een lokaal bestand met het onderstaande commando.

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

Op dezelfde manier kun je een notebook importeren met het onderstaande commando.

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

Bestandssysteem (DBFS)

Dit zijn commando's om te werken met het Databricks File System (DBFS), waaronder het uploaden en downloaden van bestanden. Veelgebruikte subcommando's in deze categorie zijn onder meer:

• cp: Kopieer bestanden naar of van DBFS.

• ls: Toon bestanden in een DBFS-map.

• rm: Verwijder bestanden of mappen uit DBFS.

Zo kun je met het onderstaande commando een lokaal bestand uploaden naar DBFS.

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

Op dezelfde manier kun je met het volgende commando een bestand downloaden van DBFS naar een lokaal pad.

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

Repos

Met de repos-commando's beheer je repositories binnen Databricks, wat versiebeheer mogelijk maakt. Veelgebruikte subcommando's zijn onder meer:

• list: Toon alle repositories.

• create: Voeg een nieuwe repository toe.

Het volgende commando toont bijvoorbeeld alle Databricks Repos in je workspace.

databricks repos list

Rechten

Met deze commando's kun je rechten instellen en beheren voor workspaces, jobs en clusters. Veelgebruikte subcommando's voor rechten zijn onder meer:

• get: Bekijk de huidige rechten.

• update: Wijzig rechten.

Met het onderstaande commando kun je bijvoorbeeld de rechten voor een specifieke resource bekijken.

databricks permissions get --type cluster --id 12345

Databricks SQL-commando's

Met deze commando's kun je werken met Databricks SQL om databases te bevragen en SQL-warehouses te beheren.

De volgende query haalt de eerste 10 rijen op uit de sales_table en toont ze.

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

Als je je kennis over Databricks SQL wilt opfrissen, raad ik onze Databricks SQL-tutorial aan om te leren hoe je met SQL gegevens opvraagt uit het Databricks SQL Warehouse.

Veelvoorkomende use-cases en voorbeeldscenario's

De Databricks CLI biedt praktische oplossingen voor het automatiseren van routinetaken. Hieronder staan uitgewerkte voorbeelden van veelvoorkomende scenario's die de veelzijdigheid laten zien.

Een cluster maken of bewerken

Gebruik een JSON-configuratiebestand, zoals cluster-config.json, dat de clusterinstellingen specificeert om een cluster te maken.

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

Voer vervolgens het volgende commando uit om het cluster te maken:

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

Om de configuratie van een bestaand cluster bij te werken, exporteer je eerst de huidige clusterinstellingen met het onderstaande commando:

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

Bewerk daarna het bestand cluster-config.json zoals nodig en pas de wijzigingen toe op het cluster.

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

Notebooks beheren

In sommige scenario's wil je misschien een notebook exporteren uit Databricks naar een lokale map en het daarna weer importeren. Gebruik het volgende commando om het notebook te exporteren:

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

Met het onderstaande commando upload je het notebook terug naar Databricks.

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

Jobs triggeren

Als je geautomatiseerde taken wilt maken, moet je mogelijk een job aanmaken die een notebook of script draait en deze inplannen om dagelijks te draaien. Gebruik eerst een JSON-bestand zoals job-config.json om een job te definiëren die een specifiek notebook uitvoert.

{
  "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"
  }
}

Maak de job aan met het onderstaande commando:

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

Vervolgens kun je de job uitvoeren op basis van het job-ID.

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

Bestandsbewerkingen op DBFS

Als je bestanden in DBFS wilt tonen, kopiëren of verwijderen, gebruik dan de volgende commando's.

Bestanden in een map bekijken:

databricks fs ls dbfs:/path/to/directory

Een lokaal bestand uploaden naar DBFS:

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

Een bestand of map verwijderen:

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

Best practices en tips

Overweeg de volgende best practices om de efficiëntie, veiligheid en betrouwbaarheid van de Databricks CLI te maximaliseren.

• Blijf up-to-date met versies: Zorg dat je Databricks CLI versie 0.200 of later gebruikt om te profiteren van actieve ontwikkeling en nieuwe functies. Oudere versies worden als legacy beschouwd en missen mogelijk ondersteuning voor de nieuwste functionaliteiten.
• Beveiliging: Sla persoonlijke toegangstokens niet in platte tekst op. Gebruik in plaats daarvan omgevingsvariabelen of veilige opslagmethoden zoals versleutelde bestanden of secrets-managementtools.
• Scripten: Gebruik Bash- of Python-scripts om taken te automatiseren door meerdere CLI-commando's te koppelen. Dit vereenvoudigt complexe workflows en verbetert de reproduceerbaarheid.
• Loggen/debuggen: Gebruik de vlag --debug om uitgebreide output voor debuggen in te schakelen. Dit helpt bij het diagnosticeren van problemen door gedetailleerde foutmeldingen te geven.

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

De Databricks CLI vergeleken met andere aanpakken

Bij het werken met Databricks heb je meerdere opties om met het platform te communiceren, waaronder de Databricks CLI, REST-API's, de Databricks Python SDK en de web-UI. Elke methode heeft voor- en nadelen, afhankelijk van de specifieke behoeften en voorkeuren van de gebruiker of organisatie.

REST-API's

De Databricks REST-API's bieden directe, low-level toegang tot Databricks-functionaliteit en zijn het meest flexibel voor taalagnostische integraties.

Databricks Python SDK

De Databricks Python SDK biedt een Pythonic interface voor interactie met Databricks, met high-level abstracties bovenop REST-API's.

Web-UI

De Databricks Web-UI biedt een interactieve grafische interface voor het beheren van clusters, jobs, notebooks en meer.

Ik vat de voordelen, zwaktes en use-cases van de bovenstaande methoden samen in de volgende tabel:

Probleemoplossing en bekende issues

Bij het gebruik van de Databricks CLI kun je te maken krijgen met veelvoorkomende fouten en uitdagingen. Hieronder vind je een samenvatting van frequente problemen en praktische oplossingen, plus tips voor het diagnosticeren van netwerkgerelateerde problemen.

Veelvoorkomende fouten

Veelvoorkomende fouten bij het gebruik van de Databricks CLI zijn onder andere:

• Autorisatie mislukt: De fout kan worden veroorzaakt door een onjuist of verlopen persoonlijk toegangstoken. Controleer of je token geldig is en correct is geconfigureerd in je CLI-instellingen. Genereer indien nodig een nieuw token.
• CLI niet gevonden in PATH: Deze fout treedt op wanneer het uitvoerbare bestand van de Databricks CLI niet in de PATH van je systeem staat. Voeg altijd de map met het CLI-uitvoerbare bestand toe aan de omgevingsvariabele PATH van je systeem.
• Token verlopen: Tokens hebben een beperkte levensduur en verlopen na een bepaalde periode. Vernieuw je token periodiek of stel een mechanisme in om tokens automatisch te vernieuwen om dit te voorkomen.

Netwerkproblemen diagnosticeren

In omgevingen met beperkte netwerken of IP-allowlists kun je problemen ondervinden bij het verbinden met Databricks. Hier zijn enkele stappen om deze problemen te diagnosticeren en op te lossen:

• Controleer netwerkconfiguratie: Zorg dat je netwerk uitgaande verbindingen naar de URL van de Databricks-workspace toestaat. Controleer of firewalls of proxyservers correct zijn geconfigureerd.

• IP-allowlists: Als je workspace IP-allowlisting vereist, zorg dan dat je IP-adres in de lijst staat. Gebruik tools zoals curl om de connectiviteit vanaf je machine naar de Databricks-API te testen.

• SSL-verificatie: Als je SSL-verificatiefouten tegenkomt, probeer dan tijdelijk SSL-verificatie uit te schakelen met de optie —k bij curl om het probleem te isoleren.

Conclusie en verdere bronnen

Ik hoop dat ik je heb kunnen overtuigen dat oefenen met de Databricks CLI de moeite waard is. Zoals je hebt gezien, maakt de Databricks CLI snelle, scriptbare automatisering mogelijk van taken zoals clustermanagement, jobs triggeren en bestandsoperaties, waardoor je minder afhankelijk bent van de web-UI en tijd bespaart. Ik ben onder de indruk van de flexibiliteit en de integratie met DevOps-pijplijnen.

Er zijn zeker veel specifieke details die ik niet in één artikel kon behandelen, dus kijk vooral in de officiële Databricks-documentatie of op de GitHub-pagina van de CLI als je op zoek bent naar het antwoord op een specifieke vraag. Wil je meer leren over de belangrijkste basisconcepten, probeer dan onze cursus Introduction to Databricks. Deze cursus leert je over Databricks als datawarehousingoplossing voor Business Intelligence. Als je het pad inslaat om Databricks te leren, raad ik ook onze gids over Databricks-certificeringen aan, zodat je niet alleen Databricks leert maar jezelf ook goed positioneert op de arbeidsmarkt.