FacetWP has an automatic indexer that performs a single re-index when an individual item (a post, page, and category or term name/slug) is edited or saved. This keeps the index up to date automatically without having to worry about it, and without putting the potentially heavy burden of a full re-index on your site.

It is also possible to programmatically trigger re-indexing, for individual posts or for all posts.

When to index programmatically?

Triggering the indexer programmatically can be used in the following scenarios:

In most of these scenarios it is recommended to temporarily or permanently disable the automatic indexer to prevent interference by multiple indexing processes running at the same time.

Available indexing functions

The FWP()->indexer->index() function can be used to trigger (re-)indexing in your own custom code:

Re-index all posts

To programmatically do a full re-index, use:

How to use custom PHP code?
PHP code can be added to your (child) theme's functions.php file. Alternatively, you can use the Custom Hooks add-on, or a code snippets plugin. More info
FWP()->indexer->index();

Re-index a single post

To programmatically re-index a single post, set the $post_id parameter:

How to use custom PHP code?
PHP code can be added to your (child) theme's functions.php file. Alternatively, you can use the Custom Hooks add-on, or a code snippets plugin. More info
$post_id = 12345; // Must be an integer!
FWP()->indexer->index( $post_id );

Re-index specific posts

To programmatically re-index multiple post IDs, use:

How to use custom PHP code?
PHP code can be added to your (child) theme's functions.php file. Alternatively, you can use the Custom Hooks add-on, or a code snippets plugin. More info
$post_ids = [ 8942, 8943, 8944 ]; // Post IDs to re-index. Use integers.
foreach ( $post_ids as $post_id ) {
    FWP()->indexer->index( $post_id );
}

Re-index specific facets for specific posts

To programmatically re-index only specific facets for specific post IDs, use:

How to use custom PHP code?
PHP code can be added to your (child) theme's functions.php file. Alternatively, you can use the Custom Hooks add-on, or a code snippets plugin. More info
$post_ids = [ 8942, 8943, 8944 ]; // Post IDs to re-index. Use integers.

$facet_names = [ 'price', 'stock_status', 'brand' ]; // Facets to re-index.
$facets = [];

foreach ( $facet_names as $name ) {
    $facet = FWP()->helper->get_facet_by_name( $name );
    if ( false !== $facet ) {
        $facets[] = $facet;
    }
}

foreach ( $post_ids as $post_id ) {
    FWP()->indexer->index_post( $post_id, $facets );
}

Re-index specific facets for all posts

To programmatically re-index only specific facets for all post IDs, use:

How to use custom PHP code?
PHP code can be added to your (child) theme's functions.php file. Alternatively, you can use the Custom Hooks add-on, or a code snippets plugin. More info
$post_ids = FWP()->indexer->get_post_ids_to_index(); // Get all indexable post IDs.

$facet_names = [ 'price', 'stock_status', 'brand' ]; // Facets to re-index.
$facets = [];

foreach ( $facet_names as $name ) {
    $facet = FWP()->helper->get_facet_by_name( $name );
    if ( false !== $facet ) {
        $facets[] = $facet;
    }
}

foreach ( $post_ids as $post_id ) {
    FWP()->indexer->index_post( $post_id, $facets );
}

Trigger re-indexing with WP-Cron

The above indexing functions can be used in WP-Cron events, to trigger one-time or periodic re-indexing.

Trigger one-time re-indexing with WP-Cron

If you want to trigger a WP-Cron event that runs only once at a specific moment, for example after finishing an import, you can use the wp_schedule_single_event() function.

The event can be scheduled to run immediately, using time() in the first parameter. Or you can specify a timestamp to let it run at a specific time later.

The following example shows how to schedule an immediate, one-time event that performs a full re-index of all posts.

The code needs to be placed in your (child) theme’s functions.php, except the wp_schedule_single_event() function, which needs to be placed in your custom code, in a hook or function where you want to initiate re-indexing, for example after finishing an import:

How to use custom PHP code?
PHP code can be added to your (child) theme's functions.php file. Alternatively, you can use the Custom Hooks add-on, or a code snippets plugin. More info
function fwp_single_index( ) {
  FWP()->indexer->index(); // Re-index all posts
}
add_action( 'fwp_single_index', 'fwp_single_index' );

// Place this in a hook or function where you want to initiate indexing, for example after finishing an import.
wp_schedule_single_event( time(), 'fwp_single_index' );

To do the same for a single post, you can pass its post ID in wp_schedule_single_event(). Note that it needs to be passed as an array, even though it is a single post ID. Also make sure the post ID is an integer, not a numerical string:

How to use custom PHP code?
PHP code can be added to your (child) theme's functions.php file. Alternatively, you can use the Custom Hooks add-on, or a code snippets plugin. More info
function fwp_single_index( $post_id ) {
  FWP()->indexer->index( $post_id ); // Re-index this post
}
add_action( 'fwp_single_index', 'fwp_single_index' );

// Place this in a hook or function where you want to initiate indexing, for example after finishing an import.
wp_schedule_single_event( time(), 'fwp_single_index', array( 456 ); // Re-indexes postID 465. Don't add more than one post ID to the array, that will NOT work. See the next example.

If you want to re-index multiple posts at once, keep in mind that passing them in an array does not work, because wp_schedule_single_event() passes all post IDs in the array to the callback function as separate arguments. The solution is to pass them as a nested array:

How to use custom PHP code?
PHP code can be added to your (child) theme's functions.php file. Alternatively, you can use the Custom Hooks add-on, or a code snippets plugin. More info
function fwp_single_index( $post_id ) {
  foreach ( $post_id as $id ) {
    FWP()->indexer->index( $id ); // Re-index this post
  }
}
add_action( 'fwp_single_index', 'fwp_single_index');

// Place this in a hook or function where you want to initiate indexing, for example after finishing an import.
wp_schedule_single_event( time(), 'fwp_single_index', array ( array ( 123,456,789 )  ) ); // Use a nested array for multiple posts. For a single post ID see the previous example.

Specify a time to run the one-time re-indexing event

All three examples above schedule the indexing event to run “now”, by setting the first parameter (the UNIX timestamp) of wp_schedule_single_event() to time(). If you need the event to run at a specific time later, you can use a relative format like time() + 3600 (one hour from now).

Or you can use PHP’s strtotime function with a relative date-time format. The following example schedules the event to index all posts at 01:00 hrs in the upcoming night:

How to use custom PHP code?
PHP code can be added to your (child) theme's functions.php file. Alternatively, you can use the Custom Hooks add-on, or a code snippets plugin. More info
function fwp_single_index( ) {
  FWP()->indexer->index(); // Re-index all posts
}
add_action( 'fwp_single_index', 'fwp_single_index' );

// Place this in a hook or function where you want to initiate indexing, for example after finishing an import.
$timestamp = strtotime('tomorrow 01:00:00'); // Calculate the UNIX timestamp for the upcoming night 01:00 hr.
wp_schedule_single_event( $timestamp, 'fwp_single_index' );

Testing the one-time re-indexing event

While testing the one-time event, be aware that WP-Cron is only triggered when there is some activity on the site on the front-end. If you don’t see the post(s) being re-indexed, make sure to load a few front-end pages of your site. Also keep in mind that after the front-end is triggered, it takes a minute for the schedule to actually run, and then for the indexer to start running and finishing (which can take a while depending on the number of posts and facets). You can follow the indexing progress by reloading the FacetWP admin page and clicking the rotating icon (or click “Show indexer stats” to see when it has last finished indexing).

While testing, you may want to disable FacetWP’s automatic indexing temporarily. Or, if your hook or function triggers the one-time event regularly, disable it permanently.

Note that if you are using wp_schedule_single_event() in code that runs on WP’s init hook, you need to make sure to use it with a priority of 21 or later (see the explanation above).

Trigger periodic re-indexing with WP-Cron

The FacetWP Schedule Indexer add-on

If you need to schedule a periodic re-index with WP-Cron, you can use the Schedule Indexer add-on. This plugin adds a WP-cron event that runs a full re-index on an hourly WP-Cron schedule. You can also choose one of the other built-in schedules (twicedaily, daily and weekly), or create your own custom schedule.

While testing the indexing schedule you have set with the Schedule Indexer add-on, be aware that WP-Cron is only triggered when there is some activity on the site on the front-end. If you don’t see the post(s) being re-indexed, make sure to load a few front-end pages of your site. If you don’t want the cron schedule to be dependent on this shortcoming of WP-Cron, you can also trigger re-indexing with a (“real”) server cron.

Trigger re-indexing with WP-CLI and server cron

If you prefer the command line, you can also use WP-CLI to manually trigger re-indexing.

Or, if you want to use a cron schedule to control indexing, you can use WP-CLI indexing commands in a server cron job. This can be useful too if you disabled WP-Cron for performance reasons, preventing you from using the Schedule Indexer add-on. Real server cron is also the best approach if you want your cron schedule to always run exactly at the scheduled time, independent of front-end site activity (which is the disadvantage of using WP-Cron).

With FacetWP’s built-in WP-CLI indexing command options you can also do partial re-indexes of only specific post types, post ID’s and facets, and you can purge the index table, as a whole or partially.

Re-indexing with WP-CLI (optimally triggered by a server cron job) is the recommended approach for indexing high-content sites, or sites with large amounts of content imported regularly. In these cases the automatic indexing process can become problematic. Using WP-CLI will give you full control over what is being indexed, when the indexing process runs exactly, and at which frequency. In this approach, FacetWP’s automatic indexing should be turned off with the facetwp_indexer_is_enabled hook.

Trigger re-indexing after importing posts or products

If you are using WP All Import or WebToffee Import Export for WooCommerce to import posts/products, FacetWP’s automatic indexing can cause several issues when it runs during the import. Our recommendation is to disable the indexer temporarily, and then automatically trigger it once the import has finished. See these pages for more info and how to do this:

Disable automatic indexing

FacetWP has an automatic indexer that performs a single re-index when an individual item (a post, page, and category or term name/slug) is edited or saved. This keeps the index up to date automatically without having to worry about it, and without putting the potentially heavy burden of a full re-index on your site.

Disable automatic indexing.
Disable automatic indexing.

Automatic indexing can be temporarily or permanently disabled with the “Enable automatic indexing” setting (introduced in version 4.3.4). This setting is enabled by default.

This can be useful if you prefer to re-index manually with the Re-index button, or if you want to run the indexer programmatically, as described in the above-mentioned scenarios.

Automatic indexing can also be disabled with the facetwp_indexer_is_enabled hook, by adding the following to your (child) theme’s functions.php. The code does exactly the same as disabling the setting.

How to use custom PHP code?
PHP code can be added to your (child) theme's functions.php file. Alternatively, you can use the Custom Hooks add-on, or a code snippets plugin. More info
add_filter( 'facetwp_indexer_is_enabled', '__return_false' );

Note that with this hook it is also possible to disable automatic indexing for certain types of content.

See also

Last updated: December 2, 2024