Medusa Search

You are an AI coding agent. The prompt below sets up, verifies, and extends Medusa Search, the managed search service of Cloud, in the user's Medusa project. Follow it end-to-end, then report the steps it hands back to the user.

Prefer the Cloud CLI (mcloud) for every Cloud operation you can run yourself, and direct the user to the Cloud dashboard only for the actions the CLI doesn't cover.

The prompt's reference section is an extract of the API, not all of it. Query the Docs MCP server or fetch the guides at https://docs.medusajs.com for anything it leaves out.

Medusa Search Prompt

Role

You are a senior Medusa developer setting up and using Medusa Search, the managed search service of Cloud, in an existing Medusa project deployed on Cloud.

Task

Set up, verify, and extend Medusa Search in the user's Medusa project so every entity the project searches is indexed and served by it.

Context

• Medusa Search is a provider of the Search Module. Cloud enables it by default for projects on Medusa v2.21.1 and later, and passes the credentials to every environment, so it needs no provider registration in medusa-config.ts and no credentials in the project.
• Medusa declares no index by default, so a project declares its own product index definition under src/search. A project installed after v2.21.1 ships with one at src/search/product.ts, and any other project may or may not have it.
• An index definition lives in a file under src/search, declares the fields the engine holds, fills the index with a seed async generator, and keeps it current with its events and consume properties.
• The graphSeed and graphConsume helpers build seed and consume from Query, so an index of an entity Query exposes needs neither written by hand. They take the same options, including a transform that maps a page of records to the documents to index. Every document must carry the record's primary key as id, and a record you leave out of the returned array stays out of the index.
• Medusa's Store API has a POST /store/search route that searches any index of the application, so a project doesn't need its own product search route. The body is a search query naming the index in entity, or a batch of them under queries, and each accepts fields, filters (including q), pagination, and search_options.
• An index is only reachable through POST /store/search once a middleware allows it with configureStoreSearch from @medusajs/framework/http, which takes an allowed_indexes object. The route narrows a product index to published products in the publishable API key's sales channels, and any further constraint is that middleware's filters option.
• Queries in a custom route run through query.search. There is no browser-side querying and no search-only key.
• Each Cloud environment has its own indexes, scoped by the environment's handle, so a preview environment never writes to production indexes. A preview branches its indexes from the base environment set in the shared previews settings, and starts with none when no base is set.
• In local development, Medusa registers the PostgreSQL Search Module Provider by default. A local project reaches Cloud's search resources only through a connection string set as MEDUSA_SEARCH_ENDPOINT and a development-only Search Module registration in medusa-config.ts. The string carries read and write access, so it suits testing rather than day-to-day local work.
• Medusa Search supports full-text search with per-field weights, typo tolerance, semantic search over embeddings, filters, facets, highlighting, and sorting. Typo tolerance and highlighting are opt-in per query through search_options, and both need a text query. Vector search is a Scale and Enterprise plan feature, and an embedding the project computes itself can have at most 1536 dimensions. Only the Enterprise plan creates the embeddings for the project.
• Search requests are a metered resource. Requests past the plan's allowance count as Flex Usage. One query.search call counts as one search request, however many facets it computes and whether or not it returns a count, so a page costs one request per search it runs. Writes count too, at one request per record written to an index, so the first seed of a large catalog costs one request per record.
• A searchable field matches terms as written. Stemming is off until the field's full_text_search provider option sets stemming: true and a language, such as dutch or german. A field holds one language, so a multi-market catalog declares a field per locale.
• Medusa Search doesn't support synonyms or boosting a hit by an attribute's value. Relevance comes from the weight of each searchable field.

CLI Usage

Use the Cloud CLI for every Cloud operation it covers, and pass --json whenever you parse the output.

The commands below are the ones this task needs. For any other command, flag, or output shape, ask the Docs MCP server or fetch the CLI reference at https://docs.medusajs.com/cloud/cli, and read https://docs.medusajs.com/cloud/cli/agents for the CLI's working principles for agents. Never guess a flag.

• Run mcloud version to confirm the CLI is installed. If it isn't, install it with npm install @medusajs/mcloud -g.
• Run mcloud whoami --json before anything else to confirm the user is logged in and to read the active context. If it fails, tell the user to run mcloud login themselves, since the command opens a browser.
• Run mcloud organizations list --json, mcloud projects list --json, and mcloud environments list --json to resolve the organization, project, and environment the user means, and ask them which one to use when more than one fits.
• Run mcloud use --organization <id> --project <id> --environment <id> once, then drop the flags from later commands.
• Run mcloud deployments list --json and mcloud deployments get <id> --json to check whether the latest deployment succeeded, and mcloud deployments build-logs <id> when it failed.
• Run mcloud logs --search "Search indexes migrated" to confirm the environment migrated its indexes, and mcloud logs --search "error" to find a failed seed.
• Run mcloud variables list --json to read an environment's variables, and mcloud variables set <key> <value> to add one. Pass --reveal only when the user asks for secret values.
• Run mcloud environments redeploy after changing a variable, and mcloud environments trigger-build to build the latest commit of the environment's branch.
• Run mcloud local build to reproduce a Cloud build on the user's machine when a deployment fails to build.

Steps

1. Report what the project has before you change anything: the Medusa version in package.json, any file under src/search, any custom search route, the storefront's search client, and any third-party search integration.
2. If the Medusa version is below v2.21.1, stop and tell the user they need to upgrade first. If the user confirms the update, update their project for them. Use the Docs MCP to retrieve update instructions based on their version, or retrieve the release details from GitHub at https://github.com/medusajs/medusa/releases.
3. Confirm the Cloud context with the CLI as described in cli_usage, and report the organization, project, and environment you'll work against.
4. Check the environment's latest deployment and its logs for the index migration. If the deployment failed, read its build logs and fix the build before anything else. If the migration didn't run, report what the logs show rather than guessing.
5. Ask the user to confirm the product index is Ready in the Medusa Admin dashboard, as described in dashboard_handoffs. This requires the Medusa application to be running at least in development.
6. Search the deployed environment by posting {\"entity\": \"product\", \"filters\": {\"q\": \"<term>\"}} to /store/search with a publishable API key, and report the hits and metadata it returns, as shown in "The Store API search route". Ask the user for the key rather than reading it from a file that isn't in the project.
7. Confirm the project declares a product index, which ships at src/search/product.ts, and create it if the file isn't there. Then decide whether it holds every field the project searches, filters, facets, and sorts by, and report what's missing.
8. Create or customize the index definition under src/search. Mark each field searchable() with a weight, filterable(), facetable(), or sortable() by how the project uses it. Build seed and consume with graphSeed and graphConsume, sharing one options object between them, and put the project's indexing rules in its transform, such as leaving an unpublished record out of the documents it returns. List the entity's create, update, and delete events in events. Follow "An index definition", "Index part of an entity", and "Share one options object between the helpers".
9. Allow every index the storefront searches on /store/search with the configureStoreSearch middleware in src/api/middlewares.ts, as shown in "The Store API search route". An index the middleware doesn't allow answers exactly like one that doesn't exist. The route narrows a product index to published products in the publishable API key's sales channels, so add a filters option only for a further constraint.
10. Write an API route with query.search only for a result the built-in route can't answer with, such as one reshaped for the storefront. Respond with the hydrated records from data and the metadata from search_result, and don't also return search_result.hits, since each hit's document repeats a record already returned. Follow "A search API route", and read "Filters", "Pagination and sorting", "Search options", "Facets", and "Highlighting" for what the query accepts.
11. Update the storefront to search through Medusa. For InstantSearch widgets, install @medusajs/instantsearch-adapter, create its search client with the storefront's JS SDK instance and the path /store/search, and pass the client and the index name to the InstantSearch provider, as shown in "The storefront search client". Otherwise, post to /store/search with the JS SDK.
12. Run npx medusa db:migrate --execute-all-links to create the index locally, then run the project's type check and tests, and report the result. Never run medusa db:migrate without that flag: it asks which link tables to sync, and the prompt is swallowed when the command's output is piped, so it waits forever.
13. Hand the deployment back to the user: they push the changes to a preview environment's branch, confirm the index fills there, then merge into the production environment's branch.

Constraints

• Do not register a search provider in medusa-config.ts for a Cloud environment. Cloud registers Medusa Search itself, and a manual registration overrides it. A local registration must be guarded by a development check.
• Do not set MEDUSA_SEARCH_ENDPOINT in a Cloud environment. It belongs in a local .env file only, and never alongside MEDUSA_CLOUD_API_KEY, which throws when the provider initializes.
• Do not print, commit, or write a connection string, an API key, or a publishable key into any file other than a local .env that git ignores.
• Do not modify POST /store/search or recreate it in the project.
• Do not filter, facet, or sort on a field the index definition doesn't mark filterable(), facetable(), or sortable().
• Do not delete a project or an environment, run a deployment, or push to any branch.
• Do not use vector search without confirming the organization is on a Scale or Enterprise plan, and do not let Medusa Search create the embeddings unless the plan is Enterprise. Follow "A semantic search field" and "Semantic and hybrid search" once it is.
• Do not narrow a graphSeed read with a filter to index part of an entity. Leave the record out of the documents transform returns instead, so a record that stops qualifying leaves the index.
• Do not repeat the fields and transform in the graphSeed and graphConsume calls. Declare one options object and pass it to both.
• Never run a Medusa or Cloud CLI command that can prompt without the flag that skips its prompts. A swallowed prompt reads as a hung command rather than an error, since the command keeps waiting with no output.
• Consult the Medusa documentation at https://docs.medusajs.com or the Docs MCP server for any API details you need, including the index definition properties, field types and modifiers, the options of graphSeed and graphConsume, and the options of query.search.

Error Handling

• If mcloud whoami reports no session, ask the user to run mcloud login and wait. Never attempt to authenticate on their behalf.
• If the project isn't deployed on Cloud, report that Medusa Search needs a Cloud project, and set the project up with the PostgreSQL Search Module Provider locally instead.
• If an index's status stays Error, read the environment's logs for the failed seed and report the cause rather than rebuilding the index repeatedly.
• If a search returns no results while the index is Ready, check that the query's fields are searchable(), that the products are published and in the request's sales channel, and that the query passes typo_tolerance when the term is misspelled, then report what you found.
• If a feature the project needs has no Medusa Search equivalent, such as synonyms, merchandising rules, geo search, or search analytics, list it under manual follow-ups instead of implementing a workaround.
• If a step needs the dashboard, stop and ask the user, quoting the path from dashboard_handoffs.
• If the repository holds no storefront, skip step 11 and list the storefront work under manual follow-ups.
• If the entity the user wants indexed isn't exposed by Query, write seed and consume yourself as described in "Custom seed and consume" rather than forcing the helpers onto it.
• If you can't tell whether a field is searched, filtered, faceted, sorted, or only displayed, ask the user rather than guessing.

Useful Documentation Links

Query the Docs MCP server or fetch these guides for the details this reference leaves out:

• Index definitions, graphSeed, graphConsume, and custom seed and consume: https://docs.medusajs.com/resources/infrastructure-modules/search/index-definitions
• Field types: https://docs.medusajs.com/resources/infrastructure-modules/search/index-definitions/fields
• Field modifiers: https://docs.medusajs.com/resources/infrastructure-modules/search/index-definitions/modifiers
• Indexing data from a linked module: https://docs.medusajs.com/resources/infrastructure-modules/search/index-definitions/linked-data
• Reindexing, migrations, and the catch-up pass: https://docs.medusajs.com/resources/infrastructure-modules/search/reindexing
• query.search, filters, pagination, search options, facets, highlighting, and vector search: https://docs.medusajs.com/learn/fundamentals/query/search
• Index, field, and query settings for Medusa Search: https://docs.medusajs.com/cloud/search/settings
• Semantic search: https://docs.medusajs.com/cloud/search/semantic-search
• The InstantSearch adapter: https://docs.medusajs.com/resources/instantsearch
• The Store API search route: https://docs.medusajs.com/api/store/search/search-indexes
• Medusa Search itself, including the index statuses and local development: https://docs.medusajs.com/cloud/search