database/postgres
1
0
Fork 0
mirror of https://github.com/postgres/postgres.git synced 2025-06-25 01:02:05 +03:00
Code Activity

Doc: improve documentation about width_bucket().

Browse Source 
Specify whether the bucket bounds are inclusive or exclusive,
and improve some other vague language.  Explain the behavior that
occurs when the "low" bound is greater than the "high" bound.
Make width_bucket_numeric's comment more like that for
width_bucket_float8, in particular noting that infinite
bounds are rejected (since they became possible in v14).

Reported-by: Ben Peachey Higdon <bpeacheyhigdon@gmail.com>
Author: Robert Treat <rob@xzilla.net>
Co-authored-by: Tom Lane <tgl@sss.pgh.pa.us>
Reviewed-by: Dean Rasheed <dean.a.rasheed@gmail.com>
Discussion: https://postgr.es/m/2BD74F86-5B89-4AC1-8F13-23CED3546AC1@gmail.com
Backpatch-through: 13
This commit is contained in:
Tom Lane
2025-06-21 12:52:37 -04:00
parent 27af8b9be8
commit 9bd588f87d
3 changed files with 20 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files

18
doc/src/sgml/func.sgml
View File

@ -1739,13 +1739,23 @@ repeat('Pg', 4) <returnvalue>PgPgPgPg</returnvalue>
which <parameter>operand</parameter> falls in a histogram
having <parameter>count</parameter> equal-width buckets spanning the
range <parameter>low</parameter> to <parameter>high</parameter>.
Returns <literal>0</literal>
The buckets have inclusive lower bounds and exclusive upper bounds.
Returns <literal>0</literal> for an input less
than <parameter>low</parameter>,
or <literal><parameter>count</parameter>+1</literal> for an input
outside that range.
greater than or equal to <parameter>high</parameter>.
If <parameter>low</parameter> &gt; <parameter>high</parameter>,
the behavior is mirror-reversed, with bucket <literal>1</literal>
now being the one just below <parameter>low</parameter>, and the
inclusive bounds now being on the upper side.
</para>
<para>
<literal>width_bucket(5.35, 0.024, 10.06, 5)</literal>
<returnvalue>3</returnvalue>
</para>
<para>
<literal>width_bucket(9, 10, 0, 10)</literal>
<returnvalue>2</returnvalue>
</para></entry>
</row>
@ -1757,8 +1767,8 @@ repeat('Pg', 4) <returnvalue>PgPgPgPg</returnvalue>
<para>
Returns the number of the bucket in
which <parameter>operand</parameter> falls given an array listing the
lower bounds of the buckets. Returns <literal>0</literal> for an
input less than the first lower
inclusive lower bounds of the buckets.
Returns <literal>0</literal> for an input less than the first lower
bound. <parameter>operand</parameter> and the array elements can be
of any type having standard comparison operators.
The <parameter>thresholds</parameter> array <emphasis>must be

4
src/backend/utils/adt/float.c
View File

@ -4010,8 +4010,8 @@ float84ge(PG_FUNCTION_ARGS)
* in the histogram. width_bucket() returns an integer indicating the
* bucket number that 'operand' belongs to in an equiwidth histogram
* with the specified characteristics. An operand smaller than the
* lower bound is assigned to bucket 0. An operand greater than the
* upper bound is assigned to an additional bucket (with number
* lower bound is assigned to bucket 0. An operand greater than or equal
* to the upper bound is assigned to an additional bucket (with number
* count+1). We don't allow "NaN" for any of the float8 inputs, and we
* don't allow either of the histogram bounds to be +/- infinity.
*/

7
src/backend/utils/adt/numeric.c
View File

@ -1702,9 +1702,10 @@ generate_series_step_numeric(PG_FUNCTION_ARGS)
* in the histogram. width_bucket() returns an integer indicating the
* bucket number that 'operand' belongs to in an equiwidth histogram
* with the specified characteristics. An operand smaller than the
* lower bound is assigned to bucket 0. An operand greater than the
* upper bound is assigned to an additional bucket (with number
* count+1). We don't allow "NaN" for any of the numeric arguments.
* lower bound is assigned to bucket 0. An operand greater than or equal
* to the upper bound is assigned to an additional bucket (with number
* count+1). We don't allow "NaN" for any of the numeric inputs, and we
* don't allow either of the histogram bounds to be +/- infinity.
*/
Datum
width_bucket_numeric(PG_FUNCTION_ARGS)