What is the ElasticPress Sync?

The ElasticPress Sync is the process of synchronizing the content stored in your website with the Elasticsearch server. In general terms, a Sync gets all your Posts and public Custom Post Type entries along with tags and public metadata and sends them to Elasticsearch.

Since ElasticPress 5.0, the Sync page, below ElasticPress in the WP Dashboard, has a single Sync button. Users can check the Delete all data and start fresh sync option to delete everything before sending the data and explore the Advanced Options section to choose what needs to be synced.

Regular Sync

Simply clicking on the Sync button without checking the Delete all data and start fresh sync option will start a regular sync. The content of your website will be sent to Elasticsearch without deleting anything and while the sync is running your searches will still be handled by ElasticPress.

This option is not available for your first sync, as you’ll need to perform a full initial sync to use the plugin (see below).

Delete all data and start fresh sync (or Full Sync)

If you check the Delete all data and start fresh sync option, the process will be slightly different. This option makes ElasticPress delete all the content stored in Elasticsearch before sending anything.

While running a sync with this option checked, ElasticPress will not be used for searches or queries, falling back to regular MySQL search functionality.

When Do I Need To Delete All Data and Start a Fresh Sync?

Reasons may vary but mostly it is related to a change in the Elasticsearch mapping. Similar to a table in MySQL, the mapping is the way we tell Elasticsearch how content should be stored: posts should have a title, content, author, meta fields, taxonomy terms, etc.

Since EP 4.0, data related to post thumbnails are now stored and that required a full sync for ElasticPress 3.6.6 (and prior) users, for example. Some specific features, like Autosuggest, need different fields added to the mapping to work, so activating those features will require a full sync.

How to Full Sync and not fall back to MySQL?

Currently, this is not possible to do via Dashboard — following WordPress’s “decisions, not options” philosophy, we avoid overwhelming users with decisions. If you find yourself needing to run a full sync without falling back to MySQL and you don’t have access to WP-CLI, you may want to start a full sync, stop it after you see “Mapping Sent” in the log section, and then start the regular sync. Please note this may cause incomplete search results during the sync process.

ElasticPress Sync and WP-CLI

WP-CLI stands for WordPress Command Line Interface and is a way to interact with your WP website via terminal. It is also possible to trigger an ElasticPress Sync using the wp elasticpress sync WP-CLI command. This command offers a lot of different options and flags to modify its behavior to fit your needs. The full list is available on this plugin documentation page.

Full Sync in WP-CLI

If you want to trigger a full sync, you simply have to add the --setup flag to the wp elasticpress sync call. If you don’t want to answer the confirmation prompt, you can also send the --yes flag, as in wp elasticpress sync --setup --yes.

How to Full Sync and not fall back to MySQL using WP-CLI?

If you don’t want to fall back to MySQL while a full sync is performed, you can split the process into two parts: call the put-mapping command to delete your content and send the new mapping, as in wp elasticpress put-mapping, and then call the index command without the --setup flag:

wp elasticpress put-mapping
wp elasticpress sync

Going more technical

If you want a code-level understanding of the process, check our Sync Process article.