Elasticsearch Queries

There are slightly different limitations on the query APIs depending on which tier of service you have (WordPress.com VIP, Jetpack Pro, or Jetpack Related Posts). Depending on the level of service different features of the Elasticsearch Query DSL are available. There are currently two APIs available:

• Post Search API (VIP and Jetpack Pro).
  • Mostly a wrapper around the Elasticsearch /_search API.
  • The response looks slightly different due to filtering out some fields and some historical reasons.
  • Supports a subset of the top query parameters. See API docs.
• Related Posts API (Free)
  • Accepts Elasticsearch Filters for modifying the results. Many common examples here.
  • Returns the post_id and blog_id of any results.

Allowed Queries (& Filters)

To avoid performance problems and ensure backwards compatibility we only allow a subset of the Elasticsearch Query DSL.

Elasticsearch has moved away from explicitly separating queries and filters, so we don’t either.

Common Queries:

• bool
• match
• multi match
• function score
  • random_score is not supported
• match all
• range
• term
• terms

Exotic Queries:

• constant score
• boosting
• dis max
• more like this / mlt
• more like this field / mlt field
• geo bounding box
• geo distance
• geo distance range
• geohash cell
• exists

Deprecated Queries (Will be removed in the future):

• and filter (deprecated, use bool)
• not filter (deprecated, use bool)
• or filter (deprecated, use bool)
• filtered query (deprecated, use bool)

Allowed Aggregations

To avoid performance problems and ensure backwards compatibility we only allow a subset of the Elasticsearch Aggregations DSL. We do not currently allow any pipeline aggregations.

Aggregations are not allowed on any analyzed content fields (eg “content”, “title”, “tag.name.en”).

Metric Aggregations

• Extended Stats
• Stats

Bucket Aggregations

• Date Histogram
• Filters
• Histogram
• Terms

Size Field

The allowed maximum size depends on your level of service:

• Jetpack Professional Plan: 0-100
• WordPress.com VIP (with a dedicated index): 0-1000
• Jetpack Free Plan (Related Posts API): 1-15

From Field

The allowed maximum from depends on your level of service:

• Jetpack Professional Plan: 0-1000
• WordPress.com VIP (with a dedicated index): 0-9000
• Jetpack Free Plan (Related Posts API): 0-50

Fields

Although it is possible to return fields from the index, this is highly discouraged for production queries. The index has been optimized to efficiently and quickly return post_id and blog_id. Returning other fields is possible, but will slow down search results.

The other reason for relying on post_id and then getting the final data from the DB is that the Elasticsearch index is only a mirror of your data. It is cached, can be delayed, or can be slightly out of sync with your database. Any of these could result in serving stale content if you rely on it.

Sorting

Basic sorting on any field is allowed. We don’t allow any scripting.

Allowed Suggestions (Experimental)

Suggestions are currently experimental as we don’t yet have any libraries using it in production. There is an open issue for how to integrate it. Only term and phrase suggestions are supported. Exact support may change.

Allowed Rescoring (Experimental)

We currently support rescoring of queries for some experimental features. You probably shouldn’t use it.

Facets (Deprecated)

Facets are deprecated and will be removed. Do not use them. Use aggregations instead. We still have some VIP clients using them which is why the API accepts them, but they probably won’t work for you.

* Elasticsearch is a trademark of Elasticsearch BV, registered in the U.S. and in other countries.