파이프라인과 함께 매개 변수 사용

파이프라인 매개 변수를 사용하면 환경 또는 데이터 세트 간에 동일한 파이프라인 소스 코드를 다시 사용할 수 있습니다. 예를 들어, dev 및 prod 카탈로그에 대해 동일한 변환을 실행하거나 실행할 때마다 다른 소스 경로에서 수집할 수 있습니다. 파이프라인에서 매개 변수를 정의하고(또는 업데이트를 시작할 때 이를 재정의할 수 있으며) SQL 소스 코드에서 이를 참조합니다.

이 페이지에서는 SQL 소스 코드에서 사용할 수 있는 파이프라인 매개 변수 기능에 대해 설명합니다. 파이프라인에서 Python 소스 코드를 매개변수화하려면 구성 필드를 사용하여 매개변수 참조에 설명된 대로 Configuration 필드를 계속 사용하세요. 구성은 파이프라인이 런타임에 읽는 Spark 구성 값을 설정하는 데도 사용됩니다. Spark 구성 설정에 대한 자세한 내용은 파이프라인 속성 참조를 참조하세요.

파이프라인 매개 변수란?

파이프라인 매개 변수는 다음을 수행할 수 있는 키-값 쌍입니다.

• 파이프라인 설정에서 기본값으로 선언합니다.
• 파이프라인 UI, 업데이트 시작 API 또는 다른 설정으로 실행 대화 상자에서 업데이트를 시작할 때 재정의합니다.
• 선택적으로 작업 수준 매개변수를 푸시다운하여 작업 내 파이프라인 태스크를 재정의합니다.
• 명명된 매개 변수 구문을 사용하여 SQL 소스 코드에서 참조합니다.

매개 변수 값은 항상 문자열입니다. 키에는 영숫자 문자, 밑줄(_), 하이픈(-) 및 마침표()가. 포함될 수 있습니다.

파이프라인 매개 변수 및 구성 필드는 다음과 같은 다양한 용도로 사용됩니다.

파이프라인 매개 변수 정의

파이프라인 설정에서 기본 매개 변수 값을 정의할 수 있습니다. 업데이트가 재정의 없이 실행되면 파이프라인은 이러한 기본값을 사용합니다.

파이프라인 UI 사용

1. 작업 영역에서 사이드바의 작업 및 파이프라인을 선택하고 파이프라인을 선택합니다.
2. 설정을 클릭합니다.
3. 파이프라인 설정 사이드바에서 매개 변수 섹션을 찾아 편집을 클릭합니다.
4. 키 및 값 항목을 추가한 다음 저장을 클릭합니다.

JSON 또는 REST API 사용

parameters 파이프라인 정의에 맵을 추가합니다.

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

전체 파이프라인 JSON 참조는 파이프라인 구성을 참조하세요.

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;

소스 코드가 업데이트 시 값이 없는 매개 변수를 참조하는 경우 오류와 함께 업데이트가 실패합니다. 파이프라인은 코드가 참조하지 않는 추가 매개 변수를 무시합니다.

업데이트 시 매개 변수 재정의

저장된 기본값을 변경하지 않고 단일 업데이트에 대한 매개 변수 값을 재정의할 수 있습니다.

• 파이프라인 UI에서 다른 설정으로 실행을 클릭하고 매개 변수 섹션을 편집합니다.
• 작업 내 파이프라인 작업의 Parameters 필드에서 매개 변수 재정의를 설정합니다. 매개 변수를 참조하세요.
• API에서 parameters 요청에 맵을 전달 합니다.

Azure Databricks 업데이트 기록에 특정 업데이트에 대한 매개 변수를 기록하고 파이프라인 실행 목록의 매개 변수 실행 열에 표시합니다.

매개 변수 우선 순위

둘 이상의 위치에서 동일한 키를 정의하면 우선 순위가 가장 높은 값이 우선합니다. 가장 높은 값에서 가장 낮은 값까지:

1. 작업 실행 매개 변수: 단일 작업 실행에 대해 제공된 값입니다(재정의).
2. 작업 매개 변수: 부모 작업에 정의된 기본값입니다.
3. 파이프라인 작업 매개 변수: 파이프라인 태스크에 설정된 값입니다.
4. 파이프라인 매개 변수: 파이프라인 설정에 정의된 기본값입니다.

이는 다른 작업 매개 변수 작업 유형에서 사용하는 우선 순위와 일치합니다.

Lakeflow 작업의 파이프라인 매개변수

작업에서 파이프라인 태스크로 파이프라인 을 예약하는 경우 태스크는 파이프라인의 기본값을 재정의하는 매개 변수를 제공할 수 있습니다. 매개 변수 값 은 동적 값 참조를 사용하여 작업 런타임 값(예: {{job.trigger.time.iso_date}} 또는 {{job.parameters.region}}.)을 삽입할 수 있습니다.

Lakeflow 작업은 노트북 작업과 SQL 작업에 전달하는 것과 동일한 방식으로, 모든 작업 매개변수를 파이프라인 작업에도 자동으로 전달합니다. 파이프라인 소스 코드는 명명된 매개 변수 구문을 사용하여 푸시다운된 값을 참조할 수 있습니다. 파이프라인 설정에서 매개 변수를 선언하는 것은 선택 사항이며 재정의 없이 실행에 대한 기본값만 설정합니다.

주의 사항 및 알려진 제한 사항

• 파이프라인은 한 번에 하나의 업데이트를 실행합니다. 파이프라인은 한 번에 하나의 업데이트만 실행할 수 있습니다. 여러 업데이트가 겹쳐 작업이 실패하는 것을 방지하기 위해 Azure Databricks는 다음 두 가지 시나리오에서 동시성을 1로 제한합니다:

  • 파이프라인 작업을 포함하며 max_concurrent_runs 둘 이상으로 구성되도록 설정된 작업입니다.
  • 반복 횟수와 관계없이 for-each 작업 내에 포함된 파이프라인 작업입니다.

  이 상한이 적용되는 경우 작업 UI에 알림이 표시됩니다. 많은 매개변수 조합으로 실행할 매개변수화된 파이프라인을 설계할 때는 상한을 고려해 계획하세요.

• 날짜 필터는 전체 새로 고침을 트리거할 수 있습니다. 일반적인 매개 변수화 사용 사례는 데이터를 날짜별로 필터링하는 것입니다. 조건자 사용에 주의하세요. 날짜 범위의 양쪽 끝에서 필터링하면 머티리얼라이즈드 뷰의 증분 처리가 무효화되고 업데이트할 때마다 전체 새로 고침이 발생합니다.

  -- 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 소스 코드를 매개 변수화하려면 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 구성 값과 충돌하는 키를 방지합니다.

관련된 문서

• 파이프라인 구성
• 작업용 파이프라인 작업
• 작업 매개 변수 구성
• 동적 값 참조란?