> ## 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/ja/reference/functions/regular-functions/machine-learning-functions) です。この関数は特徴量を個別の引数として受け取って予測を返し、追加の[予測パラメータ](#prediction-parameters)も指定できます。この 辞書 は行ではなく学習済みモデルを保持するため、汎用的な辞書インターフェイス ([`dictGet`](https://clickhouse.com/docs/ja/reference/functions/regular-functions/ext-dict-functions#dictGet)、`dictHas`、`SELECT * FROM dict`) はサポートされておらず、使用するとエラーになります。

## クイックスタート

ここでは、線形の目的変数 `y = 2*x1 + 3*x2` を対象に回帰モデルを学習させます。

**1. 学習データの行を格納するソーステーブルを作成します**。カラムは特徴量を先に並べ、最後に目的変数を配置します。

```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` レイアウトで 辞書 を作成します**。特徴量カラムをキーとし、`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;
```

真の値は `2*1 + 3*2 = 8` なので、モデルの予測は `8` に近い値になります。

## 仕組み

**学習 (ロード時) 。** ソースの各行は `(features..., target)` という 1 件の観測値です。辞書 のロード時にソースはブロック単位で読み込まれ、その後、データ全体を対象にモデルが 1 回だけ学習されます。特徴量と目的変数の値は浮動小数点数として読み込まれるため、キーカラムは数値型、ターゲット属性は floating-point 型である必要があります ([辞書 の構造](#dictionary-structure)を参照) 。

> [!WARNING]
>
> **学習時には学習データ全体がメモリ上に保持されます。** ソースをブロック単位で読み込んでも、アウトオブコア学習にはなりません。各ブロックは消費されずに蓄積されるため、学習データ全体は最初のブースティングラウンドの前にメモリに常駐し、最後のラウンドが終わるまで常駐し続けます。

**予測 (クエリ実行時) 。** 予測時、モデルはキーカラムの宣言順に並んだ特徴量ベクトルを受け取り、学習済みのブースターで評価して `Float64` を返します。`NULL` の特徴量は欠損値としてモデルに渡され、XGBoost が学習時に習得した方法で処理するため、予測が `NULL` になることはありません。すべての特徴量が定数の場合、モデルは行ごとではなくブロックごとに 1 回だけ評価されます。

**モデルは永続化されません。** モデルは 辞書 がロードされている間だけメモリ上に存在し、ロードのたびに (サーバー再起動後も含めて) ソースから再学習されます。

**モデルの再学習。** ロードのたびにスクラッチから学習されるため、`SYSTEM RELOAD DICTIONARY` を実行すると、ソーステーブルの現在の内容でモデルが再学習されます。

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

`LIFETIME` を 0 以外に設定した場合も再学習が行われます。存続期間の経過によってトリガーされた再読み込みは、通常の読み込みと同じように扱われるためです。学習データの増加に合わせてモデルを定期的にリフレッシュしたい場合は、この設定を使用してください。

## 辞書 の構造

`XGBOOST` 辞書 の形状は固定されています。

* `PRIMARY KEY` は、ネイティブの数値型(整数および浮動小数点数)の 1 つ以上のカラムで構成され、これが特徴量となります。クエリ実行時、この「キー」は予測時に渡す特徴量ベクトルを指し、保存済みのルックアップキーではありません。特徴量の順序はキーカラムの宣言順に従い、`predictXGBoost` は位置引数をこの順序でバインドします。
* これらに加えて、**`Float32` または `Float64` 型の属性を 1 つだけ**宣言します。これがモデルの学習対象となる目的変数です。この属性は常に、特徴量キーに含まれない唯一のカラムとして推論されます。目的変数を指定するパラメータはなく、属性を 2 つ以上宣言するとエラーになります。

これらの要件を満たさないカラムは、辞書 の作成時ではなく、読み込み時に拒否されます。

## レイアウトのパラメータ

指定できるのは以下のパラメータのみです。それ以外の名前を指定するとロードに失敗するため、タイプミスが黙って無視されることはなく、モデルの学習時に検出されます。`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`)。1 行につき 1 つの値を予測する目的関数である必要があり、多クラスの目的関数 (`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` | leafをさらに分割するために必要な損失減少量の最小値。 |
| `max_depth` | 木の最大深さ。 |
| `min_child_weight` | 子ノードに必要なインスタンスの重み (ヘッシアン) の合計の最小値。 |
| `max_delta_step` | 各leafの出力に許容される最大差分ステップ。 |
| `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ノードの最大数 (`grow_policy` が `lossguide` の場合に使用)。 |
| `max_bin` | 連続値の特徴量をバケット化する際に使用する離散ビンの最大数 (`tree_method` が `hist` の場合に使用)。 |
| `num_parallel_tree` | ブースティングラウンドごとに成長させる木の数 (`> 1` を指定すると、ブースティングされたランダムフォレストを学習します)。 |

パラメータ名は大文字と小文字を区別せず、各パラメータは 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` は、特徴量に続く末尾の任意引数として、`map` で構築した XGBoost 予測パラメータの定数 `Map` を受け取ります。

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

パラメータ名は、XGBoost の `XGBoosterPredictFromDMatrix` の予測パラメータに対応しています。指定できるのは以下のキーのみで、それ以外のキーを指定するとクエリは失敗します。いずれのパラメータも整数またはブール型であるため、`Map` の値は整数型である必要があります。

| パラメータ | 説明 | デフォルト |
| - | - | - |
| `type` | 予測の種別です。`predictXGBoost` は行ごとに 1 つの `Float64` を返すため、指定できるのは `0`(値)と `1`(マージン)のみです。その他の XGBoost の種別(`2`/`3` SHAP 寄与度、`4`/`5` 特徴量の相互作用、`6` leaf インデックス)は行ごとに複数の値を出力するため、受け付けられません。 | `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 回だけ評価されるため、1 行ごとではなく 1 ブロックごとに 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's のメッセージはサーバーログに出力されます。** メッセージは `XGBoost` ロガーで、XGBoost が指定したログレベルのまま書き込まれます。また、学習または予測を行うクエリに関連付けられるため、`system.text_log` にも表示されます。より多くのメッセージを確認するには `verbosity` を上げてください。

* **特徴量の順序が重要です。** `predictXGBoost` は位置依存の特徴量引数を宣言順にキーカラムへ対応付けます。そのため、特徴量引数の数はキーカラムの数と一致している必要があります。
