MetaMatrix Documentation

Overview

MetaMatrix adds a WooCommerce → MetaMatrix settings page to your WordPress admin. It maintains a flat, indexed copy of your WooCommerce product meta in a dedicated table and intercepts get_post_meta() calls transparently — themes and plugins continue to work without any code changes.

The result: sorting or filtering thousands of products by price, stock, SKU, or any custom field runs against a fast flat table instead of JOINing millions of rows in wp_postmeta.

Requirements

• WordPress 6.0 or later
• WooCommerce 7.0 or later
• PHP 7.4 or later
• Action Scheduler (bundled with WooCommerce) for background sync
• An active MetaMatrix license (Starter, Pro, or Agency)

Installation

1. Download metamatrix-1.0.1.zip from your account dashboard.
2. In WordPress admin, go to Plugins → Add New → Upload Plugin.
3. Upload the zip and click Install Now, then Activate.
4. MetaMatrix creates its index tables on activation and appears under the WooCommerce menu.

License activation

Go to WooCommerce → MetaMatrix → License. Paste your license key (format: MMBS-XXXX-XXXX-XXXX-XXXX for Starter, MMST-… for Pro, MMAG-… for Agency) and click Activate.

To move a license to a different site, click Deactivate License on the old site first.

Settings page

Go to WooCommerce → MetaMatrix. The settings page has two sections:

• Custom Indexed Columns — add your own meta keys as typed SQL columns (Pro / Agency)
• Admin Columns — Default Keys — checkboxes for 11 built-in WooCommerce keys to show as sortable columns

Two save actions are available: Save Changes (saves settings only) and Save & Run Initial Indexing (saves + queues all products for background sync).

Initial indexing

When you first install MetaMatrix, existing products are not yet in the flat table. Click Save & Run Initial Indexing to queue a background sync for all products and variations.

After the initial index, products sync automatically whenever they are saved. You can run initial indexing again at any time safely — it re-syncs all products with their latest meta values.

Admin columns

Check any of the 11 default keys in the Admin Columns — Default Keys section and save. The selected keys appear as columns in the WooCommerce Products list:

All columns are sortable — clicking the header runs a query against the flat index table with no postmeta JOIN.

Filter bar

A filter bar appears above the Products list whenever at least one MetaMatrix column is active. Use it to filter products by any active column:

1. Select a column from the dropdown.
2. Choose an operator: =, contains, >=, or <=.
3. Enter a value and click Filter.

Click the × button to clear the filter. Numeric operators (>=, <=) cast the value appropriately — useful for finding all products with stock below a threshold.

Custom typed columns (Pro / Agency)

Custom typed columns let you index your own product meta keys into a wide SQL table with a specific column type. This enables native sorting and filtering — no CAST workarounds needed.

Adding a custom column

1. Click + Add Meta Key in the Custom Indexed Columns table.
2. Enter the WP meta key (e.g. _supplier_cost). The sanitized column name is shown automatically.
3. Choose a type from the dropdown.
4. Toggle Column on to show it as a sortable admin column.
5. Click Save Changes. The ALTER TABLE runs in the background via Action Scheduler.

Supported column types

Default tracked keys

MetaMatrix automatically syncs 46 WooCommerce meta keys to the EAV flat table — these are always indexed regardless of which admin columns you enable:

You can add additional keys via the MetaMatrix_tracked_keys filter:

Object caching

MetaMatrix caches all flat table reads in the WordPress object cache group 'MetaMatrix' with a 1-hour TTL. If you have a persistent cache (Redis, Memcached) installed, repeat reads are served entirely from cache with zero database queries.

Cache is invalidated automatically when a product is saved or synced. You can also call MetaMatrix_API::invalidate( $product_id ) to manually evict a product.

To pre-warm the cache for a product (or a list of products) before a high-traffic page load:

WP-CLI commands (Pro / Agency)

MetaMatrix registers commands under wp MetaMatrix:

ProductForge integration

If both MetaMatrix and ProductForge are active, products created by ProductForge are indexed into MetaMatrix immediately — bypassing the background sync queue. No configuration needed.

If MetaMatrix is not installed, ProductForge shows a notice in the admin banner suggesting you install it for faster product queries.

Plan comparison

Troubleshooting

Products list columns not appearing

Make sure you checked at least one key in the Default Keys section and clicked Save Changes. Also check that MetaMatrix is active — if WooCommerce was deactivated and reactivated, MetaMatrix may need a page refresh to reinitialize.

Sorting doesn't seem faster

Run Save & Run Initial Indexing to ensure all products are in the flat table. You can verify via wp MetaMatrix status — the "Products indexed" count should match your total product count.

Custom column shows "Pending ALTER"

The ALTER TABLE job hasn't run yet. Action Scheduler runs on the next page load (or WP-Cron tick). Visit any admin page and refresh — the status should update to "Column exists" within a few seconds.

Background sync not running

MetaMatrix uses Action Scheduler (bundled with WooCommerce). Go to WooCommerce → Status → Scheduled Actions and check for pending MetaMatrix_sync_product actions. If WP-Cron is disabled on your host, you may need to set up a real cron job.

FAQ