# Insert stage

An insert stage inserts new data into the database. Insertable data includes instances of types, ownerships of attributes, and role players of relations.

## [](#_syntax)Syntax

The body of an insert stage is a sequence of insert statements.

All insert statements have the same syntax as their corresponding match statements.

```typeql
insert <insert-statement> [ <insert-statement> ... ]
```

## [](#_behavior)Behavior

*   [Isa statements](../../statements/isa/index.md) insert new instances of specified types. Each variable introduced in the insert clause must be accompanied by an explicit `isa` statement.
    
*   [Has statements](../../statements/has/index.md) insert new ownerships of attributes. If an attribute is provided by value, the attribute type is mandatory.
    
*   [Links statements](../../statements/links/index.md) insert new role players for relations. Role tags can be omitted if there is only a single role the role player can play.
    

## [](#_execution)Execution

If the insert stage is the first stage in a write pipeline, its body is executed once. The output stream in that case contains a single row containing the newly inserted concepts.

If the insert stage is preceded by other stages, its body is executed once for each input row. The output is then a stream of input rows extended with the newly inserted values.

## [](#_validation)Validation

Attempting to insert the following fail immediately and terminate the transaction:

*   an instance of an [abstract](../../annotations/abstract/index.md) type,
    
*   an ownership or a role player that does not conform to the schema (a player of a relation that cannot relate a role with the specified role name, a player of a type that cannot play the specified role type, an ownership for the owner that cannot own an attribute of the specified type),
    
*   an instance of an attribute type with a value that violates a constraint annotation ([`@range`](../../annotations/range/index.md), [`@regex`](../../annotations/regex/index.md), [`@values`](../../annotations/values/index.md)),
    
*   an ownership that violates a constraint annotation ([`@distinct`](../../annotations/distinct/index.md), [`@key`](../../annotations/key/index.md), [`@unique`](../../annotations/unique/index.md)).
    

[Cardinality annotations](../../annotations/card/index.md) are not enforced until the transaction is committed.

## [](#_examples)Examples

Schema for the following examples

```typeql
#!test[schema, commit]
define
  entity content owns id;
  entity page sub content,
    owns page-id,
    owns name;
  entity profile sub page,
    owns username;
  entity user sub profile,
    owns phone,
    owns karma;

  attribute id value string;
  attribute page-id sub id;
  attribute username sub page-id;
  attribute name value string;
  attribute phone value string;
  attribute karma value double;
attribute bio value string;
attribute profile-picture value string;
attribute email @independent, value string @regex("^.*@.*\.com");
user owns bio, owns profile-picture, owns email;
attribute group-id sub id;
attribute rank, value string @values("admin", "member");
attribute tag value string;
relation group-membership, relates group, relates member,  owns rank;
entity group, owns name, owns group-id, owns tag, plays group-membership:group;
user, plays group-membership:member;
```

```typeql
#!test[write]
insert
  $group isa group,
    has group-id "<group id>";
  $user isa user,
    has name "<name>",
    has bio "<bio>",
    has profile-picture "<uuid>";
  group-membership(group: $group, member: $user) has rank "member";
```

```typeql
#!test[write]
match
  $user isa user, has name "<name>";
  $group isa group, has group-id "<group id>";
insert
  group-membership(group: $group, member: $user) has rank "member";
```

[Fetch](../fetch/index.md) [Delete](../delete/index.md)

[Edit on GitHub](https://github.com/typedb/typedb-docs/edit/3.x-development/typeql-reference/modules/ROOT/pages/pipelines/insert.adoc) Edit this page on GitHub.