설명

INSERT 테이블에 새 행을 삽입한다. value 표현식에 지정된 하나 이상의 행을 삽입하거나, 쿼리 결과로부터 0개 이상의 행을 삽입할 수 있다.

대상 칼럼명은 임의의 순서대로 나열할 수 있다. 칼럼명을 지정하지 않는다면, 기본적으로 테이블의 모든 칼럼을 선언된 순서대로, 또는 VALUES 절이나 query에서 제공되는 칼럼이 N개 뿐이라면, 앞에서 부터 N개의 칼럼명을 사용한다. VALUES절이나 query에서 제공되는 값은 왼쪽부터 오른쪽의 순서대로 명시적 또는 암시적 칼럼 목록과 연결된다.

명시적 또는 암시적 칼럼 목록에 존재하지 않는 칼럼은, 그 기본값이 선언된 경우 기본값으로, 아니면 null로 채워진다.

어떠한 칼럼의 표현식이든 올바른 자료형이 아닐 경우, 자동 형변환을 시도한다.

ON CONFLICT는 unique 제약이나 exclusion 제약 위배 오류를 해소하기 위한, 대체 액션을 지정하기 위해 사용된다. (아래 ON CONFLICT Clause 참고)

선택적인 RETURNING 절은 causes INSERT로 하여금, 실제 삽입된 (또는, ON CONFLICT DO UPDATE 절이 사용된 경우, 업데이트 된) 각 행을 기반으로하는 값을 계산하고 반환하게 만든다. 이는 주로, 일련 번호와 같이 기본값으로 제공되는 값들을 알고 싶을 때 유용하다. 게다가, 테이블의 칼럼을 이용한 어떠한 표현식이든 가능하다. RETURNING 목록의 문법은 SELECT의 출력 목록과 동일하다. 성공적으로 삽입되거나 업데이트 된 행만 반환된다. 예를 들어, ON CONFLICT DO UPDATE ... WHERE절의 condition을 충족시키지 못해서 행이 잠겨졌지만 업데이트가 되지 않았을 경우, 해당 행은 반환되지 않는다.

테이블에 삽입하려면 해당 테이블에 대한 INSERT 권한이 있어야 한다. 또한, ON CONFLICT DO UPDATE가 존재한다면 UPDATE 권한도 있어야 한다.

칼럼 목록이 지정된 경우, 나열된 칼럼에 대한 INSERT 권한만 있으면 된다. 이와 유사하게, ON CONFLICT DO UPDATE가 지정된 경우, 업데이트 될 칼럼에 대한 UPDATE 권한만 있으면 된다. 다만, ON CONFLICT DO UPDATE의 경우, ON CONFLICT DO UPDATE 표현식이나 condition에서 값을 읽어야 하는 칼럼에 대한 SELECT 권한 또한 필요하다.

RETURNING 절을 사용하려면 RETURNING에 언급된 모든 칼럼에 대한 SELECT 권한이 필요하다. 물론, 쿼리로부터 행을 삽입하기 위해 query 절을 사용하는 경우라면, 쿼리 내에서 사용되는 모든 테이블과 칼럼에 대한 SELECT 권한이 필요하다.

매개 변수

Outputs

성공적으로 완료되면, INSERT 명령은 아래 형식의 명령 태그를 반환한다.

INSERT oid count

The count is the number of rows inserted or updated. oid is always 0 (it used to be the OID assigned to the inserted row if count was exactly one and the target table was declared WITH OIDS and 0 otherwise, but creating a table WITH OIDS is not supported anymore).

INSERT 명령에 RETURNING 절이 포함되어 있다면, 그 결과는, 해당 명령에서 삽입되거나 업데이트 되는 행에 대해 계산된 값이며, RETURNING 목록에 정의된 칼럼 및 값을 포함하는SELECT문의 결과와 유사하다.

Notes

If the specified table is a partitioned table, each row is routed to the appropriate partition and inserted into it. If the specified table is a partition, an error will occur if one of the input rows violates the partition constraint.

예제

films 테이블에 단일 행을 삽입한다:

INSERT INTO films VALUES
    ('UA502', 'Bananas', 105, '1971-07-13', 'Comedy', '82 minutes');

이 예제에서, len 칼럼은 생략되었고, 따라서 기본 값을 갖게 된다:

INSERT INTO films (code, title, did, date_prod, kind)
    VALUES ('T_601', 'Yojimbo', 106, '1961-06-16', 'Drama');

이 예제는 데이터 칼럼에 값을 지정하지 않고 DEFAULT 절을 사용한다:

INSERT INTO films VALUES
    ('UA502', 'Bananas', 105, DEFAULT, 'Comedy', '82 minutes');
INSERT INTO films (code, title, did, date_prod, kind)
    VALUES ('T_601', 'Yojimbo', 106, DEFAULT, 'Drama');

기본 값만으로 구성된 행을 삽입한다:

INSERT INTO films DEFAULT VALUES;

다행 VALUES 문법을 사용하여 다수의 행을 삽입한다:

INSERT INTO films (code, title, did, date_prod, kind) VALUES
    ('B6717', 'Tampopo', 110, '1985-02-10', 'Comedy'),
    ('HG120', 'The Dinner Game', 140, DEFAULT, 'Comedy');

이 예제는, films과 동일한 칼럼 레이아웃을 갖는 tmp_films 테이블로부터 films 테이블로 몇몇 행을 삽입한다:

INSERT INTO films SELECT * FROM tmp_films WHERE date_prod < '2004-05-07';

이 예제는 배열 칼럼에 삽입한다:

-- Create an empty 3x3 gameboard for noughts-and-crosses
INSERT INTO tictactoe (game, board[1:3][1:3])
    VALUES (1, '{{" "," "," "},{" "," "," "},{" "," "," "}}');
-- The subscripts in the above example aren't really needed
INSERT INTO tictactoe (game, board)
    VALUES (2, '{{X," "," "},{" ",O," "},{" ",X," "}}');

단일 행을 distributors 테이블에 삽입하고, DEFAULT 절에 의해 생성된 일련번호를 반환한다:

INSERT INTO distributors (did, dname) VALUES (DEFAULT, 'XYZ Widgets')
   RETURNING did;

Acme Corporation의 계정을 관리하는 salesperson의 sales count를 증가시키고, 로그 테이블에, 업데이트된 행 전체와 현재 시각을 기록한다:

WITH upd AS (
  UPDATE employees SET sales_count = sales_count + 1 WHERE id =
    (SELECT sales_person FROM accounts WHERE name = 'Acme Corporation')
    RETURNING *
)
INSERT INTO employees_log SELECT *, current_timestamp FROM upd;

새distributors를 적절하게 삽입 또는 업데이트 한다. did 칼럼에 나타나는 값을 제약하는 unique 인덱스가 정의되었다고 가정한다. 삽입에 사용되는 값을 참조하기 위해 특별한 excluded 테이블이 사용되었음에 주의하라:

INSERT INTO distributors (did, dname)
    VALUES (5, 'Gizmo Transglobal'), (6, 'Associated Computing, Inc')
    ON CONFLICT (did) DO UPDATE SET dname = EXCLUDED.dname;

distributor를 삽입하거나, excluded 행 (행 삽입 트리거가 발생한 전후로 제약 칼럼(들)이 일치하는 행)이 이미 존재할 경우 삽입할 행에 대해 아무 작업도 하지 않는다. 예제에서는 did 칼럼에 나타나는 값을 제약하는 unique 인덱스가 정의되어있다고 가정한다:

INSERT INTO distributors (did, dname) VALUES (7, 'Redline GmbH')
    ON CONFLICT (did) DO NOTHING;

신규 distributors를 적절하게 삽입 또는 업데이트 한다. 예제에서는, did 칼럼에 나타나는 값을 제약하는 unique 인덱스가 정의되어있다고 가정한다. 실제 업데이트 되는 행을 제한하기 위해 WHERE 절이 사용되었다. (그렇더라도, 업데이트 되지 않은 기존의 행은 여전히 잠겨있을 것이다):

-- 특정 ZIP code에 기반해서 기존 distributor는 업데이트 하지 않는다.
INSERT INTO distributors AS d (did, dname) VALUES (8, 'Anvil Distribution')
    ON CONFLICT (did) DO UPDATE
    SET dname = EXCLUDED.dname || ' (formerly ' || d.dname || ')'
    WHERE d.zipcode <> '21201';

-- 문장 내에서 제약조건을 직접 명명한다. (DO NOTHING 액션을 사용하기 위해
-- 관련된 인덱스를 사용한다)
INSERT INTO distributors (did, dname) VALUES (9, 'Antwerp Design')
    ON CONFLICT ON CONSTRAINT distributors_pkey DO NOTHING;

가능하다면 신규 distributor를 삽입한다. 그렇지 않은 경우 DO NOTHING. 예제에서는, is_active Boolean 칼럼이 true인 행의 부분집합에 대해 did 칼럼에 나타나는 값을 제약하는 unique 인덱스가 정의되었다고 가정한다:

-- 이 문장은 "WHERE is_active"의 서술부로
-- "did"에 대한 partial unique 인덱스를 infer 할 수 있지만,
-- 또한 "did" 제약에 일반적인 unique 제약을 사용할 수도 있다
INSERT INTO distributors (did, dname) VALUES (10, 'Conrad International')
    ON CONFLICT (did) WHERE is_active DO NOTHING;

Compatibility

INSERT는 RETURNING 절이 PostgreSQL 확장이며, INSERT에 WITH를 사용할 수 있고, ON CONFLICT에 대체 액션을 지정할 수 있다는 점을 제외하면, SQL 표준을 따른다. 또한, 칼럼 명 목록이 생략될 경우 모든 칼럼이 VALUES 절이나 query로 채워지진 않는다는 점은, 표준에서 허용되지 않는 점이다.

The SQL standard specifies that OVERRIDING SYSTEM VALUE can only be specified if an identity column that is generated always exists. PostgreSQL allows the clause in any case and ignores it if it is not applicable.

query의 제약사항은 SELECT에 문서화 되어 있다.