diff options
| author | Bruce Momjian | 2018-06-19 17:43:40 +0000 |
|---|---|---|
| committer | Bruce Momjian | 2018-06-19 17:43:40 +0000 |
| commit | 87a19eb9bf373f51e966ab496cce6bf3ee9cd909 (patch) | |
| tree | 40bbca7c8adb73e24ce3c5731aaa959bb4e0d4e5 | |
| parent | fb6accd27b99f5f91a7e9e5bd32b98a53fc6d6b8 (diff) | |
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
| -rw-r--r-- | doc/src/sgml/func.sgml | 28 |
1 files changed, 21 insertions, 7 deletions
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml index b851fe023a7..d73fdf6ca49 100644 --- a/doc/src/sgml/func.sgml +++ b/doc/src/sgml/func.sgml @@ -11997,13 +11997,27 @@ table2-mapping <note> <para> - In <function>json_populate_record</function>, <function>json_populate_recordset</function>, - <function>json_to_record</function> and <function>json_to_recordset</function>, - type coercion from the JSON is <quote>best effort</quote> 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> |