---
title: Proximity
description: Match documents based on token proximity within the source document
canonical: https://docs.paradedb.com/documentation/full-text/proximity
---

Proximity queries are used to match documents containing tokens that are within a certain token distance of one another.

## Overview

The following query finds all documents where the token `sleek` is at most `1` token away from `shoes`.

<CodeGroup>
```sql SQL
SELECT description, rating, category
FROM mock_items
WHERE description @@@ ('sleek' ## 1 ## 'shoes');
```

```python Django
from paradedb import ParadeDB, Proximity

MockItem.objects.filter(
    description=ParadeDB(Proximity('sleek shoes', distance=1))
).values('description', 'rating', 'category')
```

```ruby Rails
MockItem.search(:description)
        .near("sleek", anchor: "shoes", distance: 1)
        .select(:description, :rating, :category)
```

</CodeGroup>

<Note>
  Like the [term](/documentation/full-text/term) query, the query string in a
  proximity query is treated as a finalized token.
</Note>

`##` does not care about order -- the term on the left-hand side may appear before or after the term on the right-hand side.
To ensure that the left-hand term appears before the right-hand term, use `##>`.

<CodeGroup>
```sql SQL
SELECT description, rating, category
FROM mock_items
WHERE description @@@ ('sleek' ##> 1 ##> 'shoes');
```

```python Django
from paradedb import ParadeDB, Proximity

MockItem.objects.filter(
    description=ParadeDB(Proximity('sleek shoes', distance=1, ordered=True))
).values('description', 'rating', 'category')
```

```ruby Rails
MockItem.search(:description)
        .near("sleek", anchor: "shoes", distance: 1, ordered: true)
        .select(:description, :rating, :category)
```

</CodeGroup>

## Proximity Regex

In addition to exact tokens, proximity queries can also match against regex expressions.

The following query finds all documents where any token matching the regex query `sl.*` is at most `1` token away
from the token `shoes`.

<CodeGroup>
```sql SQL
SELECT description, rating, category
FROM mock_items
WHERE description @@@ (pdb.prox_regex('sl.*') ## 1 ## 'shoes');
```

```python Django
from paradedb import ParadeDB, ProximityRegex

MockItem.objects.filter(
    description=ParadeDB(ProximityRegex(left_term='shoes', pattern='sl.*', distance=1))
).values('description', 'rating', 'category')
```

```ruby Rails
MockItem.search(:description)
        .near(ParadeDB.regex_term("sl.*"), anchor: "shoes", distance: 1)
        .select(:description, :rating, :category)
```

</CodeGroup>

By default, `pdb.prox_regex` will expand to the first `50` regex matches in each document. This limit can be overridden
by providing a second argument:

<CodeGroup>
```sql SQL
-- Expand up to 100 regex matches
SELECT description, rating, category
FROM mock_items
WHERE description @@@ (pdb.prox_regex('sl.*', 100) ## 1 ## 'shoes');
```

```python Django
from paradedb import ParadeDB, ProximityRegex

MockItem.objects.filter(
    description=ParadeDB(ProximityRegex(left_term='shoes', pattern='sl.*', distance=1, max_expansions=100))
).values('description', 'rating', 'category')
```

```ruby Rails
MockItem.search(:description)
        .near(ParadeDB.regex_term("sl.*", max_expansions: 100), anchor: "shoes", distance: 1)
        .select(:description, :rating, :category)
```

</CodeGroup>

## Proximity Array

`pdb.prox_array` matches against an array of tokens instead of a single token. For example, the following query finds all
documents where any of the tokens `sleek` or `white` is within `1` token of `shoes`.

<CodeGroup>
```sql SQL
SELECT description, rating, category
FROM mock_items
WHERE description @@@ (pdb.prox_array('sleek', 'white') ## 1 ## 'shoes');
```

```python Django
from paradedb import ParadeDB, ProximityArray

MockItem.objects.filter(
    description=ParadeDB(ProximityArray('sleek', 'white', right_term='shoes', distance=1))
).values('description', 'rating', 'category')
```

```ruby Rails
MockItem.search(:description)
        .near(%w[sleek white], anchor: "shoes", distance: 1)
        .select(:description, :rating, :category)
```

</CodeGroup>

`pdb.prox_array` can also take regex:

<CodeGroup>
```sql SQL
SELECT description, rating, category
FROM mock_items
WHERE description @@@ (pdb.prox_array(pdb.prox_regex('sl.*'), 'white') ## 1 ## 'shoes');
```

```python Django
from paradedb import ParadeDB, ProxRegex, ProximityArray

MockItem.objects.filter(
    description=ParadeDB(ProximityArray(ProxRegex('sl.*'), 'white', right_term='shoes', distance=1))
).values('description', 'rating', 'category')
```

```ruby Rails
MockItem.search(:description)
        .near(ParadeDB.regex_term("sl.*"), "white", anchor: "shoes", distance: 1)
        .select(:description, :rating, :category)
```

</CodeGroup>