굵게 키워드 · 기울임 직접 채우는 자리 · [ ] 생략 가능 · ... 반복 가능. 구문 표기 규약을 참고하십시오.
{#insert-description}
## 설명
`INSERT`와 [`CREATE`](create.md)는 이름이 둘인 같은 절입니다. 파서가 둘에 대해 똑같은 트리를
만들므로, 같은 패턴을 받고, 같은 오류를 내고, 같은 실행 계획을 만듭니다.
- 패턴의 모든 요소가 만들어집니다. 이미 유효 범위의 변수에 바인딩된 요소만 예외입니다. 그 요소는
끝점으로 재사용되고 중복해서 만들어지지 않습니다.
- `INSERT`는 입력 행마다 한 번 실행됩니다. 앞에 절이 없으면 한 번 실행됩니다.
- 패턴이 바인딩하는 변수는 뒤따르는 절과, 같은 `INSERT` 안의 뒤쪽 패턴에서 보입니다.
- 모든 간선에는 레이블 하나와 방향이 정확히 있어야 합니다. 레이블을 암시적으로 만들도록
`enable_graph_ddl`을 켜 두지 않았다면, 레이블이 이미 존재해야 합니다.
{#insert-parameters}
## 매개변수
path_variable
: 패턴이 만든 경로 전체에 바인딩되는 이름이며, 생략할 수 있습니다. 그것을 반환하면 새 정점과
간선을 순서대로 나열한 `graphpath` 값이 나옵니다.
pattern
: [구문](../syntax.md)에 설명된 정점 패턴 또는 경로 패턴입니다. 속성 맵은 그 자리에
(`{title: 'Tenet'}`처럼) 적을 수도 있고, SQL 서브쿼리를 포함한 표현식에서 `=`로 통째로 줄 수도
있습니다.
{#insert-examples}
## 예제
모든 예제는 [예제 데이터셋](../../get_started/example-dataset.md)에서 실행됩니다.
영화 하나를 넣습니다. `INSERT`와 `CREATE`는 바꿔 쓸 수 있습니다. 탭을 바꿔 비교해 보십시오:
::::{tab-set}
:::{tab-item} GQL — INSERT
```cypher
INSERT (:movie {title: 'Tenet', year: 2020, genre: 'Action'});
```
:::
:::{tab-item} Cypher — CREATE
```cypher
CREATE (:movie {title: 'Tenet', year: 2020, genre: 'Action'});
```
:::
::::
```
UPDATE 1
```
두 형태는 실행 계획이 똑같습니다:
```cypher
EXPLAIN (COSTS OFF) INSERT (:movie {title: 'Tenet'});
```
```
QUERY PLAN
--------------
Graph Create
-> Result
(2 rows)
```
{#insert-return-what-you-created}
### 만든 것을 반환하기
`INSERT`도 다른 절과 마찬가지로 자기 변수를 바인딩하므로, 뒤따르는 `RETURN`이 그것을 보고할 수
있습니다:
```cypher
INSERT (p:person {name: 'John David Washington', born: 1984}) RETURN p.name AS person;
```
```
person
-------------------------
"John David Washington"
(1 row)
```
{#insert-attach-a-new-element-to-one-already-in-the-graph}
### 그래프에 이미 있는 것에 새 요소를 붙이기
앞선 `MATCH`가 바인딩한 변수는 새 정점이 아니라 끝점이므로, 간선만 만들어집니다:
```cypher
MATCH (p:person {name: 'Christopher Nolan'}), (m:movie {title: 'Tenet'})
INSERT (p)-[:directed]->(m)
RETURN count(*) AS edges;
```
```
edges
-------
1
(1 row)
```
{#insert-build-several-patterns-in-one-clause}
### 한 절에서 여러 패턴 만들기
패턴은 쉼표로 구분하며, 앞선 패턴이 바인딩한 변수를 가리킬 수 있습니다:
```cypher
MATCH (m:movie {title: 'Tenet'})
INSERT (a:person {name: 'Robert Pattinson', born: 1986}),
(b:person {name: 'Elizabeth Debicki', born: 1990}),
(a)-[:acted_in {role: 'Neil'}]->(m),
(b)-[:acted_in {role: 'Kat'}]->(m);
```
```
UPDATE 4
```
이 태그는 한 절이 만든 요소 네 개를 셉니다:
```cypher
MATCH (p:person)-[r:acted_in]->(:movie {title: 'Tenet'})
RETURN p.name AS actor, r.role AS role ORDER BY actor;
```
```
actor | role
---------------------+--------
"Elizabeth Debicki" | "Kat"
"Robert Pattinson" | "Neil"
(2 rows)
```
{#insert-take-a-property-map-from-a-sql-query}
### SQL 쿼리에서 속성 맵 가져오기
`= expression` 형태는 맵 전체를 한 번에 줍니다. 테이블에서 속성을 적재할 때 쓰십시오:
```cypher
INSERT (:movie = (SELECT jsonb_build_object('title', 'Dunkirk', 'year', 2017)));
```
```
UPDATE 1
```
```cypher
MATCH (m:movie {title: 'Dunkirk'}) RETURN m.year AS year;
```
```
year
------
2017
(1 row)
```
{#insert-notes}
## 참고
이 절은 `CREATE` 태그가 아니라 평범한 그래프 쓰기 명령 태그인 `UPDATE n`을 보고합니다. 쓰기는
하고 투영은 하지 않으려면 [`FINISH`](finish.md)와 함께 쓰십시오.
`INSERT`라고 썼어도 거부 메시지는 `CREATE`를 이름으로 부릅니다. 두 표기가 같은 절을 만들기
때문입니다. 알아 둘 만한 것들입니다:
| 패턴 | 오류 |
| --- | --- |
| `INSERT ()-[]->()` | `only one relationship type is allowed for CREATE` |
| `INSERT ()-[:acted_in\|directed]->()` | `only one relationship type is allowed for CREATE` |
| `INSERT ()-[:directed]-()` | `only directed relationships are allowed in CREATE` |
| `INSERT (:ag_vertex)` | `specifying default label is not allowed` |
| `INSERT ()-[:ag_edge]->()` | `cannot create edge on default label` |
| `INSERT (:directed)` | `label "directed" is edge label` |
| `INSERT ()-[:movie]->()` | `label "movie" is vertex label` |
| `m`이 이미 바인딩된 상태의 `INSERT (m)` | `there must be at least one relationship` |
```{note}
`insert`는 2.18에서 예약 키워드가 됐습니다. 문법이 모호해지지 않는 자리에서는 따옴표 없이도
여전히 받아들여집니다. 변수 이름(`MATCH (insert:person)`)과 패턴 안의 레이블
이름(`MATCH (n:insert)`)이 그렇습니다. `CREATE VLABEL` 이름, `RETURN` 별칭을 가리키는 `ORDER BY`
키, SQL 테이블·컬럼 이름으로는 받아들여지지 않습니다. 그 자리에는 `"insert"`로 쓰거나 이름을
바꾸십시오.
```
{#insert-compatibility}
## 호환성
```{admonition} GQL 적합성
:class: gql-conformance
§16.5의 *insert graph pattern*에 대한 GQL *INSERT 문장*(ISO/IEC 39075:2024 §13.2)을
구현합니다.
- **지원** — 정점과 간선 삽입, 문장 하나에 여러 패턴, 바인딩된 요소를 끝점으로 재사용하는 것,
인라인 속성 맵, 그리고 삽입한 패턴 전체에 대한 경로 변수.
- **미지원** — 그래프 타입을 요구하는 표준의 타입 그래프 검사(§18). AgensGraph의 그래프에는
타입이 없으므로, 삽입은 선언된 정점·간선 타입이 아니라 실제로 있는 레이블에 견주어
검증됩니다.
진행 상황은 [GQL 적합성 표](../../appendix/gql-conformance.md)에서 확인하십시오.
```
{#insert-opencypher}
### openCypher
openCypher는 이 절을 `CREATE`로 표기하며, AgensGraph는 그것을 같은 뜻으로 받습니다. `INSERT`라는
이름은 GQL과 SQL에서 왔고, SQL에서는 테이블에 대해 같은 일을 합니다.
{#insert-see-also}
## 관련 항목
- [`CREATE`](create.md) — Cypher 쪽 같은 뜻의 표기, 같은 절
- [`MERGE`](merge.md) — 이미 있지 않은 것만 만들기
- [`FOR`](for.md) {bdg-secondary-line}`GQL` — 리스트 요소마다 `INSERT`를 한 번씩 돌리기
- [`FINISH`](finish.md) {bdg-secondary-line}`GQL` — 투영 없이 쓰기
- [구문](../syntax.md) — `INSERT`가 받는 패턴 문법
- [GQL 적합성 표](../../appendix/gql-conformance.md)