Sustituciones y variables en Agrupaciones de recursos de Databricks

Artículo
02/12/2025

Agrupaciones de recursos de Databricks admite sustituciones y variables personalizadas, lo que hace que los archivos de configuración de agrupación sean más modulares y reutilizables. Tanto las sustituciones como las variables personalizadas permiten la recuperación dinámica de valores, de modo que la configuración se pueda determinar en el momento en que se implementa y se ejecuta una agrupación.

Sugerencia

También puede usar referencias de valor dinámico para los valores de parámetros de trabajo para pasar contexto sobre una ejecución de trabajo a tareas de trabajo. Consulte ¿Qué es una referencia de valores dinámicos? y Parametrización de trabajos.

Sustituciones

Puede usar sustituciones para recuperar valores de configuración que cambian en función del contexto de la implementación y ejecución de la agrupación.

Por ejemplo, al ejecutar el comando bundle validate --output json, es posible que vea un gráfico similar al siguiente:

{
  "bundle": {
    "name": "hello-bundle",
    "target": "dev",
    "...": "..."
  },
  "workspace": {
    "...": "...",
    "current_user": {
      "...": "...",
      "userName": "someone@example.com",
      "...": "...",
    },
    "...": "..."
  },
  "...": {
    "...": "..."
  }
}

Las sustituciones se pueden usar para hacer referencia a los valores de los campos de agrupación name, agrupación target y área de trabajo userName a fin de construir el área de trabajo root_path en el archivo de configuración de agrupación:

bundle:
  name: hello-bundle

workspace:
  root_path: /Users/${workspace.current_user.userName}/.bundle/${bundle.name}/my-envs/${bundle.target}

# ...

targets:
  dev:
    default: true

También puede crear sustituciones para los recursos con nombre. Por ejemplo, para la canalización configurada con el nombre my_pipeline, ${resources.pipelines.my_pipeline.target} es la sustitución del valor del destinomy_pipeline.

Para determinar las sustituciones válidas, puede usar la jerarquía de esquemas documentada en la Referencia de la API de REST o la salida del comando bundle schema.

Estas son algunas sustituciones usadas habitualmente:

${bundle.name}
${bundle.target} # Use this substitution instead of ${bundle.environment}
${workspace.host}
${workspace.current_user.short_name}
${workspace.current_user.userName}
${workspace.file_path}
${workspace.root_path}
${resources.jobs.<job-name>.id}
${resources.models.<model-name>.name}
${resources.pipelines.<pipeline-name>.name}

Variables personalizadas

Puede definir variables personalizadas simples y complejas en la agrupación a fin de habilitar la recuperación dinámica de valores necesarios para muchos escenarios. Las variables personalizadas se declaran en los archivos de configuración de paquetes dentro del mapeo de variables o en un archivo de variable-overrides.json. Para obtener información sobre la asignación de variables, consulte variables.

La siguiente configuración de ejemplo define las variables my_cluster_id y my_notebook_path:

variables:
  my_cluster_id:
    description: The ID of an existing cluster.
    default: 1234-567890-abcde123
  my_notebook_path:
    description: The path to an existing notebook.
    default: ./hello.py

Si no proporciona un valor default para una variable como parte de esta declaración, debe establecerlo al ejecutar comandos de agrupación, a través de una variable de entorno, o bien en otro lugar de los archivos de configuración de la agrupación, como se describe en Establecimiento del valor de una variable.

También puede definir y establecer valores de variable en el archivo .databricks/bundle/<target>/variable-overrides.json del proyecto de agrupación, donde <target> es el destino del área de trabajo, como dev. Ver Establecer el valor de una variable.

Hacer referencia a una variable

Para hacer referencia a una variable personalizada en la configuración de agrupación, use la sustitución${var.<variable_name>} de la variable. Por ejemplo, para hacer referencia a las variables my_cluster_id y my_notebook_path:

resources:
  jobs:
    hello-job:
      name: hello-job
      tasks:
        - task_key: hello-task
          existing_cluster_id: ${var.my_cluster_id}
          notebook_task:
            notebook_path: ${var.my_notebook_path}

Establecimiento del valor de una variable

Si no ha proporcionado un valor de default para una variable, o si desea invalidar temporalmente el valor de default para una variable, proporcione el nuevo valor temporal de la variable mediante uno de los métodos siguientes:

Proporcione el valor de la variable como parte de un comando bundle, como validate, deploy o run. Para ello, use la opción --var="<key>=<value>", donde <key> es el nombre de la variable y <value> es el valor de la variable. Por ejemplo, como parte del comando bundle validate, para proporcionar el valor de 1234-567890-abcde123 a la variable denominada my_cluster_id y el valor de ./hello.py a la variable denominada my_notebook_path, ejecute:
```
databricks bundle validate --var="my_cluster_id=1234-567890-abcde123,my_notebook_path=./hello.py"

# Or:
databricks bundle validate --var="my_cluster_id=1234-567890-abcde123" --var="my_notebook_path=./hello.py"
```
Proporcione el valor de la variable estableciendo una variable de entorno. El nombre de la variable de entorno debe comenzar por BUNDLE_VAR_. Para establecer las variables de entorno, consulte la documentación del sistema operativo. Por ejemplo, para proporcionar el valor de 1234-567890-abcde123 a la variable denominada my_cluster_id y el valor de ./hello.py a la variable denominada my_notebook_path, ejecute el siguiente comando antes de llamar a un comando bundle como validate, deploy o run:

Para Linux y macOS:
```
export BUNDLE_VAR_my_cluster_id=1234-567890-abcde123 && export BUNDLE_VAR_my_notebook_path=./hello.py
```
Para Windows:
```
"set BUNDLE_VAR_my_cluster_id=1234-567890-abcde123" && "set BUNDLE_VAR_my_notebook_path=./hello.py"
```
O bien, proporcione el valor de la variable como parte de un comando bundle como validate, deploy o run, por ejemplo para Linux y macOS:
```
BUNDLE_VAR_my_cluster_id=1234-567890-abcde123 BUNDLE_VAR_my_notebook_path=./hello.py databricks bundle validate
```
O para Windows:
```
"set BUNDLE_VAR_my_cluster_id=1234-567890-abcde123" && "set BUNDLE_VAR_my_notebook_path=./hello.py" && "databricks bundle validate"
```
Proporcione el valor de la variable dentro de los archivos de configuración de paquete utilizando el mapeo variables dentro del mapeo targets, siguiendo este formato:
```
variables:
  <variable-name>: <value>
```
Por ejemplo, para establecer valores para las variables denominadas my_cluster_id y my_notebook_path para dos destinos independientes:
```
targets:
  dev:
    variables:
      my_cluster_id: 1234-567890-abcde123
      my_notebook_path: ./hello.py
  prod:
    variables:
      my_cluster_id: 2345-678901-bcdef234
      my_notebook_path: ./hello.py
```
Proporcione el valor de la variable en el archivo .databricks/bundle/<target>/variable-overrides.json, con el siguiente formato:
```
{
  "<variable-name>": "<variable-value>"
}
```
Por ejemplo, para proporcionar valores para las variables denominadas my_cluster_id y my_notebook_path para el destino de desarrollo, cree un archivo .databricks/bundle/dev/variable-overrides.json y establezca su contenido en:
```
{
  "my_cluster_id": "1234-567890-abcde123",
  "my_notebook_path": "./hello.py"
}
```
También puede definir variables complejas en el archivo variable-overrides.json.

Nota:

Independientemente del enfoque que elija para proporcionar valores de variable, debe proporcionar los mismos valores durante las fases de implementación y ejecución. De lo contrario, podría obtener resultados inesperados entre el momento de una implementación y la ejecución de un trabajo o canalización que se base en esa implementación existente.

Orden de precedencia

La CLI de Databricks busca valores para las variables en el orden siguiente, deteniendo cuando encuentra un valor para una variable:

Dentro de las --var opciones especificadas como parte del comando bundle.
Dentro de cualquier conjunto de variables de entorno que comiencen por BUNDLE_VAR_.
En el archivo variables-overrides.json, si existe.
Dentro de las asignaciones variables, entre las asignaciones targets dentro de los archivos de configuración de agrupación.
Cualquier valor default de la definición de esa variable, entre las asignaciones variables de nivel superior dentro de los archivos de configuración de agrupación.

Definición de una variable compleja

Se supone que una variable personalizada es de tipo cadena a menos que la defina como una variable compleja. Para definir una variable personalizada con un tipo complejo para el paquete en su configuración del paquete, establezca type a complex.

Nota:

El único valor válido para la configuración type es complex. Además, la validación de la agrupación no se produce si type se establece en complex y si el valor default definido para la variable es un valor único.

En el ejemplo siguiente, la configuración del clúster se define en una variable compleja personalizada denominada my_cluster:

variables:
  my_cluster:
    description: "My cluster definition"
    type: complex
    default:
      spark_version: "13.2.x-scala2.11"
      node_type_id: "Standard_DS3_v2"
      num_workers: 2
      spark_conf:
        spark.speculation: true
        spark.databricks.delta.retentionDurationCheck.enabled: false

resources:
  jobs:
    my_job:
      job_clusters:
        - job_cluster_key: my_cluster_key
          new_cluster: ${var.my_cluster}
      tasks:
      - task_key: hello_task
        job_cluster_key: my_cluster_key

También puede definir una variable compleja en el archivo .databricks/bundles/<target>/variable-overrides.json, como se muestra en el ejemplo siguiente:

{
  "my_cluster": {
    "spark_version": "13.2.x-scala2.11",
    "node_type_id": "Standard_DS3_v2",
    "num_workers": 2
  }
}

Recuperación de un valor de id. de objeto

Para el alert, cluster_policy, cluster, dashboard, instance_pool, job, metastore, notification_destination, pipeline, query, service_principal y warehouse tipos de objeto, puede definir un lookup para la variable personalizada para recuperar un identificador de objeto con nombre mediante este formato:

variables:
  <variable-name>:
    lookup:
      <object-type>: "<object-name>"

Si se define una búsqueda para una variable, el id. del objeto con el nombre especificado se usa como valor de la variable. Esto garantiza que el id. resuelto correcto del objeto siempre se use para la variable.

Nota:

Se produce un error si no existe un objeto con el nombre especificado o si hay más de un objeto con el nombre especificado.

Por ejemplo, en la siguiente configuración, ${var.my_cluster_id} se reemplazará por el identificador del clúster compartido de 12.2.

variables:
  my_cluster_id:
    description: An existing cluster
    lookup:
      cluster: "12.2 shared"

resources:
  jobs:
    my_job:
      name: "My Job"
      tasks:
        - task_key: TestTask
          existing_cluster_id: ${var.my_cluster_id}

Compartir a través de

Sustituciones y variables en Agrupaciones de recursos de Databricks

Sustituciones

Variables personalizadas

Hacer referencia a una variable

Establecimiento del valor de una variable

Orden de precedencia

Definición de una variable compleja

Recuperación de un valor de id. de objeto

Comentarios

Recursos adicionales