From cf12d3173991350681a00a168cb865972b042ef0 Mon Sep 17 00:00:00 2001
From: "Krzysztof Magusiak (krma)" <krma@odoo.com>
Date: Mon, 2 Sep 2024 14:45:49 +0000
Subject: [PATCH] [IMP] developer/reference: new usage of Model.mapped()

odoo/odoo#185630
---
 content/developer/reference/backend/orm.rst          | 12 ++++++++----
 .../developer/reference/backend/orm/changelog.rst    |  2 ++
 content/developer/tutorials/pdf_reports.rst          |  2 +-
 3 files changed, 11 insertions(+), 5 deletions(-)

diff --git a/content/developer/reference/backend/orm.rst b/content/developer/reference/backend/orm.rst
index 638cd9d72..a08df6ab2 100644
--- a/content/developer/reference/backend/orm.rst
+++ b/content/developer/reference/backend/orm.rst
@@ -1086,13 +1086,17 @@ Map
 
 .. note::
 
-    Since V13, multi-relational field access is supported and works like a mapped call:
+    Accessing relational attributes returns the union of the recordsets.
+    You should probably always use simple attribute access and only ``mapped``
+    when you may have multiple records and you want to get a value for each
+    record in the recordset.
 
     .. code-block:: python3
 
-        records.partner_id  # == records.mapped('partner_id')
-        records.partner_id.bank_ids  # == records.mapped('partner_id.bank_ids')
-        records.partner_id.mapped('name')  # == records.mapped('partner_id.name')
+        records.partner_id  # union of partner_id from records
+        records.mapped('partner_id')  # [record['partner_id'] for record in records]
+        records.partner_id.bank_ids  # union of banks of partners of records
+        records.mapped('partner_id.name')  # for each record, get the name of the partner
 
 Sort
 ~~~~
diff --git a/content/developer/reference/backend/orm/changelog.rst b/content/developer/reference/backend/orm/changelog.rst
index 661454070..5d624f707 100644
--- a/content/developer/reference/backend/orm/changelog.rst
+++ b/content/developer/reference/backend/orm/changelog.rst
@@ -10,6 +10,8 @@ Odoo Online version 18.1
 - Declare constraints and indexes as model attributes with `#175783 <https://github.com/odoo/odoo/pull/175783>`_.
 - The `json` controllers have been renamed to `jsonrpc`. They are called the same, only the
   `type` in the python files changed. See `#183636 <https://github.com/odoo/odoo/pull/183636>`_.
+- Models' `mapped` function now behaves more like the `map` function: it always returns a
+  list where each element of the recordset is mapped. See `#185630 <https://github.com/odoo/odoo/pull/185630>`_.
 
 Odoo version 18.0
 =================
diff --git a/content/developer/tutorials/pdf_reports.rst b/content/developer/tutorials/pdf_reports.rst
index 614ff5894..e38dd1e9e 100644
--- a/content/developer/tutorials/pdf_reports.rst
+++ b/content/developer/tutorials/pdf_reports.rst
@@ -124,7 +124,7 @@ our minimal property offers template file:
                                     </tr>
                                 </thead>
                                 <tbody>
-                                    <t t-set="offers" t-value="property.mapped('offer_ids')"/>
+                                    <t t-set="offers" t-value="property.offer_ids"/>
                                     <tr t-foreach="offers" t-as="offer">
                                         <td>
                                             <span t-field="offer.price"/>