> ## 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 Term

<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

`range_term` filters over `int4range`, `int8range`, `numrange`, `tsrange`, and `tstzrange` [range fields](/legacy/indexing/create-index#range-fields).

The following query finds all ranges that contain a specific value:

<CodeGroup>
  ```sql Function Syntax theme={null}
  SELECT id, weight_range FROM mock_items
  WHERE id @@@ paradedb.range_term('weight_range', 1);
  ```

  ```sql JSON Syntax theme={null}
  SELECT id, weight_range FROM mock_items
  WHERE id @@@
  '{
      "range_term": {
          "field": "weight_range",
          "value": 1
      }
  }'::jsonb;
  ```
</CodeGroup>

`range_term` can be used with `boolean` queries to "push down" the range filter into the full text search query.

<CodeGroup>
  ```sql Function Syntax theme={null}
  SELECT id, description, category, weight_range FROM mock_items
  WHERE id @@@ paradedb.boolean(
      must => ARRAY[
          paradedb.range_term('weight_range', 1),
          paradedb.term('category', 'footwear')
      ]
  );
  ```

  ```sql JSON Syntax theme={null}
  SELECT id, description, category, weight_range FROM mock_items
  WHERE id @@@
  '{
      "boolean": {
          "must": [
              {
                  "range_term": {
                      "field": "weight_range",
                      "value": 1
                  }
              },
              {
                  "term": {
                      "field": "category",
                      "value": "footwear"
                  }
              }
          ]
      }
  }'::jsonb;
  ```
</CodeGroup>

## Range Comparison

In addition to individual terms, `range_term` can also compare a [Postgres range](https://www.postgresql.org/docs/current/rangetypes.html) against the
range field.

### Intersects

The following query finds all ranges that share at least one common
point with the query range:

Based on the SearchQueryInput enum showing `RangeIntersects` as an option, here's how we would write it:

<CodeGroup>
  ```sql Function Syntax theme={null}
  SELECT id, weight_range FROM mock_items
  WHERE id @@@ paradedb.range_term('weight_range', '(10, 12]'::int4range, 'Intersects');
  ```

  ```sql JSON Syntax theme={null}
  SELECT id, weight_range FROM mock_items
  WHERE id @@@
  '{
      "range_intersects": {
          "field": "weight_range",
          "lower_bound": {"excluded": 10},
          "upper_bound": {"included": 12}
      }
  }'::jsonb;
  ```
</CodeGroup>

### Contains

The following query finds all ranges that are contained by the query range:

<CodeGroup>
  ```sql Function Syntax theme={null}
  SELECT id, weight_range FROM mock_items
  WHERE id @@@ paradedb.range_term('weight_range', '(3, 9]'::int4range, 'Contains');
  ```

  ```sql JSON Syntax theme={null}
  SELECT id, weight_range FROM mock_items
  WHERE id @@@
  '{
      "range_contains": {
          "field": "weight_range",
          "lower_bound": {"excluded": 3},
          "upper_bound": {"included": 9}
      }
  }'::jsonb;
  ```
</CodeGroup>

### Within

The following query finds all ranges that contain the query range:

<CodeGroup>
  ```sql Function Syntax theme={null}
  SELECT id, weight_range FROM mock_items
  WHERE id @@@ paradedb.range_term('weight_range', '(2, 11]'::int4range, 'Within');
  ```

  ```sql JSON Syntax theme={null}
  SELECT id, weight_range FROM mock_items
  WHERE id @@@
  '{
      "range_within": {
          "field": "weight_range",
          "lower_bound": {"excluded": 2},
          "upper_bound": {"included": 11}
      }
  }'::jsonb;
  ```
</CodeGroup>