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 TypeDB clients, follows these Clients Guide.

[tab:TypeQL] ```typeql 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 TypeQLInsert query = TypeQL.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:TypeQL] ```typeql insert $x isa emotion; $x "like"; ``` [tab:end] [tab:Java] ```java TypeQLInsert query = TypeQL.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:TypeQL] ```typeql 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 TypeQLInsert query = TypeQL.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 version 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:TypeQL] ```typeql match $person isa person; insert $reflexive-friendship (friend: $person, friend: $person) isa friendship; ``` [tab:end] [tab:Java] ```java TypeQLInsert query = TypeQL.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:TypeQL] ```typeql match $friendship (friend: $p, friend: $p) isa friendship; get $friendship; ``` [tab:end] [tab:Java] ```java TypeQLMatch.Filtered query = TypeQL.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:TypeQL] ```TypeQL ## inserting the new friendship to a friendship list match $julie isa person, has full-name "Julie Hutchinson"; $miriam isa person, has full-name "Miriam Morton"; $f ($julie, $miriam) isa friendship; $list (owner: $miriam) isa friendship-list, has title "best friends"; insert $list (listed: $f); ``` [tab:end] [tab:Java] ```java TypeQLInsert insert_query = TypeQL.match( var("julie").isa("person").has("name", "Julie Hutchinson"), var("miriam").isa("person").has("name", "Miriam Hutchinson"), var("f").rel(var("julie")).rel(var("miriam")).isa("friendship"), var(list).rel("owner", var("miriam")).isa("friendship-list").has("title", "best friends") ).insert( var("list").rel("listed", var("f")) ); ``` [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 TypeQL(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 TypeQL(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.