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

# Range

<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 theme={null}
  SELECT description, rating, category
  FROM mock_items
  WHERE id @@@ paradedb.range(
      field => 'rating',
      range => int4range(1, 3, '[)')
  );
  ```

  ```sql JSON Syntax theme={null}
  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 theme={null}
  SELECT description, rating, category
  FROM mock_items
  WHERE id @@@ paradedb.range(
      field => 'rating',
      range => int4range(1, 3, '[]')
  );
  ```

  ```sql JSON Syntax theme={null}
  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 theme={null}
  SELECT description, rating, category
  FROM mock_items
  WHERE id @@@ paradedb.range(
      field => 'rating',
      range => int4range(1, NULL, '[)')
  );
  ```

  ```sql JSON Syntax theme={null}
  SELECT description, rating, category
  FROM mock_items
  WHERE id @@@
  '{
      "range": {
          "field": "rating",
          "lower_bound": {"included": 1},
          "upper_bound": null
      }
  }'::jsonb;
  ```
</CodeGroup>