> ## Documentation Index
> Fetch the complete documentation index at: https://docs.e6data.com/llms.txt
> Use this file to discover all available pages before exploring further.

# WIDTH_BUCKET

> Returns the bucket containing a value within an equal-width range.

<div className="e6-meta"><span className="e6-eyebrow e6-eyebrow--quiet">Scalar function</span></div>

Returns NULL for NULL arguments, nonpositive bucket count, equal bounds, non-finite numeric values/bounds, or a zero/non-finite calculated bucket width.

## Syntax

### Scalar

```sql theme={"theme":{"light":"github-light","dark":"github-dark"}}
width_bucket(value, lower, upper, buckets)
```

## Arguments

| Name | Type | Required | Description |
| - | - | - | - |
| value | TINYINT, SMALLINT, INTEGER, BIGINT, FLOAT, DOUBLE or DECIMAL(p, s) or INTERVAL | Yes | The value to classify. For DECIMAL(p, s), p is precision (total digits) and s is scale (digits after the decimal point). |
| lower | TINYINT, SMALLINT, INTEGER, BIGINT, FLOAT, DOUBLE or DECIMAL(p, s) or INTERVAL | Yes | The start of the range. Use all three bounds/value arguments as numbers, or all three as compatible intervals. The arguments are converted to a common comparison type. For DECIMAL(p, s), p is precision (total digits) and s is scale (digits after the decimal point). |
| upper | TINYINT, SMALLINT, INTEGER, BIGINT, FLOAT, DOUBLE or DECIMAL(p, s) or INTERVAL | Yes | The end of the range. Use all three bounds/value arguments as numbers, or all three as compatible intervals. The arguments are converted to a common comparison type. For DECIMAL(p, s), p is precision (total digits) and s is scale (digits after the decimal point). |
| buckets | INTEGER | Yes | The positive number of equal-width buckets. Use 1 through 2147483646. Larger counts can overflow or return incorrect bucket numbers. |

## Returns

* Type: INT
* Possible values: 0 before the first bound, 1 through buckets inside the range, or buckets + 1 beyond the final bound.
* NULL behavior: Returns NULL for NULL arguments, nonpositive bucket count, equal bounds, non-finite numeric values/bounds, or a zero/non-finite calculated bucket width.

## Properties

| Property | Value |
| - | - |
| Deterministic | Yes |
| Supports window usage | No |
| Exact result | No |

* Approximation bound: No fixed maximum error is guaranteed.

## Usage notes

* Ascending ranges include the lower bound and exclude the upper bound. Descending ranges reverse that direction.
* Numeric calculations use DOUBLE. Interval calculations can also use floating-point ratios.
* For month/day/nanosecond intervals, bounds are compared lexicographically by months, days, then nanoseconds. If bound days and nanoseconds match, only the month components are bucketed. If bound months match, only relative days and nanoseconds are bucketed; the value month component is ignored in that branch. Other mixed-component bounds return NULL.
* Year-month intervals use their month counts; day-time intervals are converted to a duration. Floating-point conversion can lose precision for large interval magnitudes.
* INTEGER and INT mean the same type; STRING means VARCHAR text. NULL can be used with a supported type. Cast NULL explicitly when its type would otherwise be unclear.
* Exact result: Floating-point computation can round the mathematical result.

## Examples

### Value and NULL input

```sql theme={"theme":{"light":"github-light","dark":"github-dark"}}
SELECT width_bucket(CAST(5 AS DOUBLE), CAST(0 AS DOUBLE), CAST(10 AS DOUBLE), 5) AS inside, width_bucket(CAST(-1 AS DOUBLE), CAST(0 AS DOUBLE), CAST(10 AS DOUBLE), 5) AS below, width_bucket(CAST(10 AS DOUBLE), CAST(0 AS DOUBLE), CAST(10 AS DOUBLE), 5) AS above;
```

| inside | below | above |
| - | - | - |
| 3 | 0 | 6 |

### Bucket boundaries

```sql theme={"theme":{"light":"github-light","dark":"github-dark"}}
SELECT width_bucket(0, 0, 10, 5) AS first_bucket, width_bucket(2, 0, 10, 5) AS next_bucket, width_bucket(10, 0, 10, 5) AS above_range;
```

| first\_bucket | next\_bucket | above\_range |
| - | - | - |
| 1 | 2 | 6 |

## Limitations

* Keep buckets at most 2147483646 so the extra bucket (buckets + 1) fits in INT. Larger counts can return incorrect results or overflow; an error is not guaranteed.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.