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:
- Matches the
organisation that plays employer, assigned to variable $org.
- Matches the
person that plays employee, assigned to variable $person.
- Inserts an
employment relation with $org and $person as its role players, assigned to variable $new-employment.
- 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.
Summary
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.
Grakn
on Github
Grakn Labs
on Discord