diff options
| author | Tom Lane <tgl@sss.pgh.pa.us> | 2025-06-21 12:52:37 -0400 |
|---|---|---|
| committer | Tom Lane <tgl@sss.pgh.pa.us> | 2025-06-21 12:52:37 -0400 |
| commit | ea06263c4aa5abadc97a6928c6b2aff0e29698ae (patch) | |
| tree | 7e18307d8e885610db8d573c0681d07da8b07aa0 /doc/src | |
| parent | fa638edc74ee4be90e94a45f8489f3be9a926d7e (diff) | |
| download | postgresql-ea06263c4aa5abadc97a6928c6b2aff0e29698ae.tar.gz postgresql-ea06263c4aa5abadc97a6928c6b2aff0e29698ae.zip | |
Doc: improve documentation about width_bucket().
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
Diffstat (limited to 'doc/src')
| -rw-r--r-- | doc/src/sgml/func.sgml | 18 |
1 files changed, 14 insertions, 4 deletions
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml index 8d7d9a2f3e8..a6d79765c1a 100644 --- a/doc/src/sgml/func.sgml +++ b/doc/src/sgml/func.sgml @@ -1824,13 +1824,23 @@ SELECT NOT(ROW(table.*) IS NOT NULL) FROM TABLE; -- detect at least one null in 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> > <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> @@ -1842,8 +1852,8 @@ SELECT NOT(ROW(table.*) IS NOT NULL) FROM TABLE; -- detect at least one null in <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 |