relevanssi_index_doc()

relevanssi_index_doc( WP_Post|int $post, bool $remove_first = false, array|string $custom_fields = '', bool $bypass_global_post = false, bool $debug = false )

The relevanssi_index_doc() function indexes a single document.

Source: /lib/indexing.php

Parameters

$post
(WP_Post | integer) The post to index if $bypass_global_post is true, either the post object or the post ID.

$remove_first
(boolean) If true, Relevanssi will remove the post from the index before indexing it. Default: false.

$custom_fields
(array | string) Which custom fields Relevanssi should index for the post? This parameter can be “all”, “visible”, or an array of custom field names. If you want to specify just one custom field, that also needs to be an array. Default: an empty string. When using this function, use the return value from relevanssi_get_custom_fields() for this parameter; it returns the custom field setting from Relevanssi settings.

$bypass_global_post
(boolean) If true, Relevanssi will index the post specified by the $post parameter. If false, Relevanssi ignores the $post parameter and indexes the global $post. Default: false.

$debug
(boolean) If true, Relevanssi will output debugging information. Default: false.

Returns

(string | integer) The function returns the number of insert queries it runs. If the indexing fails, the function returns -1. If the post is hidden, the function returns “hide”, and if a filter blocks the indexing, the function returns “donotindex”.

Usage

This function indexes a single post. Here’s how the indexing process goes:

  1. Relevanssi fetches the post again using get_post(), in order to make sure it is indexing the latest version of the post.
  2. Relevanssi Premium post exclusion setting checks whether the post can be indexed or not.
  3. The relevanssi_do_not_index filter hook checks whether the post can be indexed or not.
  4. The post is removed from the index if necessary.
  5. The relevanssi_post_to_index filter hook filters the post object.
  6. Relevanssi reads the comments (filter hooks used: relevanssi_index_comments_exclude, relevanssi_get_approved_comments_args, relevanssi_comment_author_to_index, relevanssi_comment_content_to_index, relevanssi_indexing_tokens).
  7. Relevanssi reads the taxonomy terms (filter hooks used: relevanssi_tag_before_tokenize, relevanssi_indexing_tokens).
  8. Relevanssi reads the post author (filter hooks used: relevanssi_post_author, relevanssi_indexing_tokens).
  9. Relevanssi reads the custom fields (filter hooks used: relevanssi_index_custom_fields, relevanssi_custom_field_value, relevanssi_indexing_tokens).
  10. Relevanssi reads the excerpt (filter hooks used: relevanssi_indexing_tokens).
  11. Relevanssi Premium reads custom MySQL columns (filter hooks used: relevanssi_indexing_tokens).
  12. Relevanssi Premium reads the contents of the PDF files attached to the post (filter hooks used: relevanssi_pdf_for_parent_query, relevanssi_indexing_tokens).
  13. Relevanssi reads the post title (filter hooks used: relevanssi_index_titles, the_title, relevanssi_post_title_before_tokenize, relevanssi_remove_stopwords_in_titles, relevanssi_indexing_tokens).
  14. Relevanssi reads the post content (filter hooks used: relevanssi_index_content, relevanssi_post_content, relevanssi_content_to_index, relevanssi_post_content_after_shortcodes, relevanssi_post_content_before_tokenize, relevanssi_indexing_tokens).
  15. The post data is converted into MySQL INSERT queries and inserted into the Relevanssi index table.

Using this function to index posts

Relevanssi uses this function to index new posts and to reindex updated posts. Relevanssi hooks onto the wp_insert_post, add_attachment and edit_attachment hooks with relevanssi_insert_edit() function that has additional checks on whether a post can be indexed or not. If the post is good, relevanssi_insert_edit() calls relevanssi_publish() which then calls relevanssi_index_doc().

Indexing individual posts outside this process is most often necessary when:

  • Saving the posts triggers wp_insert_post, but the posts are modified after that and Relevanssi therefore ignores those modifications. A common example is WooCommerce API product insertions, where metadata like the SKU is added after Relevanssi indexes the post.
  • Posts are saved in a way that does not trigger wp_insert_post.

In these cases, the solution is to figure out an action hook that runs at the right part of the process and then call relevanssi_index_doc(). For example, with WooCommerce, you can do this:

add_action(
  'woocommerce_new_product',
  function( $id ) {
    relevanssi_index_doc( $id, true, relevanssi_get_custom_fields(), true );
  }
);

The woocommerce_new_product action hook happens when WooCommerce finishes with the product. When you index the product at that point, Relevanssi will index all the metadata.

Examples: