Usar parâmetros com pipelines

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

Esta página descreve a funcionalidade de parâmetros do pipeline, disponível para código-fonte SQL. Para parametrizar código-fonte Python num pipeline, continue a usar o campo Configuration, conforme descrito em Referenciar parâmetros com o campo de configuração. A configuração também é usada para definir valores de configuração do Spark que os pipelines leem em tempo de execução. Para detalhes sobre as definições de configuração do Spark, consulte 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 podes:

• Declarar como predefinidos nas definições do pipeline.
• Substitua ao iniciar uma atualização a partir da interface do pipeline, da API de Iniciar atualização ou do diálogo Executar com definições diferentes .
• Substituir a tarefa de pipeline num trabalho, com propagação opcional dos parâmetros ao nível do trabalho.
• Referência a partir do código-fonte SQL usando a sintaxe do parâmetro nomeado .

Os valores dos parâmetros são sempre cadeias. As teclas podem conter caracteres alfanuméricos, sublinhados (_), hífens (-) e pontos (.).

Os parâmetros do pipeline e o campo de Configuração servem propósitos diferentes:

Definir parâmetros do pipeline

Pode definir valores predefinidos para os parâmetros nas definições do pipeline. Quando uma atualização é executada sem sobrescrições, o pipeline utiliza estes valores predefinidos.

Utilizar a IU do pipeline

1. No seu espaço de trabalho, clique Jobs e Pipelines na barra lateral e seleciona o teu pipeline.
2. Clique em Configurações.
3. Na barra lateral das definições do Pipeline , encontra a secção Parâmetros e clica em Editar.
4. Adicione as entradas Chave e Valor e, em seguida, clique em Guardar.

Utilize a API JSON ou a API REST

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

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

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

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

Refira-se a um parâmetro prefixando a chave com dois-pontos. Azure Databricks liga o valor como uma string 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 numa posição de identificador, como um catálogo, esquema ou nome de tabela, envolva-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 seu código-fonte referenciar um parâmetro que não tem valor na altura da atualização, a atualização falha com um erro. O pipeline ignora parâmetros extra que o código não referencia.

Sobrepor parâmetros aquando da atualização

Podes sobrescrever valores de parâmetros para uma única atualização sem alterar os valores predefinidos guardados.

• Na interface do pipeline, clique em Executar com definições diferentes e edite a secção Parâmetros .
• Numa tarefa de pipeline num trabalho, defina substituições de parâmetros no campo Parameters da tarefa. Consulte Parâmetros.
• Na API, passe um mapa parameters no pedido Start update.

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

Precedência de parâmetros

Quando defines a mesma chave em mais do que um lugar, o valor com a maior precedência vence. Do mais alto para o mais baixo:

1. Parâmetros de execução de tarefas: valores fornecidos para uma única execução de tarefa (sobrescrições).
2. Parâmetros do trabalho: padrões definidos no trabalho principal.
3. Parâmetros da tarefa do pipeline: valores definidos na tarefa do pipeline.
4. Parâmetros do pipeline: predefinidos nas definições do pipeline.

Isto corresponde à precedência usada por outros tipos de tarefas com parâmetros de trabalho.

Parâmetros de oleoduto em Lakeflow Jobs

Quando agenda um pipeline como tarefa de pipeline num trabalho, a tarefa pode fornecer parâmetros que substituem os predefinidos do pipeline. Os valores dos parâmetros podem utilizar referências dinâmicas de valor para injetar valores durante a execução da tarefa, como {{job.trigger.time.iso_date}} ou {{job.parameters.region}}.

O Lakeflow Jobs também propaga automaticamente todos os parâmetros do trabalho para as tarefas de pipeline, da mesma forma que os propaga para as tarefas de caderno e SQL. O código-fonte do pipeline pode referenciar qualquer valor transmitido com a sintaxe de parâmetros nomeados. Declarar um parâmetro nas definições do pipeline é opcional e só define um padrão para execuções sem override.

Ressalvas e limitações conhecidas

• Os pipelines executam uma atualização de cada vez: Um pipeline só pode executar uma atualização de cada vez. Para evitar que as tarefas falhem caso várias atualizações viessem a sobrepor-se, o Azure Databricks limita a concorrência a 1 em dois cenários:

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

  A interface do trabalho mostra uma notificação quando este limite entra em vigor. Planeie em torno do limite ao desenhar pipelines parametrizados que pretende executar com várias combinações de parâmetros.

• Filtros de data podem desencadear atualizações completas: Um caso comum de parametrização é filtrar dados por data. Tenha cuidado com os predicados: filtrar em ambos os lados de um intervalo de datas invalida o processamento incremental em vistas materializadas e desencadeia 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 apenas SQL: nesta Beta, a sintaxe dos parâmetros nomeados só pode ser usada no código-fonte SQL. Para parametrizar o código-fonte Python, continue a usar o campo Configuration com spark.conf.get(). Veja Parâmetros de referência usando o campo de configuração.

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

O campo de Configuração num pipeline aceita pares chave-valor 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 do pipeline. Utilize-o para código-fonte em Python e para chaves que pretenda ler com spark.conf.get() em vez da sintaxe de parâmetros nomeados.

O exemplo seguinte utiliza 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)

Pode definir os valores de configuração na secção Configuração das definições da pipeline ou no campo configuration do JSON da pipeline. Evite chaves que entrem em conflito com valores reservados de pipeline ou configuração do Apache Spark.

Artigos relacionados

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