오퍼레이터 로직은 커스텀 오퍼레이터가 실행하는 코드입니다.
python-run-function 연산자의 경우, 인라인 Python run() 함수입니다.
uc-udf 또는 uc-udtf 연산자의 경우, SQL 또는 Python으로 작성된 Unity 카탈로그 함수입니다.
로직을 작성하는 것은 공유 커스텀 연산자를 빌드하는 과정의 한 단계입니다. 로직을 작성하고 테스트한 후, YAML로 연산자를 설명해서 Lakeflow Designer가 UI에서 어떻게 표시할지 알 수 있게 하고, 등록해서 Operators 창에 나타나도록 합니다. 한 오퍼레이터에 대한 모든 단계를 함께 보려면, Tutorial: 복리 이자 계산기 오퍼레이터와 같은 튜토리얼을 따라가세요.
python-run-function 연산자를 작성합니다
모든 python-run-function 연산자는 다음 함수를 정의해야 합니다.run()
def run(config: Dict[str, Any], inputs: Dict[str, Any], spark) -> Dict[str, Any]:
-
config: 속성 이름으로 키가 지정된 UI에서 사용자가 구성한 값입니다. -
inputs: 입력 포트name로 키가 지정된 입력 데이터 프레임입니다. -
spark: 현재 활성 상태인 SparkSession입니다. -
반환: 출력 포트
name값과 데이터프레임을 매핑하는 사전입니다.
다음 예제에서는 입력 DataFrame에서 행을 필터링합니다.
def run(config, inputs, spark):
df = inputs["in"]
filtered = df.filter(config["filter_expression"])
return {"out": filtered}
함수를 등록하기 전에 테스트하려면 샘플 데이터가 포함된 노트북에서 호출하세요:
test_df = spark.createDataFrame(
[("Alice", 100), ("Bob", 200)],
["name", "amount"]
)
result = run(
config={"filter_expression": "amount > 100"},
inputs={"in": test_df},
spark=spark
)
result["out"].show()
운영자에게 외부 pip 패키지가 필요한 경우 YAML에 environment 필드를 추가합니다.
environment:
environment_version: '4'
dependencies:
- requests==2.31.0
- beautifulsoup4==4.12.0
UDF 또는 UDTF 연산자를 작성하세요
Unity 카탈로그 함수는 SQL이나 Python으로 작성할 수 있습니다. Python 함수는 SQL CREATE FUNCTION 문에 래핑됩니다.
SQL 함수:
CREATE OR REPLACE FUNCTION my_catalog.my_schema.calculate_bmi(weight_kg DOUBLE, height_m DOUBLE)
RETURNS DOUBLE
LANGUAGE SQL
RETURN
SELECT weight_kg / (height_m * height_m);
Python 함수(SQL로 래핑):
CREATE OR REPLACE FUNCTION my_catalog.my_schema.calculate_bmi(weight_kg DOUBLE, height_m DOUBLE)
RETURNS DOUBLE
LANGUAGE PYTHON
AS $$
return weight_kg / (height_m ** 2)
$$;
UDF는 한 번에 단일 값을 처리하고 계산된 값을 반환합니다. UTF는 행별로 테이블 행을 처리하고 모든 행에서 상태를 유지할 수 있습니다. 열 수준 변환에는 uc-udf를 사용하고 ML 클러스터링 또는 집계와 같은 작업에는 uc-udtf를 사용합니다.
UDTF 핸들러 클래스는 각 입력 행마다 실행되는 eval()를 정의합니다. 선택적으로 상태를 설정하는 terminate()와 모든 행 이후 최종 결과를 생성하는 __init__()도 정의합니다. Unity 카탈로그에서 Python 사용자 정의 테이블 함수(UDTF)를 확인하세요.
class MyOperator:
def __init__(self):
# Optional. Called before processing - initialize any values needed.
...
def eval(self, row):
# Required. Called one time per input row - process or accumulate data here.
...
def terminate(self):
# Optional. Called after all rows - perform final calculations and yield results.
...
비고
UDTF 반환 테이블에는 고정된 명시적 형식이 있어야 합니다. 반환 구성에서는 입력 열 형식을 참조할 수 없습니다.
미리보기 중 부수 효과는 건너뛰세요
Lakeflow Designer는 디자인 모드에서 미리 보기를 지원합니다. 외부 API를 호출하거나 외부 시스템에 쓰기 작업을 수행하는 연산자의 경우, 미리 보기 중 부작용을 건너뛸 수 있도록 is_preview 구성 속성을 추가하세요. 사용자는 부작용이 있는 연산자를 실행하기 위해 Run을 클릭합니다. 내장된 Python 연산자는 config["is_preview"]을 자동으로 읽기 때문에 이 속성이 필요하지 않습니다.
Python 미리보기 모드를 참조하세요.
config:
type: object
properties:
is_preview:
type: boolean
format: is_preview
default: false
Lakeflow Designer는 미리 보기 중에 이 값을 true 자동으로 설정합니다. 부작용을 건너뛰도록 로직에서 이를 확인하세요.
# In a python-run-function
if config.get("is_preview"):
return {"out": inputs["in"]}
-- In a UC function (SQL)
CASE WHEN is_preview THEN 'preview' ELSE /* actual work */ END
Unity 카탈로그 HTTP 연결을 사용하여 외부 API를 호출하세요
SQL Unity 카탈로그 함수를 기반으로 외부 API를 호출하는 커스텀 연산자라면, Unity 카탈로그 HTTP 연결을 사용하여 자격 증명을 안전하게 저장하세요:
CREATE CONNECTION my_api_connection TYPE HTTP OPTIONS (
host 'https://api.example.com',
port '443',
base_path '/v1/',
bearer_token 'your-token-here'
);
그런 다음 SQL UDF에서 http_request() 함수를 사용하여 해당 연결을 사용하세요. 자세한 내용은 외부 HTTP 서비스에 대한 연결을 참조하세요.
WorkspaceClient로 작업 공간 리소스에 접근하기
python-run-function 연산자의 경우 Azure Databricks WorkspaceClient 사용하여 작업 영역 리소스 및 외부 API에 액세스할 수 있습니다.
def run(config, inputs, spark):
from databricks.sdk import WorkspaceClient
w = WorkspaceClient()
# Use w to access workspace resources