Skip to content

The complete open source platform to run your entire marketplace. Storefront, vendor panel, admin console, and integrations in one enterprise-grade platform you own.

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.mdx
index 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 itself
next()
}
-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 middleware
Authentication 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.mdx
index 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.mdx
index 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.