@medusajs/search-postgres 2.19.0-snapshot-20260811095123

package/dist/services/postgres-search.js

@@ -0,0 +1,1054 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PostgresSearchService = void 0;
+const utils_1 = require("@medusajs/framework/utils");
+const utils_2 = require("../utils");
+/** How many documents to write per multi-row upsert statement. */
+const UPSERT_CHUNK_SIZE = 200;
+/**
+ * PostgreSQL search provider with two engines:
+ *
+ * - `native` (default) — portable GIN + `ts_rank` + `pg_trgm`
+ * - `lakebase` — Neon Lakebase Search (`lakebase_bm25` + `lakebase_ann`)
+ *
+ * Medusa Cloud uses `engine: "lakebase"`. Local / self-hosted stick to native.
+ */
+class PostgresSearchService extends utils_1.AbstractSearchProviderService {
+    constructor({ manager, logger }, options = {}) {
+        super();
+        this.extensionState_ = null;
+        if (!manager?.execute) {
+            throw new utils_1.MedusaError(utils_1.MedusaError.Types.INVALID_ARGUMENT, "The postgres search provider requires a database manager. Ensure the Search Module is configured with a Postgres connection.");
+        }
+        this.manager_ = manager;
+        this.logger_ = logger;
+        this.language_ = this.normalizeLanguage(options.language ?? "english");
+        this.engine_ = options.engine ?? "native";
+        this.embedder_ = options.embedder;
+        this.vectorDistance_ = options.vector_distance ?? "cosine";
+        if (this.engine_ !== "native" && this.engine_ !== "lakebase") {
+            throw new utils_1.MedusaError(utils_1.MedusaError.Types.INVALID_DATA, `Invalid postgres search engine "${options.engine}". Use "native" or "lakebase".`);
+        }
+    }
+    normalizeLanguage(language) {
+        if (!/^[a-z0-9_]+$/i.test(language)) {
+            throw new utils_1.MedusaError(utils_1.MedusaError.Types.INVALID_DATA, `Invalid postgres search language "${language}". Use a built-in text search configuration name such as "english" or "simple".`);
+        }
+        return language;
+    }
+    get tsConfig_() {
+        return this.extensionState_?.text_search_config ?? this.language_;
+    }
+    get isLakebase_() {
+        return this.engine_ === "lakebase";
+    }
+    async ensureExtensions(manager = this.manager_) {
+        if (this.extensionState_) {
+            return this.extensionState_;
+        }
+        try {
+            this.extensionState_ = await (0, utils_2.ensureSearchExtensions)(manager, {
+                language: this.language_,
+                catalogTable: utils_2.CATALOG_TABLE,
+                engine: this.engine_,
+            });
+        }
+        catch (error) {
+            if (error instanceof utils_1.MedusaError) {
+                throw error;
+            }
+            throw new utils_1.MedusaError(utils_1.MedusaError.Types.DB_ERROR, `Failed to initialize the postgres search catalog. Underlying error: ${error.message}`);
+        }
+        if (!this.extensionState_.pg_trgm) {
+            this.logger_?.warn("search-postgres: pg_trgm is not available. Full-text search will work, but typo_tolerance queries will be rejected.");
+        }
+        return this.extensionState_;
+    }
+    assertTypoToleranceAvailable(state) {
+        if (!state.pg_trgm) {
+            throw new utils_1.MedusaError(utils_1.MedusaError.Types.NOT_ALLOWED, "Typo tolerance requires the pg_trgm extension. Enable it with: CREATE EXTENSION IF NOT EXISTS pg_trgm;");
+        }
+    }
+    serializePlan(plan) {
+        return JSON.stringify({
+            primary_key: plan.primary_key,
+            searchable: plan.searchable,
+            vectors: plan.vectors,
+            schema_hash: plan.schema_hash,
+            fields: [...plan.fields.values()].map((planned) => ({
+                path: planned.path,
+                kind: planned.kind,
+                is_array: planned.is_array,
+                is_date: planned.is_date,
+                dimensions: planned.dimensions,
+                field: planned.field,
+            })),
+        });
+    }
+    deserializePlan(raw) {
+        const data = typeof raw === "string" ? JSON.parse(raw) : raw;
+        const fields = new Map(data.fields.map((entry) => [
+            entry.path,
+            {
+                path: entry.path,
+                kind: entry.kind,
+                is_array: entry.is_array,
+                is_date: entry.is_date,
+                dimensions: entry.dimensions,
+                field: entry.field,
+            },
+        ]));
+        return {
+            primary_key: data.primary_key,
+            searchable: data.searchable ?? [],
+            vectors: data.vectors ??
+                [...fields.values()]
+                    .filter((f) => f.kind === "vector")
+                    .map((f) => f.path),
+            schema_hash: data.schema_hash,
+            fields,
+        };
+    }
+    async getCatalog(name, manager = this.manager_) {
+        const rows = (await manager.execute(`SELECT * FROM "${utils_2.CATALOG_TABLE}" WHERE "name" = ?`, [name]));
+        if (!rows.length) {
+            return null;
+        }
+        const row = rows[0];
+        return {
+            name: row.name,
+            table_name: row.table_name,
+            schema_hash: row.schema_hash,
+            plan: this.deserializePlan(row.plan),
+            document_count: Number(row.document_count),
+            created_at: row.created_at,
+            updated_at: row.updated_at,
+        };
+    }
+    async createDocumentTable(table, plan, manager, extensions) {
+        const vectorColumns = plan.vectors
+            .map((path) => {
+            const planned = plan.fields.get(path);
+            const col = (0, utils_2.vectorColumnName)(path);
+            return `"${col}" vector(${planned.dimensions})`;
+        })
+            .join(",\n        ");
+        await manager.execute(`
+      CREATE TABLE IF NOT EXISTS "${table}" (
+        "id" text NOT NULL,
+        "document" jsonb NOT NULL,
+        "indexed" jsonb NOT NULL DEFAULT '{}'::jsonb,
+        "search_vector" tsvector NOT NULL DEFAULT ''::tsvector,
+        "search_text" text NOT NULL DEFAULT '',
+        ${vectorColumns ? `${vectorColumns},` : ""}
+        "created_at" timestamptz NOT NULL DEFAULT now(),
+        "updated_at" timestamptz NOT NULL DEFAULT now(),
+        CONSTRAINT "${table}_pkey" PRIMARY KEY ("id")
+      )
+    `);
+        // Add vector columns if the table already existed without them.
+        for (const path of plan.vectors) {
+            const planned = plan.fields.get(path);
+            const col = (0, utils_2.vectorColumnName)(path);
+            await manager.execute(`
+        ALTER TABLE "${table}"
+        ADD COLUMN IF NOT EXISTS "${col}" vector(${planned.dimensions})
+      `);
+        }
+        if (this.isLakebase_) {
+            // BM25 index is created lazily after documents exist (corpus stats).
+            await manager.execute(`DROP INDEX IF EXISTS "${table}_fts_idx"`);
+        }
+        else {
+            await manager.execute(`CREATE INDEX IF NOT EXISTS "${table}_fts_idx" ON "${table}" USING GIN ("search_vector")`);
+        }
+        if (extensions.pg_trgm) {
+            await manager.execute(`CREATE INDEX IF NOT EXISTS "${table}_trgm_idx" ON "${table}" USING GIN ("search_text" gin_trgm_ops)`);
+        }
+        await manager.execute(`CREATE INDEX IF NOT EXISTS "${table}_indexed_idx" ON "${table}" USING GIN ("indexed" jsonb_path_ops)`);
+        if (this.isLakebase_ && extensions.lakebase_vector) {
+            const opClass = (0, utils_2.vectorOpClass)(this.vectorDistance_);
+            for (const path of plan.vectors) {
+                const col = (0, utils_2.vectorColumnName)(path);
+                await manager.execute(`
+          CREATE INDEX IF NOT EXISTS "${table}_${col}_ann"
+          ON "${table}" USING lakebase_ann ("${col}" ${opClass})
+        `);
+            }
+        }
+    }
+    async ensureBm25Index(table, manager = this.manager_) {
+        if (!this.isLakebase_) {
+            return;
+        }
+        const name = (0, utils_2.bm25IndexName)(table);
+        await manager.execute(`
+      CREATE INDEX IF NOT EXISTS "${name}"
+      ON "${table}" USING lakebase_bm25 ("search_vector")
+      WITH (default_limit = 1000)
+    `);
+    }
+    async dropBm25Index(table, manager = this.manager_) {
+        if (!this.isLakebase_) {
+            return;
+        }
+        await manager.execute(`DROP INDEX IF EXISTS "${(0, utils_2.bm25IndexName)(table)}"`);
+    }
+    async dropDocumentTable(table, manager) {
+        await manager.execute(`DROP TABLE IF EXISTS "${table}" CASCADE`);
+    }
+    /**
+     * Renaming a table leaves its constraint and index names behind, and a later
+     * rebuild of the same shadow name would collide with them (or silently skip
+     * `CREATE INDEX IF NOT EXISTS`). Rename every table-derived artifact too.
+     */
+    async renameTableArtifacts(from, to, plan, manager) {
+        await manager.execute(`ALTER TABLE "${to}" RENAME CONSTRAINT "${from}_pkey" TO "${to}_pkey"`);
+        const suffixes = ["fts_idx", "trgm_idx", "indexed_idx", "bm25"];
+        for (const path of plan.vectors) {
+            suffixes.push(`${(0, utils_2.vectorColumnName)(path)}_ann`);
+        }
+        for (const suffix of suffixes) {
+            await manager.execute(`ALTER INDEX IF EXISTS "${from}_${suffix}" RENAME TO "${to}_${suffix}"`);
+        }
+    }
+    async adjustDocumentCount(name, delta, manager = this.manager_) {
+        if (!delta) {
+            return;
+        }
+        await manager.execute(`UPDATE "${utils_2.CATALOG_TABLE}"
+       SET "document_count" = GREATEST("document_count" + ?, 0), "updated_at" = now()
+       WHERE "name" = ?`, [delta, name]);
+    }
+    async setDocumentCount(name, count, manager = this.manager_) {
+        await manager.execute(`UPDATE "${utils_2.CATALOG_TABLE}"
+       SET "document_count" = ?, "updated_at" = now()
+       WHERE "name" = ?`, [count, name]);
+    }
+    async withTransaction(run) {
+        if (this.manager_.transactional) {
+            return await this.manager_.transactional(run);
+        }
+        return await run(this.manager_);
+    }
+    async upsertIndex({ index, }) {
+        (0, utils_2.assertIndexSupported)(index, this.engine_);
+        const extensions = await this.ensureExtensions();
+        const plan = (0, utils_2.buildIndexPlan)(index);
+        const table = (0, utils_2.tableNameForIndex)(index.physical_name);
+        const existing = await this.getCatalog(index.physical_name);
+        const rebuilt = !!existing && !(0, utils_2.sameSchema)(existing.plan, plan) && !!existing.table_name;
+        await this.withTransaction(async (manager) => {
+            if (rebuilt) {
+                await this.dropDocumentTable(existing.table_name, manager);
+            }
+            await this.createDocumentTable(table, plan, manager, extensions);
+            const planJson = this.serializePlan(plan);
+            if (existing) {
+                await manager.execute(`UPDATE "${utils_2.CATALOG_TABLE}"
+           SET "table_name" = ?, "schema_hash" = ?, "plan" = ?::jsonb,
+               ${rebuilt ? `"document_count" = 0,` : ""}
+               "updated_at" = now()
+           WHERE "name" = ?`, [table, plan.schema_hash, planJson, index.physical_name]);
+            }
+            else {
+                await manager.execute(`INSERT INTO "${utils_2.CATALOG_TABLE}"
+            ("name", "table_name", "schema_hash", "plan", "document_count")
+           VALUES (?, ?, ?, ?::jsonb, 0)`, [index.physical_name, table, plan.schema_hash, planJson]);
+            }
+        });
+        return this.task(index.physical_name);
+    }
+    async deleteIndex({ index, }) {
+        await this.ensureExtensions();
+        const existing = await this.getCatalog(index);
+        if (existing) {
+            await this.dropDocumentTable(existing.table_name, this.manager_);
+            await this.manager_.execute(`DELETE FROM "${utils_2.CATALOG_TABLE}" WHERE "name" = ?`, [index]);
+        }
+        return this.task(index);
+    }
+    async listIndexes() {
+        await this.ensureExtensions();
+        const rows = (await this.manager_.execute(`SELECT "name", "document_count", "created_at", "updated_at"
+       FROM "${utils_2.CATALOG_TABLE}"
+       ORDER BY "name"`));
+        return rows.map((row) => ({
+            name: row.name,
+            provider: PostgresSearchService.identifier,
+            document_count: Number(row.document_count),
+            created_at: row.created_at instanceof Date
+                ? row.created_at
+                : new Date(row.created_at),
+            updated_at: row.updated_at instanceof Date
+                ? row.updated_at
+                : new Date(row.updated_at),
+        }));
+    }
+    async swapIndex({ alias, index, }) {
+        await this.ensureExtensions();
+        const shadow = await this.getCatalog(index);
+        if (!shadow) {
+            throw new utils_1.MedusaError(utils_1.MedusaError.Types.NOT_FOUND, `The postgres search provider has no index "${index}" to swap from`);
+        }
+        const live = await this.getCatalog(alias);
+        const aliasTable = (0, utils_2.tableNameForIndex)(alias);
+        await this.withTransaction(async (manager) => {
+            if (live) {
+                await this.dropDocumentTable(live.table_name, manager);
+                await manager.execute(`DELETE FROM "${utils_2.CATALOG_TABLE}" WHERE "name" = ?`, [alias]);
+            }
+            if (shadow.table_name !== aliasTable) {
+                await manager.execute(`ALTER TABLE "${shadow.table_name}" RENAME TO "${aliasTable}"`);
+                await this.renameTableArtifacts(shadow.table_name, aliasTable, shadow.plan, manager);
+            }
+            await manager.execute(`DELETE FROM "${utils_2.CATALOG_TABLE}" WHERE "name" = ?`, [
+                index,
+            ]);
+            await manager.execute(`INSERT INTO "${utils_2.CATALOG_TABLE}"
+          ("name", "table_name", "schema_hash", "plan", "document_count", "created_at", "updated_at")
+         VALUES (?, ?, ?, ?::jsonb, ?, ?, now())`, [
+                alias,
+                aliasTable,
+                shadow.plan.schema_hash,
+                this.serializePlan(shadow.plan),
+                shadow.document_count,
+                shadow.created_at instanceof Date
+                    ? shadow.created_at
+                    : new Date(shadow.created_at),
+            ]);
+            if (shadow.document_count > 0) {
+                await this.ensureBm25Index(aliasTable, manager);
+            }
+        });
+        return this.task(alias);
+    }
+    buildSearchVectorSql(weightedParts, params) {
+        if (!weightedParts.length) {
+            return `''::tsvector`;
+        }
+        return weightedParts
+            .map((part) => {
+            params.push(part.text);
+            return `setweight(to_tsvector('${this.tsConfig_}', coalesce(?, '')), '${part.weight}')`;
+        })
+            .join(" || ");
+    }
+    async upsertDocuments({ index, documents, }) {
+        await this.ensureExtensions();
+        const catalog = await this.retrieve(index);
+        if (!documents.length) {
+            return this.task(index);
+        }
+        // Last write wins on duplicate ids — a multi-row upsert cannot touch the
+        // same id twice within one statement.
+        const projections = new Map();
+        for (const document of documents) {
+            const projection = (0, utils_2.projectIndexedDocument)(document, catalog.plan);
+            projections.set(projection.id, { document, projection });
+        }
+        const vectors = catalog.plan.vectors;
+        const entries = [...projections.values()];
+        await this.withTransaction(async (manager) => {
+            let inserted = 0;
+            for (let offset = 0; offset < entries.length; offset += UPSERT_CHUNK_SIZE) {
+                const chunk = entries.slice(offset, offset + UPSERT_CHUNK_SIZE);
+                const rowsSql = [];
+                const params = [];
+                for (const { document, projection } of chunk) {
+                    params.push(projection.id, JSON.stringify(document), JSON.stringify(projection.indexed));
+                    const vectorSql = this.buildSearchVectorSql(projection.weighted_parts, params);
+                    params.push(projection.search_text);
+                    const vectorPlaceholders = vectors.map((path) => {
+                        const embedding = projection.vectors[path];
+                        params.push(embedding ? `[${embedding.join(",")}]` : null);
+                        return `?::vector`;
+                    });
+                    rowsSql.push(`(?, ?::jsonb, ?::jsonb, ${vectorSql}, ?${vectorPlaceholders.length
+                        ? `, ${vectorPlaceholders.join(", ")}`
+                        : ""}, now())`);
+                }
+                const vectorCols = vectors.map((path) => `"${(0, utils_2.vectorColumnName)(path)}"`);
+                const vectorUpdates = vectorCols.map((col) => `${col} = EXCLUDED.${col}`);
+                const rows = await manager.execute(`
+          INSERT INTO "${catalog.table_name}"
+            ("id", "document", "indexed", "search_vector", "search_text"${vectorCols.length ? `, ${vectorCols.join(", ")}` : ""}, "updated_at")
+          VALUES ${rowsSql.join(",\n")}
+          ON CONFLICT ("id") DO UPDATE SET
+            "document" = EXCLUDED."document",
+            "indexed" = EXCLUDED."indexed",
+            "search_vector" = EXCLUDED."search_vector",
+            "search_text" = EXCLUDED."search_text"${vectorUpdates.length ? `, ${vectorUpdates.join(", ")}` : ""},
+            "updated_at" = now()
+          RETURNING (xmax = 0)::int AS inserted
+          `, params);
+                for (const row of rows) {
+                    inserted += Number(row.inserted ?? 0);
+                }
+            }
+            await this.adjustDocumentCount(index, inserted, manager);
+        });
+        // Create the BM25 index once documents exist (corpus stats need rows).
+        if (this.isLakebase_) {
+            await this.ensureBm25Index(catalog.table_name);
+        }
+        return this.task(index);
+    }
+    async deleteDocuments({ index, filters, }) {
+        await this.ensureExtensions();
+        const catalog = await this.retrieve(index);
+        await this.withTransaction(async (manager) => {
+            const ids = (0, utils_2.extractPrimaryKeyFilter)(filters, catalog.plan);
+            let deleted = [];
+            if (ids) {
+                if (ids.length) {
+                    deleted = await manager.execute(`DELETE FROM "${catalog.table_name}" WHERE "id" = ANY(?::text[]) RETURNING "id"`, [ids]);
+                }
+            }
+            else {
+                const where = (0, utils_2.toWhereClause)(filters, catalog.plan);
+                if (where?.sql) {
+                    deleted = await manager.execute(`DELETE FROM "${catalog.table_name}" WHERE ${where.sql} RETURNING "id"`, where.params);
+                }
+            }
+            await this.adjustDocumentCount(index, -deleted.length, manager);
+        });
+        return this.task(index);
+    }
+    async clearIndex({ index, }) {
+        await this.ensureExtensions();
+        const catalog = await this.retrieve(index);
+        await this.dropBm25Index(catalog.table_name);
+        await this.manager_.execute(`TRUNCATE TABLE "${catalog.table_name}"`);
+        await this.setDocumentCount(index, 0);
+        return this.task(index);
+    }
+    async search(input) {
+        const extensions = await this.ensureExtensions();
+        (0, utils_2.assertQuerySupported)(input, this.engine_);
+        const catalog = await this.retrieve(input.index.physical_name);
+        const plan = catalog.plan;
+        const options = input.search_options ?? {};
+        const skip = input.pagination?.skip ?? 0;
+        const take = input.pagination?.take ?? 20;
+        const started = Date.now();
+        for (const path of options.attributes_to_search_on ?? []) {
+            if (!plan.searchable.includes(path)) {
+                throw new utils_1.MedusaError(utils_1.MedusaError.Types.INVALID_DATA, `Field "${path}" is not searchable on search index "${input.index.name}"`);
+            }
+        }
+        // Fails early on unknown / unsupported distinct fields.
+        this.resolveDistinct(options.distinct, plan, input.index.name);
+        const q = input.q?.trim();
+        const vectorOpts = options.vector;
+        const semanticRatio = vectorOpts?.semantic_ratio ??
+            (q && vectorOpts ? 0.5 : vectorOpts ? 1 : 0);
+        if (q && !plan.searchable.length && semanticRatio < 1) {
+            throw new utils_1.MedusaError(utils_1.MedusaError.Types.INVALID_DATA, `Search index "${input.index.name}" has no searchable fields, so it cannot be queried by text`);
+        }
+        if (options.typo_tolerance && q) {
+            this.assertTypoToleranceAvailable(extensions);
+        }
+        let queryEmbedding;
+        if (vectorOpts && semanticRatio > 0) {
+            queryEmbedding = await this.resolveQueryEmbedding(vectorOpts, plan);
+        }
+        const useKeyword = !!q && semanticRatio < 1;
+        const useVector = !!queryEmbedding && semanticRatio > 0;
+        let hitRows;
+        let count;
+        if (useKeyword && useVector) {
+            ;
+            ({ hitRows, count } = await this.searchHybrid({
+                input,
+                catalog,
+                extensions,
+                queryEmbedding: queryEmbedding,
+                semanticRatio,
+                skip,
+                take,
+            }));
+        }
+        else if (useVector) {
+            ;
+            ({ hitRows, count } = await this.searchVector({
+                input,
+                catalog,
+                queryEmbedding: queryEmbedding,
+                skip,
+                take,
+            }));
+        }
+        else {
+            ;
+            ({ hitRows, count } = await this.searchKeyword({
+                input,
+                catalog,
+                extensions,
+                skip,
+                take,
+            }));
+        }
+        const facets = await this.resolveFacets({
+            table: catalog.table_name,
+            plan,
+            scopeWhere: this.buildFacetScope({
+                input,
+                catalog,
+                extensions,
+                useKeyword,
+                useVector,
+            }),
+            requests: options.facets,
+        });
+        return {
+            hits: hitRows.map((row) => {
+                const document = typeof row.document === "string"
+                    ? JSON.parse(row.document)
+                    : row.document;
+                return {
+                    id: row.id,
+                    score: options.include_score ? Number(row.score) : undefined,
+                    document: (0, utils_2.projectDocument)(document, input.attributes_to_retrieve),
+                };
+            }),
+            facets,
+            metadata: {
+                skip,
+                take,
+                count: options.count === "none" ? null : count,
+                query: input.q,
+                processing_time_ms: Date.now() - started,
+            },
+        };
+    }
+    async resolveQueryEmbedding(vectorOpts, plan) {
+        const field = vectorOpts.field;
+        const planned = plan.fields.get(field);
+        if (!planned || planned.kind !== "vector") {
+            throw new utils_1.MedusaError(utils_1.MedusaError.Types.INVALID_DATA, `Vector search field "${field}" is not a vector field on this index`);
+        }
+        if (vectorOpts.value) {
+            if (vectorOpts.value.length !== planned.dimensions) {
+                throw new utils_1.MedusaError(utils_1.MedusaError.Types.INVALID_DATA, `Vector value for "${field}" expected ${planned.dimensions} dimensions, got ${vectorOpts.value.length}`);
+            }
+            return vectorOpts.value;
+        }
+        if (!vectorOpts.query) {
+            throw new utils_1.MedusaError(utils_1.MedusaError.Types.INVALID_DATA, `search_options.vector requires either "value" (embedding) or "query" (text to embed)`);
+        }
+        if (!this.embedder_) {
+            throw new utils_1.MedusaError(utils_1.MedusaError.Types.INVALID_ARGUMENT, `search_options.vector.query requires an "embedder" function on the postgres search provider options`);
+        }
+        const embedding = await this.embedder_(vectorOpts.query);
+        if (embedding.length !== planned.dimensions) {
+            throw new utils_1.MedusaError(utils_1.MedusaError.Types.INVALID_DATA, `Embedder returned ${embedding.length} dimensions for "${field}", expected ${planned.dimensions}`);
+        }
+        return embedding;
+    }
+    /**
+     * The keyword match/rank fragments, shared by the keyword path, the hybrid
+     * count and the facet scope so they always describe the same result set.
+     * Each fragment pushes its own placeholders when invoked.
+     */
+    keywordFragments(input) {
+        const { query, catalog, extensions } = input;
+        const plan = catalog.plan;
+        const options = query.search_options ?? {};
+        const q = query.q?.trim() || undefined;
+        const typo = !!(q && options.typo_tolerance);
+        const matchAny = options.match_strategy === "any";
+        const searchOn = options.attributes_to_search_on ?? plan.searchable;
+        const searchAllFields = searchOn.length === plan.searchable.length &&
+            searchOn.every((path) => plan.searchable.includes(path));
+        const tsConfig = this.tsConfig_;
+        const vectorExpr = searchAllFields
+            ? `"search_vector"`
+            : this.onTheFlyVectorExpr(searchOn, plan);
+        const textExpr = searchAllFields
+            ? `"search_text"`
+            : this.onTheFlyTextExpr(searchOn);
+        const useBm25 = this.isLakebase_ && !!q && searchAllFields;
+        const tsquery = (params) => {
+            params.push(q);
+            // plainto_tsquery ANDs every term; match_strategy "any" flips it to OR.
+            return matchAny
+                ? `replace(plainto_tsquery('${tsConfig}', ?)::text, ' & ', ' | ')::tsquery`
+                : `plainto_tsquery('${tsConfig}', ?)`;
+        };
+        const wordSim = (params) => {
+            params.push(q);
+            return (0, utils_2.wordSimilarityCall)(extensions, "?", textExpr);
+        };
+        const rankSql = (params) => {
+            if (!q) {
+                return `0::float4`;
+            }
+            let base;
+            if (useBm25) {
+                params.push(q);
+                const bm25 = (0, utils_2.bm25IndexName)(catalog.table_name);
+                // Negative BM25 → negate so higher scores are better (API convention).
+                base = `-1 * (${vectorExpr} <@> to_bm25query(to_tsvector('${tsConfig}', ?), '${bm25}'::regclass))`;
+            }
+            else {
+                base = `ts_rank_cd(${vectorExpr}, ${tsquery(params)})`;
+            }
+            return typo ? `GREATEST(${base}, ${wordSim(params)})` : base;
+        };
+        const matchSql = q
+            ? (params) => {
+                const match = `${vectorExpr} @@ ${tsquery(params)}`;
+                return typo ? `(${match} OR ${wordSim(params)} > 0.3)` : match;
+            }
+            : undefined;
+        return { q, needsBm25Limit: useBm25, rankSql, matchSql };
+    }
+    async searchKeyword(input) {
+        const { input: query, catalog, extensions, skip, take } = input;
+        const plan = catalog.plan;
+        const options = query.search_options ?? {};
+        const filterWhere = (0, utils_2.toWhereClause)(query.filters, plan);
+        const fragments = this.keywordFragments({ query, catalog, extensions });
+        const conditionsSql = (params) => {
+            const conditions = [];
+            if (fragments.matchSql) {
+                conditions.push(fragments.matchSql(params));
+            }
+            if (filterWhere?.sql) {
+                conditions.push(`(${filterWhere.sql})`);
+                params.push(...filterWhere.params);
+            }
+            return conditions;
+        };
+        const prelude = fragments.needsBm25Limit
+            ? async (manager) => {
+                const bm25 = (0, utils_2.bm25IndexName)(catalog.table_name);
+                const [row] = await manager.execute(`SELECT to_regclass(?) IS NOT NULL AS exists`, [bm25]);
+                if (!row?.exists) {
+                    await this.ensureBm25Index(catalog.table_name, manager);
+                }
+                await manager.execute(`SELECT set_config('lakebase_bm25.default_limit', ?, true)`, [String(take + skip)]);
+            }
+            : undefined;
+        return await this.executeQuery({
+            table: catalog.table_name,
+            rankSql: fragments.rankSql,
+            conditionsSql,
+            orderSql: this.resolveOrderBy(query, plan, !!fragments.q),
+            minScore: options.min_score,
+            distinctExpr: this.resolveDistinct(options.distinct, plan, query.index.name),
+            count: options.count !== "none",
+            take,
+            skip,
+            prelude,
+        });
+    }
+    async searchVector(input) {
+        const { input: query, catalog, queryEmbedding, skip, take } = input;
+        const options = query.search_options ?? {};
+        const field = options.vector?.field;
+        if (!field) {
+            throw new utils_1.MedusaError(utils_1.MedusaError.Types.INVALID_DATA, `search_options.vector.field is required for vector search`);
+        }
+        const col = (0, utils_2.vectorColumnName)(field);
+        const op = (0, utils_2.vectorDistanceOperator)(this.vectorDistance_);
+        const filterWhere = (0, utils_2.toWhereClause)(query.filters, catalog.plan);
+        const embeddingLiteral = `[${queryEmbedding.join(",")}]`;
+        const rankSql = (params) => {
+            params.push(embeddingLiteral);
+            // Distance → relevance (higher is better).
+            return `(1.0 / (1.0 + ("${col}" ${op} ?::vector)))`;
+        };
+        const conditionsSql = (params) => {
+            const conditions = [`"${col}" IS NOT NULL`];
+            if (filterWhere?.sql) {
+                conditions.push(`(${filterWhere.sql})`);
+                params.push(...filterWhere.params);
+            }
+            return conditions;
+        };
+        const hasCustomOrder = !!Object.keys(query.pagination?.order ?? {}).length;
+        // The default order is distance ASC; expressed directly (instead of via
+        // the score alias) so the ANN index can serve the scan.
+        const fastOrderSql = hasCustomOrder
+            ? undefined
+            : (params) => {
+                params.push(embeddingLiteral);
+                return `"${col}" ${op} ?::vector ASC, "id" ASC`;
+            };
+        return await this.executeQuery({
+            table: catalog.table_name,
+            rankSql,
+            conditionsSql,
+            orderSql: this.resolveOrderBy(query, catalog.plan, true),
+            fastOrderSql,
+            minScore: options.min_score,
+            distinctExpr: this.resolveDistinct(options.distinct, catalog.plan, query.index.name),
+            count: options.count !== "none",
+            take,
+            skip,
+        });
+    }
+    async searchHybrid(input) {
+        const { input: query, catalog, extensions, queryEmbedding, semanticRatio, skip, take, } = input;
+        const options = query.search_options ?? {};
+        const plan = catalog.plan;
+        const order = query.pagination?.order ?? {};
+        const fieldOrderKeys = Object.keys(order).filter((key) => key !== "_score");
+        if (fieldOrderKeys.length) {
+            throw new utils_1.MedusaError(utils_1.MedusaError.Types.NOT_ALLOWED, `Hybrid search results are rank-fused, so they can only be ordered by "_score" (got "${fieldOrderKeys.join(", ")}"). Drop the vector option or the field order.`);
+        }
+        // Arms are relevance-ranked candidate lists; page-level options (distinct,
+        // min_score, count, order) apply to the fused list instead.
+        const candidateLimit = Math.max(take + skip, 40) * 2;
+        const armQuery = {
+            ...query,
+            pagination: {},
+            search_options: {
+                ...options,
+                min_score: undefined,
+                distinct: undefined,
+                count: "none",
+            },
+        };
+        const [keyword, vector] = await Promise.all([
+            this.searchKeyword({
+                input: armQuery,
+                catalog,
+                extensions,
+                skip: 0,
+                take: candidateLimit,
+            }),
+            this.searchVector({
+                input: armQuery,
+                catalog,
+                queryEmbedding,
+                skip: 0,
+                take: candidateLimit,
+            }),
+        ]);
+        // Reciprocal Rank Fusion over keyword + vector candidate lists. Fused
+        // scores live on the RRF scale (≤ ~1/60 per arm), which is also the scale
+        // `min_score` is compared against for hybrid queries.
+        const k = 60;
+        const keywordWeight = 1 - semanticRatio;
+        const vectorWeight = semanticRatio;
+        const scores = new Map();
+        keyword.hitRows.forEach((row, rank) => {
+            scores.set(row.id, {
+                id: row.id,
+                document: row.document,
+                indexed: row.indexed,
+                score: keywordWeight * (1 / (k + rank + 1)),
+            });
+        });
+        vector.hitRows.forEach((row, rank) => {
+            const rrf = vectorWeight * (1 / (k + rank + 1));
+            const existing = scores.get(row.id);
+            if (existing) {
+                existing.score += rrf;
+            }
+            else {
+                scores.set(row.id, {
+                    id: row.id,
+                    document: row.document,
+                    indexed: row.indexed,
+                    score: rrf,
+                });
+            }
+        });
+        let ranked = [...scores.values()].sort((a, b) => b.score - a.score);
+        if (options.distinct) {
+            const seen = new Set();
+            ranked = ranked.filter((row) => {
+                const key = this.readIndexedValue(row.indexed, options.distinct);
+                if (key === undefined) {
+                    return true;
+                }
+                if (seen.has(key)) {
+                    return false;
+                }
+                seen.add(key);
+                return true;
+            });
+        }
+        if (options.min_score !== undefined) {
+            ranked = ranked.filter((row) => row.score >= options.min_score);
+        }
+        if (order._score === "ASC") {
+            ranked.reverse();
+        }
+        const page = ranked.slice(skip, skip + take);
+        // The fused list is a bounded candidate window, so its length is not a
+        // usable total — count the union of both arms' match sets instead.
+        let count = null;
+        if (options.count !== "none") {
+            const fragments = this.keywordFragments({ query, catalog, extensions });
+            const col = (0, utils_2.vectorColumnName)(options.vector.field);
+            const filterWhere = (0, utils_2.toWhereClause)(query.filters, plan);
+            const params = [];
+            const conditions = [
+                `(${fragments.matchSql(params)} OR "${col}" IS NOT NULL)`,
+            ];
+            if (filterWhere?.sql) {
+                conditions.push(`(${filterWhere.sql})`);
+                params.push(...filterWhere.params);
+            }
+            const distinctExpr = this.resolveDistinct(options.distinct, plan, query.index.name);
+            const countExpr = distinctExpr
+                ? `COUNT(DISTINCT ${distinctExpr})`
+                : `COUNT(*)`;
+            const rows = await this.manager_.execute(`SELECT ${countExpr}::int AS count FROM "${catalog.table_name}" WHERE ${conditions.join(" AND ")}`, params);
+            count = Number(rows[0]?.count ?? 0);
+        }
+        return { hitRows: page, count };
+    }
+    /**
+     * Runs the hits + count statements for a single-arm search. Wraps the base
+     * select in subqueries when `min_score` or `distinct` need to see the score
+     * as a real column.
+     */
+    async executeQuery(parts) {
+        const { table, minScore, distinctExpr, take, skip } = parts;
+        const wrap = minScore !== undefined || !!distinctExpr;
+        const buildBase = (params) => {
+            const rank = parts.rankSql(params);
+            const conditions = parts.conditionsSql(params);
+            const whereSql = conditions.length
+                ? `WHERE ${conditions.join(" AND ")}`
+                : "";
+            return `SELECT "id", "document", "indexed", ${rank} AS score FROM "${table}" ${whereSql}`;
+        };
+        const buildWrappedFrom = (params) => {
+            let from = `(${buildBase(params)}) ranked`;
+            if (distinctExpr) {
+                // One representative row per value, picked by the requested order.
+                from = `(
+          SELECT ranked.*, ROW_NUMBER() OVER (
+            PARTITION BY ${distinctExpr} ORDER BY ${parts.orderSql}
+          ) AS __rn
+          FROM ${from}
+        ) deduped`;
+            }
+            return from;
+        };
+        const wrappedConditions = () => {
+            const outer = [];
+            if (distinctExpr) {
+                outer.push(`__rn = 1`);
+            }
+            if (minScore !== undefined) {
+                outer.push(`score >= ?`);
+            }
+            return outer;
+        };
+        let hitsSql;
+        const hitsParams = [];
+        if (!wrap) {
+            const base = buildBase(hitsParams);
+            const orderSql = parts.fastOrderSql
+                ? parts.fastOrderSql(hitsParams)
+                : parts.orderSql;
+            hitsSql = `${base} ORDER BY ${orderSql} LIMIT ? OFFSET ?`;
+            hitsParams.push(take, skip);
+        }
+        else {
+            const from = buildWrappedFrom(hitsParams);
+            const outer = wrappedConditions();
+            hitsSql = `
+        SELECT * FROM ${from}
+        ${outer.length ? `WHERE ${outer.join(" AND ")}` : ""}
+        ORDER BY ${parts.orderSql}
+        LIMIT ? OFFSET ?
+      `;
+            if (minScore !== undefined) {
+                hitsParams.push(minScore);
+            }
+            hitsParams.push(take, skip);
+        }
+        let countSql = null;
+        const countParams = [];
+        if (parts.count) {
+            if (!wrap) {
+                const conditions = parts.conditionsSql(countParams);
+                countSql = `SELECT COUNT(*)::int AS count FROM "${table}" ${conditions.length ? `WHERE ${conditions.join(" AND ")}` : ""}`;
+            }
+            else {
+                const from = buildWrappedFrom(countParams);
+                const outer = wrappedConditions();
+                countSql = `
+          SELECT COUNT(*)::int AS count FROM ${from}
+          ${outer.length ? `WHERE ${outer.join(" AND ")}` : ""}
+        `;
+                if (minScore !== undefined) {
+                    countParams.push(minScore);
+                }
+            }
+        }
+        const run = async (manager) => {
+            if (parts.prelude) {
+                await parts.prelude(manager);
+            }
+            const hitRows = await manager.execute(hitsSql, hitsParams);
+            const count = countSql
+                ? Number((await manager.execute(countSql, countParams))[0]?.count ?? 0)
+                : null;
+            return { hitRows, count };
+        };
+        // set_config in the prelude is transaction-local, so it needs the hits
+        // query inside the same transaction. Plain reads skip the overhead.
+        return parts.prelude ? await this.withTransaction(run) : await run(this.manager_);
+    }
+    async searchMany(inputs) {
+        return await Promise.all(inputs.map((input) => this.search(input)));
+    }
+    /**
+     * The WHERE fragment facets are scoped by: the filters plus the same match
+     * predicate as the hits, so facet counts describe the result set.
+     */
+    buildFacetScope(input) {
+        const { input: query, catalog, extensions, useKeyword, useVector } = input;
+        const params = [];
+        const conditions = [];
+        const matchSql = useKeyword
+            ? this.keywordFragments({ query, catalog, extensions }).matchSql
+            : undefined;
+        const vectorCond = useVector
+            ? `"${(0, utils_2.vectorColumnName)(query.search_options.vector.field)}" IS NOT NULL`
+            : undefined;
+        if (matchSql && vectorCond) {
+            conditions.push(`(${matchSql(params)} OR ${vectorCond})`);
+        }
+        else if (matchSql) {
+            conditions.push(matchSql(params));
+        }
+        else if (vectorCond) {
+            conditions.push(vectorCond);
+        }
+        const filterWhere = (0, utils_2.toWhereClause)(query.filters, catalog.plan);
+        if (filterWhere?.sql) {
+            conditions.push(`(${filterWhere.sql})`);
+            params.push(...filterWhere.params);
+        }
+        return conditions.length
+            ? { sql: conditions.join(" AND "), params }
+            : undefined;
+    }
+    async resolveFacets(input) {
+        const requests = (0, utils_2.normalizeFacetRequests)(input.requests, input.plan);
+        if (!requests.length) {
+            return undefined;
+        }
+        const result = {};
+        for (const request of requests) {
+            const query = (0, utils_2.buildFacetQuery)({
+                table: input.table,
+                whereSql: input.scopeWhere?.sql,
+                whereParams: input.scopeWhere?.params ?? [],
+                request,
+                plan: input.plan,
+            });
+            const rows = await this.manager_.execute(query.sql, query.params);
+            result[request.field] = (0, utils_2.mapFacetResult)(request, rows);
+        }
+        return result;
+    }
+    onTheFlyTextExpr(paths) {
+        if (!paths.length) {
+            return `''`;
+        }
+        return paths
+            .map((path) => {
+            const jsonPath = `'{${path.split(".").join(",")}}'`;
+            return `coalesce(indexed#>>${jsonPath}, '')`;
+        })
+            .join(` || ' ' || `);
+    }
+    onTheFlyVectorExpr(paths, plan) {
+        if (!paths.length) {
+            return `''::tsvector`;
+        }
+        return paths
+            .map((path) => {
+            const planned = plan.fields.get(path);
+            const weight = planned ? (0, utils_2.weightLabel)(planned.field.searchable) : "D";
+            const jsonPath = `'{${path.split(".").join(",")}}'`;
+            return `setweight(to_tsvector('${this.tsConfig_}', coalesce(indexed#>>${jsonPath}, '')), '${weight}')`;
+        })
+            .join(" || ");
+    }
+    resolveOrderBy(input, plan, hasScore) {
+        const order = Object.entries(input.pagination?.order ?? {});
+        if (!order.length) {
+            return hasScore
+                ? `score DESC NULLS LAST, "id" ASC`
+                : `"id" ASC`;
+        }
+        const clauses = [];
+        for (const [property, direction] of order) {
+            const dir = direction === "ASC" ? "ASC" : "DESC";
+            if (property === "_score") {
+                clauses.push(`score ${dir} NULLS LAST`);
+                continue;
+            }
+            const planned = plan.fields.get(property);
+            if (!planned) {
+                throw new utils_1.MedusaError(utils_1.MedusaError.Types.INVALID_DATA, `Cannot sort search index "${input.index.name}" by unknown field "${property}"`);
+            }
+            if (planned.is_array || planned.kind === "vector") {
+                throw new utils_1.MedusaError(utils_1.MedusaError.Types.NOT_ALLOWED, `The postgres search provider cannot sort by "${property}"`);
+            }
+            const jsonPath = `'{${property.split(".").join(",")}}'`;
+            if (planned.kind === "number") {
+                clauses.push(`(indexed#>>${jsonPath})::float8 ${dir} NULLS LAST`);
+            }
+            else if (planned.kind === "boolean") {
+                clauses.push(`(indexed#>>${jsonPath})::boolean ${dir} NULLS LAST`);
+            }
+            else {
+                clauses.push(`indexed#>>${jsonPath} ${dir} NULLS LAST`);
+            }
+        }
+        return clauses.join(", ");
+    }
+    /**
+     * Validates `search_options.distinct` and returns the SQL expression to
+     * deduplicate on, or undefined when not requested.
+     */
+    resolveDistinct(distinct, plan, indexName) {
+        if (!distinct) {
+            return undefined;
+        }
+        const planned = plan.fields.get(distinct);
+        if (!planned) {
+            throw new utils_1.MedusaError(utils_1.MedusaError.Types.INVALID_DATA, `Cannot deduplicate search index "${indexName}" by unknown field "${distinct}"`);
+        }
+        if (planned.is_array || planned.kind === "vector") {
+            throw new utils_1.MedusaError(utils_1.MedusaError.Types.NOT_ALLOWED, `The postgres search provider cannot deduplicate by "${distinct}"`);
+        }
+        return `indexed#>>'{${distinct.split(".").join(",")}}'`;
+    }
+    /** Reads a dotted path from an `indexed` jsonb value returned by a query. */
+    readIndexedValue(indexed, path) {
+        const parsed = typeof indexed === "string" ? JSON.parse(indexed) : indexed;
+        const value = path
+            .split(".")
+            .reduce((acc, segment) => (acc == null ? undefined : acc[segment]), parsed);
+        return value == null ? undefined : String(value);
+    }
+    async retrieve(index) {
+        const catalog = await this.getCatalog(index);
+        if (!catalog) {
+            const known = await this.listIndexes();
+            throw new utils_1.MedusaError(utils_1.MedusaError.Types.NOT_FOUND, `The postgres search provider has no index "${index}". Known indexes: ${known.map((entry) => entry.name).join(", ") || "(none)"}`);
+        }
+        return catalog;
+    }
+    task(index) {
+        return { index, status: "succeeded" };
+    }
+}
+exports.PostgresSearchService = PostgresSearchService;
+PostgresSearchService.identifier = "search-postgres";
+//# sourceMappingURL=postgres-search.js.map