Add remark that keepNull: false does not affect attributes in arrays (#1418)

* Add remark that keepNull: false does not affect attributes in arrays

* Update examples for 3.10,3.11,3.12 in keepNull-nested-objects at 2023-06-26T09:45:44+00:00

---------

Co-authored-by: Paula Mihu <[email protected]>
Co-authored-by: arangodb-release-bot <[email protected]>

Author: Simran-B

3.10/appendix-references-collection-object.md

@@ -990,8 +990,9 @@ used to specify the following options:
 - `keepNull`: The optional `keepNull` parameter can be used to modify
   the behavior when handling `null` values. Normally, `null` values
   are stored in the database. By setting the `keepNull` parameter to
-  `false`, this behavior can be changed so that all attributes in
-  `data` with `null` values will be removed from the target document.
+  `false`, this behavior can be changed so that top-level attributes and
+  sub-attributes in `data` with `null` values are removed from the target
+  document (but not attributes of objects that are nested inside of arrays).
   This option controls the update-insert behavior only.
 - `mergeObjects`: Controls whether objects (not arrays) will be
   merged if present in both the existing and the patch document. If
@@ -1456,8 +1457,9 @@ an object:
 - `keepNull`: The optional `keepNull` parameter can be used to modify
   the behavior when handling `null` values. Normally, `null` values
   are stored in the database. By setting the `keepNull` parameter to
-  `false`, this behavior can be changed so that all attributes in
-  `data` with `null` values will be removed from the target document.
+  `false`, this behavior can be changed so that top-level attributes and
+  sub-attributes in `data` with `null` values are removed from the target
+  document (but not attributes of objects that are nested inside of arrays).
 - `mergeObjects`: Controls whether objects (not arrays) will be
   merged if present in both the existing and the patch document. If
   set to `false`, the value in the patch document will overwrite the
@@ -1530,7 +1532,7 @@ Use a document identifier:
     {% endarangoshexample %}
     {% include arangoshexample.html id=examplevar script=script result=result %}
 
-Use the `keepNull` parameter to remove attributes with null values:
+Use the `keepNull` parameter to remove attributes with `null` values:
 
     {% arangoshexample examplevar="examplevar" script="script" result="result" %}
     @startDocuBlockInline documentsCollection_UpdateHandleKeepNull
@@ -1586,8 +1588,9 @@ The document meta-attributes `_id`, `_key` and `_rev` cannot be updated.
 The optional `keepNull` parameter can be used to modify the behavior when
 handling `null` values. Normally, `null` values are stored in the
 database. By setting the `keepNull` parameter to `false`, this behavior
-can be changed so that all attributes in `data` with `null` values will
-be removed from the target document.
+can be changed so that top-level attributes and sub-attributes in `data` with
+`null` values are removed from the target document (but not attributes of
+objects that are nested inside of arrays).
 
 The optional `waitForSync` parameter can be used to force synchronization
 of the document replacement operation to disk even in case that the

3.10/appendix-references-dbobject.md

@@ -809,8 +809,9 @@ Updates an existing document with additional boolean `options` passed via an obj
   - `keepNull`: The optional `keepNull` parameter can be used to modify 
     the behavior when handling `null` values. Normally, `null` values
     are stored in the database. By setting the `keepNull` parameter to
-    `false`, this behavior can be changed so that all attributes in
-    `data` with `null` values will be removed from the target document.
+    `false`, this behavior can be changed so that top-level attributes and
+    sub-attributes in `data` with `null` values are removed from the target
+    document (but not attributes of objects that are nested inside of arrays).
   - `mergeObjects`: Controls whether objects (not arrays) will be 
     merged if present in both the existing and the patch document. If
     set to `false`, the value in the patch document will overwrite the

3.10/aql/operations-update.md

@@ -269,10 +269,11 @@ to change them are ignored and not considered errors.
 
 ### `keepNull`
 
-When updating an attribute to the `null` value, ArangoDB does not remove the attribute 
-from the document but stores this `null` value. To remove attributes in an update
-operation, set them to `null` and set the `keepNull` option to `false`. This removes
-the attributes you specify but not any previously stored attributes with the `null` value:
+When updating an attribute to the `null` value, ArangoDB does not remove the
+attribute from the document but stores this `null` value. To remove attributes
+in an update operation, set them to `null` and set the `keepNull` option to
+`false`. This removes the attributes you specify but not any previously stored
+attributes with the `null` value:
 
 ```aql
 FOR u IN users
@@ -283,6 +284,10 @@ FOR u IN users
 The above query removes the `notNeeded` attribute from the documents and updates
 the `foobar` attribute normally.
 
+Only top-level attributes and sub-attributes can be removed this way
+(e.g. `{ attr: { sub: null } }`) but not attributes of objects that are nested
+inside of arrays (e.g. `{ attr: [ { nested: null } ] }`).
+
 ### `mergeObjects`
 
 The option `mergeObjects` controls whether object contents are

3.10/aql/operations-upsert.md

@@ -19,8 +19,15 @@ Syntax
 
 The syntax for upsert and repsert operations is:
 
-<pre><code>UPSERT <em>searchExpression</em> INSERT <em>insertExpression</em> UPDATE <em>updateExpression</em> IN <em>collection</em>
-UPSERT <em>searchExpression</em> INSERT <em>insertExpression</em> REPLACE <em>updateExpression</em> IN <em>collection</em></code></pre>
+<pre><code>UPSERT <em>searchExpression</em>
+INSERT <em>insertExpression</em>
+UPDATE <em>updateExpression</em>
+IN <em>collection</em></code></pre>
+
+<pre><code>UPSERT <em>searchExpression</em>
+INSERT <em>insertExpression</em>
+REPLACE <em>updateExpression</em>
+IN <em>collection</em></code></pre>
 
 Both variants can optionally end with an `OPTIONS { … }` clause.
 
@@ -68,9 +75,27 @@ when trying to violate unique key constraints.
 
 ### `keepNull`
 
-When updating or replacing an attribute with a null value, ArangoDB will not remove the 
-attribute from the document but store a null value for it. To get rid of attributes in 
-an upsert operation, set them to null and provide the `keepNull` option.
+When updating an attribute to the `null` value, ArangoDB does not remove the
+attribute from the document but stores this `null` value. To remove attributes
+in an update operation, set them to `null` and set the `keepNull` option to
+`false`. This removes the attributes you specify but not any previously stored
+attributes with the `null` value:
+
+```aql
+UPSERT { _key: "mary" }
+INSERT { _key: "mary", name: "Mary", notNeeded: 123 }
+UPDATE { foobar: true, notNeeded: null }
+IN users OPTIONS { keepNull: false }
+```
+
+If no document with the key `mary` exists, the above query creates such a user
+document with a `notNeeded` attribute. If it exists already, it removes the
+`notNeeded` attribute from the document and updates the `foobar` attribute
+normally.
+
+Only top-level attributes and sub-attributes can be removed this way
+(e.g. `{ attr: { sub: null } }`) but not attributes of objects that are nested
+inside of arrays (e.g. `{ attr: [ { nested: null } ] }`).
 
 ### `mergeObjects`
 

3.10/generated/Examples/001_collectionAll.generated

@@ -2,62 +2,62 @@ arangosh&gt; db.five.insert({ <span class="hljs-attr">name</span> : <span class=
 { 
   <span class="hljs-string">&quot;_id&quot;</span> : <span class="hljs-string">&quot;five/104&quot;</span>, 
   <span class="hljs-string">&quot;_key&quot;</span> : <span class="hljs-string">&quot;104&quot;</span>, 
-  <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_gM2ZmBW---&quot;</span> 
+  <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_gNZFFvK---&quot;</span> 
 }
 arangosh&gt; db.five.insert({ <span class="hljs-attr">name</span> : <span class="hljs-string">&quot;two&quot;</span> });
 { 
   <span class="hljs-string">&quot;_id&quot;</span> : <span class="hljs-string">&quot;five/106&quot;</span>, 
   <span class="hljs-string">&quot;_key&quot;</span> : <span class="hljs-string">&quot;106&quot;</span>, 
-  <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_gM2ZmBa---&quot;</span> 
+  <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_gNZFFvO---&quot;</span> 
 }
 arangosh&gt; db.five.insert({ <span class="hljs-attr">name</span> : <span class="hljs-string">&quot;three&quot;</span> });
 { 
   <span class="hljs-string">&quot;_id&quot;</span> : <span class="hljs-string">&quot;five/108&quot;</span>, 
   <span class="hljs-string">&quot;_key&quot;</span> : <span class="hljs-string">&quot;108&quot;</span>, 
-  <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_gM2ZmBa--_&quot;</span> 
+  <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_gNZFFvO--_&quot;</span> 
 }
 arangosh&gt; db.five.insert({ <span class="hljs-attr">name</span> : <span class="hljs-string">&quot;four&quot;</span> });
 { 
   <span class="hljs-string">&quot;_id&quot;</span> : <span class="hljs-string">&quot;five/110&quot;</span>, 
   <span class="hljs-string">&quot;_key&quot;</span> : <span class="hljs-string">&quot;110&quot;</span>, 
-  <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_gM2ZmBe---&quot;</span> 
+  <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_gNZFFvS---&quot;</span> 
 }
 arangosh&gt; db.five.insert({ <span class="hljs-attr">name</span> : <span class="hljs-string">&quot;five&quot;</span> });
 { 
   <span class="hljs-string">&quot;_id&quot;</span> : <span class="hljs-string">&quot;five/112&quot;</span>, 
   <span class="hljs-string">&quot;_key&quot;</span> : <span class="hljs-string">&quot;112&quot;</span>, 
-  <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_gM2ZmBe--_&quot;</span> 
+  <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_gNZFFvS--_&quot;</span> 
 }
 arangosh&gt; db.five.all().toArray();
 [ 
   { 
     <span class="hljs-string">&quot;_key&quot;</span> : <span class="hljs-string">&quot;104&quot;</span>, 
     <span class="hljs-string">&quot;_id&quot;</span> : <span class="hljs-string">&quot;five/104&quot;</span>, 
-    <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_gM2ZmBW---&quot;</span>, 
+    <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_gNZFFvK---&quot;</span>, 
     <span class="hljs-string">&quot;name&quot;</span> : <span class="hljs-string">&quot;one&quot;</span> 
   }, 
   { 
     <span class="hljs-string">&quot;_key&quot;</span> : <span class="hljs-string">&quot;106&quot;</span>, 
     <span class="hljs-string">&quot;_id&quot;</span> : <span class="hljs-string">&quot;five/106&quot;</span>, 
-    <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_gM2ZmBa---&quot;</span>, 
+    <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_gNZFFvO---&quot;</span>, 
     <span class="hljs-string">&quot;name&quot;</span> : <span class="hljs-string">&quot;two&quot;</span> 
   }, 
   { 
     <span class="hljs-string">&quot;_key&quot;</span> : <span class="hljs-string">&quot;108&quot;</span>, 
     <span class="hljs-string">&quot;_id&quot;</span> : <span class="hljs-string">&quot;five/108&quot;</span>, 
-    <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_gM2ZmBa--_&quot;</span>, 
+    <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_gNZFFvO--_&quot;</span>, 
     <span class="hljs-string">&quot;name&quot;</span> : <span class="hljs-string">&quot;three&quot;</span> 
   }, 
   { 
     <span class="hljs-string">&quot;_key&quot;</span> : <span class="hljs-string">&quot;110&quot;</span>, 
     <span class="hljs-string">&quot;_id&quot;</span> : <span class="hljs-string">&quot;five/110&quot;</span>, 
-    <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_gM2ZmBe---&quot;</span>, 
+    <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_gNZFFvS---&quot;</span>, 
     <span class="hljs-string">&quot;name&quot;</span> : <span class="hljs-string">&quot;four&quot;</span> 
   }, 
   { 
     <span class="hljs-string">&quot;_key&quot;</span> : <span class="hljs-string">&quot;112&quot;</span>, 
     <span class="hljs-string">&quot;_id&quot;</span> : <span class="hljs-string">&quot;five/112&quot;</span>, 
-    <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_gM2ZmBe--_&quot;</span>, 
+    <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_gNZFFvS--_&quot;</span>, 
     <span class="hljs-string">&quot;name&quot;</span> : <span class="hljs-string">&quot;five&quot;</span> 
   } 
 ]

3.10/generated/Examples/002_collectionAllNext.generated

@@ -2,44 +2,44 @@ arangosh&gt; db.five.insert({ <span class="hljs-attr">name</span> : <span class=
 { 
   <span class="hljs-string">&quot;_id&quot;</span> : <span class="hljs-string">&quot;five/124&quot;</span>, 
   <span class="hljs-string">&quot;_key&quot;</span> : <span class="hljs-string">&quot;124&quot;</span>, 
-  <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_gM2ZmDG--_&quot;</span> 
+  <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_gNZFFw6---&quot;</span> 
 }
 arangosh&gt; db.five.insert({ <span class="hljs-attr">name</span> : <span class="hljs-string">&quot;two&quot;</span> });
 { 
   <span class="hljs-string">&quot;_id&quot;</span> : <span class="hljs-string">&quot;five/126&quot;</span>, 
   <span class="hljs-string">&quot;_key&quot;</span> : <span class="hljs-string">&quot;126&quot;</span>, 
-  <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_gM2ZmDK---&quot;</span> 
+  <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_gNZFFw6--_&quot;</span> 
 }
 arangosh&gt; db.five.insert({ <span class="hljs-attr">name</span> : <span class="hljs-string">&quot;three&quot;</span> });
 { 
   <span class="hljs-string">&quot;_id&quot;</span> : <span class="hljs-string">&quot;five/128&quot;</span>, 
   <span class="hljs-string">&quot;_key&quot;</span> : <span class="hljs-string">&quot;128&quot;</span>, 
-  <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_gM2ZmDK--_&quot;</span> 
+  <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_gNZFFx----&quot;</span> 
 }
 arangosh&gt; db.five.insert({ <span class="hljs-attr">name</span> : <span class="hljs-string">&quot;four&quot;</span> });
 { 
   <span class="hljs-string">&quot;_id&quot;</span> : <span class="hljs-string">&quot;five/130&quot;</span>, 
   <span class="hljs-string">&quot;_key&quot;</span> : <span class="hljs-string">&quot;130&quot;</span>, 
-  <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_gM2ZmDO---&quot;</span> 
+  <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_gNZFFx---_&quot;</span> 
 }
 arangosh&gt; db.five.insert({ <span class="hljs-attr">name</span> : <span class="hljs-string">&quot;five&quot;</span> });
 { 
   <span class="hljs-string">&quot;_id&quot;</span> : <span class="hljs-string">&quot;five/132&quot;</span>, 
   <span class="hljs-string">&quot;_key&quot;</span> : <span class="hljs-string">&quot;132&quot;</span>, 
-  <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_gM2ZmDO--_&quot;</span> 
+  <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_gNZFFxC---&quot;</span> 
 }
 arangosh&gt; db.five.all().limit(<span class="hljs-number">2</span>).toArray();
 [ 
   { 
     <span class="hljs-string">&quot;_key&quot;</span> : <span class="hljs-string">&quot;124&quot;</span>, 
     <span class="hljs-string">&quot;_id&quot;</span> : <span class="hljs-string">&quot;five/124&quot;</span>, 
-    <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_gM2ZmDG--_&quot;</span>, 
+    <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_gNZFFw6---&quot;</span>, 
     <span class="hljs-string">&quot;name&quot;</span> : <span class="hljs-string">&quot;one&quot;</span> 
   }, 
   { 
     <span class="hljs-string">&quot;_key&quot;</span> : <span class="hljs-string">&quot;126&quot;</span>, 
     <span class="hljs-string">&quot;_id&quot;</span> : <span class="hljs-string">&quot;five/126&quot;</span>, 
-    <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_gM2ZmDK---&quot;</span>, 
+    <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_gNZFFw6--_&quot;</span>, 
     <span class="hljs-string">&quot;name&quot;</span> : <span class="hljs-string">&quot;two&quot;</span> 
   } 
 ]