diff --git a/content/modules/flow-ui/pages/vc/components/genericFilter-components.adoc b/content/modules/flow-ui/pages/vc/components/genericFilter-components.adoc
index 74abd2e9..f6e6c5d2 100644
--- a/content/modules/flow-ui/pages/vc/components/genericFilter-components.adoc
+++ b/content/modules/flow-ui/pages/vc/components/genericFilter-components.adoc
@@ -82,6 +82,11 @@ include::example$onboarding/src/main/resources/com/company/onboarding/view/compo
 <2> Optional `join` clause.
 <3> Mandatory `where` clause. `?` indicates the parameter that is entered by the user.
 
+[NOTE]
+====
+When `parameterClass` is an entity type, `jpqlFilter` passes the *identifier* of the selected entity as the query parameter, not the entity instance. Compare against the id of the association in the `where` clause, for example `{E}.customer.id = ?`. Comparing the association reference directly (`{E}.customer = ?`) does not match any records.
+====
+
 //todo: add example with hasInExpression="true" upon completing jmix ticket #1442
 
 === Programmatic Configuration