Introduction
Formerly known as Single Meta, the Ultra Engine is a cutting-edge feature which drastically lighten the database load by compressing posts, terms, users and options pages metadata into a single row per object.
The benefits of this functionality are significant when dealing with complex Flexible Content/Repeater structures which might generate hundreds of metadata per post, bloating the database when saving/loading posts.
Ultra Engine Meta Structure
ACF Extended
Howdy, ACF Extended
Native ACF Meta Structure
ACF Extended
Howdy, ACF Extended
Preamble
Due to the complex nature of metadata, the Performance Mode might be difficult to assimilate at first sight. This is why it is strongly recommended to backup your website and test it on a development environment first, to understand the ins and outs before going live.
In the case you rely on WP_Query on the front-end to get posts based on ACF Fields, please take a look at the WP Queries section.
Note that the Ultra Engine has been proof tested for years on production websites with the most complex ACF structures (aka Flexible Content as Page Builder). Additionally, no bugs have been reported since more than a year. See changelog.
Enable Module
The Performance Mode is disabled by default. It can be enabled and disabled in the Settings UIPRO, or with the following code:
Using acf/init
add_action('acf/init', 'my_acfe_modules');
function my_acfe_modules(){
// enable performance mode with ultra engine (default)
acf_update_setting('acfe/modules/performance', true);
}
Using acfe/init
add_action('acfe/init', 'my_acfe_modules');
function my_acfe_modules(){
// enable performance mode with ultra engine (default)
acfe_update_setting('modules/performance', true);
}
The Ultra Engine can be configured using the acfe/modules/performance/config hook. Usage example:
/**
* acfe/modules/performance/config
*
* @param $config
*
* $default_config = array(
* 'engine' => 'ultra', // ultra (default) | hybrid
* 'mode' => 'production', // test | production (default) | rollback
* 'ui' => false, // display metabox (dev mode should be enabled)
* 'post_types' => array(), // allowed post types (all)
* 'taxonomies' => array(), // allowed taxonomies (all)
* 'users' => false, // allowed user roles (none)
* 'options' => false, // allowed option id (none)
* );
*/
add_filter('acfe/modules/performance/config', 'my_acfe_performance_config');
function my_acfe_performance_config($config){
// define config
$config['engine'] = 'ultra';
$config['ui'] = true;
$config['mode'] = 'test';
// return
return $config;
}
You can also simply pass the engine in the setting:
add_action('acfe/init', 'my_acfe_modules');
function my_acfe_modules(){
// enable performance mode with ultra engine
acfe_update_setting('modules/performance', 'ultra');
}
Or pass the $config array in the setting instead:
add_action('acfe/init', 'my_acfe_modules');
function my_acfe_modules(){
// enable performance mode with config
acfe_update_setting('modules/performance', array(
'engine' => 'ultra',
'ui' => true,
'mode' => 'test',
));
}
Engine Modes
Test-Drive Mode
The Test-Drive Mode allows you to try the feature without touching normal ACF meta. This mode is a safe bet if you want to take a look at the process and make sure everything runs fine.
Production Mode
The Production Mode is the default mode. It will compress all metadata into a single row and delete ACF normal meta in the process to fully deploy its speed capacity and remove database bloat.
Rollback Mode
The Rollback Mode allows you to rollback to the normal ACF mode, and remove any Ultra Engine related meta in the process.
Getting Started
It is highly recommended to enable the Developer Mode to have a better view of Post/Taxonomies/Users/Options Pages metadata. Additionally, using the Performance Metabox will help you to switch modes on-demand.
This section will assume you use the “Ultra Engine” in “Test-Drive Mode”, with the following configuration:
add_action('acfe/init', 'my_acfe_modules');
function my_acfe_modules(){
acfe_update_setting('modules/performance', array(
'engine' => 'ultra', // use ultra engine (default)
'ui' => true, // display metabox (dev mode should be enabled)
'mode' => 'test', // use test-drive mode
));
}
I just enabled the module. What now?
Nothing. All posts metadata remain the same. Any ACF related functions such as get_field(), have_rows(), update_field() keep working just like before.
Head over a Post Edit screen, you should see your metadata as usual:
_my_field = field_5ffd218f27704
my_field = Vestibulum ac diam sit amet
_my_date = field_5ffd27b80a8af
my_date = 20210831
The conversion process begins each time you save a post. Click on the “Update” button to save your post. You should now see a new acf metadata with identitcal data, compressed into an array:
acf = array(
[_my_field] => field_5ffd218f27704
[my_field] => Vestibulum ac diam sit amet
[_my_date] => field_5ffd27b80a8af
[my_date] => 20210831
)
From now on, ACF will load/save metadata into that acf meta array seamlessly. Any ACF related functions such as get_field(), have_rows(), update_field() keep working just like before.
I still see the normal metadata. Is this normal?
Yes. This is a safeguard logic of the “Test-Drive Mode”, which keeps a copy of your normal metadata. This allows you to test the feature safely. If anything unusual happen, you can always disable the Performance Mode. Everything will return back to the normal state, like if nothing happened.
That’s it? Am I good to go?
Not yet. Normal metadata will continue to weigh on the loading of your database. In order to deploy the full performance capacity of the Ultra Engine you have to enable the “Production Mode”, which will remove the normal meta during the saving process.
What about other posts which haven’t been converted yet?
Non-converted posts will keep working as usual. See the point “I just enabled the module. What now?”
This manual process feels tedious. What if I have thousands of posts?
Once you have assimilated all the notions mentioned above, you can head over the Scripts UIPRO to mass convert your posts using the Performance Mode Converter script.
How can I rollback to the normal ACF meta?
To rollback, and cleanup Ultra Engine related meta, simply switch to the “Rollback Mode” and update the post again. Everything will return to the normal state.
WP Queries
Since the Ultra Engine compress metadata into an array, it means they will be saved as serialized data in the database, like this:
acf = "a:1:{s:8:"my_field";s:27:"Vestibulum ac diam sit amet";}"In contrast of the normal meta which save the metadata individually, like this:
my_field = "Vestibulum ac diam sit amet"
This means that any WP_Query which rely on meta_query to display posts based on ACF fields will not work anymore. Additionally, this can nullify advanced search plugins which allow to search posts based on ACF Fields, such as SearchWP or ElasticPress, since the normal metadata don’t exist anymore.
To workaround this issue, a new field setting called “Save as individual meta” is displayed for all fields in the ACF Field Group UI (see documentation). Once enabled on a field, the Ultra Engine will let the field be saved normally, even in “Production Mode”, so it can be queried by WP_Query.
Note that once the “Save as individual meta” is enabled on a field, you have to save the post, at least once, to apply its effect.
If you are using the former “Single Meta” feature, the migration is easy. Simply change the deprecated acfe/modules/single_meta setting with the new one:
add_action('acf/init', 'my_acfe_modules');
function my_acfe_modules(){
// enable performance mode with ultra engine (default)
acf_update_setting('acfe/modules/performance', true);
}
In fact, the Performance Mode use the “Ultra Engine” by default in “Production Mode”, which is the equivalent of the Single Meta logic. If you want to check the new metabox allowing to switch modes on-demand, you can use this configuration. Please make sure to enable the Developer Mode to correctly display it:
add_action('acf/init', 'my_acfe_modules');
function my_acfe_modules(){
// enable performance mode
// with ultra engine (default) + metabox
acf_update_setting('acfe/modules/performance', array(
'ui' => true,
));
}
To change allowed Post Types, Options Pages etc… you can also pass these settings as an array:
add_action('acf/init', 'my_acfe_modules');
function my_acfe_modules(){
// enable performance mode
acf_update_setting('acfe/modules/performance', array(
'engine' => 'ultra', // use ultra engine (default)
'ui' => true, // display metabox (dev mode should be enabled)
'post_types' => array('my-post-type'), // only allow 'my-post-type'
'users' => array(), // allow all user roles
));
}
Or you can simply use the acfe/modules/performance/config hook instead. See Engine Configuration above:
/**
* acfe/modules/performance/config
*
* @param $config
*/
add_filter('acfe/modules/performance/config', 'my_acfe_performance_config');
function my_acfe_performance_config($config){
// config
$config['engine'] = 'ultra'; // use ultra engine (default)
$config['ui'] = true; // display metabox (dev mode should be enabled)
$config['post_types'] = array('my-post-type'); // only allow 'my-post-type'
$config['options'] = array('my-options'); // only allow 'my-options' ids
// return
return $config;
}