add stats error faq

packages/dolt/content/other/faq.md

@@ -87,8 +87,6 @@ us know with an issue](https://github.com/dolthub/dolt/issues) or in
 [our Discord](https://discord.gg/s8uVgc3) and we'll [fix it in 24 hours](https://www.dolthub.com/blog/2024-05-15-24-hour-bug-fixes/). 
 Our goal is to be a 100% drop-in replacement for MySQL.
 
-## Why is my Dolt database so big on disk?
-
 Dolt generates a lot of garbage during some writes, especially during initial import. It's not
 unusual to get a local storage size of 20x the actual data size after an import. Running `dolt gc`
 will remove the garbage and reclaim local storage. See the [docs on `dolt
@@ -113,3 +111,30 @@ personally identifiable information is collected. You can disable this behavior
 ```bash
 dolt config --global --add metrics.disabled true
 ```
+
+## How to silence `stats failure` logs?
+
+Statistic warnings appear infrequently between dolt version upgrades
+and do not impact the correctness of database operations.
+If the error is reproducible please [report the
+issue](https://github.com/dolthub/dolt/issues/new).
+
+Statistics caches can be removed from the filesystem to silence warnings
+with `dolt_stats_purge()`:
+
+```sql
+call dolt_stats_purge();
+```
+
+Version incompatibilities should not hinder the purge command, but if
+manual intervention is desirable a specific database's
+stats cache can be removed from the filestystem:
+
+```bash
+rm -rf .dolt/stats
+```
+
+Statistics can be recollected at any time to improve join and indexing
+execution performance. See
+[the stats docs](../reference/sql/sql-support/miscellaneous#stats-controller-functions)
+for more details.

packages/dolt/content/reference/sql/sql-support/miscellaneous.md

@@ -72,7 +72,7 @@ Additional notes:
 
 Dolt currently supports table statistics for index and join costing.
 
-Statistics are collected by running `ANALYZE TABLE <table, ...>`.
+Statistics are auto-collected by default for servers, but cab be manually collected by running `ANALYZE TABLE <table, ...>`.
 
 Here is an example of how to initialize and observe statistics:
 
@@ -163,6 +163,14 @@ Dolt exposes a set of helper functions for managing statistics collection and us
 
 - `dolt_stats_status()`: Returns the latest update to statistics for the current database.
 
+- `dolt_stats_prune()`: Garbage collects the statistics cache storage, retaining only
+    the most recent statistic updates.
+
+- `dolt_stats_purge()`: Deletes the old statistics cache from the
+    filesystem. This can be used to silence warnings from backwards
+    incompatible upgrades. Statistics will need
+    to be recollected, which can be time consuming.
+
 ### Performance
 
 Lowering check intervals and update thresholds increases the refresh read and write load. Refreshing statistics uses shortcuts to avoid reading from disk when possible, but in most cases at least needs to read the target fanout level of the tree from disk to compare previous and current chunk sets. Exceeding the refresh threshold reads all data from disk associated with the new chunk ranges, which will be the most expensive impact of auto-refresh. Dolt uses ordinal offsets to avoid reading unnecessary data, but the tree growing or shrinking by a level forces a full tablescan.

packages/dolt/content/reference/sql/version-control/dolt-sql-procedures.md

@@ -1624,6 +1624,19 @@ Returns the latest update to statistics for the current database.
 Deletes the stats ref on disk and wipes the database stats held in memory for the current database.
 Stops update thread if active.
 
+## `dolt_stats_prune()`
+
+Garbage collect the statistics cache storage, retaining only
+the most recent statistic updates. Background threads need to be
+restarted after this operation.
+
+## `dolt_stats_purge()`
+
+Delete the old statistics cache from the
+filesystem. This can be used to silence warnings from backwards
+incompatible upgrades. Statistics will need
+to be recollected, which can be time consuming.
+
 # Access Control
 Dolt stored procedures are access controlled using the GRANT permissions system. MySQL database permissions trickle down to tables and procedures, someone who has Execute permission on a database would have Execute permission on all procedures related to that database. Dolt deviates moderately from this behavior for sensitive operations. See [Administrative Procedures](#administrative-procedures) below.