Использование параметров с конвейерами

Параметры конвейера позволяют повторно использовать один и тот же исходный код конвейера в средах или наборах данных. Например, вы можете применять одни и те же преобразования к каталогам dev и prod, а также при каждом запуске загружать данные из другого исходного пути. Вы определяете параметры конвейера (или переопределяете их при запуске обновления) и ссылаетесь на них из исходного кода SQL.

Это важно

Эта функция доступна в бета-версии. Администраторы рабочей области могут управлять доступом к этой функции на странице "Предварительные версии ". См. статью "Управление предварительными версиями Azure Databricks".

Параметры конвейера доступны только исходному коду SQL. Чтобы параметризовать исходный код Python в конвейере, используйте поле Configuration, как описано в разделе Ссылка на параметры с использованием поля конфигурации. Конфигурация также используется для задания параметров конфигурации Spark, которые конвейеры считывают во время выполнения. Дополнительные сведения о параметрах конфигурации Spark см. в справочнике по свойствам конвейера.

Что такое параметры конвейера?

Параметры конвейера — это пары «ключ-значение», с которыми можно:

Укажите значения по умолчанию в настройках конвейера.
Переопределяется при запуске обновления из пользовательского интерфейса конвейера, API начального обновления или диалогового окна "Запуск с разными параметрами ".
Переопределите задачу конвейера в задании с необязательным нажатием параметров уровня задания.
Ссылка на исходный код SQL с использованием синтаксиса именованных параметров.

Значения параметров всегда являются строками. Ключи могут содержать буквенно-цифровые символы, символы подчеркивания (), дефисы (_-) и точки (.).

Параметры конвейера и поле конфигурации служат различным целям:

Использование параметров для...	Используйте Configuration для...
Значения, изменяющиеся между обновлениями (целевой каталог, исходный путь, диапазон дат).	Конфигурация Spark, которая управляет поведением конвейера (`pipelines.enzyme.enabled`, `pipelines.clusterLabelsV2Enabled`).
Значения, которые нужно передать ниже из задания или задачи.	Статические, структурные свойства конвейера.
Значения, на которые вы ссылаетесь в SQL с помощью именованного синтаксиса параметров.	Значения, на которые вы ссылаетесь с помощью синтаксиса `${key}` в SQL или `spark.conf.get("key")` в Python.

Определение параметров конвейера

Значения параметров по умолчанию можно определить в параметрах конвейера. Если обновление выполняется без переопределений, конвейер использует эти значения по умолчанию.

Используйте интерфейс конвейера

В рабочей области щелкните Задания и конвейеры на боковой панели и выберите конвейер.
Нажмите кнопку "Параметры".
На боковой панели параметров конвейера найдите раздел "Параметры " и нажмите кнопку "Изменить".
Добавьте записи "Ключ " и " Значение ", а затем нажмите кнопку "Сохранить".

Использование JSON или REST API

parameters Добавьте карту в определение JSON конвейера в параметрах конвейера или при использовании REST API:

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

Полное справочное руководство по JSON для конвейера см. в разделе Конфигурации конвейера.

Использование yamL или декларативных пакетов автоматизации

Определите параметры в parameters сопоставлении определения YAML конвейера в параметрах конвейера или в декларативных пакетах автоматизации (Что такое декларативные пакеты автоматизации?):

resources:
  pipelines:
    my_pipeline:
      name: Sales pipeline
      parameters:
        source_catalog: dev_catalog
        source_schema: sales
        start_date: '2026-01-01'

Эталонные параметры в исходном коде SQL

Чтобы сослаться на параметр, поставьте двоеточие перед ключом. Azure Databricks привязывает значение в виде строки во время обновления:

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

Чтобы использовать параметр в позиции идентификатора, например каталог, схему или имя таблицы, заключите его в 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;

Если исходный код ссылается на параметр, который не имеет значения во время обновления, обновление завершается ошибкой. Конвейер игнорирует дополнительные параметры, на которые не ссылается код.

Переопределение параметров во время обновления

Значения параметров можно переопределить для одного обновления, не изменив сохраненные значения по умолчанию.

В пользовательском интерфейсе конвейера нажмите кнопку "Выполнить с разными параметрами " и измените раздел "Параметры ".
Из задачи конвейера в задании задайте переопределение параметров в поле параметров задачи. См. параметры.
Передайте через API parameters отображение в запросе Start update.

Azure Databricks записывает параметры конкретного обновления в историю обновлений и отображает их в столбце Параметры запуска в списке запусков конвейера.

Приоритет параметров

При определении одного ключа в нескольких местах значение с наивысшим приоритетом выигрывает. От самого высокого до наименьшего:

Параметры запуска задания: значения, предоставленные для одного запуска задания (переопределения).
Параметры задания: по умолчанию, определенные в родительском задании.
Параметры задачи конвейера: значения, заданные для задачи конвейера.
Параметры конвейера: значения по умолчанию, определенные в параметрах конвейера.

Это соответствует приоритету, используемому другими типами задач параметров задания.

Параметры конвейера в заданиях Lakeflow

Когда вы планируете конвейер как задачу конвейера в задании, эта задача может передавать параметры, которые переопределяют параметры конвейера, заданные по умолчанию. Значения параметров могут использовать динамические ссылки на значения, чтобы подставлять значения во время выполнения задания, такие как {{job.trigger.time.iso_date}} или {{job.parameters.region}}. Чтобы ссылаться на значение, заданное вышестоящей задачей, используйте {{tasks.<task_name>.values.<value_name>}}. См. раздел Использование значений задач для передачи сведений между задачами.

Lakeflow Jobs также автоматически передаёт все параметры задания задачам конвейера, точно так же, как блокнотам и SQL-задачам. Исходный код конвейера может ссылаться на любое переданное значение с использованием синтаксиса именованных параметров. Объявление параметра в параметрах конвейера является необязательным и задает только значение по умолчанию для выполнения без переопределения.

Предостережения и известные ограничения

Конвейеры выполняют одно обновление одновременно: конвейер может выполнять только одно обновление за раз. Чтобы задания не завершались сбоем, если в противном случае несколько обновлений перекрывались бы, Azure Databricks ограничивает параллелизм до 1 в двух сценариях:
- Задание, содержащее задачу конвейера и настроенное более чем с одним max_concurrent_runs.
- Задача конвейера, вложенная в задачу for-each, независимо от количества итераций.
В пользовательском интерфейсе задания отображается уведомление, когда это ограничение вступает в силу. При проектировании параметризованных конвейеров, которые вы планируете запускать с большим количеством комбинаций параметров, учитывайте это ограничение.
Фильтры дат могут активировать полные обновления: распространенный вариант использования параметризации — фильтрация данных по дате. Будьте осторожны с предикатами: фильтрация с обеих сторон диапазона дат делает невозможной инкрементальную обработку материализованных представлений и приводит к полному обновлению при каждом обновлении.
```
-- 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;
```
Именованные параметры доступны только для SQL: в этом бета-версии синтаксис именованных параметров можно использовать только в исходном коде SQL. Чтобы параметризировать исходный код Python, продолжайте использовать поле Configuration с spark.conf.get(). См. Справочные параметры с использованием поля конфигурации.

Укажите параметры, используя поле конфигурации

Поле "Конфигурация" в конвейере принимает произвольные пары "ключ-значение", которые предоставляются в качестве значений конфигурации Spark. Это устаревший механизм параметризации и продолжает работать вместе с параметрами конвейера. Используйте его для исходного кода Python и для ключей, которые нужно считывать с помощью spark.conf.get(), а не через синтаксис именованных параметров.

В следующем примере используется mypipeline.start_date значение конфигурации для ограничения конвейера разработки на подмножество входных данных:

SQL

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

Питон

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)

Значения конфигурации задаются в разделе "Конфигурация " параметров конвейера или в configuration поле JSON конвейера. Избегайте ключей, конфликтующих с зарезервированными значениями конвейера или конфигурации Apache Spark.

Дополнительные ресурсы

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2026-07-10