diff --git a/learn/engine/datatypes.mdx b/learn/engine/datatypes.mdx
index e969947f34..efc35b074f 100644
--- a/learn/engine/datatypes.mdx
+++ b/learn/engine/datatypes.mdx
@@ -288,6 +288,10 @@ The best way to work around this limitation is reformatting your data. The above
 ]
 ```
 
+### Updating object fields
+
+Object fields cannot be partially updated. Updating an object field with either the `PUT` or `POST` routes with an object fully replaces that value and removes any omitted subfields. Dot notation is also not supported when updating a document.
+
 ## Possible tokenization issues
 
 Even if it behaves exactly as expected, the tokenization process may lead to counterintuitive results in some cases, such as:
diff --git a/reference/api/documents.mdx b/reference/api/documents.mdx
index 0985e74368..57ef98d9bb 100644
--- a/reference/api/documents.mdx
+++ b/reference/api/documents.mdx
@@ -356,7 +356,15 @@ You can use this `taskUid` to get more details on [the status of the task](/refe
 
 Add a list of documents or update them if they already exist. If the provided index does not exist, it will be created.
 
-If you send an already existing document (same [document id](/learn/getting_started/primary_key#document-id)) the old document will be only partially updated according to the fields of the new document. Thus, any fields not present in the new document are kept and remain unchanged. Partial updates apply only to top-level fields: updating an object field replaces the entire object, removing any omitted subfields.
+If you send an already existing document (same [document id](/learn/getting_started/primary_key#document-id)) the old document will be only partially updated according to the fields of the new document. Any fields not present in the new document are kept and remain unchanged.
+
+<Warning>
+Partial updates apply only to top-level fields. You cannot perform a partial update of a nested field.
+
+Updating an object replaces the entire object and removes any omitted subfields.
+
+Using dot notation in an update request creates a new flat attribute instead of updating the existing nested field.
+</Warning>
 
 To completely overwrite a document, check out the [add or replace documents route](/reference/api/documents#add-or-replace-documents).