INSERT INTO ステートメント
テーブルにデータを挿入します。
構文
挿入するカラムのリストを (c1, c2, c3) を使用して指定できます。また、カラムの マッチャー である * や、修飾子 である APPLY、EXCEPT、REPLACE を使用することもできます。
例えば、次のテーブルを考えます:
全てのカラムにデータを挿入したいが、カラム b だけは除外したい場合、EXCEPT キーワードを使うことができます。上記の構文を参照すると、指定するカラムの数（(c1, c3)）と同じ数の値を挿入する必要があります (VALUES (v11, v13))：
この例では、2番目に挿入された行が a および c カラムに渡された値で埋められ、b カラムはデフォルト値で埋められています。DEFAULT キーワードを使用してデフォルト値を挿入することも可能です：
カラムのリストに全ての既存カラムが含まれていない場合、残りのカラムは以下の方法で埋められます：
- テーブル定義に指定された
DEFAULT表現から計算された値。 DEFAULT表現が定義されていない場合はゼロおよび空文字列。
データは、ClickHouse によってサポートされている任意の フォーマット で INSERT に渡すことができます。フォーマットはクエリ内で明示的に指定する必要があります：
例えば、次のクエリのフォーマットは基本的な INSERT ... VALUES のバージョンと同じです：
ClickHouse は、データの前にある全てのスペースと 1 行の改行を削除します。クエリを形成する際には、データがクエリ演算子の後に新しい行に置かれることを推奨します。データがスペースで始まる場合に重要です。
例：
コマンドラインクライアント または HTTP インターフェイス を使用してクエリとは別にデータを挿入することもできます。
INSERT クエリに SETTINGS を指定したい場合は、FORMAT 句の前にそれを行う必要があります。FORMAT format_name の後の全てはデータとして扱われます。例えば：
制約
テーブルに 制約 がある場合、挿入されたデータの各行に対してそれらの表現がチェックされます。どれかの制約が満たされない場合、サーバーは制約名と表現を含む例外を発生させ、クエリは停止します。
SELECT の結果を挿入
構文
カラムは SELECT 句での位置に基づいてマッピングされます。ただし、SELECT の表現内での名前と INSERT のテーブルの名前は異なる場合があります。必要に応じて型キャストが行われます。
Values 形式を除く他のデータ形式では now()、1 + 2 などの表現に値を設定することは許可されていません。Values 形式では表現の限定的な使用が許可されていますが、これは推奨されません。なぜなら、この場合非効率的なコードがその実行に使用されるからです。
データパーツを変更するための他のクエリはサポートされていません： UPDATE、DELETE、REPLACE、MERGE、UPSERT、INSERT UPDATE。
ただし、古いデータを削除するには ALTER TABLE ... DROP PARTITION を使用できます。
FORMAT 句は、SELECT 句にテーブル関数 input() が含まれている場合、クエリの最後に指定する必要があります。
非NULLデータ型のカラムに NULL の代わりにデフォルト値を挿入するためには、insert_null_as_default 設定を有効にします。
INSERT は CTE（共通テーブル式）もサポートしています。例えば、次の2つの文は等価です：
ファイルからデータを挿入
構文
上記の構文を使用して、クライアント側に保存されたファイルまたはファイルからデータを挿入します。file_name と type は文字列リテラルです。入力ファイルの フォーマット は FORMAT 句で設定する必要があります。
圧縮ファイルもサポートされています。圧縮タイプはファイル名の拡張子で検出されます。また、COMPRESSION 句で明示的に指定することもできます。サポートされているタイプは次の通りです： 'none'、'gzip'、'deflate'、'br'、'xz'、'zstd'、'lz4'、'bz2'。
この機能は コマンドラインクライアント と clickhouse-local で利用できます。
例
FROM INFILE を使用した単一ファイル
以下のクエリを コマンドラインクライアント を使用して実行します：
結果：
FROM INFILE を使用した複数ファイル（グロブ利用）
この例は前の例と非常に似ていますが、複数のファイルから FROM INFILE 'input_*.csv を使用して挿入が行われます。
テーブル関数を使用して挿入
データは テーブル関数 で参照されるテーブルに挿入できます。
構文
例
以下のクエリでは remote テーブル関数が使用されています：
結果：
ClickHouse Cloud に挿入
デフォルトでは、ClickHouse Cloud のサービスは高可用性のために複数のレプリカを提供します。サービスに接続すると、これらのレプリカのいずれかに接続が確立されます。
INSERT が成功すると、データは基盤となるストレージに書き込まれます。しかし、レプリカがこれらの更新を受け取るまでには時間がかかる場合があります。したがって、これらの他のレプリカのいずれかで SELECT クエリを実行する異なる接続を使用した場合、更新されたデータがまだ反映されないことがあります。
select_sequential_consistency を使用してレプリカが最新の更新を受け取るよう強制することができます。この設定を使用した SELECT クエリの例は次の通りです：
select_sequential_consistency を使用すると ClickHouse Keeper（ClickHouse Cloud 内部で使用）の負荷が増加し、サービスの負荷に応じてパフォーマンスが低下する可能性があることに注意してください。必要がない限り、この設定を有効にすることは推奨しません。推奨されるアプローチは、同じセッション内で read/write を実行するか、ネイティブプロトコルを使用するクライアントドライバを使用する（したがって、スティッキー接続をサポートする）ことです。
レプリケートされたセットアップに挿入
レプリケートされたセットアップでは、データはレプリケーションされた後に他のレプリカで表示されます。データは INSERT の直後にレプリケート（他のレプリカにダウンロード）されます。これは、データがすぐに共有ストレージに書き込まれ、レプリカがメタデータの変更を購読する ClickHouse Cloud とは異なります。
レプリケートされたセットアップの場合、INSERT は時にはかなりの時間がかかることがあることに注意してください（おおよそ1秒の範囲で）。このプロセスは、分散コンセンサスのために ClickHouse Keeper にコミットを行うためです。S3 をストレージに使用することも追加の遅延をもたらします。
パフォーマンスの考慮事項
INSERT は入力データを主キーでソートし、パーティションキーでパーティションに分割します。複数のパーティションに一度にデータを挿入すると、INSERT クエリのパフォーマンスが著しく低下する可能性があります。これを回避するために：
- 比較的大きなバッチ（例えば、10万行）でデータを追加します。
- ClickHouse にアップロードする前に、パーティションキーでデータをグループ化します。
次の条件ではパフォーマンスは低下しません：
- データがリアルタイムで追加されるとき。
- 通常時系列でソートされたデータをアップロードする場合。
非同期挿入
小規模だが頻繁な挿入でデータを非同期に挿入することが可能です。そのような挿入からのデータはバッチにまとめられ、安全にテーブルに挿入されます。非同期挿入を使用するには、async_insert 設定を有効にします。
async_insert や Buffer テーブルエンジン を使用すると、追加のバッファリングが発生します。
大量または長時間実行される挿入
大量のデータを挿入する場合、ClickHouse は「スクワッシング」と呼ばれるプロセスを通じて書き込み性能を最適化します。メモリ内に挿入された小さなデータブロックは、より大きなブロックに結合され、ディスクに書き込まれる前に圧縮されます。スクワッシングは、各書き込み操作に関連するオーバーヘッドを減少させます。このプロセス中、ClickHouse が max_insert_block_size 行の書き込みを完了した後、挿入されたデータはクエリ可能になります。
関連情報
