Download the PHP package shabushabu/laravel-paradedb-search without Composer

ParadeDB Search for Laravel

Integrates the pg_search Postgres extension by ParadeDB into Laravel

Supported minimum versions

Installation

[!CAUTION] Please note that this is a new package and, even though it is well tested, it should be considered pre-release software

Before installing the package you should install and enable the pg_search extension.

You can then install the package via composer:

You can also publish the config file:

These are the contents of the published config file:

Usage

Add a bm25 index

Each model that you want to be searchable needs a corresponding bm25 index. These can be generated within a migration like so:

See:

• https://docs.paradedb.com/documentation/indexing/create_index
• https://docs.paradedb.com/documentation/indexing/field_options

TantivyQL

ParadeDB Search for Laravel comes with a fluent builder for TantivyQL, a simple string-based query language.

This builder can be used within various ParadeDB expressions.

Basic query

Add an IN condition

Add an AND NOT condition

Boost a condition

Apply the slop operator

More complex example with a sub condition

Apply a simple filter

Apply a boolean filter

Apply a basic range filter

Apply an inclusive range filter

Apply an exclusive range filter

Performing a basic search

To search, you just use the custom @@@ operator in a regular Eloquent where condition.

See: https://docs.paradedb.com/documentation/full-text/overview

ParadeDB functions

For more complex operations, it might be necessary to use some of the provided ParadeDB functions, all of which have corresponding query expressions:

JSON

The right side of the @@@ operator also accepts JSON query objects, similar to how Elasticsearch Query DSL works.

See: https://docs.paradedb.com/documentation/advanced/overview

Get all the records

See: https://docs.paradedb.com/documentation/advanced/compound/all

Check that a field exists

See: https://docs.paradedb.com/documentation/advanced/term/exists

Get none of the records

See: https://docs.paradedb.com/documentation/advanced/compound/empty

Boost a query

See: https://docs.paradedb.com/documentation/advanced/compound/boost

Add a constant score

See: https://docs.paradedb.com/documentation/advanced/compound/const

Perform a disjunction max query

The DisjunctionMax constructor also accepts an array of queries, so using the fluid interface might be more convenient for multiple queries:

This also allows you to conditionally add queries:

See: https://docs.paradedb.com/documentation/advanced/compound/disjunction_max

Search for a fuzzy term

See: https://docs.paradedb.com/documentation/advanced/term/fuzzy_term

Search for a fuzzy phrase

See: https://docs.paradedb.com/documentation/advanced/phrase/fuzzy_phrase

Parse a Tantivy query string

Useful for directly searching for user-supplied queries.

Additionally, ParadeDB Search for Laravel comes with its own Tantivy Query Language Builder:

See: https://docs.paradedb.com/documentation/advanced/compound/parse

Parse a Tantivy query string for a given field

Like ShabuShabu\ParadeDB\Expressions\Parse above, but it takes a query string without fields and searches for the given field.

See: https://docs.paradedb.com/documentation/advanced/compound/parse#parse-with-field

Highlight search terms

See: https://docs.paradedb.com/documentation/full-text/highlighting

Search for a phrase

See: https://docs.paradedb.com/documentation/advanced/phrase/phrase

Perform a phrase prefix query

See: https://docs.paradedb.com/documentation/advanced/phrase/phrase_prefix

Search within a given range

Here are the supported range types (all within the ShabuShabu\ParadeDB\Query\Expressions\Ranges namespace), plus their corresponding Postgres type:

• Int4::class; or int4range
• Int8::class; or int8range
• Numeric::class; or numrange
• Date::class; or daterange
• Timestamp::class; or tsrange
• TimestampTz::class; or tstzrange

See: https://docs.paradedb.com/documentation/advanced/term/range

Find ranges for a given value

Ranges can also be compared to other ranges:

See: https://docs.paradedb.com/documentation/advanced/term/range_term

Perform a regex query

See: https://docs.paradedb.com/documentation/advanced/term/regex

Search for a term

See: https://docs.paradedb.com/documentation/advanced/term/term

Search for a set of terms

The above query can also be written in a fluid manner:

The term method allows you to conditionally add terms:

See: https://docs.paradedb.com/documentation/advanced/term/term_set

Perform a complex boolean query

Boolean queries can also be constructed in a fluid manner:

The two queries above are identical. The fluent methods allow you to conditionally add queries, though:

See: https://docs.paradedb.com/documentation/advanced/compound/boolean

Sort by rank

See: https://docs.paradedb.com/documentation/full-text/scoring

Find similar documents

When you pass a document ID, aka an Eloquent model key, then documents related to the given document are found.

Alternatively, you can pass in document fields instead of an id to search against:

See: https://docs.paradedb.com/documentation/advanced/specialized/more_like_this

Using the query builder macro

In quite a lot of cases, the column you search against will be id. For this reason, you can also use the provided whereSearch macro.

Hybrid search

pg_search also allows you to perform hybrid full-text/similarity searches. For this to work you will need to install pgvector. Please note that ParadeDB Search for Laravel registers all custom pgvector operators already for you.

See: https://docs.paradedb.com/documentation/guides/hybrid

A word of caution

While it is possible to combine ParadeDB queries with regular Eloquent queries, you will incur some performance penalties.

For optimal performance it is recommended to let the bm25 index do as much work as possible!

Getting help

If your issue has something to do with this package, then please use the issues and discussions!

If your issue is related to pg_search, tho, then please create a discussion in the ParadeDB repo.

To make this a bit easier, you can use the paradedb:help command that ships with this package:

Please note that this command is just an implementation of the paradedb.help() function. Please use this command wisely!

Testing

The tests require a PostgreSQL database, which can easily be set up by running the following script:

[!WARNING] Please note that both pg_search and pgvector extensions need to be available already.

Then run the tests:

Or with test coverage:

Or with type coverage:

Or run PHPStan:

ParadeDB test table

There is also a command that allows you to create and drop the built-in test table

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Taylor Otwell for creating Laravel
• ParadeDB for creating pg_search
• ShabuShabu
• All Contributors

Disclaimer

This is a 3rd party package and ShabuShabu is not affiliated with either Laravel or ParadeDB.

License

The MIT License (MIT). Please see License File for more information.