Add optional write documentation (#1013)

## Goal

We add documentation for `try {}` in write stages (`insert`, `put`,
`update`, `delete`).

## Implementation

Author: dmitrii-ubskii

core-concepts/modules/ROOT/pages/typeql/invalid-patterns.adoc

@@ -224,3 +224,40 @@ match
 ----
 
 ====
+
+=== Nested optional blocks in write stages
+
+A `try` block in a write stage is executed as a unit. When all variables referenced in the `try` block are bound, the write instructions are executed. While this could allow for arbitrary nesting of
+`try` blocks where the bound variables are checked at every level, for simplicity's sake nesting `try` blocks is not permitted.
+
+[,typeql]
+----
+#!test[write, fail_at=runtime]
+match
+  $person isa person;
+  try {
+    $edu isa education, links (institute: $institute, attendee: $person);
+    try { $emp isa employment, links (employer: $company, employee: $person); }; # allowed in match
+  };
+delete
+  try {
+    $edu;
+    try { $emp; }; # not allowed!
+  };
+----
+
+Use instead:
+
+[,typeql]
+----
+#!test[write, rollback]
+match
+  $person isa person;
+  try {
+    $edu isa education, links (institute: $institute, attendee: $person);
+    try { $emp isa employment, links (employer: $company, employee: $person); };
+  };
+delete
+  try { $edu; };
+  try { $emp; };
+----

core-concepts/modules/ROOT/pages/typeql/query-variables-patterns.adoc

@@ -356,6 +356,42 @@ Finished. Total rows: 3
 Optional variables *are* bound by the optional block and not internal to it.
 ====
 
+==== Optional writes
+A `try` block in a write stage such as `insert` allows for conditional writes in a larger pipeline.
+
+[,typeql]
+----
+#!test[write, rollback]
+match
+  $p isa person, has name $p-name;
+  try {
+    $e isa employment, links (employer: $c, employee: $p);
+    $c has name "Shut Shop";
+  };
+delete try { $e; };
+# pipeline continues with $p, $p-name, and $c still available
+----
+
+Optional patterns in write stages execute only if all the variables referenced in them are bound to a value.
+That means that in this example, if either `$p` or `$c` is not bound, the insert stage does nothing.
+If they are both bound, however, then a new employment relation is inserted.
+
+[,typeql]
+----
+#!test[write, rollback]
+match
+  try { $p isa person, has name $p-name; };
+  try { $c isa company, has name "Shut Shop"; };
+insert
+  try { $_ isa employment, links (employer: $c, employee: $p); };
+----
+
+[NOTE]
+====
+Note that `try` blocks may not be nested (`try { try { ... }; };`) in write stages.
+The inner `try` block can usually either be flattened into the outer block or placed at the top level in the write stage.
+====
+
 == Notes on variables
 === Variables in an answer
 Notice that a variable that is "bound" in a conjunction is guaranteed to be bound

typeql-reference/modules/ROOT/pages/patterns/optionals.adoc

@@ -34,15 +34,11 @@ match
         $_ isa marriage, links (spouse: $person, spouse: $spouse);
     };
 ----
-Here, `$spouse` will be bound to the spouse if `$person` is in a `marriage`.
-Else, `$spouse` will be bound to `None`
+Here, `$spouse` is bound to the spouse if `$person` is in a `marriage`.
+Else, `$spouse` is bound to `None`
 
-=== insert & delete
-[NOTE]
-====
-Coming soon!
-====
-Optional patterns in insert or delete stages will execute only if ALL the variables present in them are bound.
+=== insert, update, & delete
+Optional patterns in insert, update, or delete stages execute only if ALL the variables present in them are bound.
 // Re-enable the tests when we do implement it
 [,typeql]
 ----
@@ -56,18 +52,76 @@ insert
     $policy links (covered: $person);
     try { $policy links (covered: $spouse); };
 ----
-If `$person` is in a marriage, the match stage will bind `$spouse`
-and the insert stage will add them to the policy.
+If `$person` is in a marriage, the match stage binds `$spouse` and the insert stage adds them to the policy.
+
+=== put
+Because a put stage only inserts data if no existing data matches the body of the put, the patterns in a `try` block of a put stage only attempt to insert data if the mandatory patterns (i.e. those
+outside `try` blocks) fail to produce a match. When inserting data, put behaves identically to an insert stage in that a `try` block only executes if all referenced variables are bound.
+
+[,typeql]
+----
+#!test[write, rollback]
+match
+  $person isa person;
+  $spouse isa person;
+  try {
+    $policy isa policy, links (covered: $person);
+  };
+put
+  $_ isa marriage, links (spouse: $person, spouse: $spouse);
+  try {
+    $policy links (covered: $spouse);
+  };
+----
+
+In this example, if the marriage relation already exists, the put stage does not attempt to add `$spouse` to the optionally bound `$policy`.
+
+If this behavior is not desirable, the `try` block should be put in a separate insert stage instead.
+
+[,typeql]
+----
+#!test[write, rollback]
+match
+  $person isa person;
+  $spouse isa person;
+  try {
+    $policy isa policy, links (covered: $person);
+    not { $policy links (covered: $spouse); };
+  };
+put
+  $_ isa marriage, links (spouse: $person, spouse: $spouse);
+insert
+  try {
+    $policy links (covered: $spouse);
+  };
+----
+
+In this pipeline, the `marriage` relation is created if it does not already exist, and `$spouse` is always inserted as a roleplayer in `$policy` provided it is bound.
 
 [NOTE]
 ====
-Optional patterns are banned in `put` stages.
+In particular, a put stage with only `try` blocks never inserts any data!
+[,typeql]
+----
+#!test[write, rollback]
+match
+  $_ isa marriage, links (spouse: $person, spouse: $spouse);
+  try {
+    $policy isa policy, links (covered: $person);
+  };
+put
+  try {
+    $policy links (covered: $spouse);
+  };
+----
+
+In this example the `$policy` is bound only if `$person` plays a role in it, but if it doesn't also link `$spouse`, that link is not inserted.
 ====
 
 == Behavior in match clauses
 === Single origin
 In the stage that it first occurs, An optional variable may only occur in a single try-block.
-[,typeql]
+
 ----
 #!test[read, fail_at=runtime]
 match
@@ -82,7 +136,7 @@ match
 
 === Optional variables in subsequent stages
 An optional variable can be used in subsequent stages.
-An unbound optional variable will cause the pattern to fail.
+An unbound optional variable causes the pattern to fail.
 
 The following is a valid way to express the intent of the example above:
 [,typeql]