Utilizar parâmetros com pipeline

Os parâmetros de pipeline permitem reutilizar o mesmo código-fonte do pipeline em diferentes ambientes ou datasets. Por exemplo, você pode executar as mesmas transformações nos catálogos dev e prod, ou ingerir de um caminho de origem diferente em cada execução. Os parâmetros são definidos no pipeline (ou podem ser substituídos ao iniciar uma atualização) e referenciados em seu código-fonte SQL.

info

Beta

Este recurso está em Beta. Os administradores do espaço de trabalho podem controlar o acesso a esse recurso na página Pré-visualizações . Consulte Gerenciar prévias do Databricks.

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

O que são parâmetros de pipeline?

Parâmetros de pipeline são pares key-value que você pode:

• Declarar como defaults nas configurações de pipeline.
• Use configurações diferentes ao iniciar uma atualização na interface do usuário do pipeline, na API de Iniciar atualização ou na **caixa de diálogo Executar com configurações diferentes**.
• Substituir na tarefa de pipeline em um job, com pushdown opcional de parâmetros do job.
• Referência do código-fonte SQL usando a sintaxe de parâmetro nomeado.

Valores de parâmetros são sempre strings. As keys podem conter caracteres alfanuméricos, sublinhados (_), hifens (-) e pontos (.).

Parâmetros do pipeline e o campo **Configuração** têm finalidades diferentes:

Use Parâmetros para...	Use **Configuração** para...
Valores que se alteram entre atualizações (catálogo de destino, caminho de origem, intervalo de datas).	Configuração do Spark que controla o comportamento do pipeline (pipelines.enzyme.enabled, pipelines.clusterLabelsV2Enabled).
Valores que você deseja que sejam transmitidos de um job ou tarefa.	Propriedades estáticas, estruturais de pipeline.
Valores que são referenciados em SQL com a sintaxe de parâmetro nomeado.	Valores referenciados com a sintaxe ${key} em SQL ou spark.conf.get("key") em Python.

Defina os parâmetros do pipeline

É possível definir valores de parâmetro default nas configurações do pipeline. Quando uma atualização é executada sem substituições, o pipeline utiliza esses padrões.

Use a interface do usuário do pipeline

1. No seu workspace, clique em Jobs e Pipelines na barra lateral e selecione o seu pipeline.
2. Clique em Configurações .
3. Na barra lateral de **Configurações do pipeline**, encontre a seção **Parâmetros** e clique em **Editar**.
4. Adicione os campos **Chave** e **Valor** e, depois, clique em **Salvar**

Use a API JSON ou REST

Adicionar um parameters mapa à definição de pipeline

JSON

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

Para a referência completa do JSON do pipeline, consulte Configurações de pipeline.

Referência a parâmetros no código-fonte SQL

Referencie um parâmetro prefixando a chave com dois pontos. Databricks vincula o valor como uma string no momento da atualização:

SQL

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, envolva-o em IDENTIFIER():

SQL

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 seu código-fonte referenciar 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 o código não referencia.

Substituir parâmetros na atualização

É possível substituir os valores dos parâmetros para uma única atualização sem alterar os padrões salvos.

• Na interface do pipeline, clique em **execução com configurações diferentes** e edite a seção de **Parâmetros**.
• De uma tarefa de pipeline em um Job, defina as substituições de parâmetros no campo **Parâmetros** da tarefa. Consulte Parâmetros.
• Da API, passe um mapa parameters na solicitação de Iniciar atualização.

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

Precedência de parâmetro

Quando se define a mesma key em mais de um lugar, o valor com a precedência mais alta prevalece. Da mais alta para a mais baixa:

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

Isso corresponde à precedência usada por outros tipos de tarefas de parâmetros de job.

Parâmetros de pipeline nos Jobs do Lakeflow

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

O LakeFlow Jobs também passa todos os parâmetros de Job para as tarefas de pipeline automaticamente, da mesma forma que os passa para as tarefas de Notebook e SQL. O código-fonte do pipeline pode referenciar qualquer valor transmitido com a sintaxe de parâmetro nomeado. Declarar um parâmetro nas configurações do pipeline é opcional e define apenas um default para execuções sem uma substituição.

Advertências e limitações conhecidas

• Pipelines executam uma atualização por vez : Um pipeline só pode executar uma única atualização por vez. Para evitar que jobs falhem quando várias atualizações se sobreporiam de outra forma, o Databricks limita a concorrência a 1 em dois cenários:

  • Um Job que contém uma tarefa de pipeline e está configurado com max_concurrent_runs mais de um.
  • Uma tarefa de pipeline envolvida em uma tarefa for-each, independentemente da contagem de iterações.

  A IU do job mostra uma notificação quando este limite entra em vigor. Considere o limite ao projetar pipelines parametrizados que se pretende executar com muitas combinações de parâmetros.

• Filtros de data podem acionar refresh completo : Um caso de uso comum de parametrização é filtrar dados por data. Cuidado com os predicados: a filtragem em ambos os lados de um intervalo de datas invalida o processamento incremental em views materializadas e aciona um refresh completo a cada atualização.

  SQL

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

  SQL

  -- Processes incrementally
  CREATE OR REFRESH MATERIALIZED VIEW recent_orders AS
  SELECT * FROM orders
  WHERE order_date >= :start_date;

• **Parâmetros nomeados são somente SQL**: Nesta versão Beta, a sintaxe de parâmetro nomeado só pode ser usada no código-fonte SQL. Para parametrizar o código-fonte Python, continue a usar o campo **Configuração** spark.conf.get() com. Consulte Referencie parâmetros 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 key-value arbitrários que são expostos como valores de configuração do Spark. Este é o mecanismo de parametrização legado e continua a funcionar em conjunto com os parâmetros de pipeline. Utilize-o para código-fonte Python e para chaves que se deseja ler com spark.conf.get() em vez da sintaxe de parâmetro nomeado.

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

SQL

SQL

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

Python

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)

Os valores de configuração são definidos na seção **Configuration** das configurações do pipeline ou no configuration campo do JSON do pipeline. Evite chaves que entram em conflito com os valores de configuração reservados de pipeline ou Apache Spark.

Artigos relacionados

• Configure pipelines
• Tarefa de pipeline para jobs
• Configurar os parâmetros do Job
• O que é uma referência de valor dinâmico?