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

# Match

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

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

## Basic Usage

`paradedb.match` is ParadeDB's standard full text query. It tokenizes a query string and searches for matches against a specified field,
allowing for custom tokenizers and fuzzy matching.

<CodeGroup>
  ```sql Function Syntax theme={null}
  SELECT description, rating, category
  FROM mock_items
  WHERE id @@@ paradedb.match('description', 'running shoes');
  ```

  ```sql JSON Syntax theme={null}
  SELECT description, rating, category
  FROM mock_items
  WHERE id @@@
  '{
      "match": {
          "field": "description",
          "value": "running shoes"
      }
  }'::jsonb;
  ```
</CodeGroup>

<div className="mt-8" />

<ParamField body="field" required>
  Specifies the field within the document to search for the term.
</ParamField>

<ParamField body="value" required>
  Defines the phrase you are searching for within the specified field. This
  phrase is automatically tokenized in the same way as `field`.
</ParamField>

<ParamField body="tokenizer">
  By default, the query string is tokenized in the same way as the field was at
  index time. This can be configured by setting a [custom
  tokenizer](#custom-tokenizer).
</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>

## Custom Tokenizer

[`paradedb.tokenizer`](/legacy/indexing/tokenizers#tokenizing-a-query) can be passed to `tokenizer` to control how the query string is tokenized.

<CodeGroup>
  ```sql Function Syntax theme={null}
  SELECT description, rating, category
  FROM mock_items
  WHERE id @@@ paradedb.match(
      'description',
      'running shoes',
      tokenizer => paradedb.tokenizer('whitespace')
  );
  ```

  ```sql JSON Syntax theme={null}
  SELECT description, rating, category
  FROM mock_items
  WHERE id @@@
  '{
      "match": {
          "field": "description",
          "value": "running shoes",
          "tokenizer": {"type": "whitespace", "lowercase": true, "remove_long": 255}
      }
  }'::jsonb;
  ```
</CodeGroup>

<Note>
  For JSON syntax, `paradedb.tokenizer` prints the configuration object to pass into `tokenizer`.

  ```sql theme={null}
  SELECT paradedb.tokenizer('whitespace');
  ```

  <Accordion title="Expected Response">
    ```csv theme={null}
                               tokenizer
    ---------------------------------------------------------------
     {"type": "whitespace", "lowercase": true, "remove_long": 255}
    (1 row)
    ```
  </Accordion>
</Note>

## 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 Function Syntax theme={null}
  SELECT description, rating, category
  FROM mock_items
  WHERE id @@@ paradedb.match('description', 'ruining shoez', distance => 2);
  ```

  ```sql JSON Syntax theme={null}
  SELECT description, rating, category
  FROM mock_items
  WHERE id @@@
  '{
      "match": {
          "field": "description",
          "value": "ruining shoez",
          "distance": 2
      }
  }'::jsonb;
  ```
</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 Function Syntax theme={null}
  SELECT description, rating, category
  FROM mock_items
  WHERE id @@@ paradedb.match('description', 'running shoes', conjunction_mode => true);
  ```

  ```sql JSON Syntax theme={null}
  SELECT description, rating, category
  FROM mock_items
  WHERE id @@@
  '{
      "match": {
          "field": "description",
          "value": "running shoes",
          "conjunction_mode": true
      }
  }'::jsonb;
  ```
</CodeGroup>