[Bug]: Unable to filter products using the query parameter "variants[q]"

[WingNgCode]

Package.json file

{
  "name": "medusa-starter-default",
  "version": "0.0.1",
  "description": "A starter for Medusa projects.",
  "author": "Medusa (https://medusajs.com)",
  "license": "MIT",
  "keywords": [
    "sqlite",
    "postgres",
    "typescript",
    "ecommerce",
    "headless",
    "medusa"
  ],
  "scripts": {
    "build": "medusa build",
    "seed": "medusa exec ./src/scripts/seed.ts",
    "start": "medusa start",
    "dev": "medusa develop",
    "test:integration:http": "TEST_TYPE=integration:http NODE_OPTIONS=--experimental-vm-modules jest --silent=false --runInBand --forceExit",
    "test:integration:modules": "TEST_TYPE=integration:modules NODE_OPTIONS=--experimental-vm-modules jest --silent --runInBand --forceExit",
    "test:unit": "TEST_TYPE=unit NODE_OPTIONS=--experimental-vm-modules jest --silent --runInBand --forceExit"
  },
  "dependencies": {
    "@medusajs/admin-sdk": "2.2.0",
    "@medusajs/cli": "2.2.0",
    "@medusajs/framework": "2.2.0",
    "@medusajs/medusa": "2.2.0",
    "@mikro-orm/core": "5.9.7",
    "@mikro-orm/knex": "5.9.7",
    "@mikro-orm/migrations": "5.9.7",
    "@mikro-orm/postgresql": "5.9.7",
    "awilix": "^8.0.1",
    "pg": "^8.13.0"
  },
  "devDependencies": {
    "@medusajs/test-utils": "2.2.0",
    "@mikro-orm/cli": "5.9.7",
    "@swc/core": "1.5.7",
    "@swc/jest": "^0.2.36",
    "@types/jest": "^29.5.13",
    "@types/node": "^20.0.0",
    "@types/react": "^18.3.2",
    "@types/react-dom": "^18.2.25",
    "jest": "^29.7.0",
    "prop-types": "^15.8.1",
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
    "ts-node": "^10.9.2",
    "typescript": "^5.6.2",
    "vite": "^5.2.11"
  },
  "engines": {
    "node": ">=20"
  }
}

Node.js version

v21.7.1

Database and its version

PostgreSQL 17.2

Operating system name and version

MacOS Sequoia 15.1.1

Browser name

Chrome

What happended?

In the Admin API References, it is specified that the query parameter variants[q] can be passed in the API endpoint Admin List Products as shown in the following image.

I reviewed the code, and indeed the validator accepts this query parameter.

However, I get an error when passing this specific parameter.

error:   Trying to query by not existing property ProductVariant.q

The reason I need this is because I want to filter products by their SKU or barcode, which are properties of product variants.

Steps to reproduce

1. Create a Medusa application using the command create-medusa-app.
2. Create a user.
3. Create a product with a variant that includes an SKU or barcode if there are no products.
4. Make a request to the Admin List Products Endpoint with the query parameter variants[q] or variants.q:

curl --request GET \
  --url 'http://localhost:9000/admin/products?variants%5Bq%5D=test' \
  --header 'Authorization: Bearer {access_token}'

or

curl --request GET \
  --url 'http://localhost:9000/admin/products?variants.q=test' \
  --header 'Authorization: Bearer {access_token}'

5. You receive the following response with status code 500:

{
    "code": "unknown_error",
    "type": "unknown_error",
    "message": "An unknown error occurred."
}

Note: If you want to filter by the variant ID with the query param variants[id] or variants.id, it works fine, as do other query parameters such as variants[manage_inventory] or variants[allow_backorder].

Expected behavior

You can filter products by passing the query parameter variants[q] to the endpoint Admin List Products and the response will only show products whose variants properties are searchable match the query parameter.

Actual behavior

You receive the following response with a 500 status code:

{
    "code": "unknown_error",
    "type": "unknown_error",
    "message": "An unknown error occurred."
}

And the following error is displayed in the console:

error:   Trying to query by not existing property ProductVariant.q
Error: Trying to query by not existing property ProductVariant.q
    at /Users/dev/Documents/Dev/medusa-2.0/my-medusa-store/node_modules/@mikro-orm/knex/query/CriteriaNode.js:28:27
    at Array.forEach (<anonymous>)
    at new CriteriaNode (/Users/dev/Documents/Dev/medusa-2.0/my-medusa-store/node_modules/@mikro-orm/knex/query/CriteriaNode.js:23:17)
    at new ScalarCriteriaNode (/Users/dev/Documents/Dev/medusa-2.0/my-medusa-store/node_modules/@mikro-orm/knex/query/ScalarCriteriaNode.js:9:1)
    at Function.createScalarNode (/Users/dev/Documents/Dev/medusa-2.0/my-medusa-store/node_modules/@mikro-orm/knex/query/CriteriaNodeFactory.js:25:22)
    at Function.createNode (/Users/dev/Documents/Dev/medusa-2.0/my-medusa-store/node_modules/@mikro-orm/knex/query/CriteriaNodeFactory.js:22:21)
    at Function.createObjectItemNode (/Users/dev/Documents/Dev/medusa-2.0/my-medusa-store/node_modules/@mikro-orm/knex/query/CriteriaNodeFactory.js:51:25)
    at /Users/dev/Documents/Dev/medusa-2.0/my-medusa-store/node_modules/@mikro-orm/knex/query/CriteriaNodeFactory.js:42:28
    at Array.reduce (<anonymous>)
    at Function.createObjectNode (/Users/dev/Documents/Dev/medusa-2.0/my-medusa-store/node_modules/@mikro-orm/knex/query/CriteriaNodeFactory.js:41:45)
http:    GET /admin/products?variants%5Bq%5D=test ← - (500) - 20.246 ms

Link to reproduction repo

Fresh install with create-medusa-app command

[carlos-r-l-rodrigues]

Hi @WingNgCode,
the q is a query parameter, not a property from the entity, so you can use it like this:
/admin/products?q=test
/admin/products/[id]/variants?q=test

or if using the service directly, from methods like productModule.listProducts, the q is accepted on the where clause.

[WingNgCode]

Hi @WingNgCode, the q is a query parameter, not a property from the entity, so you can use it like this: /admin/products?q=test /admin/products/[id]/variants?q=test

or if using the service directly, from methods like productModule.listProducts, the q is accepted on the where clause.

Thank you for your response @carlos-r-l-rodrigues. I suppose that if I want to filter products by SKU or barcode, I will need to consider another approach or create a custom endpoint, as the query parameter described in your API references cannot be used.

[carlos-r-l-rodrigues]

That's correct. In case you need to filter by a specific field, you will have to call the method from the module, with your custom where clause.