> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-detect-table-modification.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> ClickHouse Obfuscator のドキュメント

# clickhouse-obfuscator

テーブルデータを難読化するためのシンプルなツールです。

入力テーブルを読み取り、入力データのいくつかの特性を保持しつつ、内容の異なる出力テーブルを生成します。
これにより、ベンチマーク用途に、実際の本番データにかなり近いデータを公開できます。

このツールは、データの次の特性を保持するよう設計されています。

* 各カラムおよび各カラムの組み合わせごとの値のカーディナリティ (異なる値の数) ;

* 条件付きカーディナリティ: あるカラムの値を条件にしたときの、別のカラムにおける異なる値の数;

* 整数の絶対値の確率分布、符号付き整数の符号、浮動小数点数の指数と符号の確率分布;

* 文字列長の確率分布;

* 数値が 0 となる確率、空文字列や空の配列、`NULL` の出現確率;

* LZ77 および entropy 系の codec で圧縮した場合のデータの圧縮率;

* テーブル全体にわたる時刻値の連続性 (差分の大きさ) ; 浮動小数点値の連続性;

* `DateTime` 値の日付部分;

* 文字列値の UTF-8 としての妥当性;

* 文字列値が自然に見えること。

上記の特性の多くは、パフォーマンステストで有用です。

カーディナリティ、大きさ、圧縮率などが保持されるため、
データの読み取り、フィルタリング、aggregation、ソートは、元のデータとほぼ同じ速度で動作します。

このツールは決定論的に動作します。つまり、seed 値を指定すると、変換結果は入力データと seed によって決まります。
変換の中には一対一対応で元に戻せるものもあるため、十分に大きな seed を使い、それを秘密にしておく必要があります。

データ変換にはいくつかの暗号学的 primitive を使用していますが、暗号学の観点からは適切なやり方ではありません。そのため、別の根拠がない限り、結果を安全だとみなすべきではありません。公開したくないデータが結果に残る可能性があります。

ソースデータ内の 0、1、-1 という数値、日付、配列の長さ、および null フラグは、常にそのまま保持されます。
たとえば、テーブルに 0 と 1 の値を持つ `IsMobile` というカラムがあるとします。変換後のデータでも、その値は同じままです。

そのため、ユーザーはモバイルトラフィックの正確な比率を算出できます。

別の例を挙げます。テーブルにユーザーのメールアドレスのような非公開データがあり、どのメールアドレスも公開したくない場合です。
テーブルが十分に大きく、複数の異なるメールアドレスを含み、かつ他と比べて極端に高頻度のメールアドレスが存在しなければ、すべてのデータは匿名化されます。しかし、あるカラム内の異なる値の数が少ない場合は、その一部が再現されることがあります。
このツールの動作アルゴリズムを確認し、コマンドラインパラメータを適切に調整する必要があります。

このツールが適切に機能するのは、少なくとも中程度以上のデータ量 (少なくとも数千行) がある場合に限られます。