FacetWP Relevanssi - WordPress Plugin

A Practical Guide to FacetWP Relevanssi: Relevant Search and Filters in WordPress

FacetWP Relevanssi is useful when a site needs more than another search box. It is designed for cases where visitors need to quickly find the right post, product, document, or listing within results they are already filtering. The division of responsibilities is clear: Relevanssi builds and uses its own index, while FacetWP receives the search phrase and selected facets, then refreshes the listing. Search stops being a separate page with its own rules and becomes part of a catalog, knowledge base, or archive.

This is not a promotional overview. It is a practical path through preparing data, installing the three components, choosing the Search facet engine, checking the index, building a product-catalog setup, and distinguishing a relevance issue from a template or cache issue. It also covers result limits, short search terms, stopwords, result excerpts, and the case where a standard WordPress search page has no facets.

In this guide, relevance means an order of results that is most useful for the meaning of a visitor's query. It does not promise that the first listing will always be perfect. The order depends on which fields were actually included in the Relevanssi index, which post types participate in the listing, and which additional conditions FacetWP applies.

What Changes When Search and Facets Work Together

In a typical configuration, standard WordPress search matches words in a post title, content, and excerpt. That can be enough for a small blog, but a service catalog, store with product specifications, documentation base, or job site often keeps useful information outside the main post text. It may live in custom fields, taxonomy terms, SKUs, material types, locations, and other data that visitors expect to search for even when it is not visible in the main content.

Relevanssi replaces standard search with its own index and gives administrators more control over which parts of a post are searchable. FacetWP, in turn, does not attempt to calculate relevance itself. When the Relevanssi engine is selected, it receives the IDs of matching posts from Relevanssi, then applies the current listing context and values from other facets. This boundary matters: if the order of matching listings looks strange, investigate the search index and Relevanssi rules first. If a facet does not appear, does not refresh listings, or detects the wrong WordPress loop, diagnose FacetWP and the listing template.

One Selection Flow, Not a Separate Form

Imagine an equipment catalog. A visitor enters a word related to the product's purpose, then narrows the selection by material, price range, and availability. Without integration, search may lead to a regular results page where those filters do not work, or facets may filter products without accounting for what was typed. With FacetWP Relevanssi, the user stays on one listing page: the Search facet sends the phrase to Relevanssi, while other facets narrow the set of matching posts.

The benefit is not limited to an update without a page reload. It is about predictability: people understand that they are searching content while also narrowing the answer by the attributes shown on the page. For site editors, this means the attributes in product cards, taxonomies, and custom fields should be designed not only for attractive display but also for search. Search is only as useful as the indexed data is meaningful.

Where This Integration Makes the Most Sense

• WooCommerce product catalogs, where shoppers enter a name, SKU, or task, then filter by category, price, attribute, and availability.
• Knowledge bases, where articles are organized by products, versions, user roles, and topics, while an important detail may be found in the content or additional fields.
• Service, property, or specialist directories, where a free-text query comes first and structured conditions narrow the selection afterward.
• Editorial archives, where taxonomies, authors, content types, and a predictable result order matter.

The integration is less appropriate for a site with a few dozen static pages where visitors expect only a simple title search. Do not enable a complex index solely to make a search field look more polished. Another warning sign is a project with no time to maintain its data: if SKUs are not stored consistently, taxonomy terms are used inconsistently, and content is imported in bulk without rebuilding the index afterward, the filter interface will look more convincing than the actual search results.

Who This Integration Is For and Which Expectations to Set Aside Early

FacetWP Relevanssi is intended for sites that already need a filterable listing and require more meaningful results than standard WordPress search can provide. It requires FacetWP itself, an installed copy of Relevanssi, and the integration add-on. It is not a standalone universal search engine or a substitute for a well-designed content model. The add-on connects two existing systems, so implementation quality depends on how each one is configured.

A Strong Candidate for Implementation

A suitable project usually has one or more clearly defined listings: an archive of products, posts, real estate listings, recipes, or learning-center materials. For each listing, the target post types, searchable fields, and attributes people actually use when making a choice are already understood. An editor can test the selection using real queries, and a developer can inspect the listing template and rule out conflicting queries. This does not mean complex code is required, but someone must own the data and validate the output.

It is especially sensible to consider configuring FacetWP Relevanssi when much of the value of a listing sits in metadata or terms. For example, in a course library, visitors may search by topic but decide based on level, duration, and format. In a parts catalog, a name may be incomplete while the precise identifier is stored in the SKU field and specifications. In a document library, a visitor enters a product concept and narrows the list by version or audience. These use cases cannot be solved by a single attractive search field.

When to Stop or Choose a Different Approach

Do not promise that Relevanssi will solve an extremely large data-volume problem without server requirements. FacetWP's official documentation notes that a Relevanssi index can consume hundreds of megabytes in the database; as a rough initial estimate, it suggests multiplying the size of the wp_posts table by about three. This is not an exact calculation for every site. It is an early reason to check available storage, backups, and database load.

A project with very large result sets and demanding search-infrastructure requirements should be evaluated separately. MySQL is a general-purpose database, not a specialized external search cluster. Do not expect FacetWP Relevanssi to behave like systems built for dedicated search servers. In that situation, first benchmark a copy of the project, limit indexed content types, and test real queries instead of removing standard limits without validation.

Practical rule: confirm the value of search on one listing with a set of real queries first. Then expand the index, number of facets, and implementation scope. This makes it easier to see which change improved the results and which one only increased the load.

Preparation: Data Map, Listing Location, and Resource Headroom

Before installation, describe the future results rather than the plugins. List which cards should appear, which words visitors enter, which fields or taxonomies contain useful information, and which facets will refine the matches. This brief map prevents a common mistake: enabling every custom field, creating noisy results, and then trying to fix relevance with random settings.

Inventory Fields One by One

Split data into three groups. The first is text that should genuinely be found through a free-text phrase: title, description, summary, documentation, and manufacturer name. The second is short values for facets: category, brand, material, level, region, status, and price. The third is internal data that should not participate in search: theme flags, integration identifiers, one-time tokens, and serialized settings. There is no reason to add the last group to the index, even if doing so seems like the quickest route.

In Relevanssi, you can select all fields, visible fields, or a specific list of fields. For a normal project, it is safer to begin with visible fields or explicitly listed fields. The all-fields mode can capture theme and extension metadata, which can weaken result ranking. If information is stored in ACF or another custom-field tool, first verify the actual meta-field name, then confirm results through both the admin search and the published listing.

Questions to Ask About Every Field

1. Will a visitor understand that this is the value they are searching for?
2. Should a match in this field rank higher than a match in regular content?
3. Does the field contain internal or repeated data that will create noise?
4. Is this field updated during imports, and will the index be rebuilt afterward?
5. Should visitors search this value with free text, or would a separate facet be more appropriate?

Check the FacetWP Listing

FacetWP needs a listing template because that is how the plugin determines which results and choices it should display. Before connecting Relevanssi, create a working public listing with several real cards and at least one regular facet. After creating a facet, place it on the page using its shortcode - in a Shortcode block, widget, or PHP template, depending on how the site is built. If the result container or query is detected incorrectly, changing the search engine alone will not fix the page.

Remember that new or modified facets must be indexed in FacetWP using Re-index. This is separate from building the Relevanssi index. The first index allows FacetWP to work quickly with its facet data; the second handles relevant search. After changing data or structure, verify both indexes separately.

Resources, Backups, and Bulk Imports

Building a large index is a noticeable operation for both the database and server. On a live site, choose a quiet period, keep a fresh backup, and know in advance which content is actually needed. For large catalogs, FacetWP's official documentation recommends reducing the number of indexed post types, indexed posts, and facets that are unnecessary on a specific page. If data arrives in batches, import the content first, then rebuild Relevanssi and FacetWP indexes on a planned schedule instead of evaluating search halfway through an incomplete update.

Do not turn this into a rule to always disable automatic updates. The right approach depends on the site and publishing frequency. The point of preparation is different: the administrator should know when data exists in WordPress, when it is available to the Relevanssi index, and when facets have had time to detect it. As long as those three states are mixed together, every search test remains ambiguous.

Install the Three Components and Run a First Check Without Extra Settings

A safe installation consists of sequential checks, not enabling every available option at once. First make sure FacetWP already works on a test or draft listing. Then install and activate Relevanssi through the usual WordPress process, open its settings, and build an initial index for the selected post types. After that, install the Relevanssi add-on from your FacetWP account, if it is included with your license, and activate it in the admin area.

An Order That Makes Diagnosis Easier

1. Create a database backup and record the page URL where results will be tested.
2. Confirm that FacetWP displays a normal listing and at least one working facet.
3. Install Relevanssi from the Plugins screen, activate it, and select the minimum required set of post types and fields.
4. Build the Relevanssi index and wait for completion. Do not test results against a partially indexed catalog.
5. Install the FacetWP Relevanssi add-on, then confirm that the Relevanssi option appears in the Search facet settings.
6. Create or open a Search facet, place it next to the same listing, and run a first query that definitely appears in one published card.
7. After changing facets, click Re-index in FacetWP and repeat the check.

This order is useful because it isolates failures. If the required engine is absent from Search facet settings, the cause is the add-on or its activation, not the theme template. If Relevanssi cannot find a post in the admin search, there is no reason to inspect facets yet: the issue is in the Relevanssi index or rules. If the admin search is correct but the public listing is not, then it makes sense to inspect the template, cache, and FacetWP.

Your First Test Does Not Need to Look Polished

Create a small test set of five to ten published posts with different titles and fields. Add one word only to content, another only to an indexed field, and a third to a taxonomy term. For WooCommerce, use one unique SKU. The goal is not to simulate the whole catalog immediately, but to prove each search path. Once these control records are found as expected, you can move on to real pages and bulk data.

Search Facet Settings: Engine, Auto-Refresh, and Result Order

The most important setting is not in FacetWP's general section but in the specific Search facet. After activating the integration, the Search engine field includes a Relevanssi option. Select it on the search facet placed on the page. If Relevanssi is active on the site but the facet remains set to WP Default, that is not a neutral fallback configuration: FacetWP documentation warns that a Search facet without the Relevanssi engine selected will return empty results when Relevanssi is installed. To intentionally use WP Default on a page with a facet, Relevanssi must be disabled for that page.

Search Engine: The Connection Point

After selecting Relevanssi, the query field does not automatically infer the site's structure. It sends the entered words to the Relevanssi index, receives a set of matching IDs, and works with that set inside the current FacetWP listing. As a result, the same term can behave differently on two pages: on an article page it may be limited to posts, in a catalog it may be limited to products, and in another template it may be narrowed by an additional category or a predefined query condition.

This has an important practical implication. Do not use one global Search facet as a universal answer for the entire site until you understand the boundaries of each listing. A knowledge base benefits from a clear knowledge-search page with its own template and facets. A product catalog benefits from its own results page. This is easier to test, easier to explain to visitors, and safer for performance.

Placeholder Text and When Results Refresh

Placeholder text should describe what visitors can actually search for: for example, "Product name, use, or SKU" in a store, or "Topic, command, or setting" in a knowledge base. Do not promise searches by specifications if the related field is not in the index. The placeholder does not change search behavior, but it guides user queries and therefore affects the perceived quality of search.

The automatic refresh option updates results as users type. This can feel convenient in a small catalog, but a heavier listing may need a delay until several characters are entered or a more deliberate submission. Relevanssi does not index short words by default, and every extra character in an active live-search field can create a query. There is no universal character count without measurement: check desktop and mobile pages, response speed, clarity of the loading indicator, and behavior during rapid typing.

Order by Relevance and the Sort Facet

When a Search facet is used without a Sort facet, FacetWP normally orders results by relevance. That is expected behavior for a meaning-based query: exact and heavily weighted matches appear higher. However, a catalog may sometimes need to serve a different purpose. A visitor may search for a product group and then want to sort by price, availability, or date. In that case, add a separate, clearly labeled Sort facet so visitors understand that they changed the ordering principle.

Do not disable relevance sorting simply because the first two results look similar. First check where the words matched, which fields are included in the index, and whether irrelevant data exists in custom fields. Then assess real queries. The difference between "what best matches the phrase" and "what costs less" should be visible in the interface, not hidden in an arbitrary SQL order.

Result Limits: Do Not Confuse a Visible Page with the Search Cap

Relevanssi Search facet results are limited by default through the Throttle searches setting in Settings > Relevanssi > Searching. FacetWP's official documentation states that the standard limit is 500 matching posts when throttling is enabled. This is not the pagination page size or the number of cards users see at once. It is the upper limit on the set of IDs from which the faceted listing is built.

Increasing or removing the limit should not be the first response to a complaint that a product cannot be found. First confirm that the product exists in the index, that the query is not made entirely of stopwords, that the relevant post type participates in the listing, and that other facets are not excluding it. If the cap is genuinely the problem, test a lower or otherwise reasonable value on a project copy. Removing the limit can make a listing with many posts slower to respond.

Do not skip validation after changing the engine. Enter a known term, switch one regular facet, and confirm that the card count, counter, and pagination all change consistently. This is faster than diagnosing the cause after the whole page has been styled.

What Relevanssi Actually Searches and Why the Index Needs Design

FacetWP Relevanssi does not create a second set of indexing rules. It relies on Relevanssi. The central question is therefore not "which FacetWP button should I click?" but "which information can provide evidence of relevance?" If titles, content, excerpts, selected fields, and taxonomies are included in the index, a query can reach the same post through several paths. If useful data is absent, no facet styling can restore it.

Fields, Terms, and Controlled Coverage

In Settings > Relevanssi > Indexing, choose the necessary post types and define the data sources. Include taxonomies when visitors would logically search their names. For example, a search for "compatibility" may find articles marked with that topic, while a brand-name search may find a product assigned that term. But if a taxonomy exists only for internal administrative sorting, indexing it can weaken the results.

A gradual approach is useful for custom fields. Begin with two or three significant fields, such as _sku, manufacturer, or course_level, if those are actual field names in your project. Rebuild the index, run control queries, and only then add more fields. The "all fields" option looks convenient, but it can include hidden prefixed values, page-builder settings, and technical clutter. Relevanssi documentation considers visible fields a safer starting point, while a specific field list is the most controllable option.

Multiple-Word Matching and a Useful Tradeoff

In Relevanssi search settings, you can choose the default operator. OR search returns posts containing at least one word, while results that contain all words receive priority. AND search requires every part of the query to be present. For a live catalog, OR often gives a more user-friendly first response, especially when visitors enter an incomplete name, use imperfect wording, or combine a brand with a task. Strict AND can easily produce an empty page that visitors interpret as an absence of products.

That does not mean OR is always better. For a document library where two terms together form an exact requirement, AND may be justified. Relevanssi can fall back to OR when a strict query finds nothing. Make the right choice using logged or prepared real queries: test a short phrase, two independent words, an exact name, a field term, and an ambiguous query. One attractive example does not reveal the system's behavior.

Minimum Word Length, Punctuation, and Stopwords

By default, Relevanssi does not index words shorter than three characters. Queries such as a short code, abbreviation, or two-letter designation may therefore return no results even when the facet is configured correctly. The setting is in Relevanssi's advanced indexing options. After changing the minimum length, rebuild the index. Review this setting only where short queries carry real meaning: lowering the threshold without a reason expands the index and changes match quality.

Punctuation also matters for SKUs and codes. In WooCommerce, a SKU such as AB-120 may be processed differently in the index than a merged query such as AB120. Relevanssi documents a setting for hyphen handling in advanced indexing options, after which the index must be rebuilt. For a catalog, prepare a list of common ways customers enter codes: with a hyphen, with spaces, and without either. Then your decision is based on visitor behavior rather than assumptions.

If one specific word never finds anything, check Settings > Relevanssi > Stopwords. Stopwords are excluded from the index and cannot return results. Removing a word from that list also requires rebuilding the index. This is not a reason to remove every stopword: they reduce noise for a reason. First compare the word's importance in your subject area with the risk of overly broad results.

Match Weighting as an Editorial Policy

Relevanssi calculates match weights across different parts of a post. Its developer documentation describes the relevanssi_match filter for more precise weighting, but use it only after configuring ordinary fields and reviewing results. On many projects, it is more useful to clean up titles, content, fields, and terms than to immediately write conditional weighting code. Code-based weighting becomes justified when a stable business rule exists, such as clearly marked materials needing to rank higher when a match occurs in a specific field.

It is important not to turn search into promotional ranking. If a match in a product name or article topic is genuinely stronger, that can be explained to visitors. If a weakly related post is repeatedly forced to the top, search loses trust. Measure relevance by visitor tasks, not by the desire to promote a particular card.

Inside FacetWP Relevanssi: Query, IDs, Facets, and Output

This integration is easier to maintain when viewed as four sequential states. The input is an entered phrase and selected facet values. Relevanssi then matches the phrase against its index. Next, FacetWP uses the resulting set of IDs in the context of the listing, applies filters, and refreshes the result markup. Finally, the visitor sees cards, a counter, and pagination. Each state can be tested separately.

Input: Human Queries and Selected Context

Users do not need to know database field names. They enter a phrase the way they would describe their task. This is why placeholder text and indexed data must work together. Facets supplement a query when precise structured conditions are needed. A search for "warm jacket" should not require someone to remember a formal attribute name, but selecting a size or brand is better handled with a separate control than by trying to extract it from free text.

Processing: The Relevanssi Index

Relevanssi does not search the raw page at query time the way a visitor sees it in a browser. It uses a prebuilt database index. This has two consequences. First, a new post, new field, or changed indexing setting will not fully appear until the index is updated. Second, if data is stored in an unusual format that was not included in the index, changing a theme or shortcode alone will not make it searchable.

Relevanssi's admin search is a useful intermediate checkpoint. If it returns the required posts, the core search behavior is close to correct. If the public Search facet behaves differently afterward, look for differences in listing type, additional conditions, or query interception. If the admin search itself cannot find the required post, check indexing, minimum word length, stopwords, post type, and fields first.

Filtering: FacetWP Within the Listing

FacetWP does not turn the matching set into an independent catalog. It matches that set against the active template. This is why a useful combination is possible: a search for "module" may find articles and products, but a knowledge-base page retains only articles while a store page retains only products. Do not treat this as an error without checking the intended listing design. It becomes an error when the listing boundary does not match visitor expectations or when facets are placed next to a different WordPress loop.

Output: Verifiable Results, Not Just Animation

A public page should show more than a moving indicator. It should provide a verifiable answer. Visitors should understand which query is active, how many results were found, and how to remove a restriction. A clear reset control, result counter, and explicit sorting are useful. After testing, view the page without an open console: are controls keyboard-accessible, is it clear that loading has finished, does an old card remain beside new ones, and does query context disappear on the second pagination page?

If your listing must refresh an additional block after facets are applied, use documented FacetWP events rather than an arbitrary JavaScript delay. Such customization is needed only when there is a specific element that must stay synchronized with the results. For a basic integration, it is better to ensure the template, index, and facets are correct before building extra client-side code around them.

Practical Use Case: A Spare-Parts Catalog with Purpose and SKU Search

Consider a practical use case where the integration's strengths are visible without contrived examples. A WooCommerce store sells spare parts. A product has a title, description, categories, brands, attributes, a _sku field, and variations. A buyer may know the part name, part of a code, its purpose, or an equipment model. Category navigation alone is not enough, but a search field without filters quickly produces too broad a result set.

Goal and Scope of the First Version

The first version has a simple goal: on the parts archive, a user enters a phrase and then narrows the result by brand, category, and availability. The results contain only published product cards from the current catalog. Do not try to search every inventory field, hidden internal note, and variation at the same time in the first iteration. First find the main product by title, description, brand, and SKU, then separately determine whether variation SKU search is necessary.

Prepare Data and Build the Relevanssi Index

In Relevanssi, select products among the required post types. Confirm that titles, descriptions, brand terms, and category terms are included according to your model. For SKU search, add _sku to the explicitly listed custom fields and rebuild the index. Relevanssi documentation emphasizes that SKUs are not indexed automatically. If the field is not added and the index is not rebuilt, entering a SKU into an attractive search field proves nothing.

Variable products have a separate consideration. Relevanssi can index a variation's own SKU, but the parent product may not be found by that code without additional processing. FacetWP and Relevanssi official materials provide a documented relevanssi_content_to_index filter that adds child variation SKUs to the parent product's index. Use it only if visitors genuinely search variation codes and the primary product should appear in your storefront.

A Safe Adaptation for Variation SKUs

The documented example below should not be placed in WordPress core, FacetWP, WooCommerce, or the parent theme. Add it to a child theme or managed snippets plugin instead. You do not need to replace anything before using it: the filter searches child variations only for the product post type. If the catalog has tens of thousands of variations, test indexing on a project copy first and measure the operation time.

add_filter( 'relevanssi_content_to_index', 'rlv_index_variation_skus', 10, 2 );

function rlv_index_variation_skus( $content, $post ) {
    if ( 'product' === $post->post_type ) {
        $variations = get_posts( array(
            'post_parent'    => $post->ID,
            'post_type'      => 'product_variation',
            'posts_per_page' => -1,
        ) );

        foreach ( $variations as $variation ) {
            $content .= ' ' . get_post_meta( $variation->ID, '_sku', true );
        }
    }

    return $content;
}

After adding the code, rebuild the Relevanssi index and run Re-index in FacetWP. Then search for one recorded variation SKU on the public page and confirm that the correct parent product appears. Rollback is simple: disable or remove the snippet from the child theme, rebuild the index again, and repeat the test. Do not leave the code enabled merely because it appears in documentation if visitors do not search variation numbers.

Configure the Listing and Facets

On the archive page, FacetWP must detect the product loop. Create a Search facet with a clear placeholder, select Relevanssi under Search engine, and place the shortcode beside existing category, brand, and status facets. Add a reset control, counter, and, if needed, a Sort facet nearby. Start with live search disabled or moderately delayed so behavior is easier to measure.

Check availability separately. If a product exists in Relevanssi but is hidden, excluded from the current catalog, or filtered out by another facet, it should not unexpectedly appear in the storefront. This is not a weakness of search. It is the interaction of two different rules: one handles the meaning of the query, while the other defines the allowed set of cards.

Control Query Set

1. A part name that appears only in one product title.
2. A purpose-related term that appears in several product descriptions.
3. A brand name, if it was added as an indexed taxonomy term.
4. A full parent-product SKU added through _sku.
5. A variation SKU, only if the dedicated snippet is enabled and tested.
6. A query with a hyphen and the same code without a hyphen, if customers commonly use both forms.

For every query, record the expected first card, acceptable additional cards, and the action of one facet. This list becomes a regression check after theme updates, imports, weight changes, or cache-system changes. It is more useful than the general impression that "search seems to work."

How to Verify Results After Configuration and Avoid Being Misled by Accidental Matches

A working input is not the same as working search. After configuring FacetWP Relevanssi, test at three levels: the Relevanssi index, the FacetWP listing, and public-page behavior. If you inspect only appearance, it is easy to mistake a result found in a title for success while an important field is ignored or the setup breaks after a filter is applied.

Level 1: Admin Search and Index Status

Open Relevanssi admin search and enter the same control term. This confirms whether the engine itself can see the required post. If there is no result, check the post type, selected fields, index completion, minimum word length, and stopwords in that order. Use the Relevanssi debugger for a post that should have been found: it helps confirm whether the searched word entered its index.

Level 2: Search Within the Same Listing

Open the FacetWP page in a new private window or after clearing the relevant cache. Enter the same term. Then enable one facet at a time, remove it, change sorting, and navigate pagination. At every point, results should preserve the meaning of the query. If admin search is correct but the listing is empty, review the selected Search engine, shortcode location, template detection, and additional query conditions.

Level 3: Test It Like a Visitor

Ask someone who does not know the data model to answer three real questions. For example: "Find a part for this model," "Choose material at the required level," or "Find instructions for a specific setting." Watch which phrase they enter and when they expect to use a filter. This reveals not only technical failures, but also poor placeholder text, unclear facet labels, and data that a user considers obvious but an editor did not include in the index.

Final output check: the selected phrase, card count, active facets, sorting, and pagination should all describe the same selection. If even one element loses context, visitors will doubt the search even when the index is correct.

Speed, Cache, and Index Size: Where the Real Limits Are

Improving search meaning has a cost. Relevanssi stores its index in the database, FacetWP performs facet calculations, and the page must refresh correctly after a query. Performance cannot be reduced to a single switch. You need to measure page behavior, database size, query composition, number of facets, number of choices, and cache behavior.

Limit Coverage Before Optimizing the Server

The safest gain usually comes not from aggressive caching but from reducing unnecessary work. Index only post types that participate in the relevant listings. Do not enable dozens of facets if visitors almost always use three. Do not add technical fields to the index. For WooCommerce, evaluate whether you need variation processing, indexing unavailable products, and additional fields. This makes results easier to understand and the database easier to manage.

FacetWP specifically notes that pages with large amounts of content may benefit from limiting indexed types and posts. For a fast listing with frequently repeated filter combinations, the FacetWP caching add-on may help, but it caches its own AJAX requests and is most effective when identical combinations genuinely recur. Unique free-text visitor queries will not get the same benefit as popular, predictable filters.

Page Cache and JavaScript Order

With Full Page Cache, minification, and deferred script loading, it is especially important not to rely on assumptions. FacetWP warns that HTML minification can remove the <!--fwp-loop--> comments used to identify results, while deferred scripts can disrupt JavaScript execution timing. If the search field appears but no refresh arrives, or it works only after a second action, temporarily disable the relevant optimizations, clear the cache, and repeat the control test.

Do not exclude the entire site from caching unless necessary. Find the specific setting that breaks the page. Compare behavior without HTML minification, without deferring required scripts, and with a cleared cache. Once you find the cause, restore the remaining optimizations and document the exclusion in the project documentation. An optimization is successful only if results remain correct after a cold load, not after a single administrator test.

Scheduled Updates After Imports

When data is imported regularly, first determine the update frequency. FacetWP and Relevanssi have different indexes, and both need current information. On a large site, a planned operation during a quiet period is often more reliable than an unpredictable update in the middle of an import. Relevanssi documentation describes options for scheduled index building, while FacetWP provides tools for programmatic or selective reindexing. The appropriate method depends on your infrastructure, so do not add server commands to a production project without coordinating with the person responsible for hosting.

Special Cases: Default Search Pages, WooCommerce, and Listing Builder

The integration has several conditions that are rarely visible during the first test but appear after launch. They matter because FacetWP Relevanssi intercepts the WordPress search query before it can definitively know whether a page contains a facet. For that reason, the /?s=... page, product cards, and Listing Builder templates should be tested by their own rules rather than by analogy.

A /?s=... Page Without Facets

If a standard WordPress search page contains facets, choosing the Relevanssi engine in Search facet is normally enough. However, if /?s=searchterm contains no facets, the installed integration can interfere with results and produce an empty or unexpected output. FacetWP provides a setting for this case: Settings > FacetWP > Settings > Relevanssi - Disable FacetWP on the default search page.

This is preferable to a custom solution when that is exactly the issue. Enable the setting, clear the cache, and test the theme's regular form with several queries. Official documentation also provides the facetwp_is_main_query filter, which is equivalent to this behavior, but code is needed only when the built-in setting cannot be used or a more complex condition is required. Do not use both methods at the same time without a reason.

WooCommerce: SKUs, Variations, and Catalog Visibility

SKU search requires explicit indexing of the _sku field. Variation codes require separate testing with the parent product as described above. Also check catalog visibility conditions: a product may exist in the index but not appear because of publication settings, hidden status, exclusion from the current selection, or an active filter. Separate the diagnoses: "search cannot find it" belongs to Relevanssi, while "the found product is not allowed in the storefront" more often belongs to the listing or visibility rules.

For product codes with hyphens or spaces, document the forms real customers use. Do not rely on an administrator pasting a code from the catalog unchanged. If you need to change hyphen handling in Relevanssi, rebuild the index afterward and repeat the complete control SKU set.

Listing Builder, Excerpts, and Highlighting

Relevanssi can generate custom result excerpts and highlight a query. On a standard results page, this feature relies on a template that outputs the_excerpt(). In the Search facet context, there is an important limitation: Relevanssi's built-in hit highlighting does not automatically work for Search facets. For Listing Builder, FacetWP publishes a dedicated example using the facetwp_render_output filter, which passes entered words to Relevanssi highlighting and processes the template title and content.

Use this example only if you are actually using Listing Builder, the page has a Search facet with the Relevanssi engine, and highlighting improves result readability. First copy the listing to a test page, replace the facet name with the real one, test a one-word and multi-word query, and confirm that highlighting does not break card markup. If those conditions do not apply, it is better to keep a calm excerpt without custom highlighting.

Designing the Search Experience: Which Words, Fields, and Filters Should Meet on One Page

Most search problems have a cause that appeared before any plugin was installed: the team did not decide which visitor questions are text-based and which belong to filtering. Free text works well for tasks, names, synonyms, models, intended use, and natural language. A facet works better when the choice has a limited and understandable set of values: brand, category, format, date, range, status, or availability. When these roles are mixed, the interface forces visitors to guess the internal data model.

From a Visitor Question to a WordPress Field

A useful way to design the integration is to take ten questions a real person might send to support and map them to data. The question "Is there a spare part for model X?" may involve a model name in text, a compatibility field, and a category filter. The question "Show instructions for an editor" requires content search and an audience-role facet. The question "I need an affordable beginner course" combines a word in the description, a level taxonomy, and a numeric range. This exercise makes it clear that not every value must be indexed and not every word should become its own filter.

Then inspect the result card. If a visitor finds a post by a value that is not visible on the card, the result may feel confusing. For example, a product is found through an internal compatibility designation, but the public card shows neither the model nor an explanation. You do not necessarily need to expose the entire technical field, but provide a visible sign of the match: a category, short specification, tag, or explanatory excerpt. The purpose of results is not only to lead to a product page, but also to explain why that product appeared in the selection.

Do Not Duplicate Every Facet in the Index

Sometimes a team sees that a category or brand is available as a facet and automatically adds it to every search source. That is reasonable if visitors genuinely type brand or category names into the search box. But for a closed technical status, internal label, or long list of administrative terms, it creates false matches. It is more sensible to leave the value to a facet and avoid expanding full-text relevance.

On the other hand, do not expect people always to open a filter first. In a large catalog, phrases such as "for outdoor installation" or "for beginners" are natural. If the data exists only as a short code visible in a filter, meaning-based search will be weak. The solution is not always more programming. Sometimes it is enough to add a clear editorial description or normalized visible field that both appears on the card and is indexed by Relevanssi.

Synonyms, Spelling Variants, and Audience Language

Visitors rarely phrase a query exactly as an administrator would. They type "charger" when the card uses "power supply," enter "document" when the article author wrote "guide," or enter a model name without a hyphen. First collect these variants from emails, internal search, support chats, and sales-team requests. Then decide which should be normalized in content, which should be added through a Relevanssi-supported synonym mechanism, and which are better addressed through an interface hint.

Do not create synonyms for every possible typo. Stronger candidates are frequently repeated variants that clearly relate to the product or topic. If one word has several different meanings, automatic replacement can weaken results. In those cases, facets are more useful because they let users narrow the search area without artificial intent guessing.

Build a Clear Sequence of Actions

A page works best with a clear visual sequence: the search field answers "what do you need?" while the most likely refinements sit next to or below it. The first visible facet should reflect the user's main decision, not the value that is easiest to retrieve from the database. For a store, that is often category or brand; for a knowledge base, product or role; for a directory, type and region. Secondary conditions can go into an expandable block when they are rarely used and clutter the above-the-fold area.

Filter order is part of search quality. When active values are hidden or far from the search field, visitors do not understand why the results became short. Add a visible reset option and clear counter, and do not replace placeholder text with an unclear status message. During testing, look beyond the first results: remove one facet after searching, change sorting, and navigate to the next page. Context should persist through the entire flow.

A useful interface rule: a free-text query explains intent, a facet explains a restriction, and a card explains the match. If one of these three elements is silent, visitors start trying random words instead of trusting the results.

Editorial Relevanssi Tuning After Launch: Improve Relevance Without Random Changes

Once the first working version is live, it is tempting to improve results based on one inconvenient query: add every field, raise the limit, change the operator, or promote one card with code. That creates a configuration no one can explain. It is much more reliable to keep a small search-quality log and change only one type of rule at a time. This is especially useful with FacetWP, where both the index and listing filters affect the final output.

A Minimum Set of Reference Queries

Collect fifteen to thirty real queries. They should cover different search methods rather than variations of one phrase. Include an exact-name query, a broad task query, a synonym, a custom-field value, a taxonomy term, a code with punctuation, and a two-word query. For every query, record not only the expected first card but also an acceptable range: for example, "must appear in the first five" or "must not appear at all."

Record the purpose of each test beside it. An exact-name test checks basic indexing. A term test checks taxonomy indexing. A field test checks the selected meta field. A two-word test reveals the chosen operator behavior. An SKU query checks the code and punctuation. When a result changes after an update, you immediately know which layer was affected instead of having the vague sense that "search got worse."

A Safe Order for Changes

1. First fix data and the selection of indexed fields if required information is physically absent from search.
2. Then review taxonomies, excerpts, and clear synonyms if a meaningful term does not find relevant cards.
3. After that, assess the operator, minimum word length, and punctuation rules using the selected use cases.
4. Only then discuss manual weighting or custom code.
5. Change limits and performance settings last, after proving that they are excluding correct results.

After every step, rebuild the index if indexing settings changed, and run the complete reference query set. Changing a setting without rebuilding the index creates the false impression that the setting does not work. Likewise, update the FacetWP index after changing a facet. Record the date of the change, its reason, and test results in internal project documentation. That way, a future issue can be traced back to an unusual field selection or hyphen setting.

Result Excerpts: Their Benefit and Boundary

Relevanssi custom excerpts can show the context of a match. This is useful in a knowledge base where a keyword appears deep inside a long article. But an excerpt is not free decoration. It requires the template to use the_excerpt(), and on complex pages it can involve content processing. With FacetWP, this matters particularly on pages whose post content itself contains List Builder, blocks, or elements with other queries.

Start with a short, readable excerpt on a normal post. Confirm that it contains context rather than a code fragment, technical data, or repeated title. If matches may occur only in custom fields, configure field use in excerpts according to Relevanssi documentation. Then test heavy pages with blocks separately. If a failure occurs, it is safer to exclude a specific page from search or disable excerpt generation for the problematic use case than to wait for a live listing to hang.

Hit Highlighting Should Not Harm Readability

Highlighting is useful when visitors can see an ordinary result and quickly understand why it matched. But it should remain secondary. Strong highlighting on every word, highlighting internal parts of a card, or changing element heights makes a listing feel restless. Listing Builder does not have automatic Search facet highlighting, and that is not a bug: the official example requires a separate filter and has specific conditions for use.

If you add the documented facetwp_render_output example, implement it on one test page. Replace the facet name in the code with the real name, ensure the Search facet uses Relevanssi, and make sure the template is actually Listing Builder. Test an ordinary query, a multi-word query, search reset, a facet change, and page reload. Rollback means removing the snippet from the child theme or deactivating its entry in the snippets plugin. Do not edit FacetWP or Relevanssi files.

Query Logs and Privacy

Relevanssi can keep a log of user queries. This can be useful material for improving vocabulary and cards, but it is not an unconditional setting. Official documentation warns that storing IP addresses may require consent or specific disclosures depending on applicable law. If a log is needed, decide in advance which data is stored, who can see it, how long it is kept, and how cleanup is handled. Improving relevance often requires only the phrases themselves, without additional personal data.

Do not draw conclusions from a single rare query. Look for repeated patterns: people phrase the same term differently, regularly search for a property not available in filters, or receive too many results because of an internal field. Use these signals to improve descriptions, field selection, placeholder text, and filters. This makes configuration editorial work based on real demand rather than an endless technical race.

Team Responsibilities: Who Owns Data, Templates, and Testing

FacetWP Relevanssi is often implemented across several roles. An editor creates cards and articles, a manager knows customer questions, a developer understands queries and templates, and an administrator handles updates and backups. If everyone considers search someone else's area, a problem can go in circles: a developer receives poor results even though a field is empty; an editor is asked to fix text even though a facet cannot see the required loop; an administrator disables all caching even though one script is broken.

Content Editor Responsibilities

The editor is responsible for predictable data: the same characteristic should not be entered in a description today, an arbitrary field tomorrow, and a tag the next day. If a field is intended for an SKU, it should contain an SKU. If a taxonomy describes a brand, it should not become a place for promotional phrases. The editor can also maintain a list of user wording and observe which concepts are missing from cards.

Together with the developer, the editor defines visible evidence for results. If a post is found by a term or meaningful field, visitors should see the relevant context on the card or destination page. Otherwise, search feels random. This is especially noticeable in knowledge bases, where a short description is often more important than the full article body for understanding a result.

Developer and Integrator Responsibilities

The developer confirms that FacetWP is connected to the intended listing, the Search facet is placed correctly, and additional WP_Query instances or query_posts() calls are not replacing expected results. Relevanssi has a known issue: calling query_posts() in a search-results template can quietly prevent the engine from working normally. The presence of new WP_Query() or manual post-retrieval calls in a critical location also requires deliberate review rather than automatic changes.

The developer is also responsible for documented targeted customizations. If parent-product search by variation SKU is needed, use a verified filter, place it in a child theme or managed snippet, test it with sample data, and provide a rollback plan. If you need to modify a Relevanssi query in the FacetWP context, do not automatically use pre_get_posts: the integration documentation states that this produces incorrect result counts and pagination. Use the facetwp_relevanssi_do_query hook for that case.

Site Administrator Responsibilities

The administrator monitors updates, backups, permissions for the settings page, database size, and indexing schedules. Before a large import, agree on when Relevanssi and FacetWP will be rebuilt. After updating a theme, optimization plugin, or CDN, run a short regression checklist: one search query, one facet, reset conditions, pagination, and the regular /?s=... page if it is used.

When an issue cannot be isolated, enable FacetWP Debug Mode and collect the exact symptom, page URL, entered phrase, active facets, admin-search behavior, and caching information. That report helps support or a developer far more than a message saying "the filters stopped working." Disable debug mode after diagnosis if it is no longer needed.

A Small Procedure After Every Change

1. Describe what is changing: a field, search setting, facet, template, cache setting, or snippet.
2. Assign one control query and one control card that should change.
3. Update the relevant index and wait for the process to complete.
4. Check Relevanssi admin search, then the public FacetWP page.
5. Remove and restore one facet, navigate pagination, and verify reset behavior.
6. Record the outcome and rollback method before moving to the next setting.

This procedure does not slow work down. It prevents the situation where three changes are made simultaneously and nobody knows which one fixed the issue or created a new one. That is particularly important for search that affects a catalog and conversions.

Migration, Updates, and Safe Ongoing Maintenance

After launch, the integration should not become a static artifact. A theme change, import of a new batch of products, new taxonomy, or different optimization mode can change its behavior. But FacetWP Relevanssi should be maintained through observable checks, not by continually enabling additional settings.

Before Updating

Record plugin versions and active settings in restricted technical project documentation rather than in a public guide. Create a database backup. If possible, update plugins on a staging copy first. Run the reference query list and capture the baseline page response time. This provides a comparison point. Do not rely only on the absence of a fatal error: search may open normally while no longer indexing a field or while losing context on the second page.

After an Update or Bulk Import

First check that all indexing operations have completed. Then run an admin search using a unique field, a public phrase search, and a search with one facet. For WooCommerce, check SKUs and product visibility separately. Next, open the theme's standard search page if it is used and confirm that disabling FacetWP there preserves the expected behavior. Only then does it make sense to enable caching and test a cold page load.

If an update changes the settings interface, do not transfer old habits by guesswork. Open the current official FacetWP and Relevanssi documentation, especially the integration section and changelog. Some versions change technical details or fix compatibility. A public article should explain durable principles, while current minimum requirements and the list of fixes belong in sources and internal project documentation.

When to Create a Dedicated Search Page

A catalog with complex facets does not have to share the theme's regular search page. Sometimes the clearest option is to leave regular search for the overall site and add a dedicated "Find in the catalog" or "Search the knowledge base" page with its own FacetWP listing. This reduces the risk of intercepting /?s=... queries, makes the placeholder more specific, and allows facets to be placed without compromising the theme design.

A dedicated page is justified when search areas differ by post types or criteria. Do not create two nearly identical entry points if they show the same thing and users cannot understand the difference. The title, placeholder, and filter set should clearly communicate what is being searched: products, articles, documents, or directory listings.

Signs That the Solution Needs Review

A review is needed not after the first unusual query, but when systemic signs repeat: the index consumes more resources than hosting allows; important cards regularly fall outside the result cap; users increasingly search data unsupported by the current model; optimization conflicts recur after every update; or the team cannot safely maintain its own snippets. At that point, return to the data map and scale requirements instead of adding another exception.

Sometimes the outcome is a narrower FacetWP Relevanssi listing with clear rules. Sometimes it is a separate search service or a different architecture. Both are better than forcing one plugin to solve someone else's problem. The key is to make the decision using observable data: response time, index size, query logs, reference use cases, and how understandable the output is to visitors.

Diagnosing FacetWP Relevanssi: From Symptom to Safe Fix

Problems with this integration are easier to solve by following the query path than by reinstalling every plugin. Start with one known word and one control post. Then answer these questions: is the word in the Relevanssi index, is the right engine selected for this specific facet, does the current listing allow that post, and are cache or template settings interfering? This sequence reduces the risk of accidentally hiding an issue with a new setting.

Search Facet Shows Empty Results Immediately After Activation

Symptom: the field appears, but a known query returns no cards. Likely cause: Relevanssi is not selected in the Search facet's Search engine field, the add-on is not active, or Relevanssi has no completed index. FacetWP documentation explicitly states that when Relevanssi is active, its engine option must be selected or the facet returns empty results.

What to check: open settings for this exact facet, not only the general FacetWP page. Confirm that Relevanssi appears in the engine list and is selected. Then run the same query in Relevanssi admin search. How to fix it: activate the add-on, select the engine, save the facet, rebuild the required indexes, and refresh the public page without cache. If the engine is not listed, do not change the site template - first verify the installed add-on and compatibility of the current plugin versions.

Relevanssi Finds a Post in Admin, but FacetWP Does Not Show It on the Page

Symptom: admin search is correct, but the card disappears from the listing. Likely cause: the current page limits post type, category, publication status, visibility, or another facet excludes the post. The Search facet may also be attached to the wrong results template. What to check: temporarily remove other facets, inspect the original listing without search, and confirm that the control card exists there at all.

How to fix it: align listing conditions with the purpose of the page, and check shortcode placement and FacetWP template detection. After changing a facet, run Re-index. When to roll back: if a new setting expands results beyond the intended scope of the page, restore the earlier condition and create a dedicated search page instead of turning one archive into a universal search tool.

A Required Word or SKU Cannot Be Found

Symptom: an obvious card is absent from results even though the text or code is stored in WordPress. Likely causes: the field is not in the index, the index was not rebuilt after a change, the word is a stopword, it is shorter than the minimum length, or the code was entered with different punctuation. For SKUs, first verify that _sku was added to the Relevanssi custom-field list.

What to check: use Relevanssi Debugger for the specific post, inspect the Indexing and Stopwords settings, and compare the code with and without a hyphen. For variations, separately determine whether visitors should see the parent product when searching a variation SKU. How to fix it: include only the required field, change word-length or punctuation behavior only where the need is confirmed, then rebuild the index. For variations, use the documented filter from the practical use case and test it on a project copy. When to roll back: if adding a field sharply expands irrelevant results, exclude it and consider a separate facet for the structured value.

There Are Suspiciously Few Results or Distant Cards Are Missing

Symptom: search finds some suitable materials, but the catalog indicates that more exist. Likely cause: Relevanssi Throttle searches is active and limits the Search facet result set. The standard limit stated in FacetWP documentation is 500. Other causes include active facets, catalog visibility, and an incomplete index.

What to check: repeat the query without additional facets, compare it with admin search, then inspect the limit setting. How to fix it: first reduce index noise and confirm that a wider set is actually needed. Only then change the cap using the built-in setting or a documented filter. Do not lower the setting thoughtlessly or remove the limit on a heavy listing. When to roll back: if expanding the limit noticeably slows the page or makes it unresponsive in a normal user flow, restore a safe value and design more precise facets.

Empty Results or a Freeze on a Listing Builder Page

Symptom: results disappear, the page takes a long time to respond, or Relevanssi indexing stops. Likely cause: Relevanssi custom excerpts parse post content, while a result contains Listing Builder, a block, or an element that starts a FacetWP listing again. If it returns the same post, a recursive chain and memory exhaustion may occur.

What to check: determine whether pages containing listings or blocks with FacetWP output are entering search results. Compare behavior with Relevanssi custom excerpt generation disabled. How to fix it: exclude problematic pages from results through Relevanssi Searching > Post exclusion, or disable excerpt generation if it is not critical. In a complex Listing Builder setup, use query conditions that exclude a page from its own listing. When to roll back: if excerpts are useful only on one page, do not disable them globally without assessing an alternative; first exclude the specific recursive item.

The Regular /?s=... Page Stopped Showing Results

Symptom: the page with Search facet works, while the theme's standard form leads to an empty regular search page. Likely cause: the Relevanssi integration intercepts the search query even though the standard page has no facets. What to check: compare the page URLs and confirm that /?s=... truly has no Search facet or other facets. How to fix it: enable Disable FacetWP on the default search page in Settings > FacetWP > Settings > Relevanssi, clear the cache, and repeat the query. When to roll back: if you later add facets to the standard page, return to the setting and test the required setup again.

The Field Is Visible, but Typing Does Not Refresh Anything

Symptom: the user types a phrase, but cards remain unchanged, the indicator does not disappear, or updates occur inconsistently. Likely causes: cache removed FacetWP internal comments, deferred loading disrupted JavaScript order, the page has a script error, or live search starts before its expected threshold. What to check: temporarily clear the cache, disable HTML minification and deferred loading for affected scripts, then test the page in a separate window.

How to fix it: find the specific optimization causing the conflict and configure an exclusion only for the required mechanism. Enable FacetWP debug mode if you need request and facet information, then provide the exact error message to a developer or support. When to roll back: if an optimization exclusion harms the whole page, restore it and investigate a narrower exclusion instead of abandoning caching globally.

Video: A Live Walkthrough of the Integration

The specific video Search & filter with FacetWP & Relevanssi demonstrates the same search-and-filter combination covered in the practical use case. Watch it after basic installation: compare not the author's visual design, but the presence of the Relevanssi engine in Search facet, placement of filters next to the listing, and final result validation. The recording does not replace current documentation, especially for limits and compatibility, but it helps illustrate the general configuration path.

Questions That Commonly Come Up When Implementing Search

Do I Need FacetWP Relevanssi If Relevanssi Is Already Installed?

Yes, if you want to use Relevanssi together with FacetWP Search facet. The add-on is required specifically to integrate these two systems correctly. Relevanssi alone improves WordPress search, but it does not replace the connection to a faceted listing. If facets are not needed, a standard Relevanssi configuration may be sufficient.

Why Can't I Leave WP Default Selected for Search Facet?

With Relevanssi installed, that creates an incorrect setup: FacetWP's official documentation states that Search facet must have the Relevanssi engine selected or it will return empty results. You can use WP Default only when Relevanssi is disabled on the relevant page.

Do Both Plugins Need to Be Reindexed Every Time?

Not after every page view, but after changes that affect the relevant index. After changing content, fields, or Relevanssi settings, update the Relevanssi index. After creating or modifying a facet, run FacetWP Re-index. During bulk imports, define a manageable sequence for these operations and do not evaluate results against incomplete data.

Can I Search ACF Custom Fields?

Relevanssi can index data from custom fields. Start with specifically named fields that contain text useful to visitors, then rebuild the index. Do not enable every meta field simply because ACF stores information in the database: internal and hidden values can weaken relevance.

Why Does a Two-Letter Search Return an Empty Page?

By default, Relevanssi does not index words shorter than three characters. Check the minimum word length in advanced indexing settings and consider whether users genuinely need short codes. Rebuild the index after changing the setting. Also rule out the possibility that the entered word is in the stopword list.

Will Product SKUs Be Found Automatically?

No, SKUs are not indexed automatically. Add _sku to the required Relevanssi custom fields, rebuild the index, and run a control query. For variation SKUs, the parent product requires a separate documented adaptation when that use case is needed by visitors.

Can I Remove the 500-Result Limit?

It can be configured technically, but the decision should be justified by load and listing structure. First check the index, active facets, and need for precise filters. Removing the cap on a broad heavy query can reduce speed. It is often more useful to reduce noise in the data or offer another facet.

Is the Integration Suitable for Every Theme and Builder?

Absolute compatibility cannot be promised. FacetWP must correctly detect the listing, and theme optimization and caching must not break its refresh behavior. Listing Builder has separate recommendations for excerpts and highlighting. Test the specific template and retain a small set of regression queries after updates.

When FacetWP Relevanssi Is a Strong Choice

This integration earns its place when a site already has a well-designed listing and users need two ways to refine their choice: describe what they need in their own words and apply clear structured filters. Relevanssi handles the quality and coverage of search through a prepared index, while FacetWP handles page context, facets, and result presentation. The most stable outcome comes not from enabling the maximum number of options, but from working with real fields, control queries, and clear listing boundaries.

Start with one page, one data set, and several verifiable use cases. Once search reliably finds what visitors expect, facets retain context, and cache does not interfere with refreshes, you can expand the catalog and add more complex rules. If you already have FacetWP and Relevanssi, proceed to download FacetWP Relevanssi, install the add-on in a test environment, and repeat the installation and result-validation process described above.