メインコンテンツへスキップ
スキーマ推論 を使えば、JSONデータの初期スキーマを決めたり、S3 などにある JSON のデータファイルをその場でクエリしたりできますが、データについては最適化されたバージョン管理付きスキーマを確立することを目指すべきです。以下では、JSON 構造をモデリングするための推奨アプローチについて説明します。

​
静的 JSON と動的 JSON

JSON のスキーマを定義するうえで最も重要なのは、各キーの値に対して適切な型を決めることです。各キーに適した型を判断するため、JSON 階層内の各キーに対して以下のルールを再帰的に適用することを推奨します。
  1. プリミティブ型 - キーの値がプリミティブ型である場合、そのキーがサブオブジェクト内にあるかルートにあるかにかかわらず、一般的なスキーマの設計ベストプラクティスおよび型の最適化ルールに従って型を選択してください。以下の phone_numbers のようなプリミティブ値の配列は、Array(<type>)、たとえば Array(String) としてモデル化できます。
  2. 静的か動的か - キーの値が複雑なオブジェクト、つまりオブジェクトまたはオブジェクトの配列である場合は、それが変更される可能性があるかどうかを判断します。新しいキーが追加されることがまれで、その追加を予測でき、ALTER TABLE ADD COLUMN によるスキーマ変更で対応できるオブジェクトは、静的 と見なせます。これには、一部の JSON ドキュメントでキーの一部しか存在しないオブジェクトも含まれます。新しいキーが頻繁に追加されるものや、追加されるキーを予測できないものは、動的 と見なすべきです。ただし、数百から数千のサブキーを持つ構造は、利便性の観点から動的と見なすことができます。
値が 静的 か 動的 かを判断するには、以下の該当セクション 静的オブジェクトの処理 および 動的オブジェクトの処理 を参照してください。

重要: 上記のルールは再帰的に適用する必要があります。キーの値が動的であると判断された場合、それ以上評価する必要はなく、動的オブジェクトの処理 のガイドラインに従うことができます。オブジェクトが静的な場合は、キーの値がプリミティブになるか、動的なキーに行き当たるまで、サブキーの評価を続けてください。 これらのルールを説明するために、人物を表す次の JSON の例を使用します。
これらのルールを適用すると:
  • ルートキー name、username、email、website は型 String として表現できます。カラム phone_numbers は型 Array(String) の Array プリミティブで、dob と id の型はそれぞれ Date と UInt32 です。
  • address オブジェクトには新しいキーは追加されず (追加されるのは新しい address オブジェクトのみ) 、そのため 静的 と見なせます。再帰的に見ると、すべてのサブカラムは geo を除きプリミティブ (型は String) と見なせます。geo も静的な構造で、lat と lon という 2 つの Float32 カラムを持ちます。
  • tags カラムは 動的 です。このオブジェクトには、任意の型や構造の新しいタグが自由に追加される可能性があると想定します。
  • company オブジェクトは 静的 で、含まれるキーは指定された 3 つまでです。サブキー name と catchPhrase は型 String です。キー labels は 動的 です。このオブジェクトには新しい任意のタグを追加できると想定します。値は常に文字列型のキー・バリューのペアです。
数百または数千もの静的キーを持つ構造では、それらのカラムを静的に宣言するのが現実的でないことが多いため、動的なものと見なせます。ただし、可能であれば、ストレージ使用量と推論のオーバーヘッドの両方を抑えるため、不要なパスをスキップしてください。

​
静的な構造の扱い

静的な構造には、名前付きタプル、つまり Tuple を使用することを推奨します。オブジェクトの配列は、タプルの配列、つまり Array(Tuple) として保持できます。タプルの内部でも、カラムとそれぞれの型は同じルールに従って定義する必要があります。その結果、以下に示すように、ネストしたオブジェクトを表現するために Tuple が入れ子になる場合があります。 これを示すため、先ほどの JSON の person の例を使い、動的なオブジェクトは省略します。
このテーブルのスキーマを以下に示します。
company カラムが Tuple(catchPhrase String, name String) として定義されている点に注目してください。address キーでは Array(Tuple) を使用し、geo カラムを表すためにネストした Tuple を使っています。 JSON は現在の構造のまま、このテーブルに挿入できます。
上記の例ではデータは最小限ですが、以下に示すように、タプル内のカラムはピリオド区切りの名前を使ってクエリできます。
address.street カラムが Array として返される点に注意してください。配列内の特定のオブジェクトを位置でクエリするには、カラム名の後に配列のオフセットを指定する必要があります。たとえば、最初の住所の street にアクセスするには、次のようにします。
サブカラムは、24.12 以降、ソートキーにも使用できます。

​
デフォルト値の扱い

JSON object は構造化されていても、既知のキーのうち一部しか含まれないことが多く、スパースになりがちです。幸い、Tuple 型では JSON payload 内のすべてのカラムを指定する必要はありません。指定されていない場合は、デフォルト値が使用されます。 先ほどの people table と、suite、geo、phone_numbers、catchPhrase のキーが欠けている次のスパースな JSON を見てみましょう。
以下のとおり、この行が正常に挿入されることがわかります。
この1行をクエリすると、省略されたカラム (サブオブジェクトを含む) にはデフォルト値が使われていることがわかります：
空文字列と null の区別値が空であることと値が指定されていないことを区別する必要がある場合は、Nullable 型を使用できます。ただし、これらのカラムではストレージ効率やクエリ性能に悪影響を及ぼすため、絶対に必要な場合を除き避けるべきです。

​
新しいカラムの扱い

JSON のキーが固定されている場合は、構造化されたアプローチが最もシンプルです。ただし、スキーマの変更を事前に計画できる、つまり新しいキーがあらかじめ分かっており、それに合わせてスキーマを修正できるのであれば、このアプローチは引き続き利用できます。 なお、ClickHouse はデフォルトで、ペイロードに含まれていてもスキーマに存在しない JSON キーは無視します。たとえば、nickname キーを追加した次のような変更済み JSON ペイロードを見てみましょう。
このJSONは、nickname キーを無視しても正常に挿入できます:
ALTER TABLE ADD COLUMN コマンドを使用すると、スキーマにカラムを追加できます。DEFAULT 句でデフォルト値を指定でき、以降の insert 時に値が指定されなかった場合はその値が使用されます。この値を持たない行 (そのカラムが作成される前に挿入された行) についても、このデフォルト値が返されます。DEFAULT 値が指定されていない場合は、その型のデフォルト値が使用されます。 例えば:

​
半構造化/動的な構造の扱い

キーが動的に追加されたり、複数の型を取りうる半構造化された JSON データには、JSON 型を推奨します。 より具体的には、次のようなデータでは JSON 型を使用してください。
  • 時間の経過とともに変化しうる、予測不能なキーがある。
  • 値の型が一定ではない (たとえば、ある パス には文字列が入り、別のときには数値が入ることがある) 。
  • 厳密な型付けが現実的ではなく、柔軟なスキーマが必要である。
  • 静的ではあるものの、明示的に宣言するのが現実的でない 数百、あるいは数千 の パス がある。これはまれなケースです。
company.labels オブジェクトが動的であると判断した、前述の person JSON を考えてみましょう。 company.labels には任意のキーが含まれているとします。さらに、この構造内の各キーの型は、行ごとに一貫していない可能性があります。たとえば、次のようなケースです。
オブジェクトごとに company.labels カラムはキーと型の観点で動的に変化するため、このデータをモデル化する方法はいくつかあります。
  • 単一の JSONカラム - スキーマ全体を 1 つの JSON カラムとして表現し、その配下のすべての構造を動的に扱えるようにします。
  • 対象を絞った JSONカラム - company.labels カラムに対してのみ JSON 型 を使用し、その他すべてのカラムについては上記の構造化スキーマを維持します。
最初のアプローチはこれまでの方法論には沿いませんが、単一の JSONカラムというアプローチは、プロトタイピングやデータエンジニアリングの作業に有用です。 大規模な ClickHouse の本番デプロイでは、構造を明確に定義し、可能な場合は対象を絞った動的サブ構造に対して JSON 型 を使用することを推奨します。 厳格なスキーマには、いくつもの利点があります。
  • データ検証 – 特定の構造を除けば、厳格なスキーマを適用することでカラム爆発のリスクを回避できます。
  • カラム爆発のリスクを回避 - JSON 型は、サブカラムを専用カラムとして保存することで、潜在的には数千ものカラムまでスケールできます。ただし、その結果として過剰な数のカラムファイルが作成され、パフォーマンスに影響する「カラムファイルの爆発」を招く可能性があります。これを軽減するため、JSON の基盤となる Dynamic type には max_dynamic_paths パラメータがあり、個別のカラムファイルとして保存される一意のパス数を制限できます。しきい値に達すると、追加のパスはコンパクトにエンコードされたフォーマットを使用する共有カラムファイルに保存されるため、柔軟なデータのインジェストをサポートしつつ、パフォーマンスとストレージ効率を維持できます。ただし、この共有カラムファイルへのアクセスは、専用カラムほど高性能ではありません。なお、JSONカラム は 型ヒント と組み合わせて使用することもできます。“ヒント付き” カラムは、専用カラムと同等のパフォーマンスを発揮します。
  • パスと型のイントロスペクションがより簡単 - JSON 型は、推論された型やパスを確認するための イントロスペクション関数 をサポートしていますが、静的な構造のほうが、たとえば DESCRIBE を使って簡単に調べやすい場合があります。

​
単一の JSON カラム

このアプローチは、プロトタイピングやデータエンジニアリングの作業に適しています。本番環境では、必要な場合に限り、動的な下位構造に対してのみ JSON を使用してください。
パフォーマンスに関する考慮事項単一の JSON カラムは、不要な JSON パスをスキップして (保存せずに) 、型ヒント を使用することで最適化できます。型ヒントを使うと、ユーザーはサブカラムの型を明示的に定義できるため、クエリ時の推論や間接処理を省略できます。これにより、明示的なスキーマを使用した場合と同等のパフォーマンスを実現できます。詳しくは、“型ヒントの使用とパスのスキップ” を参照してください。
ここでの単一 JSON カラムのスキーマはシンプルです。
username カラムは並び順/主キーで使用するため、JSON 定義では 型ヒント を付けています。これにより、ClickHouse はこのカラムが null にならないことを認識でき、さらにどの username サブカラムを使うべきかも判断できます (型ごとに複数存在する可能性があるため、そうしないと曖昧になります) 。
上記のテーブルに行を挿入するには、JSONAsObject フォーマットを使用できます。
推論されたサブカラムとその型は、イントロスペクション関数を使って確認できます。たとえば:
イントロスペクション関数の完全な一覧については、“イントロスペクション関数”を参照してください。 サブパスには . 記法でアクセスできます。たとえば、
行にないカラムは NULL として返される点に注目してください。 さらに、同じ型のパスごとに個別のサブカラムが作成されます。たとえば、company.labels.type には String と Array(Nullable(String)) の両方に対応するサブカラムが存在します。可能な場合は両方が返されますが、.: 構文を使って特定のサブカラムを指定できます。
ネストされたサブオブジェクトを返すには、^ が必要です。これは、明示的に要求された場合を除き、多数のカラムを読み込まないようにするための設計です。^ を付けずにアクセスしたオブジェクトは、以下のように NULL を返します。

​
特定のJSONカラム

プロトタイピングやデータエンジニアリングの作業には有用ですが、本番環境では可能な限り明示的なスキーマの使用を推奨します。 前述の例は、company.labels カラムに単一の JSON カラムを使用することでモデル化できます。
このテーブルへのデータ挿入には、JSONEachRow フォーマットを使用できます。
イントロスペクション関数を使用して、company.labels カラムの推定パスと型を確認できます。

​
型ヒントとパスのスキップの使用

型ヒントを使うと、パスとそのサブカラムの型を指定できるため、不要な型推論を避けられます。次の例では、JSONカラム company.labels 内の JSON キー dissolved、employees、founded の型を指定しています
これらのカラムに明示的な型が付いていることがわかります。
さらに、保存したくない JSON 内のパスは、SKIP と SKIP REGEXP パラメータを使ってスキップできます。これにより、ストレージ使用量を最小限に抑え、不要なパスに対する不要な推論を避けられます。たとえば、上記のデータに対して 単一の JSON カラム を使用するとします。この場合、address と company のパスをスキップできます:”
これらのカラムがデータから除外されている点に注目してください。

​
型ヒントでパフォーマンスを最適化する

型ヒントは、不要な型推論を避けるためだけの仕組みではありません。ストレージと処理における間接的なオーバーヘッドを完全になくし、さらに最適なプリミティブ型を指定できるようにします。型ヒントを持つ JSON パスは、常に従来のカラムと同じように保存されるため、discriminator columnsやクエリ時の動的な解決は不要です。 つまり、型ヒントが適切に定義されていれば、ネストされた JSON キーでも、最初からトップレベルのカラムとして定義されていた場合と同等のパフォーマンスと効率を実現できます。 そのため、データセットの大半には一貫性がありつつ JSON の柔軟性も活かしたい場合、型ヒントは、スキーマや取り込みパイプラインを再構成することなくパフォーマンスを維持できる便利な方法です。

​
動的パスの設定

ClickHouse は各 JSON パスを、真の列指向レイアウトにおけるサブカラムとして保存します。これにより、圧縮、SIMD による高速化処理、最小限のディスク I/O など、従来のカラムと同様の性能上の利点が得られます。JSON データ内のパスと型の組み合わせごとに、それぞれがディスク上の独立した column file になる可能性があります。 たとえば、2 つの JSON パスが異なる型で挿入された場合、ClickHouse は各具体的な型の値を別々のサブカラムに保存します。これらのサブカラムには個別にアクセスできるため、不要な I/O を最小限に抑えられます。なお、複数の型を持つカラムをクエリした場合でも、その値は引き続き単一の列指向レスポンスとして返されます。 さらに、offsets を利用することで、ClickHouse はこれらのサブカラムを疎ではなく高密度のまま維持し、存在しない JSON パスに対してデフォルト値を保存しません。この方法により圧縮率が最大化され、I/O もさらに削減されます。 ただし、カーディナリティが高い、または変化の大きい JSON 構造を持つケース、たとえばテレメトリー pipeline、logs、機械学習の feature store などでは、この挙動によって column file が爆発的に増える可能性があります。新しい一意の JSON パスが現れるたびに新たな column file が作成され、そのパス配下で型のバリアントが増えるたびに追加の column file も生成されます。これは読み取り性能の面では最適ですが、運用上の課題も生じます。具体的には、ファイルディスクリプタの枯渇、メモリ使用量の増加、多数の小さなファイルによる merges の低速化です。 これを軽減するため、ClickHouse では overflow subcolumn という概念が導入されています。異なる JSON パスの数がしきい値を超えると、それ以降のパスは compact なエンコードフォーマットを使って 1 つの共有ファイルに保存されます。このファイルもクエリ可能ですが、専用のサブカラムと同じ性能特性の恩恵は受けられません。 このしきい値は、JSON type 宣言内の max_dynamic_paths parameter で制御されます。
このパラメータは高く設定しすぎないでください - 値を大きくするとリソース消費が増え、効率が低下します。目安として、10,000 未満に抑えてください。構造の変化が非常に激しいワークロードでは、型ヒントと SKIP パラメータを使って、保存する内容を制限してください。 この新しいカラム型の実装に興味がある方には、詳しくはブログ記事”ClickHouse の新しい強力な JSON データ型”を読むことをおすすめします。
最終更新日 2026年6月10日