|
| 1 | +--- |
| 2 | +title: REFRESH STATS |
| 3 | +summary: Learn how to reload statistics into memory for specific tables or the whole TiDB cluster. |
| 4 | +aliases: ['/docs/dev/sql-statements/sql-statement-refresh-stats/'] |
| 5 | +--- |
| 6 | + |
| 7 | +# REFRESH STATS |
| 8 | + |
| 9 | +`REFRESH STATS` reloads persisted optimizer statistics from the TiDB system tables into memory. This statement is primarily intended for scenarios where statistics have been restored externally (for example, by BR) or when you need to reconcile in-memory statistics without rerunning `ANALYZE`. |
| 10 | + |
| 11 | +When you run `REFRESH STATS`, TiDB reuses the statistics initialization routines that are automatically triggered at startup. You can reload statistics for individual tables, every table in selected databases, or the entire cluster, and optionally choose whether to perform lightweight (`LITE`) or full (`FULL`) initialization. |
| 12 | + |
| 13 | +> **Warning:** |
| 14 | +> |
| 15 | +> This statement exists primarily for BR workflows that must reload statistics after a physical restore. Outside of BR, only run it when you explicitly debug in-memory statistics, and do not execute it on production clusters during ordinary operations. |
| 16 | +
|
| 17 | +## Synopsis |
| 18 | + |
| 19 | +```ebnf+diagram |
| 20 | +RefreshStatsStmt ::= |
| 21 | + 'REFRESH' 'STATS' RefreshTargetList RefreshMode? ClusterOption? |
| 22 | +
|
| 23 | +RefreshTargetList ::= |
| 24 | + RefreshTarget (',' RefreshTarget)* |
| 25 | +
|
| 26 | +RefreshTarget ::= |
| 27 | + TableName |
| 28 | + | SchemaWildcard |
| 29 | + | GlobalWildcard |
| 30 | +
|
| 31 | +TableName ::= |
| 32 | + Identifier ('.' Identifier)? |
| 33 | +
|
| 34 | +SchemaWildcard ::= |
| 35 | + Identifier '.' '*' |
| 36 | +
|
| 37 | +GlobalWildcard ::= |
| 38 | + '*' '.' '*' |
| 39 | +
|
| 40 | +RefreshMode ::= |
| 41 | + 'FULL' |
| 42 | + | 'LITE' |
| 43 | +
|
| 44 | +ClusterOption ::= |
| 45 | + 'CLUSTER' |
| 46 | +``` |
| 47 | + |
| 48 | +## Options |
| 49 | + |
| 50 | +- **Targets (`RefreshTargetList`)** |
| 51 | + - `table_name` refreshes a table in the current database. |
| 52 | + - `db_name.table_name` refreshes a fully qualified table. |
| 53 | + - `db_name.*` refreshes every table in the specified database. |
| 54 | + - `*.*` refreshes every table in the cluster. |
| 55 | +- **`FULL`** |
| 56 | + Forces TiDB to load full statistics (histograms, TopN, CMSketches) into memory, equivalent to setting [`lite-init-stats`](/tidb-configuration-file.md#lite-init-stats-new-in-v710) to `false` for this operation. Use this when you need complete statistics immediately after the refresh. |
| 57 | +- **`LITE`** |
| 58 | + Uses lightweight initialization, equivalent to `lite-init-stats = true`, which skips loading histograms and other heavy structures until they are needed. |
| 59 | +- **`CLUSTER`** |
| 60 | + Broadcasts the refresh request to every TiDB server. Without this keyword, only the TiDB node that receives the statement reloads its in-memory statistics. |
| 61 | +- **Default mode** |
| 62 | + If neither `FULL` nor `LITE` is specified, TiDB uses the current value of [`lite-init-stats`](/tidb-configuration-file.md#lite-init-stats-new-in-v710). |
| 63 | + |
| 64 | +## Examples |
| 65 | + |
| 66 | +- Refresh statistics for a single table on the connected TiDB node: |
| 67 | + |
| 68 | + {{< copyable "sql" >}} |
| 69 | + |
| 70 | + ```sql |
| 71 | + REFRESH STATS orders; |
| 72 | + ``` |
| 73 | + |
| 74 | +- Refresh all tables in `sales` with lightweight initialization: |
| 75 | + |
| 76 | + {{< copyable "sql" >}} |
| 77 | + |
| 78 | + ```sql |
| 79 | + REFRESH STATS sales.* LITE; |
| 80 | + ``` |
| 81 | + |
| 82 | +- Force every TiDB node to load full statistics for the entire cluster: |
| 83 | + |
| 84 | + {{< copyable "sql" >}} |
| 85 | + |
| 86 | + ```sql |
| 87 | + REFRESH STATS *.* FULL CLUSTER; |
| 88 | + ``` |
| 89 | + |
| 90 | +## Privileges |
| 91 | + |
| 92 | +To execute `REFRESH STATS`, you must either have the `RESTORE_ADMIN` privilege or hold `SELECT` on every targeted table. If you do not have sufficient privileges, TiDB returns an error and aborts the statement. |
| 93 | + |
| 94 | +## MySQL compatibility |
| 95 | + |
| 96 | +`REFRESH STATS` is a TiDB-specific extension and is not part of MySQL. |
| 97 | + |
| 98 | +## See also |
| 99 | + |
| 100 | +- [Statistics](/statistics.md) |
| 101 | +- [`ANALYZE TABLE`](/sql-statements/sql-statement-analyze-table.md) |
| 102 | +- [`LOCK STATS`](/sql-statements/sql-statement-lock-stats.md) |
0 commit comments