Indexables

In ElasticPress 3.0, we’ve introduced the concept of Indexables, a way to enable indexing, search, and queries on any queryable object in WordPress, such as Posts or Comments, for example.

ElasticPress ships with the following built-in Indexables:

• Posts
• Comments
• Terms
• Users (available on the ElasticPress Labs plugin.)

You can also create your own custom Indexables by extending the Indexable class.

Post Indexable

ElasticPress integrates with WP_Query if the query corresponds to a search, i.e., the s parameter is set and is not empty, or if the ep_integrate parameter is passed (see below) to the query object. ElasticPress converts integrated WP_Query objects to Elasticsearch readable queries. The plugin also adds some extra WP_Query arguments for extra functionality.

WP_Query Parameters

ep_integrate (bool)

Allows you to run queries through Elasticsearch instead of MySQL. This parameter is the meat of the plugin.

Get 20 of the latest posts:

new \WP_Query(
	[
		'ep_integrate'   => true,
		'post_type'      => 'post',
		'posts_per_page' => 20,
	]
);

Get all posts with a specific category slug:

new \WP_Query(
	[
		'ep_integrate'   => true,
		'post_type'      => 'post',
		'posts_per_page' => -1,
		'tax_query'      => [
			[
				'taxonomy' => 'category',
				'terms'    => [ 'term-slug' ],
				'field'    => 'slug',
			],
		],
	]
);

Setting ep_integrate to false will override the s parameter if provided.

orderby (string)

Order results by field name, instead of relevance (the default.) Supports: relevance, date, type, modified, name, and title. Anything else will be interpreted as a document path i.e. meta.my_key.long or meta.my_key.raw.

You can sort by multiple fields as well i.e. title meta.my_key.raw

search_fields (array)

If you do not want to use the Weighting Dashboard, you can send an array of fields to be used by ElasticPress searches. In admin contexts, where the Weighting Dashboard is not used, this parameter defaults to [ 'post_title', 'post_excerpt', 'post_content' ].

• post_title (string) Applies current search to post titles.
• post_content (string) Applies current search to post content.
• post_excerpt (string) Applies current search to post excerpts.
• taxonomies (string => array/string) Applies the current search to terms within a taxonomy or taxonomies.
• meta (string => array/string) Applies the current search to post meta.
• author_name (string) Applies the current search to author login names.

The following will fuzzy search across post_title, post_excerpt, post_content, and terms within taxonomies category and post_tag:

new \WP_Query(
	[
		's'             => 'term search phrase',
		'search_fields' => [
			'post_title',
			'post_content',
			'post_excerpt',
			'taxonomies' => [
				'category',
				'post_tag',
			],
		],
	]
);

The following will fuzzy search across post_title, post_excerpt, post_content, and post meta keys meta_key_1 and meta_key_2:

new \WP_Query(
	[
		's'             => 'meta search phrase',
		'search_fields' => [
			'post_title',
			'post_content',
			'post_excerpt',
			'meta' => [
				'meta_key_1',
				'meta_key_2',
			],
		],
	]
);

The following will fuzzy search across post_title, post_excerpt, post_content and author user_login:

new \WP_Query(
	[
		's'             => 'meta search phrase',
		'search_fields' => [
			'post_title',
			'post_content',
			'post_excerpt',
			'author_name',
		],
	]
);

aggs (array)

Add aggregation results to your search results. For example:

new \WP_Query(
	[
		's'    => 'search phrase',
		'aggs' => [
			'name'       => 'name-of-aggregation', // (can be whatever you'd like)
			'use-filter' => true, // (*bool*) used if you'd like to apply the other filters (i.e. post type, tax_query, author), to the aggregation
			'aggs'       => [
				'name'  => 'name-of-sub-aggregation',
				'terms' => [
					'field' => 'terms.name-of-taxonomy.name-of-term',
				],
			],
		],
	]
);

site__in (int/string/array)

This parameter only applies in multi-site environments. It lets you search for posts on specific sites or across the network. By default, site__in defaults to current which searches the current site on the network. This article has some examples of how to use this parameter.

Comment Indexable

The Comment Indexable is only enabled if the Comment feature is activated (see this blog post about how you can do that.) ElasticPress integrates with WP_Comment_Query if the ep_integrate or search parameter passed to the query object. ElasticPress converts WP_Comment_Query arguments to Elasticsearch readable queries. The plugin also adds some extra WP_Comment_Query arguments for extra functionality.

WP_Comment_Query Parameters

• orderby (string) Order results by a specific field name. Supports: comment_agent, comment_approved, comment_author, comment_author_email, comment_author_IP, comment_author_url, comment_content, comment_date, comment_date_gmt, comment_ID, comment_karma, comment_parent, comment_post_ID, comment_type, user_id, meta_value and meta_value_num; anything else will be interpreted as a document path i.e. meta.my_key.long or meta.my_key.raw. Default is comment_date_gmt.
• search (string) Search keyword. By default used to search against comment_author, comment_author_email, comment_author_url, comment_author_IP and comment_content.
• search_fields (array) If not specified, defaults to array( 'comment_author', 'comment_author_email', 'comment_author_url', 'comment_author_IP', 'comment_content' ).
• site__in (int/string/array) This parameter only applies in a multi-site environment. It lets you search for comments on specific sites or across the network.

Term Indexable

The Comment Indexable is only enabled if the Terms feature is activated (see this blog post about how you can do that.) ElasticPress integrates with WP_Term_Query if the ep_integrate or search parameter passed to the query object. ElasticPress converts WP_Term_Query arguments to Elasticsearch readable queries. The plugin also adds some extra WP_Term_Query arguments for extra functionality.

WP_Term_Query Parameters

• orderby (string) Order results by a specific field name. Supports: slug, id, description, and name. Anything else will be interpreted as a document path i.e. meta.my_key.long or meta.my_key.raw. Default is comment_date_gmt.
• search_fields (array) If not specified, defaults to [ 'name', 'slug', 'taxonomy', 'description' ].
• site__in (int/string/array) This parameter only applies in a multi-site environment. It lets you search for comments on specific sites or across the network.

User Indexable

The User Indexable is only enabled if the User feature is activated. ElasticPress integrates with WP_User_Query if the ep_integrate or search parameter passed (see below) to the query object. ElasticPress converts WP_User_Query arguments to Elasticsearch readable queries. The plugin also adds some extra WP_User_Query arguments for extra functionality.

Supported WP_User_Query Parameters

• blog_id (int) The blog id on a multisite environment. Defaults to the current blog id.
• search Searches for possible string matches on columns. Note: Use of the * wildcard before and/or after the string is not currently supported in ElasticPress.
• search_fields Specify fields to be searched. Defaults to [ 'user_login', 'user_nicename', 'display_name', 'user_url', 'user_email', 'meta.first_name', 'meta.last_name', 'meta.nickname' ]
• search_columns Specify columns in the user database table to be searched. Note: this is merged into search_fields before being sent to Elasticsearch with search_fields overwriting search_columns.