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

# XGBoost 딕셔너리

> XGBOOST 딕셔너리를 구성하여 그래디언트 부스팅 모델을 학습시키고 수치형 대상 값을 예측합니다.

[ClickHouse Cloud에서 지원되지 않음](https://clickhouse.com/docs/products/cloud/guides/cloud-compatibility.md#list-of-unsupported-features)

`xgboost` (`XGBOOST`) 딕셔너리는 로드 시점에 학습용 행이 담긴 원본 테이블을 사용해 [XGBoost](https://xgboost.readthedocs.io/) 그래디언트 부스팅 모델을 학습한 다음, 입력된 피처 벡터에 대해 숫자형 대상 값을 예측합니다. 피처 컬럼이 딕셔너리 키가 되며, 단일 속성은 모델이 학습하는 대상 값입니다.

이 딕셔너리는 피처가 숫자형인 표 형식 데이터의 회귀 및 이진 분류에 적합합니다. 예를 들어 여러 측정값으로 특정 값을 예측하거나, 학습된 대상 값을 기준으로 행에 점수를 매기는 작업에 활용할 수 있습니다. 다중 클래스 목적 함수는 지원되지 않습니다([레이아웃 매개변수](#layout-parameters) 참고).

> [!NOTE]
>
> XGBoost 통합은 실험적 기능입니다. `XGBOOST` 딕셔너리를 생성하거나 `predictXGBoost`를 호출하기 전에 `enable_xgboost` 설정으로 활성화하십시오.
>
> ```sql theme={null}
> SET enable_xgboost = 1;
> ```
>
> `CREATE DICTIONARY`만 지원됩니다. 서버 설정 파일에 정의된 `XGBOOST` 딕셔너리는 로드되지 않습니다.

이 딕셔너리는 [`predictXGBoost`](https://clickhouse.com/docs/ko/reference/functions/regular-functions/machine-learning-functions)로만 쿼리할 수 있습니다. 이 함수는 피처를 개별 인수로 받아 예측값을 반환하며, 추가 [예측 매개변수](#prediction-parameters)도 지정할 수 있습니다. 이 딕셔너리는 행이 아닌 학습된 모델을 저장하므로 [`dictGet`](https://clickhouse.com/docs/ko/reference/functions/regular-functions/ext-dict-functions#dictGet), `dictHas`, `SELECT * FROM dict`와 같은 일반 딕셔너리 인터페이스는 지원되지 않으며, 사용 시 오류가 발생합니다.

## 빠른 시작

여기서는 선형 대상 `y = 2*x1 + 3*x2`를 대상으로 회귀 모델을 학습시킵니다.

**1. 원본 테이블을 생성합니다.** 이 테이블에는 학습용 행이 저장되며, 피처(feature) 컬럼 다음에 대상 컬럼이 오도록 구성합니다.

```sql theme={null}
CREATE TABLE training_data (x1 Float64, x2 Float64, y Float64)
ENGINE = MergeTree ORDER BY tuple();
```

**2. 학습 데이터 삽입:**

```sql theme={null}
INSERT INTO training_data
SELECT number AS x1, number * 2 AS x2, 2 * x1 + 3 * x2 AS y
FROM numbers(100);
```

**3. `XGBOOST` 레이아웃(layout)으로 딕셔너리를 생성합니다.** 피처(feature) 컬럼은 키가 되고, `y`는 대상 속성이 됩니다:

```sql theme={null}
CREATE DICTIONARY model (x1 Float64, x2 Float64, y Float64)
PRIMARY KEY (x1, x2)
SOURCE(CLICKHOUSE(TABLE 'training_data'))
LAYOUT(XGBOOST(
    objective 'reg:squarederror'
    num_iterations 100
    max_depth 6
))
LIFETIME(0);
```

`PRIMARY KEY (x1, x2)`는 `x1`과 `x2`를 피처로 지정합니다. 모델이 학습하는 대상은 `y`이며, 키에 포함되지 않은 유일한 컬럼이므로 자동으로 추론됩니다. `LAYOUT`의 매개변수는 XGBoost 하이퍼파라미터입니다([레이아웃 매개변수](#layout-parameters) 참조).

**4. 예측** — `predictXGBoost`는 피처를 위치 기반으로 전달받아 예측값을 반환합니다.

```sql theme={null}
SELECT predictXGBoost('model', 1.0, 2.0) AS prediction;
```

실제 값(ground truth)은 `2*1 + 3*2 = 8`이므로 모델의 예측값은 `8`에 가깝습니다.

## 동작 방식

**학습(로드 시점).** 각 소스 행은 `(features..., target)` 형태의 관측값입니다. 딕셔너리가 로드되면 소스를 블록 단위로 읽은 뒤, 전체 데이터에 대해 모델을 한 번 학습합니다. 피처 값과 대상 값은 부동 소수점 수로 읽히므로 키 열(Key Columns)은 숫자형이어야 하고, 대상 속성은 floating-point 타입이어야 합니다([딕셔너리 구조](#dictionary-structure) 참조).

> [!WARNING]
>
> **학습 시 전체 학습 세트를 메모리에 보관합니다.** 소스를 블록 단위로 읽는다고 해서 외부 메모리(out-of-core) 학습이 되는 것은 아닙니다. 각 블록은 소비되지 않고 누적되므로, 첫 번째 부스팅 라운드가 시작되기 전에 전체 학습 세트가 메모리에 올라가며 마지막 라운드가 끝날 때까지 메모리에 유지됩니다.

**예측(쿼리 시점).** 예측 시 모델은 키 열(Key Columns)이 선언된 순서대로 구성된 피처 벡터를 입력받아 학습된 부스터에 통과시킨 후 `Float64` 값을 반환합니다. `NULL` 피처는 결측값으로 모델에 전달되며, XGBoost는 학습 과정에서 익힌 방식대로 이를 처리하므로 예측 결과가 `NULL`이 되는 경우는 없습니다. 모든 피처가 상수이면 모델은 행마다 평가되지 않고 블록당 한 번만 평가됩니다.

**모델은 영구 저장되지 않습니다.** 모델은 딕셔너리가 로드되어 있는 동안에만 메모리에 존재하며, 서버 재시작 후를 포함해 로드될 때마다 소스로부터 다시 학습됩니다.

**모델 재학습.** 로드할 때마다 처음부터 새로 학습하므로, `SYSTEM RELOAD DICTIONARY`를 실행하면 원본 테이블의 현재 내용을 기준으로 모델이 재학습됩니다.

```sql theme={null}
INSERT INTO training_data VALUES (5, 10, 40);
SYSTEM RELOAD DICTIONARY model;
```

`LIFETIME`을 0이 아닌 값으로 설정해도 재학습이 수행됩니다. 수명(lifetime)에 따라 트리거되어 다시 로드하는 것도 일반 로드와 다르지 않기 때문입니다. 학습 데이터가 늘어날 때 모델을 주기적으로 갱신하려면 이 설정을 사용하십시오.

## 딕셔너리 구조

`XGBOOST` 딕셔너리는 다음과 같이 고정된 구조적 형태(Shape)를 가집니다.

* `PRIMARY KEY`는 네이티브 숫자 유형(정수(integer) 및 부동 소수점 수)의 컬럼 하나 이상으로 구성되며, 이 컬럼들이 피처가 됩니다. 쿼리 시점에 이 "키"는 저장된 조회(lookup) 키가 아니라 예측에 사용할 피처 벡터입니다. 피처 순서는 키 컬럼의 선언 순서를 따르며, `predictXGBoost`는 위치 인수를 이 순서대로 바인딩합니다.
* 이와 함께 **`Float32` 또는 `Float64` 타입의 속성을 정확히 1개** 선언하십시오. 이 속성은 모델이 학습하는 대상입니다. 이 속성은 항상 피처 키에 속하지 않는 유일한 컬럼으로 추론되므로 이름을 지정하는 매개변수는 따로 없으며, 속성을 2개 이상 선언하면 오류가 발생합니다.

이러한 요구 사항을 충족하지 않는 컬럼은 딕셔너리를 생성할 때가 아니라 로드할 때 거부됩니다.

## 레이아웃(layout) 매개변수

아래에 나열된 매개변수만 허용되며, 그 외의 이름을 사용하면 로드가 실패합니다. 따라서 오타가 있으면 조용히 무시되지 않고 모델 학습 시점에 감지됩니다. `num_iterations`는 ClickHouse가 직접 처리하며(해당 설명 참고), 나머지 매개변수는 모두 문자열 형태 그대로 XGBoost 부스터에 전달되고 XGBoost 자체의 기본값과 값 범위를 따릅니다. 자세한 내용은 [XGBoost 매개변수 참고 문서](https://xgboost.readthedocs.io/en/stable/parameter.html)를 참고하십시오.

| 매개변수 | 설명 |
| - | - |
| `num_iterations` | 부스팅 라운드 수(학습할 트리 개수)입니다. 양의 정수이며, 부스터로 전달되지 않고 학습 루프 반복 횟수로 사용됩니다. 기본값은 `100`입니다. |
| `booster` | 부스터 유형으로, `gbtree`, `gblinear`, `dart` 중 하나입니다. |
| `objective` | 학습 목적 함수입니다(예: `reg:squarederror`, `binary:logistic`). 행마다 단일 값을 예측하는 목적 함수여야 하며, 다중 클래스 목적 함수(`multi:softmax`, `multi:softprob`)는 거부됩니다. |
| `seed` | 난수 seed입니다. 학습은 기본적으로 결정적이므로, 확률적 매개변수(`subsample`, `sampling_method`, 모든 `colsample_*`)를 함께 설정한 경우에만 모델이 달라집니다. |
| `verbosity` | XGBoost의 로깅 상세 수준으로, `0`(출력 없음), `1`(경고, 기본값), `2`(정보) 중 하나입니다. 디버그 수준 `3`은 활성화 시 켜지는 타이밍 모니터가 thread-safe하지 않으므로 거부됩니다. XGBoost가 기록하는 메시지에만 영향을 주며 학습된 모델에는 영향을 주지 않습니다. 메시지가 기록되는 위치는 [참고](#notes)를 확인하십시오. |
| `nthread` | 학습에 사용할 병렬 스레드 수입니다. 값은 허용되어 전달되지만 현재는 아무 효과가 없습니다. 번들된 XGBoost는 OpenMP 없이 빌드되므로 학습과 예측은 항상 단일 스레드에서 실행됩니다. |
| `eta` | 각 부스팅 라운드 후 적용되는 스텝 크기 축소 값입니다. 이 표기만 허용되며, XGBoost의 `learning_rate` 별칭은 허용되지 않습니다. |
| `gamma` | 리프를 추가로 분할하는 데 필요한 최소 손실 감소량입니다. |
| `max_depth` | 트리의 최대 깊이입니다. |
| `min_child_weight` | 자식 노드에 필요한 인스턴스 가중치(헤시안) 합계의 최솟값입니다. |
| `max_delta_step` | 각 리프 출력에 허용되는 최대 델타 스텝입니다. |
| `subsample` | 각 부스팅 라운드에서 샘플링할 학습 행의 비율입니다. |
| `sampling_method` | 행 샘플링 방식으로, `uniform` 또는 `gradient_based`입니다. `subsample`을 `1`보다 작게 설정한 경우에만 효과가 있습니다. |
| `colsample_bytree` / `colsample_bylevel` / `colsample_bynode` | 트리별 / 수준별 / 분할별로 샘플링할 컬럼(피처)의 비율입니다. |
| `lambda` | 가중치에 대한 L2 정규화 항입니다. 이 표기만 허용되며, XGBoost의 `reg_lambda` 별칭은 허용되지 않습니다. |
| `alpha` | 가중치에 대한 L1 정규화 항입니다. 이 표기만 허용되며, XGBoost의 `reg_alpha` 별칭은 허용되지 않습니다. |
| `tree_method` | 트리 구성 알고리즘으로, `auto`, `exact`, `approx`, `hist` 중 하나입니다. |
| `scale_pos_weight` | 양성 및 음성 가중치의 균형을 조정하며, 클래스 불균형이 있을 때 유용합니다. |
| `grow_policy` | 트리에 새 노드를 추가하는 방식으로, `depthwise` 또는 `lossguide`입니다. |
| `max_leaves` | 리프 노드(leaf nodes)의 최대 개수입니다(`grow_policy`가 `lossguide`일 때 사용). |
| `max_bin` | 연속형 피처를 버킷으로 나눌 때 사용하는 이산 빈의 최대 개수입니다(`tree_method`가 `hist`일 때 사용). |
| `num_parallel_tree` | 부스팅 라운드마다 생성하는 트리 수입니다(`> 1` 값을 지정하면 부스팅된 랜덤 포레스트를 학습합니다). |

매개변수 이름은 대소문자를 구분하지 않으며, 각 매개변수는 한 번만 지정할 수 있습니다. 값은 양의 정수, 부동소수점 수 또는 따옴표로 묶은 문자열이어야 합니다. 음수 리터럴은 레이아웃에 전달되기 전에 딕셔너리 DDL 단계에서 거부되므로 `seed`에 음수를 지정할 수 없습니다.

예를 들어, 스텝 크기 `eta`도 함께 설정하는 딕셔너리는 다음과 같습니다.

```sql theme={null}
CREATE DICTIONARY model_tuned (x1 Float64, x2 Float64, y Float64)
PRIMARY KEY (x1, x2)
SOURCE(CLICKHOUSE(TABLE 'training_data'))
LAYOUT(XGBOOST(
    objective 'reg:squarederror'
    num_iterations 100
    max_depth 6
    eta 0.3
))
LIFETIME(0);
```

## 예측 매개변수

`predictXGBoost`는 피처 뒤에 오는 마지막 인수로, XGBoost 예측 매개변수를 담은 상수 `Map`을 선택적으로 받을 수 있습니다. 이 `Map`은 `map`으로 생성합니다.

```sql theme={null}
SELECT predictXGBoost('model', 1.0, 2.0, map('type', 0, 'iteration_end', 0));
```

매개변수 이름은 XGBoost `XGBoosterPredictFromDMatrix`의 예측 매개변수에 대응합니다. 아래 키만 허용되며, 그 외의 키를 사용하면 쿼리가 실패합니다. 모든 매개변수는 정수(integer) 또는 불리언이므로 `Map` 값은 정수 타입이어야 합니다.

| 매개변수 | 설명 | 기본값 |
| - | - | - |
| `type` | 예측 유형입니다. `predictXGBoost`는 행마다 하나의 `Float64`를 반환하므로 `0`(값)과 `1`(마진)만 허용됩니다. 그 외의 XGBoost 유형(`2`/`3` SHAP 기여도, `4`/`5` 피처 상호작용, `6` 리프 인덱스)은 행마다 여러 값을 출력하므로 거부됩니다. | `0` |
| `iteration_begin` | 예측에 포함할 첫 번째 부스팅 라운드로, `0`부터 셉니다(경계값 포함). 모델 학습 시 사용한 부스팅 반복 횟수(`num_iterations`)를 초과할 수 없습니다. | `0` |
| `iteration_end` | 포함할 마지막 부스팅 라운드의 다음 값입니다(경계값 미포함). 따라서 `iteration_end 1`은 첫 번째 라운드만 사용하고, `0`은 모든 라운드를 사용합니다. `iteration_begin`과 동일한 범위 제한이 적용됩니다. | `0` |

## 참고 사항

* **계산형 딕셔너리의 의미 체계.** 이 딕셔너리는 *계산형* 딕셔너리입니다. 행 대신 학습된 모델을 보유하며, `predictXGBoost`로만 쿼리할 수 있습니다. 일반 딕셔너리 인터페이스는 지원되지 않으며 사용 시 오류가 발생합니다. 해당 작업은 `dictGet`(조회할 저장된 속성이 없으며, "키"는 예측에 사용할 피처 벡터입니다), `dictHas`(저장된 키가 없습니다), `SELECT * FROM dict`, 그리고 딕셔너리를 테이블처럼 조인하는 작업입니다. `predictXGBoost`가 유일한 진입점이므로, 모든 예측에서 `enable_xgboost` 설정이 활성화되어 있어야 합니다.

* **숫자 컬럼만 지원.** 모든 피처(키) 컬럼은 네이티브 숫자 유형이어야 하며, 대상 속성은 `Float32` 또는 `Float64`여야 합니다. 학습 및 예측 시 값은 부동 소수점으로 읽힙니다. `predictXGBoost`의 피처 인수는 `Nullable`일 수도 있습니다. 자세한 내용은 [동작 방식](#how-it-works)을 참조하십시오.

* **`system.dictionaries`에는 저장된 항목이 표시되지 않습니다.** 이 딕셔너리는 행을 저장하지 않고 모델을 학습하므로, `direct` 딕셔너리와 마찬가지로 `element_count`는 `0`이며 `bytes_allocated`도 `0`입니다. 학습된 모델은 XGBoost가 관리하며, XGBoost는 사용 중인 메모리 양을 보고하지 않기 때문입니다. `query_count`와 `found_rate`는 `predictXGBoost`가 모델에 전달한 행 수를 집계합니다. 모든 피처가 상수인 호출은 블록당 한 번만 평가되므로, 행마다 집계되지 않고 블록당 1개의 행으로 집계됩니다.

* **다시 로드하는 데 실패하면 이전 모델이 유지됩니다.** 원본 테이블이 삭제되었거나, 스키마가 변경되었거나, 하이퍼파라미터가 더 이상 허용되지 않는 등의 이유로 재학습에 실패하더라도 딕셔너리의 예측이 실패하지는 않습니다. 대신 마지막으로 학습에 성공한 모델을 계속 제공하면서 오류를 기록합니다. 모델이 여전히 현재 소스 데이터를 반영하는지 확인하려면 `system.dictionaries`에서 `last_successful_update_time`과 `last_exception`을 비교하십시오.

  ```sql theme={null}
  SELECT name, status, last_successful_update_time, last_exception
  FROM system.dictionaries
  WHERE name = 'model';
  ```

* **XGBoost의 메시지는 서버 로그에 기록됩니다.** 이 메시지는 XGBoost가 지정한 로그 수준에 따라 `XGBoost` 로거로 기록되며, 학습 또는 예측을 수행하는 쿼리에 연결되므로 `system.text_log`에도 표시됩니다. 더 많은 메시지를 보려면 `verbosity`를 높이십시오.

* **피처 순서가 중요합니다.** `predictXGBoost`는 위치 기반 피처 인수를 선언 순서대로 키 열(Key Columns)에 바인딩하며, 피처 인수의 개수는 키 열(Key Columns)의 개수와 일치해야 합니다.
