# CREATE
Adds vertices and edges to the graph, one for every element of its pattern.
## Synopsis
CREATE pattern [, pattern ] ...
bold keywords · italic placeholders you supply · [ ] optional · ... repeatable. See Syntax conventions.
## Description
`CREATE` writes the pattern you give it into the graph. It takes the same pattern
syntax [`MATCH`](match.md) reads with, but every element is built rather than
looked for.
- `CREATE` **always creates**. It does not check whether an identical vertex or
edge is already there. To create only what is missing, use
[`MERGE`](merge.md).
- An element that names a **variable already in scope** is reused, not rebuilt.
That is how an edge is attached to vertices a `MATCH` found: the endpoints are
bound variables, so only the edge is new.
- An element that names a **new variable, or none**, is created. A pattern can
therefore create a vertex and its edge in one step.
- Every element needs enough information to be built. An edge needs a label and a
direction; a vertex without a label becomes a bare `ag_vertex`.
- A property map may be a **map literal**, a query parameter, or `= expression`
where the expression yields a jsonb object. That last form is how a whole table
row becomes a property bag. See [`LOAD FROM`](load-from.md).
- `CREATE` runs once per incoming row. With no clause in front of it, it runs
once.
- `CREATE` may lead a query or follow another clause, and it may end one. Add a
[`RETURN`](return.md) to see what it built.
[`INSERT`](insert.md) is an exact synonym, the spelling ISO/IEC 39075 uses.
## Parameters
pattern
: A path pattern in [`MATCH`](match.md) syntax. Several may be listed, separated
by commas; they are created in order and may share variables.
## Examples
Every example runs against [the example dataset](../../get_started/example-dataset.md).
The last example undoes them.
### Create one vertex
```cypher
CREATE (:movie {title: 'Tenet', year: 2020, genre: 'Action'});
```
```
UPDATE 1
```
A graph write reports the number of graph elements it touched under the `UPDATE`
tag, whatever the clause was.
### Create a vertex and see what you made
```cypher
CREATE (p:person {name: 'John David Washington', born: 1984})
RETURN p.name AS person, p.born AS born;
```
```
person | born
-------------------------+------
"John David Washington" | 1984
(1 row)
```
### Create an edge between two existing vertices
Find both endpoints, then create only the edge:
```cypher
MATCH (d:person {name: 'Christopher Nolan'}), (m:movie {title: 'Tenet'})
CREATE (d)-[r:directed]->(m)
RETURN d.name AS director, label(r) AS edge, m.title AS film;
```
```
director | edge | film
---------------------+------------+---------
"Christopher Nolan" | "directed" | "Tenet"
(1 row)
```
`d` and `m` are already bound, so they are reused. Had the pattern written
`(d:person {name: 'Christopher Nolan'})` again inside the `CREATE`, a second
Christopher Nolan would have been created.
### Create a vertex and its edge together
Anything in the pattern that is not already bound is built:
```cypher
MATCH (m:movie {title: 'Tenet'})
CREATE (a:person {name: 'Elizabeth Debicki', born: 1990})-[r:acted_in {role: 'Kat'}]->(m)
RETURN a.name AS actor, r.role AS role, m.title AS film;
```
```
actor | role | film
---------------------+-------+---------
"Elizabeth Debicki" | "Kat" | "Tenet"
(1 row)
```
### Create several patterns at once
Comma-separated patterns are built in one clause and can share variables:
```cypher
MATCH (p:person {name: 'John David Washington'}), (m:movie {title: 'Tenet'})
CREATE (p)-[:acted_in {role: 'The Protagonist'}]->(m),
(m)-[:related_to {weight: 2}]->(:movie {title: 'Memento', year: 2000, genre: 'Thriller'});
```
```
UPDATE 3
```
Three elements: one `acted_in` edge, one `related_to` edge, and the `Memento`
vertex. `Tenet` now has four edges:
```cypher
MATCH (m:movie {title: 'Tenet'})-[r]-(x)
RETURN label(r) AS edge, label(x) AS other, coalesce(x.name, x.title) AS name
ORDER BY edge, name;
```
```
edge | other | name
--------------+----------+-------------------------
"acted_in" | "person" | "Elizabeth Debicki"
"acted_in" | "person" | "John David Washington"
"directed" | "person" | "Christopher Nolan"
"related_to" | "movie" | "Memento"
(4 rows)
```
### Watch CREATE duplicate
Nothing about `CREATE` is idempotent:
```cypher
CREATE (:person {name: 'Duplicate', born: 1}), (:person {name: 'Duplicate', born: 1});
```
```
UPDATE 2
```
```cypher
MATCH (p:person {name: 'Duplicate'}) RETURN count(*) AS rows;
```
```
rows
------
2
(1 row)
```
Running the first statement again would make four. Use [`MERGE`](merge.md), or a
unique constraint, when a key has to stay unique.
### Undo the examples
```cypher
MATCH (p:person {name: 'Duplicate'}) DELETE p;
MATCH (m:movie) WHERE m.title IN ['Tenet', 'Memento'] DETACH DELETE m;
MATCH (p:person) WHERE p.name IN ['John David Washington', 'Elizabeth Debicki'] DETACH DELETE p;
```
```
UPDATE 2
UPDATE 6
UPDATE 2
```
## Notes
A vertex's id is assigned from the label's own sequence, so the number a new
vertex gets depends on what has been created in that label before. Read it with
`id(v)`; do not depend on a particular value.
```{note}
A `CREATE` with no label — `CREATE ()` — is legal and produces a vertex of the
graph's base label `ag_vertex`. Such a vertex is invisible to every
`MATCH (n:label)` and easy to lose track of. Always give a label.
```
## Compatibility
### The clause name (ISO/IEC 39075 §13.2)
The standard's data-inserting statement is `INSERT`, not `CREATE`. AgensGraph
accepts both spellings for the same clause; see [`INSERT`](insert.md). SQL's
`CREATE` statements, such as `CREATE GRAPH` and `CREATE VLABEL`, are separate
statements and are unaffected.
## See also
- [`INSERT`](insert.md) {bdg-primary-line}`GQL` — the standard spelling of this clause
- [`MERGE`](merge.md) — create only what is not already there
- [`MATCH`](match.md) — the pattern syntax, and how to bind endpoints first
- [`SET`](set.md) — change properties after creating
- [`DELETE`](delete.md) — remove what you created
- [`LOAD FROM`](load-from.md) — create from the rows of a table