The complete open source platform to run your entire marketplace. Storefront, vendor panel, admin console, and integrations in one enterprise-grade platform you own.
TypeScript b2b-marketplacecomposable-commerceecommerceenterpriseheadless-commercemarketplacemedusamedusajsmulti-vendortypescript
docs: correct cross-module filtering to use the Index Module (query.index)
vholik52da8e4d1b59
diff --git a/apps/docs/rc/resources/best-practices/api-routes.mdx b/apps/docs/rc/resources/best-practices/api-routes.mdxindex e88e8e43e..448f7beb9 100644--- a/apps/docs/rc/resources/best-practices/api-routes.mdx+++ b/apps/docs/rc/resources/best-practices/api-routes.mdx@@ -174,42 +174,44 @@ const { data: brands, metadata } = await query.graph({## Middlewares as filters-Middlewares aren't only for validation — they're where you inject **scoping filters** so handlers stay ignorant of the rule. A small middleware writes onto `req.filterableFields`; because the handler already forwards that to Query, the scope is applied without the handler knowing. For example, let `GET /admin/products?brand_id=…` filter products by their linked brand:+Middlewares aren't only for validation — they're where you inject **scoping filters** so handlers stay ignorant of the rule. A small middleware writes onto `req.filterableFields`; because the handler already forwards that to Query, the scope is applied without the handler knowing. For example, force `GET /admin/brands` to only ever return active rows:-```ts title="src/api/admin/products/middlewares.ts"+```ts title="src/api/admin/brands/middlewares.ts"import {MedusaRequest,MedusaResponse,MedusaNextFunction,} from "@medusajs/framework/http"-const filterByBrand = (+const onlyActive = (req: MedusaRequest,_res: MedusaResponse,next: MedusaNextFunction) => {- if (req.query.brand_id) {- req.filterableFields.brand = { id: req.query.brand_id }- }+ req.filterableFields.is_active = true // a column on the brand module itselfnext()}-export const adminProductsMiddlewares = [+export const adminBrandsMiddlewares = [{method: ["GET"],- matcher: "/admin/products",+ matcher: "/admin/brands",middlewares: [- validateAndTransformQuery(AdminGetProductsParams, adminProductQueryConfig.list),- filterByBrand,+ validateAndTransformQuery(AdminGetBrandsParams, adminBrandQueryConfig.list),+ onlyActive,],},]```<Tip>- Filtering by a **linked** field (like `brand`) works because the [module link](/rc/resources/best-practices/module-links#filtering-by-links) exists — Query resolves the relation. Applying it in middleware means a new route on the same resource is scoped correctly by construction, not by remembering to add a filter.+ Injecting a filter in middleware means a new route on the same resource is scoped by construction, not by remembering to add a filter. This works with `query.graph` because `is_active` lives on the **brand's own module**.</Tip>+<Warning>+ You can only filter this way on a field that belongs to the entity's **own module**. Filtering by a **linked** module's field (e.g. products by their `brand`) does **not** work with `query.graph` — Query aggregates modules after the fact, so there's no join to filter on. Cross-module filtering requires the [Index Module](/rc/resources/best-practices/module-links#filtering-by-a-linked-field--the-index-module) and `query.index`.+</Warning>+## Trust the auth middlewareAuthentication and actor resolution happen in middleware (`authenticate`), so by the time your handler runs the actor is already established — **trust it**. Read identity from the request context, never from the body:diff --git a/apps/docs/rc/resources/best-practices/custom-fields.mdx b/apps/docs/rc/resources/best-practices/custom-fields.mdxindex 5e2821a29..883653533 100644--- a/apps/docs/rc/resources/best-practices/custom-fields.mdx+++ b/apps/docs/rc/resources/best-practices/custom-fields.mdx@@ -43,10 +43,10 @@ Register the Custom Fields module and describe the field in `medusa-config.ts`.}```-The value now lives in the module's own `custom_fields` side table — linked to the product, queryable through `query.graph`, and written through `additional_data` on the entity's create/update route.+The value now lives in the module's own `custom_fields` side table — linked to the product, readable alongside it through `query.graph`, and written through `additional_data` on the entity's create/update route. (Filtering products *by* a custom-field value is cross-module and needs the [Index Module](/rc/resources/best-practices/module-links#filtering-by-a-linked-field--the-index-module), not `query.graph`.)<Warning>- **Prefer the `custom_fields` link over stuffing values into `metadata`.** `metadata` is an untyped JSON bag with no schema, no queryable columns, and no clean extension point — it turns into a dumping ground. The Custom Fields module gives you a real linked table (`custom_fields.*`) with typed columns you can query and filter, while still being config-only. Reach for `metadata` only for genuinely throwaway, never-queried scratch data.+ **Prefer the `custom_fields` link over stuffing values into `metadata`.** `metadata` is an untyped JSON bag with no schema, no queryable columns, and no clean extension point — it turns into a dumping ground. The Custom Fields module gives you a real linked table (`custom_fields.*`) with typed columns you can read and (via the Index Module) filter on, while still being config-only. Reach for `metadata` only for genuinely throwaway, never-queried scratch data.</Warning><Tip>diff --git a/apps/docs/rc/resources/best-practices/module-links.mdx b/apps/docs/rc/resources/best-practices/module-links.mdxindex b3e8d113d..1c78d641f 100644--- a/apps/docs/rc/resources/best-practices/module-links.mdx+++ b/apps/docs/rc/resources/best-practices/module-links.mdx@@ -112,55 +112,46 @@ createRemoteLinkStep(productBrandLinks)Because `createRemoteLinkStep` already knows how to compensate, links created this way are torn down automatically if a later step in the workflow throws. This is the whole reason to link inside a workflow rather than in a route.</Tip>-## Filtering by links+## Reading vs filtering across a link-A link isn't just for reading nested data — you can **filter and scope queries by it**. A common case: list only the products that belong to a given brand.+This is the distinction that trips people up:-Because the `product ↔ brand` link exists, you can filter products by a field on the linked brand in a single `query.graph` call — no join to write, no second query:+- **Reading** linked data — fetching `brand.*` alongside a product — works with `query.graph`. Query aggregates the two modules' data to build the result.+- **Filtering** by a linked module's field — "give me products *where* `brand.id = X`" — does **not** work with `query.graph`.-```ts title="Filter products by their linked brand"-const { data: products } = await query.graph({+<Warning>+ `query.graph` **cannot filter by a linked (cross-module) field.** Because modules are isolated and Query aggregates their data after the fact, there's no join to filter on. Passing `filters: { brand: { id } }` to `query.graph` will not scope products by brand.+</Warning>++You can still filter by a field that lives on the entity's **own** module (a plain column like `product.status` or `offer.seller_id`) — that's a normal `query.graph` filter. It's only *linked-module* fields that need a different tool.++### Filtering by a linked field — the Index Module++Cross-module filtering is what the [Index Module](https://docs.medusajs.com/learn/fundamentals/module-links/index-module) (`@medusajs/index`) exists for. It ingests data models into a single relational store on startup, so you can filter one entity by another's fields. Install it, make sure both models are ingested, and query with `query.index` instead of `query.graph`:++```ts title="Filter products by their linked brand — query.index, not query.graph"+const { data: products, metadata } = await query.index({entity: "product",fields: ["id", "title", "brand.name"],filters: {brand: {- id: brandId, // only products linked to this brand+ id: brandId, // ✅ cross-module filter — resolved by the Index Module},},})```-The idiomatic way to apply such a filter on a route is a small **middleware** that injects it onto `req.filterableFields`, so the handler stays ignorant of the scoping rule and every route on the resource is filtered by construction:--```ts title="src/api/admin/products/middlewares.ts"-const filterByBrand = (- req: MedusaRequest,- _res: MedusaResponse,- next: MedusaNextFunction-) => {- if (req.query.brand_id) {- req.filterableFields.brand = { id: req.query.brand_id }- }- next()-}-```--```ts title="Handler just forwards the filters"-const { data: products, metadata } = await query.graph({- entity: "product",- fields: req.queryConfig.fields,- filters: req.filterableFields, // brand filter already injected- pagination: req.queryConfig.pagination,-})-```+<Note>+ By default Medusa ingests only `Product`, `ProductVariant`, `Price`, `PriceSet`, and `SalesChannel`. To filter products by a **custom** module like Brand, you must [ingest that model](https://docs.medusajs.com/learn/fundamentals/module-links/index-module#how-to-ingest-custom-data-models) into the Index Module first. The Index Module is still marked experimental, though it powers filtering in the Medusa Admin.+</Note>-The [middlewares-as-filters](/rc/resources/best-practices/api-routes#middlewares-as-filters) section covers this pattern in full.+`query.index` takes the same shape as `query.graph` (entity, fields, filters, pagination), so a route handler can forward `req.filterableFields` to it exactly the same way — the only change is `graph` → `index`.## Checklist for a link- Declared in its own file under `src/links/`, using `defineLink`.- Argument order reflects the natural reading direction; `isList` set on the many side(s).- Migration generated and run (`medusa db:migrate`).-- Cross-module reads go through `query.graph`, never a service-to-service call.+- Cross-module **reads** go through `query.graph`, never a service-to-service call.+- Cross-module **filters** go through `query.index` (Index Module, with the model ingested) — `query.graph` can't filter by a linked field.- Links are created/removed only inside workflows via `createRemoteLinkStep` / `dismissRemoteLinkStep`.-- Filtering/scoping by a linked field is applied as a `filterableFields` middleware, not inlined in each handler.