HHH-11485 - Document that the @Filter annotation only applies to query

documentation/src/main/asciidoc/userguide/chapters/domain/basic_types.adoc

@@ -1638,7 +1638,27 @@ include::{extrasdir}/basic/mapping-filter-entity-query-example.sql[]
 ----
 ====
 
-Just like with entities, collections can be filtered as well, but only if the filter is explicitly enabled on the currently running Hibernate `Session`.
+[IMPORTANT]
+====
+Filters apply to entity queries, but not to direct fetching.
+Therefore, in the following example, the filter is not taken into consideration when fetching an entity from the Persistence Context.
+
+[[mapping-filter-entity-example]]
+.Fetching entities mapped with `@Filter`
+[source, JAVA, indent=0]
+----
+include::{sourcedir}/basic/FilterTest.java[tags=mapping-filter-entity-example]
+----
+
+[source, SQL, indent=0]
+----
+include::{extrasdir}/basic/mapping-filter-entity-example.sql[]
+----
+
+As you can see from the example above, contrary to an entity query, the filter does not prevent the entity from being loaded.
+====
+
+Just like with entity queries, collections can be filtered as well, but only if the filter is explicitly enabled on the currently running Hibernate `Session`.
 This way, when fetching the `accounts` collections, Hibernate is going to apply the `@Filter` clause filtering criteria to the associated collection entries.
 
 [[mapping-filter-collection-query-example]]

documentation/src/main/asciidoc/userguide/chapters/domain/extras/basic/mapping-filter-entity-example.sql

@@ -0,0 +1,16 @@
+SELECT
+    a.id as id1_0_0_,
+    a.active as active2_0_0_,
+    a.amount as amount3_0_0_,
+    a.client_id as client_i6_0_0_,
+    a.rate as rate4_0_0_,
+    a.account_type as account_5_0_0_,
+    c.id as id1_1_1_,
+    c.name as name2_1_1_ 
+FROM
+    Account a 
+LEFT OUTER JOIN
+    Client c 
+        ON a.client_id=c.id
+WHERE
+    a.id = 2

documentation/src/test/java/org/hibernate/userguide/mapping/basic/FilterTest.java

@@ -30,6 +30,7 @@
 
 import static org.hibernate.testing.transaction.TransactionUtil.doInJPA;
 import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertFalse;
 import static org.junit.Assert.assertNotNull;
 import static org.junit.Assert.assertNull;
 
@@ -129,7 +130,21 @@ public void testLifecycle() {
 			}
 		} );
 
-		//tag::mapping-filter-entity-query-example[]
+		//tag::mapping-filter-entity-example[]
+		doInJPA( this::entityManagerFactory, entityManager -> {
+			log.infof( "Activate filter [%s]", "activeAccount");
+
+			entityManager
+				.unwrap( Session.class )
+				.enableFilter( "activeAccount" )
+				.setParameter( "active", true);
+
+			Account account = entityManager.find( Account.class, 2L );
+			assertFalse( account.isActive() );
+		} );
+		//end::mapping-filter-entity-example[]
+
+		// tag::mapping-filter-entity-query-example[]
 		doInJPA( this::entityManagerFactory, entityManager -> {
 			List<Account> accounts = entityManager.createQuery(
 				"select a from Account a", Account.class)