New ACM paper, free-tier cloud, and open-source license

Insert query

An Insert query is used to insert new data into a database. You can insert an instance of a type, assign ownership of an attribute, or add a new role player for a relation. For a practical guide on how to send an Insert query to TypeDB, see the Insert query page of the TypeDB Manual.

Syntax

An Insert query consists of an optional match clause and an insert clause:

[match <pattern>]
insert <insert_pattern>

where <insert_pattern> is a pattern of valid data-specific TypeQL statements including isa / isa!, has, role assignment, and value assignment.

The optional match clause <pattern> can be any valid match pattern: for more information, see the Patterns and Statements sections.

Behavior

An Insert query inserts new data into a TypeDB database, as specified in its insert clause pattern. The data to be inserted is specified using new variables (i.e., variables not appearing in the optional match clause) or values.

  • Entities, attributes, or relations are inserted using isa statements.

  • Ownerships of attributes are inserted using a has statement. Note that inserting an ownership of an attribute that doesn’t yet exist in a database (with a new value), implicitly inserts such an attribute.

  • Role players are usually assigned as a part of a relation insertion with a role assignment statement.

Query execution

If a match clause is specified in an Insert query, then its insert clause is executed once per every result of the match clause. If there is no match clause in an Insert query, then the insert clause is executed exactly once.

For an Insert query to succeed, inserted data must not violate the schema of a database.

Query response

An Insert query returns a lazy Stream/Iterator of ConceptMap objects with the inserted data.

Insert without matching

For this example, use a database with the IAM schema and sample data loaded.

To insert new data with no connection to existing database data, we can use an Insert query without a match clause:

Insert example
insert $p isa person, has full-name "Bob";

The above query inserts a person entity that owns a full-name attribute whose value is "Bob".

If there is no such attribute in a database, then it will be created by this query implicitly.

Insert with matching

For this example, use a database with the IAM schema and sample data loaded.

To be able to insert new data that is connected to existing concepts, use a match clause in an Insert query to match the existing data from a database first:

Match insert example
match
$p isa person, has full-name "Bob";
insert
$p has email "bob@typedb.com";

The above query finds a person entity that has the full-name attribute with the value of Bob and makes it the owner of the email attribute with the value of bob@typedb.com.

If there is no person that matches the match clause pattern, then there will be no information inserted by the query. If there are multiple instances that match the pattern, then every matched person will be assigned ownership of the email attribute.

Insert entities

For this example, use a database with the IAM schema and sample data loaded.

To insert an entity, use a concept variable followed by an isa statement with the entity’s type (label or variable). The isa is usually combined with statements to assign attribute ownerships or roles in relations. You can use the same concept variable in multiple statements to insert more about the entity or combine statements into a composite statement.

Entities without any additional information associated with them are almost indistinguishable from one another.

While it is possible to insert an entity without any attributes owned or roles played, such an entity can’t be easily found in a database or distinguished from other entities of the same type. As a best practice, we recommend using the same query to add at least some information about the inserted entity.

You can also use the @key or @unique annotations for an attribute type ownership schema definition to add constraints that make it much easier to uniquely address instances of this entity type.

Inserting an entity example
insert
$p isa person, has full-name "John Parkson";

The above query inserts a person entity with the following attributes:

  • full-name — value is John Parkson,

  • email — value is john.parkson@gmail.com,

  • credential — value is qwerty1.

Insert attributes

For this example, use a database with the IAM schema and sample data loaded.

Inserting an attribute requires setting both type and value of a new attribute. You can specify the value with a comparator or value assignment statement.

You can insert an attribute explicitly. Use a variable followed by a value and isa pattern with an attribute type to insert an attribute.

Explicit attribute insertion
insert
$s 34 isa size-kb;

Attributes that are not owned by any other instances are called orphaned attributes and aren’t very useful to store in a database.

To implicitly insert an attribute, assign an ownership of it with a has statement. If an attribute with the type and value doesn’t exist in the database, it is created implicitly.

Implicit attribute insertion
insert
$f isa file, has path "new-file.txt";

The above query inserts a file entity and assigns it an ownership of path attribute with the value of new-file.txt. If there is no such attribute in a database, it is inserted implicitly as a result of assigning the ownership.

Insert ownerships

Attributes are immutable. Rather than changing a value of an owned attribute, you can delete an ownership of it and replace with an ownership of another attribute with a different value.

To insert an ownership of an attribute, use a has statement:

Inserting ownership
match
$p isa person, has full-name "John Parkson";
insert
$p has credential "qwerty1";

The above query matches a person that has full-name "John Parkson", that we inserted earlier, and assign for the person to be owner of attribute of the type credential and value qwerty1. If the attribute doesn’t exist, it is created/inserted implicitly by this query.

Multivalued attributes

TypeDB supports multivalued attributes by allowing ownership of multiple attributes of the same type.

For example, if the person entity type can own the email attribute type, then an instance of the person can own multiple (from zero to many) email attributes with different values.

Multivalued attribute example
match
$p isa person, has full-name "John Parkson";
insert
$p has email "john.parkson@typedb.com",
    has email "admin@jp.com",
    has email "jp@gmail.com";

The above query assigns ownership of three different attributes of the email type to the matched person entity from one of the previous examples: Insert entities. As a result, the matched entity should own six attributes, four of which are of the email type.

See fetch output
Multiple emails owned by a person
{
    "p": {
        "attribute": [
            { "value": "John Parkson", "value_type": "string", "type": { "label": "full-name", "root": "attribute" } },
            { "value": "admin@jp.com", "value_type": "string", "type": { "label": "email", "root": "attribute" } },
            { "value": "jp@gmail.com", "value_type": "string", "type": { "label": "email", "root": "attribute" } },
            { "value": "john.parkson@gmail.com", "value_type": "string", "type": { "label": "email", "root": "attribute" } },
            { "value": "john.parkson@typedb.com", "value_type": "string", "type": { "label": "email", "root": "attribute" } },
            { "value": "qwerty1", "value_type": "string", "type": { "label": "credential", "root": "attribute" } }
        ],
        "type": { "label": "person", "root": "entity" }
    }
}

Insert relations

For this example, use a database with the IAM schema and sample data loaded.

Inserting a relation requires specifying at least one role player.

From a data modeling perspective, the existence of a relation implies the existence of role players for all its roles. Inserting a relation without a role player for a role can create an incomplete data state. Like a marriage relation with only one known spouse.

Use a role assignment statement with an isa statement in an insert clause to insert a relation.

Inserting a relation
match
$op isa operation, has name "view_file";
insert
$f isa file, has path "new-relation.txt";
$a (object: $f, action: $op) isa access;

In the above example we match an operation with the view_file name and insert a file with the new-relation.txt path to insert a relation of the access type between them with roles object and action played by the file and operation respectively.

Insert role players

For this example, use a database with the IAM schema and sample data loaded.

To add a new role player for an existing relation, match the relation from a database and use a role assignment statement with only new roleplayers. Don’t use an isa / isa! statement with relation type as it will insert a new relation instead of adding roles to an existing one.

Adding a role player
match
$f isa file, has path "new-relation.txt";
$op isa operation, has name "view_file";
$a (action: $op) isa access;
insert
$a (object: $f);

Multiple role players

A role in a relation can be played more than once (by multiple role players).

Multiple players for a role
match
$p1 isa subject, has full-name "Pearle Goodman";
$p2 isa subject, has full-name "Masako Holley";
$o isa object, has path "zewhb.java";
insert
$obj-ownership (owner: $p1, owner: $p2, object: $o) isa object-ownership;

The above query:

  1. Finds the person entity ($p1) by its full-name attribute Pearle Goodman.

  2. Finds the person entity ($p2) by its full-name attribute Masako Holley.

  3. Finds the object entity ($o) by its path attribute zewhb.java.

  4. Inserts an object-ownership relation ($obj-ownership) which relates $p1 (as owner) and $p2 (as owner) to $o (as object).

In short, it makes Pearle Goodman and Masako Holley both play the same role in the same relation.

Learn more

Lesson 4.1: Inserting simple data

Learn more about inserting data into a database in the TypeDB Learning course.

Insert query

See how to send an Insert query to TypeDB.

Provide Feedback