Rebuilding Super Speedy Search tables from the command line: wp sss rebuild

The wp sss rebuild WP-CLI command runs a rebuild outside an admin HTTP request. It avoids web request timeouts, but PHP, MariaDB, and disk still need enough resources. This article covers the commands and their scopes.

Before you start

On a large catalogue, run the command inside screen or tmux so a dropped SSH connection does not interrupt it. Record free RAM and disk space, take a reliable database backup, and choose a quiet traffic window. On Multisite, pass --url to select the site whose index you intend to rebuild.

For an example with measured resource use, see Rebuilding a large search index with limited memory.

Command reference

Run commands from the WordPress root. Replace the example URL with your site’s main URL.

--normal keeps a present suggestions table; if the table is missing, it is built. --full rebuilds suggestions even when they exist. With neither flag, the command follows the Force Suggestions Rebuild setting. The all scope records the current database version after success, including with --normal. The narrower search scope leaves the global version alone because it is only a partial rebuild. The positional force argument does not change recovery behavior.

How the table swap works

The rebuild manager checks for an active generation, removes recognized abandoned rebuild tables, and builds staged tables beside the live index. It runs SQL statements in sequence and reports per-statement timings. At promotion, it uses an atomic table rename with a short-lived backup table, then drops that backup. It also updates the search-column settings. A successful all migration writes the current SSS database version and flushes the object cache.

The old live index stays available until the swap. A failure before the swap usually leaves it intact. A failure after the swap needs inspection of the current table and settings. There is no one-step CLI rollback after the backup table has been dropped.

Scheduling

Measure a manual run before scheduling one. Choose a frequency that matches your catalogue changes and fits your maintenance window. For example, a weekly normal rebuild:

0 3 * * 0 cd /path/to/wp && wp --url=https://example.com sss rebuild all --normal >> /var/log/sss-rebuild.log 2>&1

Avoid overlapping jobs. Run the taxonomy-suggestions scope separately only if your site uses it and you have measured its cost.

If a rebuild fails

Read the last completed step, the SQL error, and the process exit status. Check whether the live index exists, whether the required columns and FULLTEXT index are present, and what sss_db_version says. If a build is still active, let it finish or use wp sss rebuild cancel for that active generation. Wait for MariaDB rollback to finish before retrying.

A failed rebuild may have crossed the table swap. Do not assume the old index is still present, and do not manually drop staging or backup tables just because their names look old. Use your database backup or infrastructure snapshot for a known rollback point. Once the cause is fixed and resources are sufficient, rerun the intended command with an explicit --normal or --full flag.

For the measured 5.47-to-5.50 migration procedure and recovery checks, see Rebuilding a large search index with limited memory.

Related products

Super Speedy SearchSpeeds up front-end and wp-admin search