​
Basic Usage

Tantivy comes with its own string-based query language.

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:

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')
]);

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

SELECT description, rating, category
FROM mock_items
WHERE id @@@ paradedb.parse('speaker electronics', lenient => true);

​
Conjunction Mode

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

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');

With conjunction_mode set to true, queries are ANDed together. This means that the following two queries are equivalent:

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'
);

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

SELECT description, rating, category
FROM mock_items
WHERE id @@@ paradedb.parse_with_field(
  'description',
  'speaker bluetooth',
  conjunction_mode => true
);

​
Enumerated Types

To query a custom enum with paradedb.parse, the underlying ordinal value must be used.

-- 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');