From 957b86a5abaffaf7709270332f24cad9ad3ee8ec Mon Sep 17 00:00:00 2001
From: Bruce Momjian <bruce@momjian.us>
Date: Tue, 19 Jun 2018 13:43:40 -0400
Subject: [PATCH] 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: yshaladi@denodo.com
Discussion: https://postgr.es/m/152571684246.9460.18059951267371255159@wrigleys.postgresql.org
Backpatch-through: 9.4
---
doc/src/sgml/func.sgml | 28 +++++++++++++++++++++-------
1 file changed, 21 insertions(+), 7 deletions(-)
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 6f89512c040..75f6d3b3dec 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -10843,14 +10843,28 @@ table2-mapping
<note>
<para>
- In <function>json_populate_record</>, <function>json_populate_recordset</>,
- <function>json_to_record</> and <function>json_to_recordset</>,
- type coercion from the JSON is <quote>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
+ <function>json_populate_record</function>,
+ <function>json_populate_recordset</function>,
+ <function>json_to_record</function> and
+ <function>json_to_recordset</function> use constants, the typical use
+ would be to reference a table in the <literal>FROM</literal> clause
+ and use one of its <type>json</type> or <type>jsonb</type> columns
+ as an argument to the function. Extracted key values can then be
+ referenced in other parts of the query, like <literal>WHERE</literal>
+ clauses and target lists. Extracting multiple values in this
+ way can improve performance over extracting them separately with
+ per-key operators.
</para>
+
+ <para>
+ JSON keys are matched to identical column names in the target
+ row type. JSON type coercion for these functions is <quote>best
+ effort</quote> 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.
+ </para>
</note>
<note>
--
GitLab