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

May 12, 2026

The wp sss rebuild WP-CLI command runs the same rebuild logic as the admin Rebuild button, but without the 30-second PHP request timeout, memory limits and wp-cron reliability problems that often kill long-running rebuilds on shared hosting. This article covers every subcommand, when to prefer CLI over the admin button, and how to schedule rebuilds via cron. (If you can use CLI, you should prefer CLI at all times, it’s faster and 100% reliable)

When to prefer the CLI

Use the CLI whenever any of these apply:

  • The admin Rebuild button times out, returns a 502, or stalls.
  • You have tens of thousands of posts/products — the index build alone can take several minutes.
  • You’ve enabled Taxonomy Suggestions with triple-depth combinations on a large catalogue.
  • You want scheduled nightly refreshes that don’t depend on wp-cron firing.
  • You want clean stdout output to grep, redirect, or pipe.

The admin UI is fine for small sites and ad-hoc rebuilds, but the CLI is the reliable path for everything else. The Advanced tab inside the SSS settings now lists every CLI command with this same guidance.

Command reference

All commands run from the WordPress root (where wp-config.php lives):

CommandWhat it rebuilds
wp sss rebuildEverything — search index, post-title suggestions, taxonomy combinations (same as wp sss rebuild all).
wp sss rebuild allExplicit form of the default. Useful in cron entries so the intent is documented.
wp sss rebuild searchOnly the main search index (wp_superspeedysearch). Skips suggestions and taxonomy combinations.
wp sss rebuild suggestionsOnly the post-title suggestion table. Skips the search index and taxonomy combinations.
wp sss rebuild taxonomy_suggestionsOnly the taxonomy-combinations table. Useful as a separate nightly cron because triples can be expensive.
wp sss rebuild cancelCancels any in-progress rebuild and rolls back its temporary tables. Safe to run any time.
wp sss rebuild <scope> forceSame as the matching scope, but waits for any in-progress rollback to finish before starting. Use when a previous rebuild was killed and cancel reports “still rolling back”.

What the command does

  1. Cancels any in-progress rebuild and waits (or aborts cleanly with a “still rolling back” message — use force to wait).
  2. Creates a staging table for the chosen scope.
  3. Runs each SQL statement in sequence, printing the time taken per statement.
  4. On success, renames the staging table over the live table atomically (so search keeps working uninterrupted up to the swap).
  5. Writes the sss_search_columns option so the runtime knows which columns are in the FULLTEXT index.
  6. Flushes the WordPress object cache.

The object-cache flush at the end is important: without it, sites with a persistent object cache (Redis, Memcached) could keep serving the pre-rebuild alloptions blob, and the runtime’s MATCH() query builder would lag the actual rebuilt FULLTEXT index. The symptom was a stream of Can't find FULLTEXT index matching the column list errors until the cache happened to expire. From 5.52 the CLI rebuild flushes the cache automatically as its final step.

Output

Each SQL statement is printed with its execution time and affected-rows count:

Super Speedy Search: Rebuilding all...
Query 0:  SET SESSION SQL_MODE='ALLOW_INVALID_DATES';
Super Speedy Search: Query 0 completed in 0.0021 seconds (affected rows: 0)
Query 1:  CREATE TABLE `wp_superspeedysearch_stage_...` (...);
Super Speedy Search: Query 1 completed in 0.0145 seconds (affected rows: 0)
...
Super Speedy Search: Flushed object cache.
Success: Rebuild all completed.

On error, the offending SQL and $wpdb->last_error are printed and the command exits non-zero, so cron jobs can detect failures.

Scheduling via cron

Recommended pattern: run a full rebuild nightly when traffic is low. Add this to the server crontab (NOT wp-cron — the OS-level crontab is more reliable for long-running jobs):

0 3 * * * cd /path/to/wp && wp sss rebuild >> /var/log/sss-rebuild.log 2>&1

For sites with expensive triple-depth taxonomy combinations on a large catalogue, you may want to split:

# Search index + post-title suggestions nightly
0 3 * * * cd /path/to/wp && wp sss rebuild suggestions >> /var/log/sss-rebuild.log 2>&1

# Taxonomy combinations weekly (Sunday 04:00)
0 4 * * 0 cd /path/to/wp && wp sss rebuild taxonomy_suggestions >> /var/log/sss-taxonomy.log 2>&1

Combine into a single nightly entry if both fit comfortably in your maintenance window.

Handling failures

If a rebuild dies partway (server killed it, out-of-memory, etc.) the next run will refuse to start with:

Super Speedy Search: Cancelled SQL query is still rolling back, please wait before retrying.

This is MySQL rolling back the staging table on its own — the live search table is unaffected. Wait a few minutes, then retry. If you need to force it (e.g. cron is about to fire again), use the force suffix:

wp sss rebuild force

This polls for the rollback to complete, then proceeds.

If the rebuild itself errored (printed an SQL error before “Flushed object cache”), the live search table was not swapped — old data is still serving. Investigate the SQL error, fix the cause (most often a column collation mismatch or a missing meta column referenced in your Weights settings), and re-run.

What needs a rebuild vs. what doesn’t

ChangeRebuild needed?
Toggling which fields are indexed (title, content, excerpt, meta values, taxonomy descriptions)Yes — index columns change
Adding a meta key to Meta SearchYes — meta column added to SSS table
Adding/removing/changing a Taxonomy Suggestions combination rowYes — combinations table regenerated
Enabling/disabling Post Title Suggestions or Taxonomy SuggestionsYes if turning on (so the relevant table is built) — turning off doesn’t need a rebuild, the table is just ignored
Tuning Weights factors / Post Type Promotion / directionNo — weights are applied at query time
Changing search results template / overrule template / mixed sections layoutNo — template and post-type resolution are runtime decisions
Per-term cache or redirectNo — stored in wp_sss_search_redirects, applied at query time
Cache Settings tuning (frequency thresholds, slow-search thresholds)No — applied at query time
Adding/removing synonymsNo — applied at query time
Adding/removing posts/productsNo — SSS picks up new and changed posts via WP’s post hooks automatically

When in doubt: weights, caching, and template settings are runtime. Anything that changes which columns or rows the SSS table holds needs a rebuild.

Tips

  • Always log to a file when running from cron. The >> /var/log/sss-rebuild.log 2>&1 pattern keeps the per-query timings around so you can spot when a query starts taking longer than usual.
  • Don’t run two rebuilds in parallel. The cancel/wait protocol handles a re-entry from cron, but launching two scopes simultaneously (e.g. search and taxonomy_suggestions at the same time) is not supported.
  • CLI bypasses wp-cron entirely. If wp-cron is unreliable on your host, schedule via OS cron — that’s the whole reason this command exists.
  • The Readiness Status panel on the Advanced tab shows whether the SSS index matches the current admin settings. If it’s amber/red after a rebuild, something in your settings (often a missing meta key or a CPT that disappeared) doesn’t match what got built — the panel tells you what’s mismatched.
×
▲
▼
1/1