MySQL :: MySQL 5.1 リファレンスマニュアル (オンラインヘルプ)

MySQL 5.1 リファレンスマニュアル (オンラインヘルプ) :: 8 SQL ステートメント構文 :: 8.2 データ取り扱いステートメント :: 8.2.5 INSERT 構文

Section Navigation [Toggle]

8.2.5. `INSERT` 構文

8.2.5.1. INSERT ... SELECT 構文
8.2.5.2. INSERT DELAYED 構文
8.2.5.3. INSERT ... ON DUPLICATE KEY UPDATE 構文

INSERT [LOW_PRIORITY | DELAYED | HIGH_PRIORITY] [IGNORE]
    [INTO] tbl_name [(col_name,...)]
    {VALUES | VALUE} ({expr | DEFAULT},...),(...),...
    [ ON DUPLICATE KEY UPDATE
      col_name=expr
        [, col_name=expr] ... ]

または

INSERT [LOW_PRIORITY | DELAYED | HIGH_PRIORITY] [IGNORE]
    [INTO] tbl_name
    SET col_name={expr | DEFAULT}, ...
    [ ON DUPLICATE KEY UPDATE
      col_name=expr
        [, col_name=expr] ... ]

または

INSERT [LOW_PRIORITY | HIGH_PRIORITY] [IGNORE]
    [INTO] tbl_name [(col_name,...)]
    SELECT ...
    [ ON DUPLICATE KEY UPDATE
      col_name=expr
        [, col_name=expr] ... ]

INSERT は既存テーブルに新しい行を挿入します。INSERT ... VALUES と INSERT ... SET 型のステートメントは、明示的に指定された値に基づいて行を挿入します。INSERT ... SELECT 型は別のテーブルから選択された行を挿入します。INSERT ... SELECT については項8.2.5.1. 「INSERT ... SELECT 構文」でさらに詳しく説明されています。

古い行に上書きするために、INSERT の代わりに REPLACE を利用することができます。REPLACE は、古い行を複製したユニークキー値を含む新しい行の処理において INSERT IGNORE に相当するものです。新しい行は、破棄されるのではなく、古い行を置き換えるために使用されます。項8.2.7. 「REPLACE 構文」を参照してください。

tbl_name は行が挿入されるべきテーブルです。ステートメントが値を提供しなければいけないカラムは次のように指定することができます。

テーブル名の後にカンマで区切られたカラム名のリストを提供することができます。この場合、名前が付けられた各カラムの値には VALUES リストか SELECT ステートメントが与えられなければいけません。
もし INSERT ... VALUES か INSERT ... SELECT にカラム名のリストを指定しなければ、VALUES リストか SELECT ステートメントがテーブル内すべてのカラムの値を提供する必要があります。テーブル内のカラムの順序がわからない場合は、DESCRIBE tbl_name を使用して見つけます。
SET 節はカラム名を明示的に指示します。

カラム値を与える方法はいくつかあります。

厳密な SQL モードで実行していない場合、値が明示的に指定されていないカラムはすべて、デフォルトの (明示的または暗黙的な) 値に設定されます。たとえば、もしテーブル内のすべてのカラムに名前を付けないカラムのリストを指定すると、名づけられていないカラムはそのデフォルト値に設定されます。デフォルト値の割り当てについては項6.1.4. 「データ型デフォルト値」で説明しています。Constraints on Invalid Data も参照してください。

もし、デフォルト値を持たないすべてのカラムの値を明示的に指定しないかぎりエラーを発生させる INSERT ステートメントが必要であれば、厳密モードを利用する必要があります。Server SQL Modes を参照してください。
明示的にカラムをそのデフォルト値に設定するには、キーワード DEFAULT を利用してください。これはテーブル内の各カラムの値を持たない不完全な VALUES リストの書き込みを防ぐことができるので、一部を除くすべてのカラムに値を割り当てる INSERT ステートメントの書き込みを簡単にします。そうでなければ、VALUES リスト内のそれぞれの値に対応するカラム名のリストを書かなければいけません。

また、与えられたカラムのデフォルト値を生成する式の中で利用されるより一般的な形として、DEFAULT(col_name) を利用することもできます。
もしカラムリストと VALUES リストの両方が空なら、INSERT は各カラムセットを利用してそのデフォルト値に行を作成します。
```
INSERT INTO tbl_name () VALUES();
```
厳密モードでは、もしどのカラムもデフォルト値を持っていなければエラーが発生します。そうでなければ、MySQL は明示的に指定されたデフォルト値を持たないすべてのカラムに対して暗黙のデフォルト値を利用します。
カラム値を提供するために expr 式を指定することができます。もし式の型がカラムの型に合わなければ、型の変換が行われる可能性があり、そしてデータの型によっては、与えられた値の変換が別の挿入値を生み出すことがあります。たとえば、文字列 '1999.0e-2' を、INT、FLOAT、DECIMAL(10,6)、または YEAR カラムに挿入すると、それぞれ 1999、19.9921、19.992100、そして 1999 が挿入されることになります。INT と YEAR カラムに格納された値が 1999 である理由は、文字列から整数への変換時には、文字列の最初の部分の、有効な整数や年として判断される部分だけを見るからです。浮動小数点と固定小数点カラムに対しては、文字列から浮動小数点への変換時には、文字列全体を有効な浮動小数点として判断します。

expr 式は、値のリストに早いうちに設定されたすべてのカラムを参照することができます。たとえば、col2 の値は、すでに割り当てられた col1 を参照することができるので、上記のようなことが可能なのです。
```
INSERT INTO tbl_name (col1,col2) VALUES(15,col1*2);
```
しかし、col1 の値は、col1 のあとで割り当てられた col2 を参照するため、次のようなものは正当ではありません。
```
INSERT INTO tbl_name (col1,col2) VALUES(col2*2,15);
```
1 つの例外が AUTO_INCREMENT 値を持つカラムに関係しています。別の値の割り当て後に AUTO_INCREMENT 値が発生するので、その割り当ての中での AUTO_INCREMENT カラムへの参照は 0 を返すのです。

VALUES 構文を利用する INSERT ステートメントは複数行を挿入することができます。これをするためには、それぞれが括弧で囲まれカンマで区切られている、カラム値の複数リストを含んでください。例 :

INSERT INTO tbl_name (a,b,c) VALUES(1,2,3),(4,5,6),(7,8,9);

各行の値のリストは括弧で囲まれている必要があります。次のステートメントは、カラム名の数とリストの中の値の数が合わないため、不正となります。

INSERT INTO tbl_name (a,b,c) VALUES(1,2,3,4,5,6,7,8,9);

このコンテキストでは、VALUE は VALUES の同義語です。どちらも、値リストの数については何も示しておらず、値リストが 1 つの場合でも複数の場合でも使用できます。

INSERT に関して影響を受けた行の値は、ROW_COUNT() 関数 (項7.11.3. 「情報関数」を参照) または mysql_affected_rows() C API 関数 (mysql_affected_rows() を参照) を使用して取得できます。

もし INSERT ... VALUES ステートメントを複数値リストか INSERT ... SELECT と共に利用すると、そのステートメントはこのフォーマットで文字列情報を返します。

Records: 100 Duplicates: 0 Warnings: 0

Records はステートメントによって生成された行数を指示します。(Duplicates はゼロ以外にすることができるため、これは必ずしも実際に挿入された行数ではありません。) 既存の一意のインデックス値を複製するので、Duplicates は挿入できなかった行数を指示します。Warnings は、何らかの形で問題があった、カラム値挿入の試みの回数を指示します。警告は次のような条件時に発生します。

NOT NULL を宣言していたカラムに NULL を挿入する。複合行 INSERT ステートメントや INSERT INTO ... SELECT ステートメントに対しては、カラムはカラムデータ型の暗黙のデフォルト値に設定されます。数値型、文字列型の空の文字列 ('')、そして日付、時間型の「ゼロ」値に対してのこの値は 0 です。サーバーは単列を返すかどうかを確認するために SELECT からの結果セットを検査しないため、INSERT INTO ... SELECT ステートメントは複合行挿入と同じ方法で扱われます。(単列 INSERT に対しては、NULL が NOT NULL カラムに挿入されたとき、警告は発生しません。代わりに、ステートメントはエラーになり失敗します)。
数値カラムを、範囲外の値に設定する。値はその範囲の終点に一番近いところでクリップされます。
数値カラムに '10.34 a' のような値を割り当てる。末尾の数値以外のテキストは取り除かれ、残りの数値部分が挿入されます。もし文字列値がその最初の部分に数値を持たない場合は、そのカラムは 0 に設定されます。
文字列を、カラムの最大長さを上回る文字列カラムに (CHAR、VARCHAR、TEXT、または BLOB) 挿入する。値はカラムの最大長さまで切り捨てられます。
日付や時間カラムに不正である値を挿入する。カラムはその型にとって適正であるゼロの値に設定されます。

もし C API を利用していれば、mysql_info() 関数を呼び出すことで、情報文字列を得ることができます。mysql_info() を参照してください。

もし AUTO_INCREMENT カラムを持つテーブルに INSERT が行を挿入すれば、SQL LAST_INSERT_ID() 関数を利用することでそのカラムに利用される値を見つけることができます。C API の内部から、mysql_insert_id() 関数を利用してください。しかし、2 つの関数がいつでもまったく同じ働きをする訳ではないことに注意してください。AUTO_INCREMENT カラムに関しての、INSERT ステートメントの動作の更なる情報は項7.11.3. 「情報関数」と mysql_insert_id() で紹介されています。

INSERT ステートメントは次の修飾子をサポートします。

もし DELAYED キーワードを利用すると、サーバーはバッファーに挿入される行を置くので、INSERT DELAYED ステートメントを発行するクライアントは即座に再開されます。もしテーブルが使用中であれば、サーバーが行を保持します。テーブルがフリーであればサーバーは行の挿入を始め、新しいリクエストがないかを調べるために定期的にテーブルを確認します。もしあれば、遅れた行の列はテーブルが再度フリーになるまでサスペンドされます。項8.2.5.2. 「INSERT DELAYED 構文」を参照してください。

サーバーは、INSERT ... SELECT か INSERT ... ON DUPLICATE KEY UPDATE に対して DELAYED を無視します。

MySQL 5.1.19 からは、DELAYED は、テーブルまたはトリガーにアクセスする関数を使用しているか、または関数またはトリガーから呼び出される INSERT に対しても無視されます。
もし LOW_PRIORITY キーワードを利用すると、別のクライアントがテーブルからの読み込みをしなくなるまで、INSERT の実行が遅れます。これには、既存クライアントが読み込みをしている最中、そして INSERT LOW_PRIORITY ステートメントが待っている最中に読み込みを始めてしまう別のクライアントが含まれます。しかし、INSERT LOW_PRIORITY ステートメントを発行するクライアントがリードヘビー環境の中で長時間 (または永遠に) 待つことは可能です。(これは、クライアントにそのまま作業を続けさせる INSERT DELAYED とは逆の機能です。並列挿入ができなくなるので、通常 LOW_PRIORITY は MyISAM テーブルと一緒には利用されません。項4.3.3. 「同時挿入」を参照してください。

もし HIGH_PRIORITY を指定すると、サーバーが --low-priority-updates オプションでスタートされている場合その効果が無効になります。また、並行挿入も利用されなくなります。項4.3.3. 「同時挿入」を参照してください。

LOW_PRIORITY と HIGH_PRIORITY は、テーブルレベルロックのみを使用するストレージエンジン (MyISAM、MEMORY、MERGE) にのみ影響を与えます。
もし IGNORE キーワードを利用したら、INSERT ステートメントの実行中に起きたエラーは警告として扱われます。たとえば、IGNORE がないと、テーブル内に既存の UNIQUE インデックスや PRIMARY KEY 値を複製する行に重複キーエラーが起き、そのステートメントは異常終了されます。IGNORE を利用すると、行の挿入はされませんが、エラーも発行されません。

IGNORE には、指定された値に一致するパーティションが見つからない、パーティション化されたテーブルへの挿入に関して同様の効果があります。IGNORE を指定しないと、このような INSERT ステートメントはエラーで異常終了します。ただし、INSERT IGNORE が使用されている場合は、一致しない値を含む行に対する挿入操作が暗黙のうちに失敗しますが、一致した行はすべて挿入されます。(例については、LIST Partitioningを参照してください)。

もし IGNORE が指定されなければ、データ変換はステートメントに関するエラーを引き起こします。IGNORE を利用すると、不正な値は一番近い値に調節されて挿入され、警告が発生されますがステートメントは異常終了しません。いくつのテーブルが実際に挿入されたのか、mysql_info() C API 関数を利用して調べることができます。
もし ON DUPLICATE KEY UPDATE を指定し、UNIQUE インデックスか PRIMARY KEY 内で複製値を引き起こす行が挿入されると、古い行の UPDATE が実行されます。行ごとの影響を受けた行の値は、行が新しい行として挿入された場合は 1、既存の行が更新された場合は 2 です。項8.2.5.3. 「INSERT ... ON DUPLICATE KEY UPDATE 構文」を参照してください。

テーブルに挿入するには、そのテーブルに対する INSERT 権限が必要です。ON DUPLICATE KEY UPDATE 節が使用されていて、重複キーのために代わりに UPDATE が実行される場合、このステートメントには、更新されるカラムに対する UPDATE 権限が必要です。読み取られるが、変更されないカラムの場合は、SELECT 権限のみが必要です (ON DUPLICATE KEY UPDATE 節にある col_name=expr 割り当ての右側でのみ参照されるカラムの場合など)。

Top / Previous / Next / Up / Table of Contents

8.2.5. INSERT 構文

8.2.5. `INSERT` 構文