doc: explain use of json_populate_record{set}()

The set-returning nature of these functions make their use unclear. The
modified paragraph was added in PG 9.4.

Reported-by: [email protected]
Discussion:  https://postgr.es/m/152571684246.9460.18059951267371255159@wrigleys.postgresql.org

Backpatch-through: 9.4

diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index b851fe023a72dc65f031fed9ded0647c0d9277f0..d73fdf6ca49c03a3c6dff7603fe407754255fa70 100644 (file)
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -11997,13 +11997,27 @@ table2-mapping
 
   
     
-      In json_populate_record, json_populate_recordset,
-      json_to_record and json_to_recordset,
-      type coercion from the JSON is best effort and may not result
-      in desired values for some types.  JSON keys are matched to
-      identical column names in the target row type.  JSON fields that do not
-      appear in the target row type will be omitted from the output, and
-      target columns that do not match any JSON field will simply be NULL.
+      While the examples for the functions
+      json_populate_record,
+      json_populate_recordset,
+      json_to_record and
+      json_to_recordset use constants, the typical use
+      would be to reference a table in the FROM clause
+      and use one of its json or jsonb columns
+      as an argument to the function.  Extracted key values can then be
+      referenced in other parts of the query, like WHERE
+      clauses and target lists.  Extracting multiple values in this
+      way can improve performance over extracting them separately with
+      per-key operators.
+    
+
+    
+      JSON keys are matched to identical column names in the target
+      row type.  JSON type coercion for these functions is best
+      effort and may not result in desired values for some types.
+      JSON fields that do not appear in the target row type will be
+      omitted from the output, and target columns that do not match any
+      JSON field will simply be NULL.