Usa parámetros con canalizaciones

Los parámetros de canalización permiten reutilizar el mismo código fuente de canalización en entornos o conjuntos de datos. Por ejemplo, puede ejecutar las mismas transformaciones con los catálogos dev y prod, o ingerir datos desde una ruta de origen diferente en cada ejecución. Define los parámetros en la canalización (o los sobrescribes al iniciar una actualización) y haces referencia a ellos desde el código fuente SQL.

Importante

Esta característica se encuentra en su versión beta. Los administradores del área de trabajo pueden controlar el acceso a esta característica desde la página Vistas previas . Consulte Administrar versiones preliminares de Azure Databricks.

En esta página se describe la característica de parámetros de canalización, disponible para el código fuente de SQL. Para parametrizar el código fuente de Python en una canalización, siga usando el campo Configuration tal como se describe en Hacer referencia a parámetros mediante el campo de configuración. La configuración también se utiliza para establecer valores de configuración de Spark que los pipelines leen en tiempo de ejecución. Para más información sobre las opciones de configuración de Spark, consulte Referencia de propiedades de canalización.

¿Qué son los parámetros de canalización?

Los parámetros de canalización son pares de clave-valor que pueden:

Definir como valores predeterminados en la configuración de la canalización.
Anule al iniciar una actualización desde la interfaz de usuario de la canalización, la API de inicio de actualización o el cuadro de diálogo Ejecutar con diferentes configuraciones.
Invalide en la tarea de canalización de un trabajo, con la inserción opcional de parámetros de nivel de trabajo.
Haga referencia al código fuente SQL mediante la sintaxis de parámetro con nombre.

Los valores de parámetro siempre son cadenas. Las teclas pueden contener caracteres alfanuméricos, caracteres de subrayado (_), guiones (-) y puntos (.).

Los parámetros de canalización y el campo Configuración sirven para diferentes propósitos:

Utilice Parámetros para...	Utilice Configuración para...
Valores que cambian entre actualizaciones (catálogo de destino, ruta de acceso de origen, intervalo de fechas).	Configuración de Spark que controla el comportamiento de la canalización (`pipelines.enzyme.enabled`, `pipelines.clusterLabelsV2Enabled`).
Valores que desea propagar de un trabajo o de una tarea.	Propiedades estáticas y estructurales de la canalización.
Valores a los que se hace referencia en SQL con sintaxis de parámetros con nombre.	Valores a los que hace referencia con la sintaxis de `${key}` en SQL o `spark.conf.get("key")` en Python.

Definición de parámetros de canalización

Puede definir valores de parámetro predeterminados en la configuración de canalización. Cuando se ejecuta una actualización sin anulaciones, la canalización usa estos valores predeterminados.

Uso de la interfaz de usuario de canalización

En el área de trabajo, haga clic en Trabajos y canalizaciones en la barra lateral y seleccione la canalización.
Haga clic en Configuración.
En la barra lateral Configuración de canalización, busque la sección Parámetros y haga clic en Editar.
Agregue entradas clave y valor y, a continuación, haga clic en Guardar.

Uso de la API JSON o REST

Agregue un parameters mapa a la definición de canalización:

{
  "name": "Sales pipeline",
  "parameters": {
    "source_catalog": "dev_catalog",
    "source_schema": "sales",
    "start_date": "2026-01-01"
  }
}

Para obtener la referencia completa de JSON de canalización, consulte Configuraciones de canalización.

Parámetros de referencia en el código fuente de SQL

Haga referencia a un parámetro anteponiendo dos puntos a la clave. Azure Databricks enlaza el valor como una cadena en el momento de la actualización:

CREATE OR REFRESH MATERIALIZED VIEW transaction_summary AS
SELECT account_id,
  COUNT(txn_id) AS txn_count,
  SUM(txn_amount) AS account_revenue
FROM :source_catalog.sales.transactions
WHERE txn_date >= :start_date
GROUP BY account_id

Para usar un parámetro en una posición de identificador, como un catálogo, un esquema o un nombre de tabla, encapsularlo en IDENTIFIER():

USE CATALOG IDENTIFIER(:source_catalog);
USE SCHEMA IDENTIFIER(:source_schema);

CREATE OR REFRESH MATERIALIZED VIEW daily_sales AS
SELECT date(timestamp) AS date,
  SUM(price) AS total_sales
FROM transactions
GROUP BY date;

Si el código fuente hace referencia a un parámetro que no tiene ningún valor en el momento de la actualización, se produce un error en la actualización. La canalización omite parámetros adicionales a los que no hace referencia el código.

Invalidar parámetros en tiempo de actualización

Puede invalidar los valores de parámetro de una sola actualización sin cambiar los valores predeterminados guardados.

En la interfaz de usuario de canalización, haga clic en Ejecutar con diferentes configuraciones y edite la sección Parámetros .
En una tarea de canalización dentro de un trabajo, configure las anulaciones de parámetros en el campo Parámetros de la tarea. Consulte Parámetros.
Desde la API, pase un parameters mapa en la solicitud Iniciar actualización .

Azure Databricks registra los parámetros de una actualización específica en el historial de actualizaciones y los muestra en la columna Parámetros de ejecución de la lista de ejecuciones de la canalización.

Precedencia de parámetros

Al definir la misma clave en más de un lugar, el valor con la prioridad más alta gana. De mayor a menor:

Parámetros de ejecución de trabajos: valores proporcionados para una sola ejecución de trabajo (invalidaciones).
Parámetros de trabajo: los valores predeterminados definidos en el trabajo primario.
Parámetros de tarea de canalización: valores establecidos en la tarea de canalización.
Parámetros de canalización: valores predeterminados definidos en la configuración de la canalización.

Esto coincide con la prioridad usada por otros tipos de tareas de parámetros de trabajo.

Parámetros de canalización en Lakeflow Jobs

Al programar una canalización como una tarea de canalización en un trabajo, la tarea puede proporcionar parámetros que invaliden los valores predeterminados de la canalización. Los valores de los parámetros pueden utilizar referencias a valores dinámicos para inyectar valores del tiempo de ejecución del trabajo, como {{job.trigger.time.iso_date}} o {{job.parameters.region}}.

Los trabajos de Lakeflow también propagan automáticamente todos los parámetros del trabajo a las tareas de canalización, de la misma manera que los propagan a las tareas de cuaderno y de SQL. El código fuente de la canalización puede hacer referencia a cualquier valor transferido mediante la sintaxis de parámetros con nombre. Declarar un parámetro en la configuración de canalización es opcional y solo establece un valor predeterminado para las ejecuciones sin invalidación.

Advertencias y limitaciones conocidas

Las canalizaciones ejecutan una actualización cada vez: una canalización solo puede ejecutar una única actualización a la vez. Para evitar que se produzcan errores en los trabajos cuando varias actualizaciones se superpongan de otra manera, Azure Databricks limita la simultaneidad a 1 en dos escenarios:
- Un trabajo que contiene una tarea de canalización y está configurado con más de un max_concurrent_runs.
- Una tarea de canalización encapsulada en una tarea for-each, independientemente del recuento de iteraciones.
La interfaz de usuario del trabajo muestra una notificación cuando este límite surte efecto. Tenga en cuenta el límite al diseñar canalizaciones parametrizadas que tenga previsto ejecutar con muchas combinaciones de parámetros.
Los filtros de fecha pueden desencadenar actualizaciones completas: un caso de uso de parametrización común es filtrar los datos por fecha. Tenga cuidado con los predicados: el filtrado en ambos lados de un intervalo de fechas invalida el procesamiento incremental en vistas materializadas y desencadena una actualización completa en cada actualización.
```
-- Triggers a full refresh on each update
CREATE OR REFRESH MATERIALIZED VIEW recent_orders AS
SELECT * FROM orders
WHERE order_date >= :start_date AND order_date < :end_date;
```
```
-- Processes incrementally
CREATE OR REFRESH MATERIALIZED VIEW recent_orders AS
SELECT * FROM orders
WHERE order_date >= :start_date;
```
Los parámetros con nombre son solo SQL: en esta versión Beta, la sintaxis de parámetros con nombre solo se puede usar en el código fuente de SQL. Para parametrizar Python código fuente, siga usando el campo Configuration con spark.conf.get(). Consulte Parámetros de referencia mediante el campo de configuración.

Hacer referencia a parámetros utilizando el campo de configuración

El campo Configuración de una canalización acepta pares clave-valor arbitrarios que se exponen como valores de configuración de Spark. Este es el mecanismo de parametrización heredado y sigue funcionando junto con los parámetros de canalización. Úselo para el código fuente de Python y para las claves que quiera leer mediante spark.conf.get() en lugar de la sintaxis de parámetros con nombre.

En el ejemplo siguiente se usa un mypipeline.start_date valor de configuración para limitar una canalización de desarrollo a un subconjunto de datos de entrada:

SQL

CREATE OR REFRESH MATERIALIZED VIEW customer_events
AS SELECT * FROM source_table WHERE date > '${mypipeline.start_date}';

Pitón

from pyspark import pipelines as dp
from pyspark.sql.functions import col

@dp.table
def customer_events():
  start_date = spark.conf.get("mypipeline.start_date")
  return spark.read.table("source_table").where(col("date") > start_date)

Los valores de configuración se establecen en la sección Configuración de la configuración de la canalización o en el configuration campo del JSON de la canalización. Evite las claves que entren en conflicto con la canalización reservada o los valores de configuración de Apache Spark.

Comentarios

¿Le resultó útil esta página?

Last updated on 2026-06-01