# block_range

Resolves a UTC day or a pair of instants to a half-open block window [from_block, to_block). Each end is resolved independently with at_or_after: from_block is the first block at or after the start, and to_block is the first block at or after the end, so to_block itself lies outside the window. A DATE supplies UTC midnight at the start of that day and UTC midnight at the start of the next day. An end after the current tip timestamp resolves to tip + 1, so a window that has not ended yet holds every block mined so far.

Canonical HTML: <https://determica.com/docs/functions/block_range>

- Kind: scalar function
- Category: [Chain reads](/docs/category/chain-reads.md)
- Tags: RPC

Resolves a UTC day or a pair of instants to a half-open block window [from_block, to_block). Each end is resolved independently with at_or_after: from_block is the first block at or after the start, and to_block is the first block at or after the end, so to_block itself lies outside the window. A DATE supplies UTC midnight at the start of that day and UTC midnight at the start of the next day. An end after the current tip timestamp resolves to tip + 1, so a window that has not ended yet holds every block mined so far.

## Overload 1: block_range(CLIENT, DATE)

```sql
block_range(CLIENT, DATE)
```

Accepts a DATE and returns the block interval covering that UTC calendar day.

- Kind: scalar
- Execution context: Live RPC
- Behavior: Immediate Read
- Execution modes: Live Client
- Input shape: Scalar Arguments
- Planning contract: Runtime
- Cardinality: One Per Input
- Determinism: External State
- Return shape: Scalar
- Schema stability: Fixed
- Stability: Stable
- Side effects: network_io

### Requirements

- attached_live_client
- rpc

### Risks

- provider_limits
- chain_reorganization

### Inputs

- `client` (CLIENT; required; positional) — Attached live CLIENT for the chain to search.
- `date` (DATE; required; positional) — UTC calendar date. The range begins at midnight and ends at midnight at the start of the next day.

### Returns

Half-open block window

Returns STRUCT(from_block BIGINT, to_block BIGINT): from_block is the first block in the window and to_block the first block after it. Pass from_block and to_block - 1 to get_logs, whose bounds are both inclusive. Passing to_block unchanged also reads the first block after the window.

- `block_range` (STRUCT(from_block BIGINT, to_block BIGINT))

Half-open block window. Returns STRUCT(from_block BIGINT, to_block BIGINT): from_block is the first block in the window and to_block the first block after it. Pass from_block and to_block - 1 to get_logs, whose bounds are both inclusive. Passing to_block unchanged also reads the first block after the window.

### Examples

_Named parameters · Needs RPC · RPC required_

```sql
-- Resolve the [from_block, to_block) bounds for one UTC day
SELECT
  (range).from_block AS from_block,
  (range).to_block AS to_block
FROM (
  SELECT block_range($client, '2024-01-15'::DATE) AS range
);
```

## Overload 2: block_range(CLIENT, TIMESTAMP WITH TIME ZONE, TIMESTAMP WITH TIME ZONE)

```sql
block_range(CLIENT, TIMESTAMP WITH TIME ZONE, TIMESTAMP WITH TIME ZONE)
```

Accepts two TIMESTAMPTZ values and resolves their absolute instants to a half-open block interval.

- Kind: scalar
- Execution context: Live RPC
- Behavior: Immediate Read
- Execution modes: Live Client
- Input shape: Scalar Arguments
- Planning contract: Runtime
- Cardinality: One Per Input
- Determinism: External State
- Return shape: Scalar
- Schema stability: Fixed
- Stability: Stable
- Side effects: network_io

### Requirements

- attached_live_client
- rpc

### Risks

- provider_limits
- chain_reorganization

### Inputs

- `client` (CLIENT; required; positional) — Attached live CLIENT for the chain to search.
- `from_timestamp` (TIMESTAMP WITH TIME ZONE; required; positional) — Absolute TIMESTAMPTZ start instant resolved with at_or_after.
- `to_timestamp` (TIMESTAMP WITH TIME ZONE; required; positional) — Absolute TIMESTAMPTZ end instant resolved with at_or_after. It need not follow the start.

### Returns

Half-open block window

Returns STRUCT(from_block BIGINT, to_block BIGINT): from_block is the first block in the window and to_block the first block after it. Pass from_block and to_block - 1 to get_logs, whose bounds are both inclusive. Passing to_block unchanged also reads the first block after the window.

- `block_range` (STRUCT(from_block BIGINT, to_block BIGINT))

Half-open block window. Returns STRUCT(from_block BIGINT, to_block BIGINT): from_block is the first block in the window and to_block the first block after it. Pass from_block and to_block - 1 to get_logs, whose bounds are both inclusive. Passing to_block unchanged also reads the first block after the window.

## Overload 3: block_range(CLIENT, TIMESTAMP, TIMESTAMP)

```sql
block_range(CLIENT, TIMESTAMP, TIMESTAMP)
```

Accepts two plain TIMESTAMP values, interprets them as UTC, and returns a half-open block interval.

- Kind: scalar
- Execution context: Live RPC
- Behavior: Immediate Read
- Execution modes: Live Client
- Input shape: Scalar Arguments
- Planning contract: Runtime
- Cardinality: One Per Input
- Determinism: External State
- Return shape: Scalar
- Schema stability: Fixed
- Stability: Stable
- Side effects: network_io

### Requirements

- attached_live_client
- rpc

### Risks

- provider_limits
- chain_reorganization

### Inputs

- `client` (CLIENT; required; positional) — Attached live CLIENT for the chain to search.
- `from_timestamp` (TIMESTAMP; required; positional) — UTC TIMESTAMP start instant resolved with at_or_after.
- `to_timestamp` (TIMESTAMP; required; positional) — UTC TIMESTAMP end instant resolved with at_or_after. It need not follow the start.

### Returns

Half-open block window

Returns STRUCT(from_block BIGINT, to_block BIGINT): from_block is the first block in the window and to_block the first block after it. Pass from_block and to_block - 1 to get_logs, whose bounds are both inclusive. Passing to_block unchanged also reads the first block after the window.

- `block_range` (STRUCT(from_block BIGINT, to_block BIGINT))

Half-open block window. Returns STRUCT(from_block BIGINT, to_block BIGINT): from_block is the first block in the window and to_block the first block after it. Pass from_block and to_block - 1 to get_logs, whose bounds are both inclusive. Passing to_block unchanged also reads the first block after the window.

## Guidance

### Failures and ordering

NULL input, transport initialization failure, or boundary-search failure returns NULL. A search failure affects every row sharing that transport in the input vector.

A malformed, detached, or non-live CLIENT raises an error.

Historical boundaries require a provider that retains the requested blocks.

Start and end boundaries are resolved independently; reversed inputs are not rejected.

## Related functions

- [block_at](/docs/functions/block_at.md) — Usually After
- [get_logs](/docs/functions/get_logs.md) — Usually Before
- [latest_block](/docs/functions/latest_block.md) — See Also