GuideForms
Login GuideForms PRO

How filtering works

Every guide in GuideForms is a filter pipeline. Each step collects a selection from the visitor, converts it into one or more filter rules, and sends those rules to the backend where they’re matched against an indexed copy of your content. This page explains the full flow from click to results.

The filtering pipeline

Here’s what happens each time a visitor makes a selection:

  1. Visitor selects — They click a card, drag a slider, or fill out a form. The frontend converts the selection into filter rules using the mapping you configured in the editor (e.g. card “Electronics” → taxonomy:category = 15).
  2. Filters are collected — The session keeps track of active filters from every step. When a selection changes, the full set of filters is flattened into a single array.
  3. API request — The frontend sends the filter array to the GuideForms REST API via a POST request to /guideforms/v1/guides/{id}/count.
  4. Index query — The backend runs each filter against the facet index — a denormalized database table that stores every filterable value for every post. Each filter returns a set of matching post IDs.
  5. Combination — The result sets are combined using the guide’s filter combination setting: AND (intersection — posts must match all filters) or OR (union — posts matching any filter are included).
  6. Response — The backend returns the match count. The frontend updates the UI — showing the live count, enabling or disabling the Continue button, and refreshing card-level counts.

When the visitor reaches the results page, a similar request is made to /guideforms/v1/guides/{id}/results, which returns the actual post data (titles, images, excerpts, links) instead of just a count.

How selections become filters

Cards

When you configure a card in the editor, you assign one or more filters to it — for example, taxonomy:category equals Electronics. When a visitor clicks that card, its filters are added to the active set. In single-select mode, clicking a different card replaces the previous card’s filters. In multi-select mode, the filters from all selected cards are merged together.

Sliders

Slider filters map to a numeric data source (like meta:_price). A single-value slider produces a comparison filter (e.g. _price ≤ 500), while a range slider produces a between filter (e.g. _price between 200 and 800). The filter updates every time the visitor releases the slider handle.

AND vs OR combination

The Filter Combination setting in the guide’s Settings tab controls how filters from different steps interact:

  • AND (default) — A post must match every active filter to appear in the results. This narrows the results with each step, which is the most common behavior. Example: if step 1 filters by “Laptops” and step 2 filters by “Under $1,000”, only laptops under $1,000 are shown.
  • OR — A post needs to match any active filter. This broadens the results, which is useful for discovery-style guides where each step adds more options rather than narrowing down. Example: if step 1 filters by “Laptops” and step 2 filters by “Tablets”, both laptops and tablets are shown.

Most guides should use AND. Switch to OR only if your steps represent additive criteria rather than narrowing criteria.

Live match counts

When a Cards step has filters configured, each card shows a small number indicating how many posts currently match if that card were selected. These counts are fetched in real time by combining the card’s own filters with all filters from previous steps.

Cards with a count of zero are automatically disabled — they appear faded and can’t be clicked. This prevents visitors from making dead-end selections that would return no results.

A global match count is also shown (if enabled in the Settings tab under Progress Display), updating after every selection so visitors always know how many results remain.

Dynamic slider boundaries

Slider steps can adapt their range based on earlier selections. When a visitor completes a Cards step, the Slider step fetches updated min/max boundaries from the index — scoped to only the posts that match the previous filters. For example, after selecting “Laptops” in step 1, a price slider might show $300–$3,000 instead of the full $10–$10,000 range across all products. This makes the slider more precise and useful.

Performance

Filtering is fast because it runs against the facet index rather than querying WordPress directly. The index is a flat, denormalized database table with targeted indexes on the columns used for lookups. Simple queries (one or two filters) use optimized SQL with COUNT(DISTINCT post_id). Complex queries with up to five AND filters use efficient self-joins. Results are cached for 30 seconds to avoid duplicate queries during rapid interactions.

Next steps