> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sifi.life/llms.txt
> Use this file to discover all available pages before exploring further.

# Lakeflow 증분 처리 가이드

> **참고**
> Spark Declarative Pipelines(SDP)의 기본 개념, Streaming Table과 Materialized View의 차이는 **[교육자료 → 데이터 엔지니어링 → SDP](/training/05-data-engineering/spark-declarative-pipelines/overview)** 를 참고하세요. 이 가이드는 프로덕션 운영 시 Full Refresh 방지 전략에 집중합니다.

## 왜 이 가이드가 필요한가

Lakeflow Declarative Pipeline(구 DLT)은 선언적으로 데이터 파이프라인을 정의하는 강력한 도구입니다. 하지만 파이프라인을 운영하다 보면, 사소한 수정 하나가 **전체 데이터를 처음부터 다시 처리(Full Refresh)** 하는 상황을 만들 수 있습니다.

이 문제는 단순히 "시간이 오래 걸린다"는 수준이 아닙니다.

> **주의**
> **Streaming Table** 의 Full Refresh는 체크포인트가 초기화되어 **데이터 손실 또는 중복** 위험이 있습니다. **Materialized View** 의 Full Recompute는 전체 소스를 다시 읽어 **비용이 수십\~수백 배 폭증** 할 수 있습니다.

실제 프로덕션 환경에서 테라바이트급 테이블의 Full Refresh가 발생하면, 수 시간의 다운타임과 수천 달러의 추가 비용이 발생합니다. 이 가이드는 Full Refresh가 **언제, 왜** 발생하는지 정확히 이해하고, 이를 **방지하거나 안전하게 관리** 하는 전략을 제공합니다.

***

## Streaming Table vs Materialized View: Full Refresh 비교

두 테이블 유형은 Full Refresh의 의미와 변동성가 근본적으로 다릅니다. 아래 테이블은 핵심 차이를 요약합니다.

| 구분                  | Streaming Table (ST)                     | Materialized View (MV)                           |
| ------------------- | ---------------------------------------- | ------------------------------------------------ |
| **처리 모델**           | Append-only, 체크포인트 기반                    | 전체 결과를 선언적으로 정의                                  |
| **Full Refresh 의미** | 체크포인트 삭제 → 소스부터 전체 재수집                   | 기존 결과 삭제 → 전체 소스 재계산                             |
| **데이터 손실 위험**       | 높음 (소스가 만료/삭제된 경우 복구 불가)                 | 낮음 (소스 데이터가 살아있으면 재계산 가능)                        |
| **비용 영향**           | 소스 재수집 + 재처리 비용                          | 전체 소스 스캔 + 재계산 비용                                |
| **자동 발생 여부**        | 특정 변경 시 시스템이 강제 요구                       | Enzyme 엔진이 자동으로 full/incremental 선택              |
| **사용자 제어**          | `pipelines.reset.allowed = false`로 방지 가능 | `REFRESH POLICY INCREMENTAL STRICT`(Beta)로 강제 가능 |

핵심 시사점: Streaming Table은 "방지"에 집중해야 하고, Materialized View는 "최적화"에 집중해야 합니다. ST는 Full Refresh 자체를 막아야 하며, MV는 Enzyme이 incremental로 처리할 수 있도록 쿼리와 소스를 설계해야 합니다.

***

## 가이드 구성

이 가이드는 세 개의 서브페이지로 구성됩니다.

### [Streaming Table 증분 처리](streaming-table)

Streaming Table에서 Full Refresh가 발생하는 정확한 조건, Full Refresh 없이 가능한 변경, 보호 설정(`pipelines.reset.allowed`), Append Flow 패턴, 체크포인트 복구 옵션을 다룹니다.

### [Materialized View 증분 처리](materialized-view)

Enzyme(Databricks 내부 최적화 엔진)의 동작 원리, Full Recompute를 유발하는 5가지 원인, 소스 테이블 전제조건(Row Tracking, Deletion Vectors, CDF), 쿼리 설계 원칙, REFRESH POLICY(Beta)를 다룹니다.

### [CDC & 실전 체크리스트](cdc-checklist)

APPLY CHANGES(AUTO CDC)를 활용한 SCD Type 1/2 패턴과, 파이프라인 설계/수정/모니터링을 위한 실전 체크리스트를 제공합니다.

***

## 파이프라인 삭제/변경 시 테이블 보호 (2026년 신규)

2026년 초에 파이프라인 삭제 및 변경 시 테이블을 보호하는 새로운 기능들이 추가되었습니다.

### 1. 파이프라인 삭제 시 테이블 유지 (`cascade=false`)

기존에는 파이프라인을 삭제하면 관련된 모든 Streaming Table, Materialized View, View가 함께 삭제되었습니다. 이제 `cascade=false` 옵션으로 **파이프라인만 삭제하고 테이블은 유지**할 수 있습니다.

```python theme={null}
# Python SDK
from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

# 파이프라인 삭제 — 테이블은 유지
w.pipelines.delete(
    pipeline_id="<pipeline-id>",
    cascade=False  # 테이블을 삭제하지 않고 비활성(inactive) 상태로 유지
)
```

```bash theme={null}
# REST API
curl -X DELETE \
  "https://<workspace>/api/2.0/pipelines/<pipeline-id>?cascade=false" \
  -H "Authorization: Bearer <token>"
```

> **상태**: Beta (2026년 4월 기준). 기본값은 `cascade=true`(기존 동작 유지).

| 옵션                  | 동작                                           |
| ------------------- | -------------------------------------------- |
| `cascade=true` (기본) | 파이프라인 + 모든 테이블 삭제                            |
| `cascade=false`     | 파이프라인만 삭제, 테이블은 **비활성(inactive)** 상태로 UC에 유지 |

### 2. 비활성 테이블 자동 정리

파이프라인 정의에서 테이블을 제거하면(코드에서 `CREATE STREAMING TABLE` 삭제 등), 해당 테이블이 **비활성(inactive)** 상태가 됩니다. 새 옵션으로 이런 비활성 테이블을 **자동으로 정리**할 수 있습니다.

> **주의**: 이 기능을 활성화하면, 파이프라인 정의에서 실수로 테이블을 제거했을 때 데이터가 삭제될 수 있습니다. 프로덕션에서는 신중하게 사용하세요.

### 3. Full Refresh 방지 (기존)

프로덕션 Streaming Table에는 반드시 설정:

```sql theme={null}
CREATE OR REFRESH STREAMING TABLE production_orders
TBLPROPERTIES ('pipelines.reset.allowed' = 'false')
AS SELECT * FROM STREAM(bronze_orders);
```

이 설정이 있으면 실수로 Full Refresh를 실행해도 **시스템이 거부**합니다.

***

## 참고 자료

| 문서                             | 링크                                                                                                                                       |
| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
| Pipeline Updates (공식 문서)       | [docs.databricks.com/ldp/updates](https://docs.databricks.com/aws/en/ldp/updates)                                                        |
| Checkpoint Recovery            | [docs.databricks.com/ldp/recover-streaming](https://docs.databricks.com/aws/en/ldp/recover-streaming)                                    |
| Incremental Refresh            | [docs.databricks.com/optimizations/incremental-refresh](https://docs.databricks.com/aws/en/optimizations/incremental-refresh)            |
| Append Flows                   | [docs.databricks.com/ldp/flows](https://docs.databricks.com/aws/en/ldp/flows)                                                            |
| Optimizing MV Recomputes (블로그) | [databricks.com/blog/optimizing-materialized-views-recomputes](https://www.databricks.com/blog/optimizing-materialized-views-recomputes) |
| APPLY CHANGES API              | [docs.databricks.com/ldp/cdc](https://docs.databricks.com/aws/en/ldp/cdc)                                                                |

이 참고 자료들은 각 서브페이지에서도 맥락에 맞게 링크됩니다.