From 4152f67645474a3acccd64c04558d2e633053705 Mon Sep 17 00:00:00 2001
From: "Krzysztof Magusiak (krma)" <krma@odoo.com>
Date: Thu, 13 Nov 2025 13:38:05 +0000
Subject: [PATCH] [IMP] core: new SQL alias builder

Update the documentation with more recent examples of usage of the Query
object.

closes odoo/documentation#15257

Related: odoo/odoo#234156
Related: odoo/enterprise#98682
Related: odoo/upgrade#8757
Signed-off-by: Krzysztof Magusiak (krma) <krma@odoo.com>
---
 content/developer/reference/backend/orm.rst   | 38 ++++++++++++++++++-
 .../reference/backend/orm/changelog.rst       |  1 +
 2 files changed, 38 insertions(+), 1 deletion(-)

diff --git a/content/developer/reference/backend/orm.rst b/content/developer/reference/backend/orm.rst
index 8bb260b77..f13ba0cf4 100644
--- a/content/developer/reference/backend/orm.rst
+++ b/content/developer/reference/backend/orm.rst
@@ -712,6 +712,7 @@ Useful environment methods
 .. automethod:: Environment.is_admin
 .. automethod:: Environment.is_system
 .. automethod:: Environment.execute_query
+    :noindex:
 
 Altering the environment
 ------------------------
@@ -749,9 +750,32 @@ The recommended way to build SQL queries is to use the wrapper object
 
 .. autoclass:: odoo.tools.SQL
 
-    .. automethod:: SQL.join
     .. automethod:: SQL.identifier
 
+:func:`~odoo.api.Environment.execute_query` environment method allows to flush
+(see later), execute and fetch results at once.  To translate model fields into
+SQL, and build queries, a useful abstraction is provided in
+
+.. autoclass:: odoo.models.Query
+
+    .. automethod:: Query.select
+    .. automethod:: Query.subselect
+    .. automethod:: Query.is_empty
+    .. automethod:: Query.get_result_ids
+    .. autoproperty:: Query.table
+
+.. example::
+
+    .. code-block:: python
+
+        query = Query(self.env['model'])
+        query.add_where(SQL("%s > %s", query.table.some_field, 'test'))
+        query.select()
+        # SELECT model.id
+        # FROM model
+        # WHERE model.some_field > 'test'
+
+
 One important thing to know about models is that they don't necessarily perform
 database updates right away. Indeed, for performance reasons, the framework
 delays the recomputation of fields after modifying records. And some database
@@ -781,6 +805,11 @@ when flushing.
 
 .. automethod:: Model.flush_recordset
 
+.. automethod:: odoo.api.Environment.execute_query
+
+When using the Query builder and ``execute_query``, model flushes are done based
+on the metadata in the ``SQL``.
+
 Because models use the same cursor and the :class:`~odoo.api.Environment`
 holds various caches, these caches must be invalidated when *altering* the
 database in raw SQL, or further uses of models may become incoherent. It is
@@ -799,6 +828,13 @@ SQL, but not ``SELECT`` (which simply reads the database).
         # invalidate 'state' from the cache
         self.env['model'].invalidate_model(['state'])
 
+    .. code-block:: python
+
+        # get name and country name for all records, flushing and joins are
+        # done automatically
+        query = Query(self.env['model'])
+        self.env.execute_query(query.select(SQL(query.table.name, query.table.country_id.name)))
+
 Just like flushing, one can invalidate either the whole cache, the cache of all
 the records of a model, or the cache of specific records. One can even
 invalidate specific fields on some records or all records of a model. As the
diff --git a/content/developer/reference/backend/orm/changelog.rst b/content/developer/reference/backend/orm/changelog.rst
index b61170de8..7e3f79a75 100644
--- a/content/developer/reference/backend/orm/changelog.rst
+++ b/content/developer/reference/backend/orm/changelog.rst
@@ -8,6 +8,7 @@ Odoo Online version 19.1
 ========================
 
 - New API for ir.config_parameter. See `#223180 <https://github.com/odoo/odoo/pull/223180>`_.
+- New API to build SQL. See `#234156 <https://github.com/odoo/odoo/pull/234156>`_.
 
 Odoo version 19.0
 =================