# create

By enabling more precise and flexible creation of nodes and relationships within
the graph structure, the `create` module enhances the ability of developers to
model, manipulate, and query complex graph data.

| Trait               | Value               |
| ------------------- | ------------------- |
| **Module type**     | util                |
| **Implementation**  | C++                 |
| **Graph direction** | directed/undirected |
| **Edge weights**    | weighted/unweighted |
| **Parallelism**     | sequential          |

## Procedures

> **Info**
>
> You can execute this algorithm on [graph projections, subgraphs or portions of the graph](https://memgraph.com/docs/advanced-algorithms/run-algorithms#run-procedures-on-subgraph).

### `node()`

Provides a more flexible way of creating nodes than Cypher’s `CREATE` clause by
allowing labels and properties to be extracted as results of other procedures
and sent as a list or map.

> **Info**
>
> This procedure is equivalent to **apoc.create.node**.

#### Input:

- `subgraph: Graph` (**OPTIONAL**) ➡ A specific subgraph, which is an [object of type Graph](https://memgraph.com/docs/advanced-algorithms/run-algorithms#run-procedures-on-subgraph) returned by the `project()` function, on which the algorithm is run. 
If subgraph is not specified, the algorithm is computed on the entire graph by default.

- `label: List[string]` ➡ A list of all the labels to be added to the new node.
- `props: Map` ➡ A map with key/value pairs to be added as new node's properties.

#### Output:

- `node: Node` ➡ The new node which is added to the graph.

#### Usage:

To add labels `Person` and `Programmer` to a new node, use the following query:

```cypher
CALL create.node(["Person", "Programmer"], {name: "Ana", age: 20})
YIELD node
RETURN node;
```

```plaintext
+----------------------------+
| node                       |
+----------------------------+
| {                          |
|     "id": 1,               |
|     "labels": [            |
|        "Person",           |
|        "Programmer"        |
|     ],                     |
|     "properties": {        |
|       name: "Ana",         |
|       age: 20              |
|     },                     |
|     "type": "node"         |
| }                          |
+----------------------------+
```

### `nodes()`

Create nodes with given labels and properties. For each property map, a separate node is created.

> **Info**
>
> This procedure is equivalent to **apoc.create.nodes**.

#### Input:

- `subgraph: Graph` (**OPTIONAL**) ➡ A specific subgraph, which is an [object of type Graph](https://memgraph.com/docs/advanced-algorithms/run-algorithms#run-procedures-on-subgraph) returned by the `project()` function, on which the algorithm is run. 
If subgraph is not specified, the algorithm is computed on the entire graph by default.

- `label: List[string]` ➡ A list with labels of the new nodes.
- `props: List[Map]` ➡ A list of property maps for new nodes, for each map, a separate node is created.

#### Output:

- `node: Node` ➡ Created node(s).

#### Usage:

Use the following query to create two nodes with the defined labels and properties:

```cypher
CALL create.nodes(["Human", "Soldier"], [{branch: "Marines", MOS: "Gunner"}, {branch: "Army", MOS: "Paratrooper"}]) 
YIELD node 
RETURN node;
```

```plaintext
+----------------------------+
| node                       |
+----------------------------+
| {                          |
|     "id": 0,               |
|     "labels": [            |
|        "Human",            |
|        "Soldier"           |
|     ],                     |
|     "properties": {        |
|       MOS: "Gunner",       |
|       branch: "Marines"    |
|     },                     |
|     "type": "node"         |
| }                          |
+----------------------------+
| {                          |
|     "id": 1,               |
|     "labels": [            |
|        "Human",            |
|        "Soldier"           |
|     ],                     |
|     "properties": {        |
|       MOS: "Paratrooper",  |
|       branch: "Army"       |
|     },                     |
|     "type": "node"         |
| }                          |
+----------------------------+
```

### `set_property()`

Sets the property of the input node(s), based on the provided key-value pair. If
the property doesn't exist, creates a new one. Input node(s) can be a single
node, node ID, or a list of nodes and node IDs. Otherwise, an exception is
thrown.

#### Input:

- `subgraph: Graph` (**OPTIONAL**) ➡ A specific subgraph, which is an [object of type Graph](https://memgraph.com/docs/advanced-algorithms/run-algorithms#run-procedures-on-subgraph) returned by the `project()` function, on which the algorithm is run. 
If subgraph is not specified, the algorithm is computed on the entire graph by default.

- `nodes: any` ➡ Input node(s) - can be a node, node's ID, or a list of nodes and IDs.
- `key: string` ➡ The name of the property which is about to be set.
- `value: any` ➡ The new value of the property.

#### Output:

- `node: Node` ➡ Node(s) with modified property.

#### Usage:

Use the following query to add properties to nodes:

```cypher
CREATE (d:Dog),(h:Human);
MATCH (d:Dog), (h:Human)
CALL create.set_property([d,id(h)],"property", 50) 
YIELD node 
RETURN node;
```

```plaintext
+----------------------------+
| node                       |
+----------------------------+
| {                          |
|     "id": 0,               |
|     "labels": [            |
|        "Dog"               |
|     ],                     |
|     "properties": {        |
|       property: 50         |
|     },                     |
|     "type": "node"         |
| }                          |
+----------------------------+
| {                          |
|     "id": 1,               |
|     "labels": [            |
|        "Human"             |
|     ],                     |
|     "properties": {        |
|       property: 50         |
|     },                     |
|     "type": "node"         |
| }                          |
+----------------------------+
```

### `set_properties()`

Adds the provided properties to the node(s).

#### Input:

- `subgraph: Graph` (**OPTIONAL**) ➡ A specific subgraph, which is an [object of type Graph](https://memgraph.com/docs/advanced-algorithms/run-algorithms#run-procedures-on-subgraph) returned by the `project()` function, on which the algorithm is run. 
If subgraph is not specified, the algorithm is computed on the entire graph by default.

- `input_nodes: Any` ➡ Input node(s) - can be a node, node's ID, or a list of nodes and IDs.
- `input_keys: List[string]` ➡ A list of all the property keys to be added to the node(s).
- `input_values: List[Any]` ➡ A list of all the corresponding property values to be added to the node(s).

#### Output:

- `node: Node` ➡ Node(s) with new properties.

#### Usage:

Use the following query to add the properties `age` and `grade` to the nodes:

```cypher
CREATE (:Student {name: "Ana"});
CREATE (:Student {name: "Maria"});
MATCH (s:Student) CALL create.set_properties(s, ["age", "grade"], [20, "1st"])
YIELD node
RETURN node;
```

```plaintext
+----------------------------+
| node                       |
+----------------------------+
| {                          |
|     "id": 1,               |
|     "labels": [            |
|        "Student"           |
|     ],                     |
|     "properties": {        |
|       name: "Ana",         |
|       age: 20,             |
|       grade: "1st"         |
|     },                     |
|     "type": "node"         |
| }                          |
+----------------------------+
| {                          |
|     "id": 2,               |
|     "labels": [            |
|        "Student"           |
|     ],                     |
|     "properties": {        |
|       name: "Maria",       |
|       age: 20,             |
|       grade: "1st"         |
|     },                     |
|     "type": "node"         |
| }                          |
+----------------------------+
```

### `remove_properties()`

Removes the properties from the given node(s). Input node(s) can be a single
node, node ID, or a list of nodes and node IDs. Otherwise, an exception is
thrown.

> **Info**
>
> This procedure is equivalent to **apoc.create.removeProperties**.

#### Input:

- `subgraph: Graph` (**OPTIONAL**) ➡ A specific subgraph, which is an [object of type Graph](https://memgraph.com/docs/advanced-algorithms/run-algorithms#run-procedures-on-subgraph) returned by the `project()` function, on which the algorithm is run. 
If subgraph is not specified, the algorithm is computed on the entire graph by default.

- `nodes: any` ➡ Input node(s) - can be a node, node's ID, or a list of nodes and IDs.
- `keys: List[string]` ➡ A list of properties which are to be removed.

#### Output:

- `node: Node` ➡ Node(s) with removed properties.

#### Usage:

Use the following query to remove the the `property` and `property2` properties
from nodes:

```cypher
CREATE (d:Dog {property: 30, property2: 50}),(h:Human {property: 80});
MATCH (d:Dog), (h:Human)
CALL create.remove_properties([d,id(h)],["property", "property2"])
YIELD node
RETURN node;
```

```plaintext
+----------------------------+
| node                       |
+----------------------------+
| {                          |
|     "id": 0,               |
|     "labels": [            |
|        "Dog"               |
|     ],                     |
|     "properties": {},      |
|     "type": "node"         |
| }                          |
+----------------------------+
| {                          |
|     "id": 1,               |
|     "labels": [            |
|        "Human"             |
|     ],                     |
|     "properties": {},      |
|     "type": "node"         |
| }                          |
+----------------------------+
```

### `set_rel_property()`

Adds the provided property to the relationship(s).

#### Input:

- `subgraph: Graph` (**OPTIONAL**) ➡ A specific subgraph, which is an [object of type Graph](https://memgraph.com/docs/advanced-algorithms/run-algorithms#run-procedures-on-subgraph) returned by the `project()` function, on which the algorithm is run. 
If subgraph is not specified, the algorithm is computed on the entire graph by default.

- `input_rel: Any` ➡ Input relationship(s) - can be a relationship, elationship's ID, or a list of relationships and IDs.
- `input_key: string` ➡ Property key that needs to be added to the relationship(s).
- `input_value: Any` ➡ The corresponding property value that needs to be added to the relationship(s).

#### Output:

- `relationship: Relationship` ➡ Relationship(s) with a new property.

#### Usage:

Use the following query to set the `since` property on a relationship:

```cypher
MERGE (s1:Student) MERGE (s2:Student)
CREATE (s1)-[k:KNOWS]->(s2);
MATCH (:Student)-[k:KNOWS]->(:Student)
CALL create.set_rel_property(k, "since", 2020) 
YIELD relationship
RETURN relationship;
```

```plaintext
+----------------------------+
| relationship               |
+----------------------------+
| {                          |
|     "id": 1,               |
|     "start": 1,            |
|     "end": 2,              |
|     "label": "KNOWS",      |
|     "properties": {        |
|       since: 2020          |
|     },                     |
|     "type": "relationship" |
| }                          |
+----------------------------+
```

### `remove_labels()`

Removes the provided labels from the node(s).

> **Info**
>
> This procedure is equivalent to **apoc.create.removeLabels**.

#### Input:

- `subgraph: Graph` (**OPTIONAL**) ➡ A specific subgraph, which is an [object of type Graph](https://memgraph.com/docs/advanced-algorithms/run-algorithms#run-procedures-on-subgraph) returned by the `project()` function, on which the algorithm is run. 
If subgraph is not specified, the algorithm is computed on the entire graph by default.

- `nodes: Any` ➡ Input node(s) - can be a node, node's ID or a list of nodes and nodes' IDs.
- `label: List[string]` ➡ A list of labels to be removed (if exist) from the nodes(s).

#### Output:

- `node: Node` ➡ Node(s) without provided labels.

#### Usage:

Use the following query to remove the `Student` and `Engineer` labels from
nodes:  

```cypher
CREATE (:Person:Student:Programmer {name: "Ana"});
MATCH (p:Person) CALL create.remove_labels(p, ["Student", "Engineer"])
YIELD node
RETURN node;
```

```plaintext
+----------------------------+
| node                       |
+----------------------------+
| {                          |
|     "id": 1,               |
|     "labels": [            |
|        "Person",           |
|        "Programmer",       |
|     ],                     |
|     "properties": {        |
|       name: "Ana"          |
|     },                     |
|     "type": "node"         |
| }                          |
+----------------------------+
```

### `relationship()`

Creates a new relationship with the given type and properties directed from ->
to.

#### Input:

- `subgraph: Graph` (**OPTIONAL**) ➡ A specific subgraph, which is an [object of type Graph](https://memgraph.com/docs/advanced-algorithms/run-algorithms#run-procedures-on-subgraph) returned by the `project()` function, on which the algorithm is run. 
If subgraph is not specified, the algorithm is computed on the entire graph by default.

- `from: Node` ➡ The tail node.
- `relationshipType: string` ➡ The relationship type.
- `properties: Map` ➡ Properties of the new relationship(s).
- `to: Node` ➡ The head node.

#### Output:

- `relationship: Relationship` ➡ The new relationship(s).

#### Usage:

Use the following queries to create a new relationship between two nodes: 

```cypher
CREATE (p:Person {name: "Cillian Murphy"});
CREATE (m:Movie {title:"Oppenheimer"});

MATCH (p:Person {name: "Cillian Murphy"})
MATCH (m:Movie {title: "Oppenheimer"})
CALL create.relationship(p, "ACTED_IN", {roles:['Oppenheimer']}, m)
YIELD relationship
RETURN relationship;
```

```plaintext
+-----------------------------+
| relationship                |
+-----------------------------+
| {                           |
|     "id": 0,                |
|     "start": 0              |
|     "end": 0                |
|     "label": "Acted_in"     |
|     "properties": {         |
|       roles: ["Oppenhimer"] |
|     },                      |
|     "type": "relationship"  |
| }                           |
+-----------------------------+
```

### `set_rel_properties()`

Adds the provided properties to the given relationships and returns the modified
relationships. If the property already exists it is modified.

#### Input:

- `subgraph: Graph` (**OPTIONAL**) ➡ A specific subgraph, which is an [object of type Graph](https://memgraph.com/docs/advanced-algorithms/run-algorithms#run-procedures-on-subgraph) returned by the `project()` function, on which the algorithm is run. 
If subgraph is not specified, the algorithm is computed on the entire graph by default.

- `relationships: int|Relationship|List[int|Relationship]` ➡ Relationships that need to be modified are indicated using their object or ID.
- `keys: List[string]` ➡ A list of all the property keys that need to be added to the relationship(s).
- `values: List[Any]` ➡ A list of all the corresponding property values that need to be added to the relationship(s).

#### Output:

- `relationship: Relationship` ➡ the modified relationship(s).

#### Usage:

Use the following query to add the `really` and `until` properties to a
relationship:

```cypher
CREATE (idora:Person {name: "Idora"})
CREATE (ivan:Person {name: "Ivan"})
CREATE (ivan)-[:Friend {since:"long ago"}]->(idora);

MATCH (:Person)-[friends:Friend]->(:Person) 
CALL create.set_rel_properties(friends, ["really", "until"], [true, "forever"])
YIELD relationship
RETURN relationship;
```

```plaintext
+----------------------------+
| relationship               |
+----------------------------+
| {                          |
|     "id": 0,               |
|     "start": 1,            |
|     "end": 0,              |
|     "label": "Friend",     |
|     "properties": {        |
|       "really": true,      |
|       "since": "long ago", |
|       "until": "forever"  |
|     },                     |
|     "type": "relationship" |
| }                          |
+----------------------------+
```

### `remove_rel_properties()`

Removes the provided properties from a given relationships and returns the
modified relationships. If a property doesn't exist in the given relationship
nothing happens.

#### Input:

- `subgraph: Graph` (**OPTIONAL**) ➡ A specific subgraph, which is an [object of type Graph](https://memgraph.com/docs/advanced-algorithms/run-algorithms#run-procedures-on-subgraph) returned by the `project()` function, on which the algorithm is run. 
If subgraph is not specified, the algorithm is computed on the entire graph by default.

- `relationships: int|Relationship|List[int|Relationship]` ➡ Relationships that need to be modified.
- `keys: List[string]` ➡ A list of property names that need to be removed from the given relationships.

#### Output:

- `relationship: Relationship` ➡ The modified relationship(s).

#### Usage:

Use the following query to remove property `until` from a relationship:

```cypher
CREATE (matija:Person {name: "Matija"})
CREATE (ivan:Person {name: "Ivan"})
CREATE (ivan)-[:Friend {since: 'forever and ever', until: 'forever'}]->(matija);

MATCH (:Person)-[friends:Friend]->(:Person)
CALL create.remove_rel_properties(friends, ["until"])
YIELD relationship 
RETURN relationship;
```

```plaintext
+------------------------------------+
| relationship                       |
+------------------------------------+
| {                                  |
|     "id": 0,                       |
|     "start: 1,                     |
|     "end": 0,                      |
|     "label": "Friend",             |
|     "properties": {                |
|       "since": "forever and ever"  |
|     },                             |
|     "type": "relationship"         |
| }                                  |
+------------------------------------+
```