---
title: Range
noindex: true
---

<Danger>
  **Legacy Docs:** This page describes our legacy API. It will be deprecated in
  a future version. Please use the [v2 API](/) where possible.
</Danger>

## Basic Usage

Finds documents containing a term that falls within a specified range of values.

<CodeGroup>
```sql Function Syntax
SELECT description, rating, category
FROM mock_items
WHERE id @@@ paradedb.range(
    field => 'rating',
    range => int4range(1, 3, '[)')
);
```
```sql JSON Syntax
SELECT description, rating, category
FROM mock_items
WHERE id @@@
'{
    "range": {
        "field": "rating",
        "lower_bound": {"included": 1},
        "upper_bound": {"excluded": 3}
    }
}'::jsonb;
```
</CodeGroup>

<div className="mt-8" />

<ParamField body="field" required>
  Specifies the field within the document to search for the term.
</ParamField>
<ParamField body="range" required>
  A Postgres range specifying the range of values to match the field against.
  Range types include `int4range`, `int8range`, `daterange`, `tsrange`, and
  `tstzrange`.
</ParamField>

## Inclusive vs. Exclusive Range

The `range` argument accepts a Postgres [range type](https://www.postgresql.org/docs/current/rangetypes.html).
An inclusive lower bound is represented by `[` while an exclusive lower bound is represented by `(`. Likewise, an inclusive upper bound is represented by `]`, while an exclusive upper bound is represented by `)`.
For instance, the following query selects ratings between `1` and `3`, inclusive.

<CodeGroup>
```sql Function Syntax
SELECT description, rating, category
FROM mock_items
WHERE id @@@ paradedb.range(
    field => 'rating',
    range => int4range(1, 3, '[]')
);
```
```sql JSON Syntax
SELECT description, rating, category
FROM mock_items
WHERE id @@@
'{
    "range": {
        "field": "rating",
        "lower_bound": {"included": 1},
        "upper_bound": {"included": 3}
    }
}'::jsonb;
```
</CodeGroup>

## Unbounded Range

Passing `NULL` into either the upper or lower bound causes Postgres to treat the upper/lower bounds as
positive/negative infinity.

<CodeGroup>
```sql Function Syntax
SELECT description, rating, category
FROM mock_items
WHERE id @@@ paradedb.range(
    field => 'rating',
    range => int4range(1, NULL, '[)')
);
```
```sql JSON Syntax
SELECT description, rating, category
FROM mock_items
WHERE id @@@
'{
    "range": {
        "field": "rating",
        "lower_bound": {"included": 1},
        "upper_bound": null
    }
}'::jsonb;
```
</CodeGroup>
