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))); + + + + SQL/JSON Query Functions