---
title: Proximity
noindex: true
---

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`.

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

<Note>
  Like the [term](/v2/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 `##>`.

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

## 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`.

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

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:

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

## 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`.

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

`pdb.prox_array` can also take regex:

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