From 662d684d0eddffb381369e909d8c70bd723025ac Mon Sep 17 00:00:00 2001
From: Luca Dametto <postgresqlmailing@damettoluca.com>
Date: Sun, 15 Dec 2024 18:33:13 +0100
Subject: [PATCH] Improved documentation for Syntax, s. Operators Precedence

---
 doc/src/sgml/syntax.sgml | 12 +++++++++++-
 1 file changed, 11 insertions(+), 1 deletion(-)

diff --git a/doc/src/sgml/syntax.sgml b/doc/src/sgml/syntax.sgml
index 916189a7d6..79f3b9ce5f 100644
--- a/doc/src/sgml/syntax.sgml
+++ b/doc/src/sgml/syntax.sgml
@@ -1111,7 +1111,7 @@ CAST ( '<replaceable>string</replaceable>' AS <replaceable>type</replaceable> )
        <entry><token>&lt;</token> <token>&gt;</token> <token>=</token> <token>&lt;=</token> <token>&gt;=</token> <token>&lt;&gt;</token>
 </entry>
        <entry></entry>
-       <entry>comparison operators</entry>
+       <entry>comparison operators *</entry>
       </row>
 
       <row>
@@ -1151,6 +1151,16 @@ CAST ( '<replaceable>string</replaceable>' AS <replaceable>type</replaceable> )
     matter what yours does.
    </para>
 
+   <para>
+    * Note that <productname>PostgreSQL</productname> follows SQL's 3VL,
+    due to that some comparisons regarding NULL values may not work as
+    you might expect.
+    As an example, two nullable columns that contain NULL, when compared using
+    the <literal>OPERATOR</literal> <token>=</token>, will return nothing
+    instead of TRUE like your programming language may do.
+    In this case, only 'IS NOT DISTINCT FROM' would return the result you expect.
+   </para>
+   
    <para>
     When a schema-qualified operator name is used in the
     <literal>OPERATOR</literal> syntax, as for example in:
-- 
2.39.5 (Apple Git-154)