Name: ElasticPress
Owner: 10up
Description: A fast and flexible search and query engine for WordPress.
Created: 2014-06-10 04:29:30.0
Updated: 2018-01-13 12:34:30.0
Pushed: 2018-01-11 15:20:20.0
Homepage: https://elasticpress.io
Size: 3023
Language: PHP
GitHub Committers
| User | Most Recent Commit | # Commits |
|---|
Other Committers
| User | Most Recent Commit | # Commits |
|---|
A fast and flexible search and query engine for WordPress.
Please note: master is the stable branch
Upgrade Notice: Versions 1.6.1, 1.6.2, 1.7, 1.8, 2.1, 2.1.2, 2.2 require re-syncing.
ElasticPress, a fast and flexible search and query engine for WordPress, enables WordPress to find or ?query? relevant content extremely fast through a variety of highly customizable features. WordPress out-of-the-box struggles to analyze content relevancy and can be very slow. ElasticPress supercharges your WordPress website making for happier users and administrators. The plugin even contains features for popular plugins.
ElasticPress integrates with the WP_Query object returning results from Elasticsearch instead of MySQL.
http or https). URLs without a protocol prefix will not be parsed correctly and will cause ElasticPress to error out.Once syncing finishes, your site is officially supercharged. You also have access to ElasticPress's powerful WP_Query integration API.
Instantly find the content you?re looking for. The first time.
?I want a cotton, woman?s t-shirt, for under $15 that?s in stock.? Faceted product browsing strains servers and increases load times. Your buyers can find the perfect product quickly, and buy it quickly.
ElasticPress understands data in real time, so it can instantly deliver engaging and precise related content with no impact on site performance.
Available API functions:
ep_find_related( $post_id, $return = 5 )
Get related posts for a given $post_id. Use this in a theme or plugin to get related content.
Optionally index all of your content, including private and unpublished content, to speed up searches and queries in places like the administrative dashboard.
Indexes text inside of popular file types, and adds those files types to search results.
Suggest relevant content as text is entered into the search field.
WP_Query and the ElasticPress Query IntegrationElasticPress integrates with WP_Query if the ep_integrate parameter is passed (see below) to the query object. If the search feature is activated (which it is by default), all queries with the s parameter will be integrated with as well. ElasticPress converts WP_Query arguments to Elasticsearch readable queries. Supported WP_Query parameters are listed and explained below. ElasticPress also adds some extra WP_query arguments for extra functionality.
ws you to run queries through Elasticsearch instead of MySQL. This parameter is the meat of the plugin. For example:
20 of the latest posts
new WP_Query( array(
'ep_integrate' => true,
'post_type' => 'post',
'posts_per_page' => 20,
) );
all posts with a specific category slug
new WP_Query( array(
'ep_integrate' => true,
'post_type' => 'post',
'posts_per_page' => -1,
'tax_query' => array(
array(
'taxonomy' => 'category',
'terms' => array( 'term-slug' ),
'field' => 'slug',
),
),
) );
ing `ep_integrate` to `false` will override the `s` parameter if provided.
ch keyword. By default used to search against ```post_title```, ```post_content```, and ```post_excerpt```. (Requires search feature)
er of posts to show per page. Use -1 to show all posts (the ```offset``` parameter is ignored with a -1 value). Set the ```paged``` parameter to paginate based on ```posts_per_page```.
er posts by terms in taxonomies. Takes an array of form:
new WP_Query( array(
's' => 'search phrase',
'tax_query' => array(
array(
'taxonomy' => 'taxonomy-name',
'field' => 'slug',
'terms' => array( 'term-slug-1', 'term-slug-2', ... ),
),
),
) );
outer array supports the `relation` parameter. Acceptable values are `and` and `or`. The default is `and`.
The following shorthand parameters can be used for querying posts by specific dates:
This is a simple example which will return posts which are created on January 1st of 2012 from all sites:
WP_Query( array(
's' => 'search phrase',
'sites' => 'all',
'year' => 2012,
'monthnum' => 1,
'day' => 1,
specific dates/times as well as an array of arrays with keys and values (array|string|int|boolean)
containing the following parameters `after, ``before`,inclusive``, `compare, ``column```, and
h are created after January 1st 2012 and January 3rd 2012 8AM GMT:
new WP_Query( array(
's' => 'search phrase',
'date_query' => array(
array(
'column' => 'post_date',
'after' => 'January 1st 2012',
),
array(
'column' => 'post_date_gmt',
'after' => 'January 3rd 2012 8AM',
),
),
) );
ently only the ```AND``` value is supported for the ```relation``` parameter.
and you pass in sting without specific time, it will be converted to 00:00:00 on that date. In this case, even if inclusive was set to true, the date would not be included in the query. If you want to include that specific date, you need to pass the time as well. (e.g. 'before' => '2012-01-03 23:59:59')
The example will return all posts which are created on January 5th 2012 after 10:00PM and 11:00PM inclusively, because the time is specified:
WP_Query( array(
's' => 'search phrase',
'date_query' => array(
array(
'column' => 'post_date',
'before' => 'January 5th 2012 11:00PM',
),
array(
'column' => 'post_date',
'after' => 'January 5th 2012 10:00PM',
),
'inclusive' => true,
),
ompare``` supports the following options:
`=``` - Posts will be returned that are created on a specified date.
`!=``` - Posts will be returned that are not created on a specified date.
`>``` - Posts will be returned that are created after a specified date.
`>=``` - Posts will be returned that are created on a specified date or after.
`<``` - Posts will be returned that are created before a specified date.
`<=``` - Posts will be returned that are created on a specified date or before that.
`BETWEEN``` - Posts will be returned that are created between a specified range.
`NOT BETWEEN``` - Posts will be returned that are created not in a specified range.
`IN``` - Posts will be returned that are created on any of the specified dates.
`NOT IN``` - Posts will be returned that are not created on any of the specified dates.
will return all posts which are created during Monday to Friday, between 9AM to 5PM:
WP_Query( array(
's' => 'search phrase',
'date_query' => array(
array(
'hour' => 9,
'compare' => '>=',
),
array(
'hour' => 17,
'compare' => '<=',
),
array(
'dayofweek' => array( 2, 6 ),
'compare' => 'BETWEEN',
),
),
er posts by post meta conditions. Meta arrays and objects are serialized due to limitations of Elasticsearch. Takes an array of form:
new WP_Query( array(
's' => 'search phrase',
'meta_query' => array(
array(
'key' => 'key_name',
'value' => 'meta value',
'compare' => '=',
),
),
) );
`=``` - Posts will be returned that have a post meta key corresponding to ```key``` and a value that equals the value passed to ```value```.
`!=``` - Posts will be returned that have a post meta key corresponding to ```key``` and a value that does NOT equal the value passed to ```value```.
`>``` - Posts will be returned that have a post meta key corresponding to ```key``` and a value that is greater than the value passed to ```value```.
`>=``` - Posts will be returned that have a post meta key corresponding to ```key``` and a value that is greater than or equal to the value passed to ```value```.
`<``` - Posts will be returned that have a post meta key corresponding to ```key``` and a value that is less than the value passed to ```value```.
`<=``` - Posts will be returned that have a post meta key corresponding to ```key``` and a value that is less than or equal to the value passed to ```value```.
`EXISTS``` - Posts will be returned that have a post meta key corresponding to ```key```.
`NOT EXISTS``` - Posts will be returned that do not have a post meta key corresponding to ```key```.
outer array also supports a ```relation``` (string) parameter. By default ```relation``` is set to ```AND```:
new WP_Query( array(
's' => 'search phrase',
'meta_query' => array(
array(
'key' => 'key_name',
'value' => 'meta value',
'compare' => '=',
),
array(
'key' => 'key_name2',
'value' => 'meta value',
'compare' => '!=',
),
'relation' => 'AND',
),
) );
ible values for ```relation``` are ```OR``` and ```AND```. If ```relation``` is set to ```AND```, all inner queries must be true for a post to be returned. If ```relation``` is set to ```OR```, only one of the inner meta queries must be true for the post to be returned.
'DECIMAL', 'SIGNED', 'TIME', and 'UNSIGNED'. By default WordPress casts meta values to these types in MySQL so some of these don't make sense in the context of Elasticsearch. ElasticPress does no “runtime” casting but instead compares the value to a different type compiled during indexing
NUMERIC - Compares query value to integer version of stored meta value.SIGNED - Compares query value to integer version of stored meta value.UNSIGNED - Compares query value to integer version of stored meta value.BINARY - Compares query value to raw, unanalyzed version of stored meta value. For actual attachment searches, check out this.CHAR - Compares query value to raw, unanalyzed version of stored meta value.DECIMAL - Compares query value to float version of stored meta value.DATE - Compares query value to date version of stored meta value. Query value must be formatted like 2015-11-14DATETIME - Compares query value to date/time version of stored meta value. Query value must be formatted like 2012-01-02 05:00:00 or yyyy:mm:dd hh:mm:ss.TIME - Compares query value to time version of stored meta value. Query value must be formatted like 17:00:00 or hh:mm:ss.If no type is specified, ElasticPress will just deduce the type from the comparator used. `type`
is very rarely needed to be used.
ws you to query meta with the defined key. Requires `meta_value` or `meta_value_num` be used as well.
value will be queried against the key defined in `meta_key`.
value will be queried against the key defined in `meta_key`.
er posts by post type. ```any``` will search all public post types. `WP_Query` defaults to either `post` or `any` if no `post_type` is provided depending on the context of the query. This is confusing. ElasticPress will ALWAYS default to `any` if no `post_type` is provided. If you want to search for `post` posts, you MUST specify `post` as the `post_type`.
ify post IDs to retrieve.
ify post IDs to exclude.
er of posts to skip in ascending order.
number of posts to be used with ```posts_per_page```.
posts associated with certain author ID.
posts associated with certain author. Use ```user_nicename``` (NOT name).
r results by field name instead of relevance. Supports: ```title```, ```modified```, `meta_value`, `meta_value_num`, ```type```, ```name```, ```date```, and ```relevance```; anything else will be interpretted 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`
h direction to order results in. Accepts ```ASC``` and ```DESC```. Default is ```DESC```.
posts that have the specified post parent.
The following are special parameters that are only supported by ElasticPress.
ot specified, defaults to ```array( '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. The following will fuzzy search across ```post_title```, ```post_excerpt```, ```post_content```, and terms within taxonomies ```category``` and ```post_tag```:
```php
new WP_Query( array(
's' => 'term search phrase',
'search_fields' => array(
'post_title',
'post_content',
'post_excerpt',
'taxonomies' => array( 'category', 'post_tag' ),
),
) );
```
`meta``` (*string* => *array*/*string*)
Applies the current search to post meta. The following will fuzzy search across ```post_title```, ```post_excerpt```, ```post_content```, and post meta keys ```meta_key_1``` and ```meta_key_2```:
```php
new WP_Query( array(
's' => 'meta search phrase',
'search_fields' => array(
'post_title',
'post_content',
'post_excerpt',
'meta' => array( 'meta_key_1', 'meta_key_2' ),
),
) );
```
`author_name``` (*string*)
Applies the current search to author login names. The following will fuzzy search across ```post_title```, ```post_excerpt```, ```post_content``` and author ```user_login```:
```php
new WP_Query( array(
's' => 'username',
'search_fields' => array(
'post_title',
'post_content',
'post_excerpt',
'author_name',
),
) );
```
aggregation results to your search result. For example:
's' => 'search phrase',
'aggs' => array(
'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' => array(
'name' => 'name-of-sub-aggregation',
'terms' => array(
'field' => 'terms.name-of-taxonomy.name-of-term',
),
),
),
is a built-in WordPress parameter that caches retrieved posts for later use. It also forces meta and terms to be pulled and cached for each cached post. It is extremely important to understand when you use this parameter with ElasticPress that terms and meta will be pulled from MySQL not Elasticsearch during caching. For this reason, ```cache_results``` defaults to false.
parameter only applies in a multi-site environment. It lets you search for posts on specific sites or across the network.
efault, ```sites``` defaults to ```current``` which searches the current site on the network:
's' => 'search phrase',
'sites' => 'current',
can search on all sites across the network:
's' => 'search phrase',
'sites' => 'all',
can also specify specific sites by id on the network:
's' => 'search phrase',
'sites' => 3,
can even specify a group of specific sites on the network:
's' => 'search phrase',
'sites' => array( 2, 3 ),
e:_ Nesting cross-site `WP_Query` loops can result in unexpected behavior.
The following commands are supported by ElasticPress:
wp elasticpress index [--setup] [--network-wide] [--posts-per-page] [--nobulk] [--offset] [--show-bulk-errors] [--post-type]
Index all posts in the current blog.
--network-wide will force indexing on all the blogs in the network. --network-wide takes an optional argument to limit the number of blogs to be indexed across where 0 is no limit. For example, --network-wide=5 would limit indexing to only 5 blogs on the network.--setup will clear the index first and re-send the put mapping.--posts-per-page let's you determine the amount of posts to be indexed per bulk index (or cycle).--nobulk let's you disable bulk indexing.--offset let's you skip the first n posts (don't forget to remove the --setup flag when resuming or the index will be emptied before starting again).--show-bulk-errors displays the error message returned from Elasticsearch when a post fails to index (as opposed to just the title and ID of the post).--post-type let's you specify which post types will be indexed (by default: all indexable post types are indexed). For example, --post-type="my_custom_post_type" would limit indexing to only posts from the post type “my_custom_post_type”. Accepts multiple post types separated by comma.wp elasticpress delete-index [--network-wide]
Deletes the current blog index. --network-wide will force every index on the network to be deleted.
wp elasticpress put-mapping [--network-wide]
Sends plugin put mapping to the current blog index. --network-wide will force mappings to be sent for every index in the network.
wp elasticpress recreate-network-alias
Recreates the alias index which points to every index in the network.
wp elasticpress activate-feature <feature-slug> [--network-wide]
Activate a feature. If a re-indexing is required, you will need to do it manually. --network-wide will affect network activated ElasticPress.
wp elasticpress deactivate-feature <feature-slug> [--network-wide]
Deactivate a feature. --network-wide will affect network activated ElasticPress.
wp elasticpress list-features [--all] [--network-wide]
Lists active features. --all will show all registered features. --network-wide will force checking network options as opposed to a single sites options.
wp elasticpress stats
Returns basic stats on Elasticsearch instance i.e. number of documents in current index as well as disk space used.
wp elasticpress status
ElasticPress can be used with the Elasticsearch Shield plugin
`ES_SHIELDin your ``wp-config.php``` file with the username and password of your Elasticsearch Shield user. For example:ne( 'ES_SHIELD', 'username:password' );
Dashboard sync can be disabled by defining the constant EP_DASHBOARD_SYNC as false in your wp-config.php file.
ne( 'EP_DASHBOARD_SYNC', false );
This can be helpful for managed sites where users initiating a sync from the dashboard could potentially cause issues such as deleting the index and limiting this control to WP-CLI is preferred. When disabled, features that would require reindexing are also prevented from being enabled/disabled from the dashboard.
ElasticPress has a robust API for registering your own features. Refer to the code within each feature for detailed examples. To register a feature, you will need to call the ep_register_feature() function like so:
action( 'plugins_loaded', function() {
ep_register_feature( 'slug', array(
'title' => 'Pretty Title',
'setup_cb' => 'setup_callback_function',
'feature_box_summary_cb' => 'summary_callback_function',
'feature_box_long_cb' => 'long_summary_callback_function',
'requires_install_reindex' => true,
'requirements_status_cb' => 'requirements_status_callback_function',
'post_activation_cb' => 'post_activation_callback_function',
) );
The only arguments that are really required are the slug and title of the associative arguments array. Here are descriptions of each of the associative arguments:
title (string) - Pretty title for featurerequires_install_reindex (boolean) - Setting to true will force a reindex after the feature is activated.setup_cb (callback) - Callback to a function to be called on each page load when the feature is activated.post_activation_cb (callback) - Callback to a function to be called after a feature is first activated.feature_box_summary_cb (callback) - Callback to a function that outputs HTML feature box summary (short description of feature).feature_box_long_cb (callback) - Callback to a function that outputs HTML feature box full description.requirements_status_cb (callback) - Callback to a function that determines if the features requirements are met. This function needs to return a EP_Feature_Requirements_Status object. EP_Feature_Requirements_Status is a simple class with a code and a message property. Code 0 means there are no requirement issues; code 1 means there are issues with warnings; code 2 means the feature does not have it's requirements met and cannot be used. The message property of the object can be used to store warnings.If you build an open source custom feature, let us know! We'd be happy to list the feature within ElasticPress documentation.
Follow the configuration instructions above to setup the plugin.
Within the terminal change directories to the plugin folder. Initialize your testing environment by running the following command:
For VVV users:
bin/install-wp-tests.sh wordpress_test root root localhost latest
For VIP Quickstart users:
bin/install-wp-tests.sh wordpress_test root '' localhost latest
where:
Our test suite depends on a running Elasticsearch server. You can supply a host to PHPUnit as an environmental variable like so:
OST="http://192.168.50.4:9200" phpunit
We have a Debug Bar Plugin available for ElasticPress. This tool allows you to examine all the ElasticPress queries on each page load.
If you identify any errors or have an idea for improving the plugin, please open an issue. We're excited to see what the community thinks of this project, and we would love your input!
ElasticPress is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.