npm.io
2.22.7 • Published 4d ago

@medusajs/search-postgres

Licence
MIT
Version
2.22.7
Deps
0
Size
184 kB
Vulns
0
Weekly
0
Stars
36.8K

Medusa logo

@medusajs/search-postgres

Documentation | Website

Building blocks for digital commerce

Medusa is released under the MIT license. PRs welcome! Discord Chat Follow @medusajs

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 $eq means "contains".
  • Value, range, and stats facets scoped to the query's matches.
  • distinct (one hit per value) and min_score.
  • Vector and hybrid search on the lakebase engine. On native, 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"

Resources

Keywords