docs: limitation when selecting related object that was modified by n after insert trigger

docs/references/api/resource_embedding.rst

@@ -816,6 +816,23 @@ Response:
  }
  }
 
+.. note::
+
+ Selecting a related object right after doing an insert may give unexpected results if said object was modified in a trigger.
+ For example, let's say there's an ``AFTER INSERT`` trigger on ``films`` that inserts a new record to ``technical_specs``.
+ Doing the same ``POST`` request as above, but selecting ``select=title,technical_spec(*)`` instead, it would return:
+
+ .. code-block:: json
+
+ {
+ "title": "127 hours",
+ "techinal_specs": null
+ }
+
+ Since PostgREST does the insertion in a single transaction, the selection is done before the changes are made to the related table, that's why the ``technical_specs`` is empty.
+ In the future we'll implement the insertions of tables and embedded resources at the same time.
+ For now, an alternative is to use :ref:`table_functions` instead.
+
 .. _nested_embedding:
 
 Nested Embedding