Lesson 4.1: Inserting simple data

To insert new data into a database, we use an Insert clause. The following query inserts a new user.

This Insert query consists of a single insert clause, which inserts a single entity of type user and assigns it three attributes: one each of types id, name, and birth-date.

Using a write transaction, try running. After running it, make sure to commit the transaction. The new user should now be in the database! You can check by switching to a new read transaction and then running the following query, which lists the names of users in the database.

If you have correctly executed the Insert query, the new user Evelin should appear in the results.

An Insert query can insert any number of entities and relations. In the following query, we insert four new entities: a paperback, a contributor, a publisher, and a publication event, along with two new relations between them: an authoring relation and a publishing relation.

Reminder: commit your changes!

Notice that we have given the book two genre attributes! This is perfectly permissible since your schema permits it with @card(0..). All attributes in TypeDB may multivalued with this setting, with the default being 0 or 1 attributes with @card(0..1). Cardinality configuration is an important part of constraining your data into the shapes and semantics you desire - such as allowing an entity or relation to own any number of attributes of the same type, or allowing exactly 1, or any other range of quantities of them.

So far, the Insert queries we’ve seen have only created entirely new entities, relations between them, and their attributes. We can also write Insert queries that create relations between existing entities, or add new attributes to existing entities or relations. To do so, we use an Insert query with two clauses: a match clause followed by an insert clause. In the following example, we record the stock of the newly added edition of Frankenstein.

→ Commit

This query matches the book we inserted previously by its ISBN, and then gives it a new stock attribute. In a Fetch query, the match clause identifies matching data within the database, and the fetch clause specifies what to retrieve from each match. In an Insert query, the match clause serves the same function, but then we insert new data for each match rather than retrieving existing data.

In order to insert a new attribute, we have to match the attribute’s existing owner, represented in the last query by the $book variable. Similarly, in the next query, we insert a new relation by matching the relation’s existing role players, represented by the $city and $publication variables. It records the fact that the publication of this edition of Frankenstein by Dover Publications took place in NYC.

→ Commit

An Insert query without a match clause always inserts the data described in the insert clause once. However, an Insert query with a match clause will insert the data described in the insert clause multiple times, once for each match found. The following query would assign a stock attribute to every paperback in the database, even if it already had one!

→ DON’T COMMIT YET

Likewise, the following query would create a locating relation for every publication entity with a year attribute equal to 1994.

→ Close your transaction without committing

Since we don’t want these changes to be permanent (they’re just for demonstration), simply close your transaction to throw away the changes. Before committing, your changes will live as a set of changes in the transactional snapshot of your database. If you did commit, those changes are merged back into the database. If you don’t, they are simply discarded. Any changes before commit are invisible to other transactions.

TypeDB 3.0 ships with a new alternative to insert: the put clauses. Put clauses check if the pattern provided exists in its entirety, and if it does not, it inserts the entire pattern:

A put is equivalent to doing:

match action-execution relates $role; fetch { "role": $role, },

match $user isa user, has id "u0012"; insert $login isa login, has success true; $rel isa action-execution, links (action: $login, executor: $user), has timestamp 2024-03-04T07:32:03.287;