Document wrapping insert with select (#6936)

* Document wrapping `insert` with `select`

* Add `with` example of wrapping insert w/ select

* Add select wrap info to `update` docs

docs/edgeql/insert.rst

@@ -117,6 +117,44 @@ You can only ``insert`` instances of concrete (non-abstract) object types.
   ... };
   error: QueryError: cannot insert into abstract object type 'default::Person'
 
+By default, ``insert`` returns only the inserted object's ``id`` as seen in the
+examples above. If you want to get additional data back, you may wrap your
+``insert`` with a ``select`` and apply a shape specifying any properties and
+links you want returned:
+
+.. code-block:: edgeql-repl
+
+  db> select (insert Hero {
+  ...   name := "Spider-Man"
+  ...   # secret_identity is omitted
+  ... }) {id, name};
+  {
+    default::Hero {
+      id: b0fbe9de-3e90-11ec-8c12-ffa2d5f0176a,
+      name: "Spider-Man"
+    }
+  }
+
+You can use :ref:`ref_eql_with` to tidy this up if you prefer:
+
+.. code-block:: edgeql-repl
+
+  db> with NewHero := (insert Hero {
+  ...   name := "Spider-Man"
+  ...   # secret_identity is omitted
+  ... })
+  ... select NewHero {
+  ...   id,
+  ...   name,
+  ... }
+  {
+    default::Hero {
+      id: b0fbe9de-3e90-11ec-8c12-ffa2d5f0176a,
+      name: "Spider-Man"
+    }
+  }
+
+
 .. _ref_eql_insert_links:
 
 Inserting links

docs/edgeql/update.rst

@@ -90,6 +90,27 @@ To remove items, use ``-=``.
   ... filter .title = "Black Widow";
   {default::Movie {num_characters: 2}}
 
+Returning data on update
+------------------------
+
+By default, ``update`` returns only the inserted object's ``id`` as seen in the
+examples above. If you want to get additional data back, you may wrap your
+``update`` with a ``select`` and apply a shape specifying any properties and
+links you want returned:
+
+.. code-block:: edgeql-repl
+
+  db> select (update Hero
+  ...   filter .name = "Hawkeye"
+  ...   set { name := "Ronin" }
+  ... ) {id, name};
+  {
+    default::Hero {
+      id: d476b12e-3e7b-11ec-af13-2717f3dc1d8a,
+      name: "Ronin"
+    }
+  }
+
 With blocks
 -----------
 
@@ -118,6 +139,27 @@ the results of a complex query.
   You can pass any object-type expression into ``update``, including
   polymorphic ones (as above).
 
+You can also use ``with`` to make returning additional data from an update more
+readable:
+
+.. code-block:: edgeql-repl
+
+  db> with UpdatedHero := (update Hero
+  ...   filter .name = "Hawkeye"
+  ...   set { name := "Ronin" }
+  ... )
+  ... select UpdatedHero {
+  ...   id,
+  ...   name
+  ... };
+  {
+    default::Hero {
+      id: d476b12e-3e7b-11ec-af13-2717f3dc1d8a,
+      name: "Ronin"
+    }
+  }
+
+
 See also
 --------