Overview

The INSERT statement allows you to insert new nodes and edges into the graph using path patterns. It supports the insertion of both individual graph elements and paths, while paths are essentially sequences of nodes connected by edges.

Labels and properties cannot be created during data insertion. Ensure that the specified labels and properties already exist in the graph before inserting data. For managing labels (schemas in UQL) and properties, refer to Schema and Property in UQL.

<insert statement> ::= 
  "INSERT" <insert path pattern> [ { "," <insert path pattern> }... ]

<insert path pattern> ::= 
  <insert node pattern> [ { <insert edge pattern> <insert node pattern> }... ]

<insert node pattern> ::= "(" [ <insert element pattern filler> ] ")"

<insert edge pattern> ::= 
    "<-[" [ <insert element pattern filler> ] "]-"
  | "-[" [ <insert element pattern filler> ] "->"

<insert element pattern filler> ::=
    <element variable declaration> [ <label and property specification> ]
  | [ <element variable declaration> ] <label and property specification>

<label and property specification> ::=
   <label expression> [ "{" <property key value pair list> "}" ]

Details

• Each node or edge must have a specified label.
• A unique value must be provided for the system property _id for each node.
• The system property _uuid cannot be manually specified; it is automatically generated by the system.
• The source and destination nodes of an edge must be defined by placing the respective node patterns on both sides of the edge pattern, with the direction clearly indicated.

Example Graph Structure

The following examples rely on this graph structure:

To create the graph structure, run the following UQL queries one by one against an empty graph:

// Create schemas (labels)
create().node_schema("User").node_schema("Club").edge_schema("Follows").edge_schema("Joins")

// Create properties
create().node_property(@User, "name").node_property(@User, "gender").edge_property(@Follows, "createdOn", datetime).edge_property(@Joins, "memberNo", uint32)

Inserting Individual Nodes

Individual nodes can be inserted with node patterns. Each node must be assigned a label and a unique value for the system property _id of the string type, and may optionally include values for custom properties.

This query inserts two nodes: one labeled User with the _id and name properties specified, and another labeled Club with the _id property specified.

INSERT (:User {_id: "U01", name: 'Quasar92'}), (:Club {_id: "C01"})

This query inserts and returns one node bound to the variable mochaeach.

INSERT (mochaeach:User {_id: "U02", name: 'mochaeach', gender: 'female'})
RETURN mochaeach

Result: mochaeach

Inserting Edges

Edges can only be inserted with path patterns where each full edge pattern has node patterns on both sides and must include a direction to indicate its source and destination nodes. Each edge must be assigned a label and may optionally include values for custom properties.

You can either insert the source and destination nodes along with edges or connect edges to existing nodes.

Inserting Endpoints Along with Edges

This query inserts three nodes labeled User and two edges labeled Follows.

INSERT (:User {_id: 'U03', name: 'rowlock'})-[:Follows {createdOn: '2024-1-5'}]->(:User {_id: 'U04', name: 'Brainy', gender: 'male'})<-[:Follows {createdOn: '2024-2-1'}]-(:User {_id: 'U05', name: 'purplechalk', gender: 'female'})

Connecting to Existing Nodes

This query inserts and returns an edge labeled Joins. The source and destination nodes are found by the preceding MATCH statement and bound to variables n1 and n2 respectively.

MATCH (n1:User {_id: 'U04'}), (n2:Club {_id: 'C01'})
INSERT (n1)-[e:Joins {memberNo: 1}]->(n2)
RETURN e

Result: e

Inserting Connected Paths

This query inserts two paths that intersect at a node. To reuse that node, the variable c02 is employed.

INSERT (:User {_id: 'U06', name: 'waveBliss'})-[:Joins {memberNo: 1}]->(c02:Club {_id: 'C02'})<-[:Joins {memberNo: 2}]-(:User {_id: 'U07', name: 'bella', gender: 'female'}), 
       (:User {_id: 'U08', name: 'Roose'})-[:Joins {memberNo: 3}]->(c02)