GuideForms
Login GuideForms PRO

Facet Index

GuideForms doesn’t query WordPress directly when filtering. Instead, it maintains a dedicated facet index — a flat database table that stores every filterable value for every post in a format optimized for fast lookups. This is what makes real-time match counts and instant results possible, even on large sites.

What the index stores

The index is a single database table (wp_guide_facet_index) with one row per post–field–value combination. Each row contains:

  • Post ID — Which post this row belongs to.
  • Post Type — The post type (post, product, etc.).
  • Facet Source — Which indexer adapter created the row (taxonomy, meta, acf, woocommerce, aawp).
  • Facet Name — The field name (e.g. “category”, “_price”, “color”).
  • Facet Value — The text value (slug, string, or raw value).
  • Facet Value Num — A numeric representation used for comparisons and term ID lookups.
  • Facet Display — A human-readable label (e.g. the category name instead of its slug).

A single product with 3 categories, a price, and 2 ACF fields would have at least 6 rows in the index. This denormalized structure avoids the expensive JOINs that would be needed to query the same data through WordPress’s standard postmeta and term relationship tables.

Indexer adapters

Six built-in adapters handle different data sources. Each one knows how to read data from its source and write rows to the index:

  • Default — Post fields: title, date, author, type. Always active.
  • Taxonomy — All public taxonomies. Handles hierarchical terms by indexing ancestor terms separately, so filtering by a parent category also matches posts in child categories.
  • Meta — Custom post meta fields (excluding private, ACF, and WooCommerce keys). Auto-detects numeric values.
  • WooCommerce — Product price, sale price, stock status, SKU, ratings, and dimensions. Only active when WooCommerce is installed.
  • ACF — All ACF field types (text, number, select, checkbox, true/false, date, taxonomy). Only active when ACF is installed.
  • AAWP — Amazon product data (price, rating, reviews, Prime status, etc.). Only active when the AAWP integration is enabled.

Automatic updates

The index stays in sync with your content through WordPress hooks. When any of the following happen, the affected post is automatically re-indexed:

  • Post saved or updated — The post’s index rows are deleted and rebuilt.
  • Post status changes — Publishing, unpublishing, or trashing a post triggers a re-index.
  • Post deleted — All index rows for that post are removed.
  • Taxonomy terms assigned or removed — The post’s taxonomy rows are rebuilt.
  • Term edited — If a term’s name or slug changes, all posts with that term are re-indexed.
  • Post meta updated — Changes to meta fields trigger a re-index (internal WordPress keys are excluded).
  • ACF fields saved — ACF’s own save hook triggers re-indexing after ACF writes its data.
  • WooCommerce product updated — Product and stock changes trigger re-indexing.

Changes are batched — if multiple hooks fire for the same post in a single request, the post is only re-indexed once at the end.

Manual rebuild

Sometimes you need to rebuild the entire index from scratch — for example after a bulk import, after activating a new plugin that adds filterable data, or if results seem stale.

Go to GuideForms → Tools and click the Rebuild Index button. The rebuild runs in batches to avoid timeouts:

  1. The index table is cleared.
  2. GuideForms scans all published guides to find which filter sources are in use.
  3. Each source/field combination is indexed one at a time, with a progress indicator.
  4. When finished, the last-rebuild timestamp is updated and a summary shows the total rows and posts indexed.

On most sites the rebuild takes a few seconds. Large sites with tens of thousands of posts and many filter sources may take up to a minute.

Index status

The Tools page shows the current state of the index:

  • Total rows — How many rows are in the index table.
  • Total posts — How many unique posts are indexed.
  • Facets — A breakdown by source showing how many posts each facet covers.
  • Last rebuild — When the index was last fully rebuilt.

Troubleshooting

Results are missing or wrong

The most common cause is a stale index. Rebuild it from GuideForms → Tools. This resolves issues caused by bulk imports, direct database changes, or plugin updates that changed data without triggering WordPress hooks.

A new data source doesn’t appear

If you installed a new plugin (WooCommerce, ACF, AAWP) after GuideForms was already active, its indexer adapter may not have run yet. Rebuild the index to pick up the new data source.

Card counts show zero when they shouldn’t

Check that the filter source, operator, and value match your actual data. A common mistake is using a taxonomy term ID that doesn’t exist or a meta key with a typo. Also verify that the target post type in the guide’s Settings tab matches the post type that has the data.

Next steps