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

# Tantivy Query String

<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

Tantivy comes with its own [string-based query language](https://docs.rs/tantivy/latest/tantivy/query/struct.QueryParser.html).

`paradedb.parse` accepts Tantivy query strings, which is useful for concisely expressing complex queries or directly executing queries provided
by the end user. For instance, the following two queries are equivalent:

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

  SELECT description, rating, category
  FROM mock_items
  WHERE id @@@ paradedb.boolean(should => ARRAY[
  paradedb.phrase('description', ARRAY['running', 'shoes']),
  paradedb.term('category', 'footwear')
  ]);

  ```

  ```sql JSON Syntax theme={null}
  SELECT description, rating, category
  FROM mock_items
  WHERE id @@@ '{
    "parse": {"query_string": "description:\"running shoes\" OR category:footwear"}
  }'::jsonb

  SELECT description, rating, category
  FROM mock_items
  WHERE id @@@ '{
    "boolean": {
      "should": [
        {
          "phrase": {
            "field": "description",
            "phrases": ["running", "shoes"]
          }
        },
        {
          "term": {
            "field": "category",
            "value": "footwear"
          }
        }
      ]
    }
  }'::jsonb;
  ```
</CodeGroup>

<div className="mt-8" />

## Lenient Query Parsing

By default, `paradedb.parse` uses strict syntax parsing. This means that if any part of the query does not conform to Tantivy's query string syntax, the query fails.
For instance, a valid field name must be provided before every query (i.e. `category:footwear`).

By setting `lenient` to `true`, the query is executed on a best-effort basis. For example, if no field names are provided, the query is executed over all fields in the index:

<CodeGroup>
  ```sql Function Syntax theme={null}
  SELECT description, rating, category
  FROM mock_items
  WHERE id @@@ paradedb.parse('speaker electronics', lenient => true);
  ```

  ```sql JSON Syntax theme={null}
  SELECT description, rating, category
  FROM mock_items
  WHERE id @@@
  '{
      "parse": {
          "query_string": "speaker electronics",
          "lenient": true
      }
  }'::jsonb;
  ```
</CodeGroup>

## Conjunction Mode

By default, queries in the query string are `OR`ed together. For instance, the following two queries are equivalent:

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

  SELECT description, rating, category
  FROM mock_items
  WHERE id @@@ paradedb.parse('description:speaker OR category:electronics');

  ```

  ```sql JSON Syntax theme={null}
  SELECT description, rating, category
  FROM mock_items
  WHERE id @@@
  '{
      "parse": {
          "query_string": "description:speaker category:electronics"
      }
  }'::jsonb;

  SELECT description, rating, category
  FROM mock_items
  WHERE id @@@
  '{
      "parse": {
          "query_string": "description:speaker OR category:electronics"
      }
  }'::jsonb;
  ```
</CodeGroup>

With conjunction\_mode set to true, queries are `AND`ed together. This means that the following two queries are equivalent:

<CodeGroup>
  ```sql Function Syntax theme={null}
  SELECT description, rating, category
  FROM mock_items
  WHERE id @@@ paradedb.parse(
    'description:speaker category:electronics',
    conjunction_mode => true
  );

  SELECT description, rating, category
  FROM mock_items
  WHERE id @@@ paradedb.parse(
  'description:speaker AND category:electronics'
  );

  ```

  ```sql JSON Syntax theme={null}
  SELECT description, rating, category
  FROM mock_items
  WHERE id @@@
  '{
      "parse": {
          "query_string": "description:speaker category:electronics",
          "conjunction_mode": true
      }
  }'::jsonb;

  SELECT description, rating, category
  FROM mock_items
  WHERE id @@@
  '{
      "parse": {
          "query_string": "description:speaker AND category:electronics"
      }
  }'::jsonb;
  ```
</CodeGroup>

## Parse with Field

`paradedb.parse_with_field` takes a field name and a query string without field names. It's useful for executing user-provided query
strings over specific fields. Like `paradedb.parse`, `lenient` and `conjunction_mode` can be passed to this function.

<CodeGroup>
  ```sql Function Syntax theme={null}
  SELECT description, rating, category
  FROM mock_items
  WHERE id @@@ paradedb.parse_with_field(
    'description',
    'speaker bluetooth',
    conjunction_mode => true
  );
  ```

  ```sql JSON Syntax theme={null}
  SELECT description, rating, category
  FROM mock_items
  WHERE id @@@
  '{
      "parse_with_field": {
          "field": "description",
          "query_string": "speaker bluetooth",
          "conjunction_mode": true
      }
  }'::jsonb;
  ```
</CodeGroup>

## Enumerated Types

To query a custom [enum](/legacy/indexing/create-index#enumerated-types) with `paradedb.parse`, the
underlying ordinal value must be used.

<CodeGroup>
  ```sql Function Syntax theme={null}
  -- Assume we have indexed an enum called color and 'red' has an ordinal of 1.0
  SELECT description, rating, category
  FROM mock_items
  WHERE id @@@ paradedb.parse('color:1.0');
  ```

  ```sql JSON Syntax theme={null}
  -- Assume we have indexed an enum called color and 'red' has an ordinal of 1.0
  SELECT description, rating, category
  FROM mock_items
  WHERE id @@@
  '{
      "parse": {
          "query_string": "color:1.0"
      }
  }'::jsonb;
  ```
</CodeGroup>