Insert basics — AQL

Insert

1
insert User {
2
  email := $email,
3
  name  := $name,
4
  age   := $age
5
};

1
-- $1: email
2
-- $2: name
3
-- $3: age
4
INSERT INTO "user" ("email", "name", "age")
5
VALUES ($1, $2, $3)
6
RETURNING *;

Inserting with a link

Assign a link by passing a subquery that resolves to the FK value.

1
insert Post {
2
  title  := $title,
3
  author := (select User filter .email = $email)
4
};

1
-- $1: title
2
-- $2: email
3
INSERT INTO "post" ("title", "author")
4
VALUES ($1, (SELECT u.id FROM "user" u WHERE u.email = $2 LIMIT 1))
5
RETURNING *;

The SQL samples on these pages write RETURNING * for brevity. Axel actually emits the explicit column list of the inserted row — RETURNING "id", "title", "author" for the query above — which is what the generated row type is built from.

A link assignment accepts any scalar expression that resolves to the FK value, not just a solo subquery:

A bare parameter — pass the FK directly; a lone link param infers uuid.
```
1
insert Post { title := $title, author := $author_id };
```

A subquery projection — select a linked FK column rather than the row id with (select …).link.

1
insert GithubInstallation {
2
  organization    := (select GithubInstallation filter .installation_id = $iid<int64>).organization,
3
  installation_id := $iid<int64>
4
};

A ?? chain — coalesce several lookups; the FK resolves from whichever finds a row first.

1
insert GithubInstallation {
2
  organization    := (select Organization filter .id = $org<uuid>?)
3
                   ?? (select GithubInstallation filter .installation_id = $iid<int64>?).organization,
4
  installation_id := $iid<int64>
5
};

See Optional parameters — value subquery for how an omitted param lets the chain fall through.

A sub-insert — create the linked row inline; it lowers to a CTE. See Conflicts for the (unsupported) interaction with unless conflict on sub-inserts.
```
1
insert Post {
2
  title  := $title,
3
  author := (insert User { email := $email, name := $name })
4
};
```

To handle a uniqueness collision, see Conflicts. To reassign a link on an existing row, see Updating links.