diff --git a/documentation/docs/install-pmm/install-pmm-client/connect-database/mysql/mysql.md b/documentation/docs/install-pmm/install-pmm-client/connect-database/mysql/mysql.md
index 1749796ecdf..5920bb87b79 100644
--- a/documentation/docs/install-pmm/install-pmm-client/connect-database/mysql/mysql.md
+++ b/documentation/docs/install-pmm/install-pmm-client/connect-database/mysql/mysql.md
@@ -119,6 +119,12 @@ While you can use both at the same time we recommend using only one--there is so
 
 The choice depends on the version and variant of your MySQL instance, and how much detail you want to see.
 
+#### QAN data sources
+
+QAN reads queries only from the slow query log written to a file
+(`log_output=FILE`) or from Performance Schema. It does not support the
+general query log or a slow query log written to a table (`log_output=TABLE`).
+
 #### Data source comparison
 
 Here are the benefits and drawbacks of Slow query log and Performance Schema metrics sources:
diff --git a/documentation/docs/troubleshoot/qan_issues.md b/documentation/docs/troubleshoot/qan_issues.md
index a15f27a1944..8a78a43cebd 100644
--- a/documentation/docs/troubleshoot/qan_issues.md
+++ b/documentation/docs/troubleshoot/qan_issues.md
@@ -106,3 +106,9 @@ docker run -e PMM_CLICKHOUSE_CONFIG=low-memory ... percona/pmm-server:3
     
 
 The `switch-config.sh` script is deprecated and will be removed in a future PMM release; use `PMM_CLICKHOUSE_CONFIG` instead.
+
+### Why do I see `?` instead of real query values?
+
+Your application is likely using server-side prepared statements (common with JDBC and ORM frameworks). 
+
+Performance Schema exposes prepared statement parameters as placeholders rather than real values. See [Prepared statements show placeholders instead of values](../use/qan/mysql.md#prepared-statements-show-placeholders-instead-of-values).
diff --git a/documentation/docs/use/qan/mysql.md b/documentation/docs/use/qan/mysql.md
index 50e28a2dd01..f7653c85694 100644
--- a/documentation/docs/use/qan/mysql.md
+++ b/documentation/docs/use/qan/mysql.md
@@ -42,3 +42,12 @@ PMM Agent includes a configurable **Performance Schema Refresh Rate** that can h
 
 If you're still missing some query examples, consider [using the slow query log (`slowlog`)](../../install-pmm/install-pmm-client/connect-database/mysql/mysql.md#configure-data-source) as the query source instead. 
 The `slowlog` retains actual query texts over time and can help capture examples even when Performance Schema history buffers are exhausted.
+
+
+## Prepared statements show placeholders instead of values
+
+If your application uses server-side prepared statements (common with JDBC and most ORM frameworks), query examples in QAN appear as `?` placeholders instead of literal values, and EXPLAIN is unavailable for those queries.
+
+This is how upstream MySQL exposes prepared statements to Performance Schema, not a PMM limitation.
+
+To see real values and working EXPLAIN, switch to the [file-based slow query log](../../install-pmm/install-pmm-client/connect-database/mysql/mysql.md#configure-data-source) as your query source. The slowlog records executed statements with their actual parameter values.
\ No newline at end of file