TypeDB 3.0 is live! Get started for free.

Inserting data

This page explains how to insert data in a TypeDB database.

Overview

Data in TypeDB is inserted using insert stages in write pipelines, which can executed in write (or schema) transactions.

Inserts can be performed as part of a single-stage query, in which case the data insert will occur exactly once. Inserts can also be part of multi-stage a pipelines, potentially with multiple input rows from the preceding stage (e.g., a match stage), in which case we perform one data insert for each input row.

Refer to the Insert stage page for a detailed explanation and additional examples.

Running inserts

To insert data, open a write transaction. This allows you to read and write data to your database while keeping the schema secure.

Insert stages begin with the keyword insert. Multiple statements can be combined within the same insert stage and the same variable may appear in multiple statements (but the variable will refer to the same data in all those statements).

Insert statements

Let’s give a brief overview of what kinds of statements can be used in an insert stage.

Inserting instances with isa

To create new data instances we can use isa statements. The following simple query creates a new data instance of type user:

Inserting a user entity
insert $x isa user;

We may also create relations:

Inserting a friendship relation (without role players)
insert $f isa friendship;

Note, to persist in the database, a relation would need at least one role player (see player insertion below).

Similarly, attributes can only be created using isa independently of owners when marked as @independent in the schema.

Inserting attribute ownerships with has

Connections of attributes to their “owner” data instances can be inserted using has statements.

Inserting a single user and a username for that user
insert
  $x isa user;
  $x has username "User";

This can be further shortened to:

Inserting a single user together with their username
insert
  $x isa user, has username "User";

If the username attribute "User" does not yet exist when running the above, it will be created anonymously by the above query (“anonymously” meaning that we do not assign it to any variable). No isa statement is required!

Connections of relations to their “role players” data instances can be created using links statements.

Inserting users, a friendship, and links between users via that friendship
insert
  $x isa user, has username "User_1";
  $y isa user, has username "User_2";
  $f isa friendship;
  $f links (friend: $x, friend: $y);

The last line can be further shortened to:

Relation constructor syntax
  $f isa friendship (friend: $x, friend: $y);

We can even keep the friendship instance anonymous (i.e., not assign it to a variable) if we do not need it otherwise, by simply writing:

Anonymous relation constructor syntax
  friendship (friend: $x, friend: $y);

Inserting with data pipelines

Most commonly, insert stages are use as part of data pipelines. This let’s us first retrieve specific data, which we can then augment with new data.

Match-insert pipeline example
match
  $u isa user, has username "Bob";
insert
  $new-u isa user, has username "Charlie", has email "charlie@typedb.com";
  $f isa friendship, links (friend: $u, friend: $new-u);

The first stage of the pipeline retrieves the users called "Bob" from the database. For each answer of the first stage, the second stage is then executed: this inserts a new user called "Charlie"

See the data pipeline reference for more information.

Insert stage answers

An insert stage returns all concepts inserted into the database as a stream of concept rows. A collected stream of concept rows can be interpreted as a table with a header containing variables and rows with respective concept answers for each variable. This lets you verify if the result meets your expectations.

For example, the following is a snapshot of a TypeDB Console’s response to the previous query (iid s may vary):

Match-insert example’s result
   ------------
    $f     | iid 0x1f00020000000000000001 isa friendship
    $new-u | iid 0x1e00030000000000000003 isa user
    $u     | iid 0x1e00030000000000000000 isa user
   ------------

Committing changes

Do not forget to commit your transaction to preserve the changes.

Some data constraints are only validated upon commit. This means you might discover inconsistencies in your data during the commit process, and the commit will be rejected.

While most validations occur during operation time to keep data synchronized, commit-time validations are necessary to allow flexible data modifications. For example, validating inserted data against cardinality during operation time could block modifications entirely.

If you want to abort your changes, simply close the transaction or perform a rollback. Refer to Transactions for more details.

Having troubles?

Refer to the Debugging queries page for common debugging tips.