Posted on

Index custom field contents

Custom fields (also known as post meta or meta fields) are a major part of WordPress the default search won’t search. That’s a big problem for people who use solutions like Advanced Custom Fields or Carbon Fields to develop sites: on sites developed with custom field plugins large parts of the post, content may be stored in the custom fields. If that information is not available for searching, the search is useless.

Relevanssi comes to the rescue! Relevanssi can index and search custom field content. No coding is required, for the most part, only more complicated solutions will require additional code – and if you can build those, you’ll be able to handle the required coding for Relevanssi.

Compatible custom field plugins

Relevanssi works with everything that stores the data in WordPress custom fields. That includes Advanced Custom Fields, Carbon Fields, CMB2, Toolset Types, Piklist and Custom Field Suite.

How to set up custom fields

By default, Relevanssi doesn’t index any custom fields. That is easy to change. Just go to the Relevanssi settings page, navigate to the Indexing tab and find this setting:

Custom field settings
Custom field settings

Here you can see the possible settings. You can choose to index all custom fields, which is the easy option. It covers everything and may lead to garbage results, as many themes and plugins include all sorts of metadata in the custom fields, and a lot of that is not useful for search.

Usually, indexing the visible custom fields is the best option: it covers all custom fields that are visible in the user interface, on the post edit page. WordPress hides all the custom fields that have names that start with underscores from the post edit pages: that’s where the theme settings are generally hidden.

If there are just a few specific custom fields you want to index, you can choose to index only some custom fields, which will open up an input field where you can list the custom fields you want to include.

Indexing some custom fields
Indexing some custom fields. “_sku” is a typical example.

Using custom fields in excerpts

If the content matching the search query is only in custom fields and not in post content, Relevanssi won’t be able to use it in excerpts. That is fortunately easy to fix. Just go to Relevanssi settings and the Excerpts and Highlights tab, and enable the “Use custom fields for excerpts” option.

Use custom fields for excerpts
Use custom fields for the excerpts option.

Now Relevanssi will automatically include the custom field content for excerpts.

Advanced excerpts from custom fields

If you want more control over how the custom fields are used for excerpts, you can use the relevanssi_pre_excerpt_content and relevanssi_excerpt_content to filter the content that is used for excerpts.

These filter hooks are almost identical: they filter the post content and get the post object and the search query as parameters. The only difference is that relevanssi_pre_excerpt_content runs before the_content is applied, and relevanssi_excerpt_content runs after.

43 comments Index custom field contents

    1. Sure, Meta Box is fine, as long as the data is stored in the actual WP custom fields. More complicated data structures (well, anything beyond strings) may require additional code to make Relevanssi understand the structure.

      1. Any update now in 2023, meaning is it fully compatible with Metabox? As with ACF…
        Also does it fully work with WPML (multilanguage)?
        Thanks for the update

        1. Mike, I don’t know about Metabox compatibility. I have no idea how Metabox works, and nobody has asked me about it. If it’s based on custom fields like ACF is, then there should be no problems with it.

          Relevanssi is compatible with WPML. I wouldn’t say “fully” because WPML is generally a headache, and is anything really “fully” compatible with WPML? I doubt it. There will always be fringe cases that don’t work well, but if you stick tot he basics, Relevanssi works fine with WPML.

  1. Can Relevanssi be configured to create a search structure that can access multiple custom fields with an AND effect? We have a kind of page, for instance, which has antique prints; custom fields on these pages include “publisher/editor” and “publication date”. We’d like to be able to enable searches across these two fields, returning only results that contain both search values. An example might be “Curtis” in the publisher editor field, and “1862” in the publication date field, with the returns being only Curtis publications from 1862.


    1. Yes, but you don’t actually want to use Relevanssi for that kind of searching. If all searching just targets custom fields, forget Relevanssi, and just use the Meta Query functionality in WP_Query. Using Meta Query, you’ll be able to formulate complicated AND queries with multiple custom fields.

      1. Thanks.

        We won’t be using Relevanssi just for these custom fields, but for general search on a fairly substantive site. However, the primary content is held in two kinds of pages (custom post types), both of which include multiple custom fields. We want users to be able to choose what they want to search (everything; everything within one of the custom post types; custom post text content; one or more custom fields; etc.).

        1. Yes, you can run meta queries as part of Relevanssi queries – but it’s still a good idea to drop Relevanssi off and just use the meta_query, if that’s all you need in a particular search. The search will perform better that way.

          But yes, this can be done with Relevanssi, but it won’t happen out of the box, it’ll require quite a bit of custom programming to make everything work the way you want it to work.

          What does “fairly substantive” mean? Hundreds of posts? Thousands, tens of thousands, hundreds of thousands?

  2. The site is a bit unusual, in that it is not at all “interactive”. All content is posted by admins and editors, and there is no provision for comments or dialogue. Most content is held on one custom post type, with a combination of image, text, links to other images in slideshow form and links to other site pages. There are about 2000 of these and related pages, which will grow significantly over time.

    There are also some 7000 media items, all photographs, which hold content in descriptions and captions that we need to be able to include in the search.

    So in terms of “posts” it’s smallish, but is well into mid-range in terms of total content.

    On a separate note, I’ve not received any notifications by email of replies. Is this normal?


    1. Sounds like something Relevanssi can handle, but it will probably require some custom programming to make it work.

      I don’t know about the emails, that’s a Jetpack service, and I have no knowledge of that. I know you need to confirm the subscription, so if you haven’t done that, then it won’t work.

  3. One last question — you say Relevanssi could handle the task, but may require some custom programming.

    Can you confirm that Relevanssi can search media items, in the media library — that is, the caption and fields associated with photographs?

    Sorry to post this here, not really about custom fields, but this should be our last query.

    1. You do need to confirm the subscription to get the emails. Maybe the confirmation email went in your spam folder?

      Yes, Relevanssi can search media items, that doesn’t require any custom programming. That’s a core feature for Relevanssi.

  4. Hi Saari,

    I was using custom type on my website but when I searching for custom type article don’t have any result show on my site.

    I’ve done the setting:
    1.Tick the custom type for the index on “Post types”
    2.Custom field: All
    3.Excerpts: Tick Index the post excerpt Index the post excerpt

    Excerpts and highlights:
    1. Use custom fields for excerpts: Tick Use custom field content for building excerpts

    Is any setting I lost?

    Best regards,


    1. Hsin-Hui, the settings are correct. Have you rebuilt the index after adjusting the custom field settings? Can you find the posts by title or content? If not, make sure the search is not being restricted by post type; some themes restrict the search to just posts.

  5. I have a custom field on my post called “keyword” that I would like to store a likely search term that doesn’t show up in the post anywhere. I have set Relevanssi to index all of my custom fields.

    When I test and type in my exact text that I have in the custom field (for example: tuesday blues 3) I get results but not the particular post that has that exact text in a custom field. I have reindexed after adding the custom field and its data.

    Can you help?

    Thanks! John

    1. John, at least the search on your website is not Relevanssi: it does not respond to Relevanssi parameters at all. So that might be the explanation here: something else is interfering with the search and you’re not seeing Relevanssi results at all.

      1. Well that’s a surprise! I do have FacetWP but have the integration plugin installed and activated. Is there something else that I need to do?

        1. Your theme may not be compatible, and may require changes. I’m not really up to what’s going on in the Genesis / StudioPress world these days; Genesis-based themes used to be fairly compatible with Relevanssi, but I can’t tell if that has changed in recent years. So unfortunately I can’t tell what’s up – that would require looking under the hood to see what your theme is actually doing on the search results page.

  6. I have several custom post types set up using Toolset and have followed the directions on this page. I’ve done the following:
    1. Under Post Types on the Indexing page, I’ve ticked the custom post types I would like indexed.
    2. Set Custom Fields dropdown to All.
    3. Clicked Build the Index.

    But search terms within a custom post type are not coming up in results.

    For example, I have books (a custom post type) that live on country pages (another custom post type). Books do not have their own pages. When I search by country name, the country shows up in search results, but the country does not show up when I search for a book that is on the country page.

    I’m not sure if I’m allowed to include URLs for reference, but please let me know if it would help if I did.

    1. StJenna, if books don’t have their own pages, what searching for books should return? The country page? In that case making Relevanssi index the book pages won’t help at all, because Relevanssi does not know there’s a connection between the books and the countries; Relevanssi would in that case want to return the book pages (I’m guessing they’re excluded from search, and Relevanssi respects that unless you check the “Don’t respect ‘exclude_from_search'” option in Relevanssi).

      Looks like you’d need some custom code here to make this work right. When the countries are indexed, the function should find all the books related to that country and include their contents in the country post for Relevanssi indexing. Done that way this would work the way you expect it to work.

      How are the books connected to the countries?

  7. The book content is on the country pages. Example:

    Since the content is on the country page, I would expect that if you searched for the book, the country page would show. Books are excluded from search but are marked to be indexed.

    Books are connected to countries through a relationship established in the Toolset plugin. Perhaps it has something to do with the shortcodes used by Toolset?

    1. If you don’t want books to appear in search results, you don’t need to index books for Relevanssi.

      You are using shortcodes to display the books on the pages? If the shortcodes are compatible with Relevanssi, just making Relevanssi expand shortcodes in indexing should be enough. If that doesn’t work, then the shortcodes aren’t compatible – that’s fairly common as well.

      If expanding shortcodes is not enough to make it work, then you need custom code that checks the relationships and reads in the book content when the countries are indexed.

  8. Yes, I am using shortcodes through Toolset, which I saw on the Relevanssi site is compatible. I also have the box checked to expand shortcodes. I’m thinking I must have some setting somewhere that’s incorrect. I’m just not sure which.

    1. It’s possible the shortcode simply isn’t enabled correctly for Relevanssi. You can check it. Just add this to your theme functions.php:

      add_filter( 'relevanssi_post_content_before_tokenize', function( $content ) { error_log( json_encode( $content ) ); return $content; } );

      Then go save a country page. Relevanssi will now print the post content it sees to the error log. Do you see the shortcodes in there, or the expanded content?

  9. I’m not sure if what I did is correct as I have never used the WordPress error log. I found error_log in my file manager, but it seems to be a log of only php errors and something about a dynamic library; I don’t see anything about Relevanssi in there. Is that the correct file?

    1. Yes, that’s the correct file – the PHP error_log() function prints to that file.

      You can check it by adding

      error_log("Testing the error log");

      to your theme functions.php so that it’s run every time your site loads a page, and see if that works.

      Add the code, save a post and check the log then, there should be something from Relevanssi there (if there isn’t and you’ve checked that the log works, then that’s another problem: that would mean Relevanssi isn’t actually active when saving posts).

  10. Hi. I want to create a search only for one custom field in Relevanssi. For instance, I’ve created a custom number field for “special guest” for a podcast. How do I set this up on the front end and back-end?

    1. First you need Relevanssi Premium, because the searches in the free version just don’t include enough information about the custom fields (you could do it with the free version, but at the cost of a lot of database queries, which may make the search too inefficient).

      Second you need to add some kind of parameter to the search in the front end, so that your backend filter can recognise when you’re doing this special search.

      Third you need a filter function on relevanssi_match that will remove all the results that don’t match the custom field, based on the customfield_detail (see Custom field -based weight here).

  11. We’re using Carbon Fields on our site, but I can’t find a way to include data from the complex fields.
    I’ve tried to use “%” like on the repeatable field in ACF, with no luck.

    The meta_keys have this structure:

    .. and like this if it’s a complex within a complex:

    I’ve tried with this:

    and this:

    .. with no luck… Any ideas how to solve this?
    Selecting Relevanssi to use “All” Custom Fields is not an option, since this will take forever to index (12+ hours)

    1. There’s no built-in support for the Carbon Fields format in Relevanssi, you need to do it yourself.

      There are couple of approaches here. You can either include or exclude. As long as you choose some custom fields to index, Relevanssi will give you the list of custom fields it indexes in the filter relevanssi_index_custom_fields. You can set the setting to “all” and then remove unwanted fields from the array of field names, or you can set it to “some” and then add only the fields you want to include, based on some suitable pattern.

      1. Got it to work by setting it to “All” and then excluding all of the meta_keys which did not follow the specific pattern “_sections_sections”. I found these keys by running a simple SQL Query. Now it only takes 15-20 mins to index all posts.

        Thank you, for your quick and helpfull reply.

  12. I would like to index all visible custom fields in addition to “_sku” – is there a simple way of doing that without having to select “some” and manually entering all of the visible field names?

    1. David, choose “visible”, and then add this to your theme functions.php:

      add_filter( 'relevanssi_index_custom_fields', function( $fields ) { $fields[] = '_sku'; return $fields; } );

  13. Hi,

    Great job with this plugin. Congrats…
    I’m using this plugin for my woocommerce and now, I added 2 custom fields (_sku and other one) and the searches works well, however, when I have a variable product, which has different sku’s by variation, the search don’t find the product.

    There is any way to fix this?
    Thank you.
    Best regards.

  14. I am using ACF blocks with ACF pro in my Full-Site-Editing theme.
    The output comes from the php script and so it is not in the comments of the page.

    Can relevanssi anyhow include the ACF block output to the search?

  15. i want this to only search for woocomerce product pages based on product titles and want to exclude pages or post from search results. How to get this done. Please help!

Leave a Reply

Are you a Relevanssi Premium customer looking for support? Please use the Premium support form.

Your email address will not be published. Required fields are marked *