diff --git a/doc/src/sgml/func/func-json.sgml b/doc/src/sgml/func/func-json.sgml
index 1ec73cff464..595110bd7e9 100644
--- a/doc/src/sgml/func/func-json.sgml
+++ b/doc/src/sgml/func/func-json.sgml
@@ -3189,6 +3189,45 @@ $.* ? (@ like_regex "^\\d+$")
or a character string that can be successfully cast to jsonb.
+
+
+ Deciding between SQL/JSON functions and PostgreSQL-specific operators:
+
+
+
+
+ Use SQL/JSON functions (e.g., JSON_EXISTS,
+ JSON_QUERY, JSON_VALUE)
+ when writing portable applications, or when you need granular control over empty/error
+ handling (for example, DEFAULT ... ON EMPTY and ... ON ERROR).
+
+
+
+
+ Use operators (e.g., ->>, @?,
+ @@) for conciseness in ad-hoc queries, and when you want to take advantage
+ of GIN operator classes that index these operators.
+
+
+
+
+
+
+
+ GIN indexes on jsonb support different operator classes.
+ The default jsonb_ops operator class supports several operators,
+ while jsonb_path_ops supports fewer operators but is typically smaller
+ and faster for @>, @?, and @@ queries.
+
+
+ For queries that frequently filter on specific JSON scalar values extracted at known paths,
+ a B-tree expression index can be more efficient than a general GIN index. For example:
+
+ CREATE INDEX idx_user_id ON users ((json_value(data, '$.user_id' RETURNING int)));
+
+
+
+