Docs: Order of json aggregate functions
The order of json related aggregate functions in the docs is currently
like this:
[...]
json_agg
json_objectagg
json_object_agg
json_object_agg_strict
json_object_agg_unique
json_arrayagg
json_object_agg_unique_strict
max
min
range_agg
range_intersect_agg
json_agg_strict
[...]
json_arrayagg and json_agg_strict are out of place.
Attached patch puts them in the right spot. This is the same down to v16.
Best,
Wolfgang
Attachments:
v1-0001-Fix-order-of-json-aggregate-functions-in-docs.patchtext/x-patch; charset=UTF-8; name=v1-0001-Fix-order-of-json-aggregate-functions-in-docs.patchDownload
From ad857a824d893a3e421c6c577c1215f71c1ebfe3 Mon Sep 17 00:00:00 2001
From: Wolfgang Walther <walther@technowledgy.de>
Date: Wed, 19 Jun 2024 19:40:49 +0200
Subject: [PATCH v1] Fix order of json aggregate functions in docs
---
doc/src/sgml/func.sgml | 96 +++++++++++++++++++++---------------------
1 file changed, 48 insertions(+), 48 deletions(-)
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 2609269610b..c3b342d832f 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -21790,6 +21790,54 @@ SELECT NULLIF(value, '(none)') ...
<entry>No</entry>
</row>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>json_agg_strict</primary>
+ </indexterm>
+ <function>json_agg_strict</function> ( <type>anyelement</type> )
+ <returnvalue>json</returnvalue>
+ </para>
+ <para role="func_signature">
+ <indexterm>
+ <primary>jsonb_agg_strict</primary>
+ </indexterm>
+ <function>jsonb_agg_strict</function> ( <type>anyelement</type> )
+ <returnvalue>jsonb</returnvalue>
+ </para>
+ <para>
+ Collects all the input values, skipping nulls, into a JSON array.
+ Values are converted to JSON as per <function>to_json</function>
+ or <function>to_jsonb</function>.
+ </para></entry>
+ <entry>No</entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm><primary>json_arrayagg</primary></indexterm>
+ <function>json_arrayagg</function> (
+ <optional> <replaceable>value_expression</replaceable> </optional>
+ <optional> <literal>ORDER BY</literal> <replaceable>sort_expression</replaceable> </optional>
+ <optional> { <literal>NULL</literal> | <literal>ABSENT</literal> } <literal>ON NULL</literal> </optional>
+ <optional> <literal>RETURNING</literal> <replaceable>data_type</replaceable> <optional> <literal>FORMAT JSON</literal> <optional> <literal>ENCODING UTF8</literal> </optional> </optional> </optional>)
+ </para>
+ <para>
+ Behaves in the same way as <function>json_array</function>
+ but as an aggregate function so it only takes one
+ <replaceable>value_expression</replaceable> parameter.
+ If <literal>ABSENT ON NULL</literal> is specified, any NULL
+ values are omitted.
+ If <literal>ORDER BY</literal> is specified, the elements will
+ appear in the array in that order rather than in the input order.
+ </para>
+ <para>
+ <literal>SELECT json_arrayagg(v) FROM (VALUES(2),(1)) t(v)</literal>
+ <returnvalue>[2, 1]</returnvalue>
+ </para></entry>
+ <entry>No</entry>
+ </row>
+
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm><primary>json_objectagg</primary></indexterm>
@@ -21900,31 +21948,6 @@ SELECT NULLIF(value, '(none)') ...
<entry>No</entry>
</row>
- <row>
- <entry role="func_table_entry"><para role="func_signature">
- <indexterm><primary>json_arrayagg</primary></indexterm>
- <function>json_arrayagg</function> (
- <optional> <replaceable>value_expression</replaceable> </optional>
- <optional> <literal>ORDER BY</literal> <replaceable>sort_expression</replaceable> </optional>
- <optional> { <literal>NULL</literal> | <literal>ABSENT</literal> } <literal>ON NULL</literal> </optional>
- <optional> <literal>RETURNING</literal> <replaceable>data_type</replaceable> <optional> <literal>FORMAT JSON</literal> <optional> <literal>ENCODING UTF8</literal> </optional> </optional> </optional>)
- </para>
- <para>
- Behaves in the same way as <function>json_array</function>
- but as an aggregate function so it only takes one
- <replaceable>value_expression</replaceable> parameter.
- If <literal>ABSENT ON NULL</literal> is specified, any NULL
- values are omitted.
- If <literal>ORDER BY</literal> is specified, the elements will
- appear in the array in that order rather than in the input order.
- </para>
- <para>
- <literal>SELECT json_arrayagg(v) FROM (VALUES(2),(1)) t(v)</literal>
- <returnvalue>[2, 1]</returnvalue>
- </para></entry>
- <entry>No</entry>
- </row>
-
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
@@ -22033,29 +22056,6 @@ SELECT NULLIF(value, '(none)') ...
<entry>No</entry>
</row>
- <row>
- <entry role="func_table_entry"><para role="func_signature">
- <indexterm>
- <primary>json_agg_strict</primary>
- </indexterm>
- <function>json_agg_strict</function> ( <type>anyelement</type> )
- <returnvalue>json</returnvalue>
- </para>
- <para role="func_signature">
- <indexterm>
- <primary>jsonb_agg_strict</primary>
- </indexterm>
- <function>jsonb_agg_strict</function> ( <type>anyelement</type> )
- <returnvalue>jsonb</returnvalue>
- </para>
- <para>
- Collects all the input values, skipping nulls, into a JSON array.
- Values are converted to JSON as per <function>to_json</function>
- or <function>to_jsonb</function>.
- </para></entry>
- <entry>No</entry>
- </row>
-
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
--
2.45.1
Am Mo., 22. Juli 2024 um 15:19 Uhr schrieb Wolfgang Walther
<walther@technowledgy.de>:
The order of json related aggregate functions in the docs is currently
like this:[...]
json_agg
json_objectagg
json_object_agg
json_object_agg_strict
json_object_agg_unique
json_arrayagg
json_object_agg_unique_strict
max
min
range_agg
range_intersect_agg
json_agg_strict
[...]json_arrayagg and json_agg_strict are out of place.
Attached patch puts them in the right spot. This is the same down to v16.
I compiled and it worked and didn't throw an error.
The changes to the patch seem useful in my perspective, for making it
easier to find the functions in the documentation, so people will find
them easier.
There is another table which isn't sorted too, the "Hypothetical-Set
Aggregate Functions". Which would be in need of an alphabetical
sorting too, if all the tables on this side
of the documentation should look alike.
Regards
Marlene
On Tue, 2024-07-23 at 11:45 +0200, Marlene Reiterer wrote:
Am Mo., 22. Juli 2024 um 15:19 Uhr schrieb Wolfgang Walther <walther@technowledgy.de>:
The order of json related aggregate functions in the docs is currently
like this:[...]
json_agg
json_objectagg
json_object_agg
json_object_agg_strict
json_object_agg_unique
json_arrayagg
json_object_agg_unique_strict
max
min
range_agg
range_intersect_agg
json_agg_strict
[...]json_arrayagg and json_agg_strict are out of place.
Attached patch puts them in the right spot. This is the same down to v16.
I compiled and it worked and didn't throw an error.
The changes to the patch seem useful in my perspective, for making it
easier to find the functions in the documentation, so people will find
them easier.There is another table which isn't sorted too, the "Hypothetical-Set
Aggregate Functions". Which would be in need of an alphabetical
sorting too, if all the tables on this side
of the documentation should look alike.
There are only four hypothetical-set aggregate functions, so it is no problem
to find a function in that list.
I would say that it makes sense to apply the proposed patch, even if we
don't sort that short list.
Yours,
Laurenz Albe
On Thu, 20 Jun 2024 at 05:50, Wolfgang Walther <walther@technowledgy.de> wrote:
json_arrayagg and json_agg_strict are out of place.
Attached patch puts them in the right spot. This is the same down to v16.
Thank you. I've pushed this and ended up backpatching to 16 too. It's
quite hard to unsee the broken order once seen.
It seems worth the backpatch both to reduce pain for any future
backpatches and also because the aggregates seemed rather badly
placed.
David