---
title: Match
description: The query builder version of the match query
canonical: https://docs.paradedb.com/documentation/query-builder/match
---

<Note>
  Highlighting is not supported for `pdb.match` if `distance` is greater than
  zero.
</Note>

<Note>
  For most use cases, we recommend using the
  [match](/documentation/full-text/match) query instead.
</Note>

Under the hood, the [match](/documentation/full-text/match) conjunction and disjunction operators get rewritten to this query builder function.
This function exposes a few advanced configuration options like the ability to use a custom tokenizer.

<CodeGroup>
```sql SQL
SELECT description, rating, category
FROM mock_items
WHERE description @@@ pdb.match('running shoes');
```

```python Django
from paradedb import Match, ParadeDB

MockItem.objects.filter(
    description=ParadeDB(Match('running shoes', operator='OR'))
).values('description', 'rating', 'category')
```

```ruby Rails
MockItem.search(:description)
        .matching_any("running shoes")
        .select(:description, :rating, :category)
```

</CodeGroup>

<div className="mt-8" />

<ParamField body="value" required>
  The query to match against. This query is automatically tokenized in the same
  way as the field on the left-hand side of `@@@`.
</ParamField>
<ParamField body="distance" default={0}>
  If greater than zero, fuzzy matching is applied. Configures the maximum
  Levenshtein distance (i.e. single character edits) allowed to consider a term
  in the index as a match for the query term. Maximum value is `2`.
</ParamField>
<ParamField body="transposition_cost_one" default={true}>
  When set to `true` and fuzzy matching is enabled, transpositions (swapping two
  adjacent characters) as a single edit in the Levenshtein distance calculation,
  while `false` considers it two separate edits (a deletion and an insertion).
</ParamField>
<ParamField body="prefix" default={false}>
  When set to `true` and fuzzy matching is enabled, the initial substring
  (prefix) of the query term is exempted from the fuzzy edit distance
  calculation, while false includes the entire string in the calculation.
</ParamField>
<ParamField body="conjunction_mode" default={false}>
  When set to `true`, **all** tokens of the query have to match in order for a
  document to be considered a match. For instance, the query `running shoes` is
  by default executed as `running OR shoes`, but setting `conjunction_mode` to
  `true` executes it as `running AND shoes`.
</ParamField>

## Fuzzy Matching

When `distance` is set to a positive integer, fuzzy matching is applied. This allows `match` to tolerate typos in the query string.

<CodeGroup>
```sql SQL
SELECT description, rating, category
FROM mock_items
WHERE description @@@ pdb.match('ruining shoez', distance => 2);
```

```python Django
from paradedb import Match, ParadeDB

MockItem.objects.filter(
    description=ParadeDB(Match('ruining shoez', operator='OR', distance=2))
).values('description', 'rating', 'category')
```

```ruby Rails
MockItem.search(:description)
        .matching_any("ruining shoez", distance: 2)
        .select(:description, :rating, :category)
```

</CodeGroup>

## Conjunction Mode

By default, `match` constructs an `OR` boolean query from the query string's tokens. For instance, the query `running shoes` is executed as `running OR shoes`.

When set to `true`, `conjunction_mode` constructs an `AND` boolean query instead.

<CodeGroup>
```sql SQL
SELECT description, rating, category
FROM mock_items
WHERE description @@@ pdb.match('running shoes', conjunction_mode => true);
```

```python Django
from paradedb import Match, ParadeDB

MockItem.objects.filter(
    description=ParadeDB(Match('running shoes', operator='AND'))
).values('description', 'rating', 'category')
```

```ruby Rails
MockItem.search(:description)
        .matching_all("running shoes")
        .select(:description, :rating, :category)
```

</CodeGroup>
