@medusajs/search-postgres
Documentation | Website
Building blocks for digital commerce
PostgreSQL Search Module Provider for Medusa: full-text search, typo tolerance, filters, and facets over your search indexes, stored in the application's own PostgreSQL database. It's the default search provider, so search works without an external search engine. It ships with @medusajs/medusa and is registered through the @medusajs/medusa/search-postgres path.
At a glance
| Package | @medusajs/search-postgres |
| Type | Module Provider (Search Module) |
| Provider ID | search-postgres |
| Registered by default | Yes, with id: "postgres" (engine: "native" when self-hosted, "lakebase" on Medusa Cloud) |
| Import from | @medusajs/medusa/search-postgres |
Engines
| Engine | Where | Keyword search | Vector search |
|---|---|---|---|
native (default) |
Any PostgreSQL database | PostgreSQL full-text search (tsvector) with pg_trgm typo tolerance |
Not supported |
lakebase |
Medusa Cloud only | BM25 (lakebase_bm25) with pg_trgm typo tolerance |
ANN (lakebase_ann), and hybrid keyword + vector search |
Features
- Free-text search with field weights and
match_strategy"all"(default),"any", or"last"(typeahead: the last term matches as a prefix). - Filters with
$eq,$ne,$in,$nin, range operators, and$and/$or/$not. On array fields, a bare value or$eqmeans "contains". - Value, range, and stats facets scoped to the query's matches.
distinct(one hit per value) andmin_score.- Vector and hybrid search on the
lakebaseengine. Onnative, vector fields are dropped from the index with a warning, and vector queries are rejected.
Highlighting, geo fields, cursor pagination, and query-time locales aren't supported and are rejected.
Installation
No installation needed. The provider is a dependency of @medusajs/medusa and is registered by default.
Usage
Register the provider yourself to pass options:
import { defineConfig } from "@medusajs/framework/utils"
module.exports = defineConfig({
// ...
modules: [
{
resolve: "@medusajs/medusa/search",
options: {
providers: [
{
resolve: "@medusajs/medusa/search-postgres",
id: "postgres",
options: {
// requires a medusa_search_german text search configuration
language: "german",
},
},
],
},
},
],
})
Then run the migrations, which enable the pg_trgm and unaccent extensions, create the medusa_search_english text search configuration, and create your search indexes:
npx medusa db:migrate
To create or update only the search indexes, run npx medusa db:migrate:search.
If you set language to anything other than english, create a matching medusa_search_<language> text search configuration yourself.
Configuration
| Option | Type | Description | Default |
|---|---|---|---|
engine |
"native" | "lakebase" |
The search backend. lakebase works only on Medusa Cloud. |
"native" |
language |
string |
The PostgreSQL text search configuration language, such as english or simple. |
"english" |
embedder |
(text: string) => Promise<number[]> |
Turns text into an embedding. Required for vector fields that use .embed() and for search_options.vector.query. |
- |
vector_distance |
"cosine" | "l2" | "inner_product" |
Distance metric for vector indexes. | "cosine" |