> ## 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.

> Clickhouse Obfuscator のドキュメント

# clickhouse-obfuscator

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

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

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

* 各カラムおよび各カラムのタプルにおける値のカーディナリティ (異なる値の数) ;

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

* 整数の絶対値の確率分布、符号付き整数の符号、Float の指数と符号;

* 文字列の長さの確率分布;

* 数値が 0 である確率、空文字列や空配列、`NULL` である確率;

* LZ77 およびエントロピー系 codec で圧縮した場合のデータの圧縮率;

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

* `DateTime` 値の日付部分;

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

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

上記の性質の多くは、性能テストに有用です。

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

このツールは決定論的に動作します。seed 値を指定すると、変換結果は入力データと seed によって決まります。
一部の変換は一対一対応で、逆変換できる可能性があるため、十分に大きな seed を使用し、それを secret として保持する必要があります。

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

0、1、-1 の数値、日付、配列の長さ、null フラグは、常に元データとまったく同じまま保持されます。
たとえば、テーブルに 0 と 1 の値を持つ `IsMobile` カラムがある場合、変換後のデータでもその値は同じです。

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

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

このツールが適切に機能するのは、少なくともある程度まとまった量のデータがある場合だけです (少なくとも数千行) 。