Refs #34964 -- Doc'd that Q expression order is preserved.

1 files changed, 12 insertions, 0 deletions

diff --git a/docs/ref/models/constraints.txt b/docs/ref/models/constraints.txt
index cc308cedf2..0d6d87afbe 100644
--- a/docs/ref/models/constraints.txt
+++ b/docs/ref/models/constraints.txt
@@ -119,6 +119,18 @@ specifies the check you want the constraint to enforce.
 For example, ``CheckConstraint(check=Q(age__gte=18), name='age_gte_18')``
 ensures the age field is never less than 18.
 
+.. admonition:: Expression order
+
+    ``Q`` argument order is not necessarily preserved, however the order of
+    ``Q`` expressions themselves are preserved. This may be important for
+    databases that preserve check constraint expression order for performance
+    reasons. For example, use the following format if order matters::
+
+        CheckConstraint(
+            check=Q(age__gte=18) & Q(expensive_check=condition),
+            name="age_gte_18_and_others",
+        )
+
 .. admonition:: Oracle
 
     Checks with nullable fields on Oracle must include a condition allowing for