Edit on Github

Insert Instances of an Entity Type

To insert an instance of an entity type into the knowledge graph, we use the insert keyword followed by a series of statements that are similar to match patterns. To try the following examples with one of the Grakn clients, follows these Clients Guide.

[tab:Graql] ```graql insert $p isa person, has full-name "John Parkson", has gender "male", has email "john.parkson@gmail.com", has phone-number "+44-1234=567890"; ``` [tab:end] [tab:Java] ```java GraqlInsert query = Graql.insert( var("p").isa("person").has("full-name", "John Parkson").has("email", "john.parkson@gmail.com").has("phone-number", "+44-1234-567890") ); ``` [tab:end]

This insert query inserts a person with a full-name attribute of John Parkson, an email attribute of john.parkson@gmail.com and a phone number of +44-1234-567890.

Insert Instances of an Attribute Type

Similar to inserting an instance of an entity, to insert an instance of an attribute, we use the insert keyword followed by the variable pattern to describe the attribute of interest and its value.

[tab:Graql] ```graql insert $x isa emotion; $x "like"; ``` [tab:end] [tab:Java] ```java GraqlInsert query = Graql.insert( var("x").eq("like").isa("emotion") ); ``` [tab:end]

Insert Instances of a Relation Type

Given the dependent nature of relations, inserting an instance of a relation is quite different from that of an entity. The roles of a relation to be inserted are expected to be played by instances that already exist in the knowledge graph. Therefore inserting a relation is always preceded by matching the role players - what is commonly called the match insert. What follows the insert keyword, is a series of statements that are similar to the match patterns.

[tab:Graql] ```graql match $org isa organisation, has name "Facelook"; $person isa person, has email "tanya.arnold@gmail.com"; insert $new-employment (employer: $org, employee: $person) isa employment; $new-employment has reference-id "WGFTSH"; ``` [tab:end] [tab:Java] ```java GraqlInsert query = Graql.match( var("org").isa("organisation").has("name", "Facelook"), var("person").isa("person").has("email", "tanya.arnold@gmail.com") ).insert( var("new-employment").rel("employer", "org").rel("employee", "person").has("reference-id", "WGFTSH").isa("employment") ); ``` [tab:end]

This match insert query:

  1. Matches the organisation that plays employer, assigned to variable $org.
  2. Matches the person that plays employee, assigned to variable $person.
  3. Inserts an employment relation with $org and $person as its role players, assigned to variable $new-employment.
  4. Inserts the ownership of reference-id with value WGFTSH to the $new-employment relation instance.

Duplicate Role Players

[Note] As of Grakn 1.7.0, relations are allowed to have duplicate role players.

This means we can model true reflexive relations. Taking friendship as an example

[tab:Graql] ```graql match $person isa person; insert $reflexive-friendship (friend: $person, friend: $person) isa friendship; ``` [tab:end] [tab:Java] ```java GraqlInsert query = Graql.match( var("person").isa("person") ).insert( var("reflexive-friendship").rel("friend", "person").rel("friend", "person").isa("friendship") ); ``` [tab:end]

As a consequence, you can query for the duplicate role player as a duplicate role player and get an answer back:

[tab:Graql] ```graql match $friendship (friend: $p, friend: $p) isa friendship; get $friendship; ``` [tab:end] [tab:Java] ```java GraqlMatch.Filtered query = Graql.match( var("friendship").rel("friend", "p").rel("friend", "p").isa("friendship") ).get("friendship"); ``` [tab:end]

Extending a relation with a new role player

We can add role players to a relation by matching the relation and the concept that will be the new role player, and then insert the new role player into the same relation.

[tab:Graql] ```graql ## inserting the new role player into some theoretical multi-employment relation match $emp (employer: $org, employee: $p) isa employment; $p2 isa person; not { $p = $p2; }; insert $emp (employee: $p2) isa employment; ``` [tab:end] [tab:Java] ```java GraqlInsert insert_query = Graql.match( var("emp").rel("employer", var("org")).rel("employee", var("p")).isa("employment"), var("p").isa("person"), var("p2").isa("person"), not(var("p").eq(var("p2"))) ).insert( var("emp").rel("employee", var("p2")).isa("employment") ); ``` [tab:end]

Clients Guide

[Note] **For those developing with Client [Java](../client-api/java)**: Executing an `insert` query, is as simple as calling the [`query().insert()`](../client-api/java) method on a transaction and passing the query object to it.
[Note] **For those developing with Client [Node.js](../client-api/nodejs)**: Executing an `insert` query, is as simple as passing the Graql(string) query to the `query().insert()` function available on the [`transaction`](../client-api/nodejs#transaction) object.
[Note] **For those developing with Client [Python](../client-api/python)**: Executing an `insert` query, is as simple as passing the Graql(string) query to the `query().insert()` method available on the [`transaction`](../client-api/python#transaction) object.


An insert query optionally preceded by a match clause is used to insert a data instance into the knowledge graph.

Next, we learn how to delete data from a knowledge graph.