Condividi tramite

Modelli di aggregazione di asset di Databricks

  • Articolo

Questo articolo descrive la sintassi per i modelli di bundle di asset di Databricks, che funzionano con l'interfaccia della riga di comando di Databricks 0.218.0 e versioni successive. I bundle consentono la gestione a livello di codice dei flussi di lavoro di Azure Databricks. Vedere Che cosa sono i bundle di asset di Databricks?

I modelli di aggregazione consentono agli utenti di creare bundle in modo coerente e ripetibile, stabilendo strutture di cartelle, passaggi di compilazione e attività, test e altri attributi dell'infrastruttura distribuita come codice (IaC) DevOps comuni in una pipeline di distribuzione dell'ambiente di sviluppo.

Ad esempio, se si eseguono regolarmente processi di Databricks che richiedono pacchetti personalizzati con un passaggio di compilazione dispendioso in termini di tempo durante l'installazione, è possibile velocizzare il ciclo di sviluppo creando un modello di bundle che supporta ambienti contenitore personalizzati.

I modelli di bundle definiscono la struttura di directory del bundle che verrà creato e includono un databricks.yml.tmpl modello di file di configurazione, nonché un databricks_template_schema.json file contenente variabili di richiesta utente.

Creare un bundle basato su un modello

Questa sezione descrive come usare un modello di bundle, un modello di bundle predefinito di Azure Databricks o un modello di bundle personalizzato.

Usare un modello di bundle predefinito

Per usare un modello di bundle predefinito di Azure Databricks per creare il bundle, usare il comando dell'interfaccia della riga di comando di Databricksbundle init, specificando il nome del modello predefinito da usare. Ad esempio, il comando seguente crea un bundle usando il modello di bundle Python predefinito:

databricks bundle init default-python

Se non si specifica un modello predefinito, il bundle init comando presenta il set di modelli disponibili da cui è possibile scegliere.

Azure Databricks offre i modelli di bundle predefiniti seguenti:

Modello Descrizione
default-python Modello per l'uso di Python con Databricks. Questo modello crea un bundle con un processo e una pipeline delta live tables. Vedere default-python.
default-sql Modello per l'uso di SQL con Databricks. Questo modello contiene un file di configurazione che definisce un processo che esegue query SQL in un'istanza di SQL Warehouse. Vedere default-sql.
dbt-sql Modello che sfrutta dbt-core per lo sviluppo locale e i bundle per la distribuzione. Questo modello contiene la configurazione che definisce un processo con un'attività dbt, nonché un file di configurazione che definisce i profili dbt per i processi dbt distribuiti. Vedere dbt-sql.
mlops-stacks Modello avanzato di stack completo per l'avvio di nuovi progetti stack MLOps. Vedere mlops-stacks e aggregazioni di asset di Databricks per stack MLOps.

Usare un modello di bundle personalizzato

Per usare un modello di bundle diverso dai modelli di bundle predefiniti di Azure Databricks, passare il percorso locale o l'URL remoto del modello al comando dell'interfaccia della riga di comando di Databricksbundle init.

Ad esempio, il comando seguente usa il dab-container-template modello creato nell'esercitazione sul modello di bundle personalizzato:

   databricks bundle init /projects/my-custom-bundle-templates/dab-container-template

Creare un modello di bundle

I modelli di bundle usano la sintassi di creazione di modelli del pacchetto Go. Vedere la documentazione del modello di pacchetto Go.

Come minimo, un progetto di modello di bundle deve avere:

  • File databricks_template_schema.json nella radice del progetto che definisce una variabile di richiesta utente per il nome del progetto bundle.
  • File databricks.yml.tmpl che si trova in una template cartella che definisce la configurazione per tutti i bundle creati con il modello. Se il databricks.yml.tmpl file fa riferimento a modelli di configurazione aggiuntivi *.yml.tmpl , specificare il percorso di questi nel include mapping.

Facoltativamente, è possibile aggiungere sottocartelle e file alla cartella di cui si vuole eseguire il template mirroring nei bundle creati dal modello.

Definire le variabili di richiesta utente

Il primo passaggio per la creazione di un modello di bundle di base consiste nel creare una cartella di progetto modello e un file denominato databricks_template_schema.json nella radice del progetto. Questo file contiene le variabili per cui gli utenti forniscono valori di input quando usano il modello per creare un bundle usando bundle init. Questo formato di file segue la specifica dello schema JSON.

mkdir basic-bundle-template
touch basic-bundle-template/databricks_template_schema.json

Aggiungere quanto segue al databricks_template_schema.json file e quindi salvare il file:

{
   "properties": {
   "project_name": {
      "type": "string",
      "default": "basic_bundle",
      "description": "What is the name of the bundle you want to create?",
      "order": 1
   }
   },
   "success_message": "\nYour bundle '{{.project_name}}' has been created."
}

In questo file:

  • project_name è l'unico nome della variabile di input.
  • default è un valore predefinito facoltativo se un valore non viene fornito dall'utente con --config-file come parte del bundle init comando o sottoposto a override dall'utente al prompt dei comandi.
  • description è il prompt dell'utente associato alla variabile di input, se un valore non viene fornito dall'utente con --config-file come parte del bundle init comando.
  • order è un ordine facoltativo in cui ogni prompt dell'utente viene visualizzato se un valore non viene fornito dall'utente con --config-file come parte del bundle init comando. Se order non viene specificato, gli utenti visualizzano l'ordine in cui sono elencati nello schema.
  • success_message è un messaggio facoltativo visualizzato al termine della creazione del progetto.

Compilare la struttura di cartelle

Creare quindi la cartella richiesta template e compilare la struttura di cartelle al suo interno. Questa struttura verrà con mirroring in base ai bundle creati con questo modello. Inserire anche tutti i file che si desidera includere in tali cartelle. Questo modello di bundle di base archivia i file in una src cartella e include un semplice notebook.

mkdir -p basic-bundle-template/template/src
touch basic-bundle-template/template/src/simple_notebook.ipynb

Aggiungere quanto segue al simple_notebook.ipynb file:

print("Hello World!")

Popolare i file dei modelli di configurazione

Creare ora il file necessario databricks.yml.tmpl nella template cartella :

touch basic-bundle-template/template/databricks.yml.tmpl

Popolare questo file con il modello di configurazione di base YAML. Questo modello di configurazione stabilisce il nome del bundle, un processo usando il file del notebook specificato e due ambienti di destinazione per i bundle creati usando questo modello. Sfrutta anche le sostituzioni di bundle, che è altamente consigliato. Vedere Sostituzioni bundle.

# This is the configuration for the Databricks Asset Bundle {{.project_name}}.

bundle:
  name: {{.project_name}}

# The main job for {{.project_name}}
resources:
    jobs:
        {{.project_name}}_job:
        name: {{.project_name}}_job
        tasks:
            - task_key: notebook_task
            job_cluster_key: job_cluster
            notebook_task:
                notebook_path: ../src/simple_notebook.ipynb
        job_clusters:
            - job_cluster_key: job_cluster
            new_cluster:
                node_type_id: i3.xlarge
                spark_version: 13.3.x-scala2.12

targets:
  # The deployment targets. See https://docs.databricks.com/en/dev-tools/bundles/deployment-modes.html
  dev:
    mode: development
    default: true
    workspace:
      host: {{workspace_host}}

  prod:
    mode: production
    workspace:
      host: {{workspace_host}}
      root_path: /Shared/.bundle/prod/${bundle.name}
    {{- if not is_service_principal}}
    run_as:
      # This runs as {{user_name}} in production. Alternatively,
      # a service principal could be used here using service_principal_name
      user_name: {{user_name}}
    {{end -}}

Testare il modello di bundle

Infine, testare il modello. Creare una nuova cartella di progetto bundle, quindi usare l'interfaccia della riga di comando di Databricks per inizializzare un nuovo bundle usando il modello:

mkdir my-test-bundle
cd my-test-bundle
databricks bundle init ../basic-bundle-template

Per il prompt, What is your bundle project name?digitare my_test_bundle.

Dopo aver creato il bundle di test, viene restituito il messaggio di esito positivo del file di schema. Se si esamina il contenuto della my-test-bundle cartella, verrà visualizzato quanto segue:

my-test-bundle
   ├── databricks.yml
   └── src
      └── simple_notebook.ipynb

E il file databricks.yml è ora personalizzato:

# This is the configuration for the Databricks Asset Bundle my-test-bundle.

bundle:
  name: my-test-bundle

# The main job for my-test-bundle
resources:
    jobs:
        my-test-bundle_job:
        name: my-test-bundle_job
        tasks:
            - task_key: notebook_task
                job_cluster_key: job_cluster
                notebook_task:
                    notebook_path: ../src/simple_notebook.ipynb
        job_clusters:
            - job_cluster_key: job_cluster
                new_cluster:
                    node_type_id: i3.xlarge
                    spark_version: 13.3.x-scala2.12

targets:
  # The 'dev' target, used for development purposes. See [_](https://docs.databricks.com/en/dev-tools/bundles/deployment-modes.html#development-mode)
  dev:
    mode: development
    default: true
    workspace:
      host: https://my-host.cloud.databricks.com

  # The 'prod' target, used for production deployment. See [_](https://docs.databricks.com/en/dev-tools/bundles/deployment-modes.html#production-mode)
  prod:
    mode: production
    workspace:
      host: https://my-host.cloud.databricks.com
      root_path: /Shared/.bundle/prod/${bundle.name}
    run_as:
      # This runs as someone@example.com in production. Alternatively,
      # a service principal could be used here using service_principal_name
      user_name: someone@example.com

Condividere il modello

Se si vuole condividere questo modello di bundle con altri utenti, è possibile archiviarlo nel controllo della versione con qualsiasi provider supportato da Git e a cui gli utenti hanno accesso. Per eseguire il bundle init comando con un URL Git, assicurarsi che il databricks_template_schema.json file si trova nel percorso radice relativo a tale URL Git.

Suggerimento

È possibile inserire il databricks_template_schema.json file in una cartella diversa rispetto alla radice del bundle. È quindi possibile usare l'opzione bundle init del --template-dir comando per fare riferimento a tale cartella, che contiene il databricks_template_schema.json file.

Passaggi successivi