Usar parâmetros com pipelines

Os parâmetros de pipeline permitem reutilizar o mesmo código-fonte de pipeline em ambientes ou conjuntos de dados. Por exemplo, você pode executar as mesmas transformações nos catálogos dev e prod ou ingerir dados de um caminho de origem diferente em cada execução. Defina parâmetros no pipeline (ou substitua-os ao iniciar uma atualização) e referencie-os no código-fonte do SQL.

Esta página descreve o recurso de parâmetros de pipeline, disponível no código-fonte SQL. Para parametrizar o código-fonte em Python em um pipeline, continue a usar o campo Configuration, conforme descrito em Referenciar parâmetros usando o campo de configuração. A configuração também é usada para definir valores de configuração do Spark que os pipelines leem em runtime. Para obter detalhes sobre as configurações do Spark, consulte a referência de propriedades do Pipeline.

O que são parâmetros de pipeline?

Os parâmetros do pipeline são pares chave-valor que você pode:

• Defina como padrão nas configurações do pipeline.
• Substituir ao iniciar uma atualização na interface do pipeline, na API Start update ou na caixa de diálogo Executar com configurações diferentes.
• Substituição da tarefa da pipeline em um job, com propagação opcional de parâmetros no nível do job.
• Referência a partir do código-fonte SQL usando a sintaxe de parâmetro nomeado.

Valores de parâmetro são sempre cadeias de caracteres. As chaves podem conter caracteres alfanuméricos, sublinhados (_), hifens (-) e períodos (.).

Os parâmetros de pipeline e o campo Configuração servem a diferentes finalidades:

Definir parâmetros de pipeline

Você pode definir valores de parâmetro padrão em configurações de pipeline. Quando uma atualização é executada sem substituições, o pipeline usa esses valores padrão.

Usar a interface do usuário do pipeline

1. No seu espaço de trabalho, clique no Jobs and Pipelines na barra lateral e selecione seu pipeline.
2. Clique em Configurações.
3. Na barra lateral de configurações do Pipeline , localize a seção Parâmetros e clique em Editar.
4. Adicione entradas de Chave e Valor e clique em Salvar.

Usar a API REST ou JSON

Adicione um mapa parameters à definição de pipeline:

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

Para obter a referência JSON completa do pipeline, consulte as configurações do Pipeline.

Parâmetros de referência no código-fonte do SQL

Faça referência a um parâmetro prefixando a chave com dois-pontos. Azure Databricks associa o valor como uma cadeia de caracteres no momento da atualização:

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 um parâmetro em uma posição de identificador, como um catálogo, esquema ou nome de tabela, embrulhe-o em 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;

Se o código-fonte fizer referência a um parâmetro que não tem valor no momento da atualização, a atualização falhará com um erro. O pipeline ignora parâmetros extras que não são referenciados pelo código.

Sobrescrever parâmetros durante a atualização

Você pode substituir valores de parâmetro para uma única atualização sem alterar os padrões salvos.

• Na interface do usuário do pipeline, clique em Executar com configurações diferentes e edite a seção Parâmetros .
• Em uma tarefa de pipeline em um trabalho, defina as substituições de parâmetro no campo Parâmetros da tarefa. Consulte Parâmetros.
• Na API, passe um parameters mapa na solicitação Iniciar atualização .

Azure Databricks registra os parâmetros de uma atualização específica no histórico de atualizações e os exibe na coluna Parâmetros de execução da lista de execuções do pipeline.

Precedência de parâmetro

Quando você define a mesma chave em mais de um lugar, o valor com a precedência mais alta ganha. Do mais alto para o mais baixo:

1. Parâmetros de execução de trabalho: valores fornecidos para uma única execução de trabalho (substituições).
2. Parâmetros da tarefa: valores padrão definidos na tarefa pai.
3. Parâmetros da tarefa de pipeline: valores configurados na tarefa de pipeline.
4. Parâmetros do pipeline: valores padrão definidos nas configurações do pipeline.

Isso corresponde à precedência usada por outros tipos de tarefa de parâmetro de trabalho.

Parâmetros de pipeline no Lakeflow Jobs

Quando você programa um pipeline como uma tarefa de pipeline em um trabalho, a tarefa pode fornecer parâmetros que substituem os valores padrão do pipeline. Os valores de parâmetro podem usar referências de valor dinâmico para injetar valores de tempo de execução de trabalho, como {{job.trigger.time.iso_date}} ou {{job.parameters.region}}.

O Lakeflow Jobs também repassa automaticamente todos os parâmetros do job para as tarefas de pipeline, da mesma forma que os repassa para as tarefas de notebook e SQL. O código-fonte do pipeline pode referenciar qualquer valor propagado usando a sintaxe de parâmetros nomeados. Declarar um parâmetro nas configurações de pipeline é opcional e define apenas um padrão para execuções sem uma substituição.

Ressalvas e limitações conhecidas

• Os pipelines executam uma atualização por vez: um pipeline só pode executar uma única atualização por vez. Para evitar que os trabalhos falhem quando várias atualizações se sobrepõem de outra forma, Azure Databricks limita a simultaneidade a 1 em dois cenários:

  • Um trabalho que contém uma tarefa de pipeline e está configurado com mais de um max_concurrent_runs.
  • Uma tarefa de pipeline envolvida por uma tarefa for-each, independentemente do número de iterações.

  A interface do usuário do trabalho mostra uma notificação quando esse limite entra em vigor. Planeje em torno do limite ao projetar pipelines parametrizados que você pretende executar com muitas combinações de parâmetros.

• Os filtros de data podem disparar atualizações completas: um caso comum de uso de parametrização é filtrar dados por data. Tenha cuidado com predicados: filtrar em ambos os lados de um intervalo de datas invalida o processamento incremental em visualizações materializadas e aciona uma atualização completa a cada atualização.

  -- 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;
  

• Os parâmetros nomeados são somente SQL: nesta Versão Beta, a sintaxe de parâmetro nomeada só pode ser usada no código-fonte do SQL. Para parametrizar o código-fonte em Python, continue usando o campo Configuration com spark.conf.get(). Consulte parâmetros de referência usando o campo de configuração.

Parâmetros de referência usando o campo de configuração

O campo Configuração em um pipeline aceita pares de chave-valor arbitrários expostos como valores de configuração do Spark. Este é o mecanismo legado de parametrização e continua funcionando em conjunto com os parâmetros de pipeline. Use isso para código-fonte Python e para chaves que você deseja ler com spark.conf.get() em vez da sintaxe de parâmetros nomeados.

O exemplo a seguir usa um mypipeline.start_date valor de configuração para limitar um pipeline de desenvolvimento a um subconjunto de dados de entrada:

SQL

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

Python

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)

Defina os valores de configuração na seção Configuration das configurações do pipeline ou no campo configuration do JSON do pipeline. Evite chaves que entrem em conflito com os valores de configuração do pipeline reservado ou do Apache Spark.

Artigos relacionados

• Configurar pipelines
• Tarefa de pipeline para trabalhos
• Configurar parâmetros de trabalho
• O que é uma referência de valor dinâmico?