Introduction

eZ Platform exposes very powerful Search API, allowing both Full Text search and querying the content repository using several built-in Criteria and Sort Clauses. These are supported across several search engines, allowing you to plug in another search engine without changing your code.

Available Search Engines

Currently 3 search engines exists on their own eZ Platform Bundles:

1. Legacy, a database-powered search engines for basic needs.
2. Solr, an integration providing better overall performance, much better scalability and support for more advance search capabilities RECOMMENDED
3. ElasticSearch, similar to Solr integration, however currently not under active development EXPERIMENTAL, NOT SUPPORTED

Usage

Search Criteria and Sort Clauses

Search Criteria  and Sort Clauses are value object classes used for building Search Query, to define filter criteria and ordering of the result set. eZ Platform provides a number of standard Criteria and Sort Clauses that you can use out of the box and that should cover the majority of use cases.

Search Engine Handling of Search Criteria and Sort Clauses

As Search Criteria and Sort Clauses are value objects which are used to define the Query from API perspective, they are are common for all storage engines. Each storage engine needs to implement its own handler for corresponding Criterion and Sort Clause value object, which will be used to translate the value object into storage specific search query.

Custom Criteria and Sort Clauses

Sometimes you will find that standard Search Criteria and Sort Clauses provided with eZ Publish are not sufficient for you needs. Most often this will be the case if you have developed a custom Field Type using external storage, which therefore can not be searched using standard Field Criterion.

In this case you can implement a custom Criterion or Sort Clause, together with the corresponding handlers for the storage engine you are using.

Difference between Content and Location Search

These are two basic types of searches, you can either search for Locations or for Content. Each has dedicated methods in Search Service:

All Criteria and Sort Clauses will be accepted with Location Search, but not all of them can be used with Content Search. Reason for this is that while one Location always has exactly one Content item, one Content item can have multiple Locations. In this context some Criteria and Sort Clauses would produce ambiguous queries and such will therefore not be accepted by Content Search.

Content Search will explicitly refuse to accept Criteria and Sort Clauses implementing these abstract classes:

• eZ\Publish\API\Repository\Values\Content\Query\Criterion\Location

• eZ\Publish\API\Repository\Values\Content\SortClause\Criterion\Location

How to configure your own Criterion and Sort Clause Handlers

After you have implemented your Criterion / Sort Clause and its handler, you will need to configure the handler for the service container using dedicated service tags for each type of search. Doing so will automatically register it and handle your Criterion / Search Clause when it is given as a parameter to one of the Search Service methods.

Available tags for Criterion handlers in Legacy Storage Engine are:

• ezpublish.search.legacy.gateway.criterion_handler.content
• ezpublish.search.legacy.gateway.criterion_handler.location

Available tags for Sort Clause handlers in Legacy Storage Engine are:

• ezpublish.search.legacy.gateway.sort_clause_handler.content
• ezpublish.search.legacy.gateway.sort_clause_handler.location

Example of registering ContentId Criterion handler, common for both Content and Location Search

Example of registering Depth Sort Clause handler for Location Search

Criteria Independence Example

• Location A is visible
• Location B is hidden

• Content has Location B
• Content is visible (it has Location A that is visible)

Reference

Search Criteria Reference

Criteria are the filters for Content and Location Search, for generic use of API Search see Search Criteria and Sort Clauses .

A Criterion consist of two parts just like SortClause and FacetBuilder:

• The API Value: Criterion
• Specific handler per search engine: Criterion Handler

Criterion represents the value you use in the API, while CriterionHandler deals with the business logic in the background translating the value to something the Search engine can understand.

Common concepts for most Criteria

For how to use each and every Criterion see the list below, as it depends on the Criterion Value constructor, but in general you should be aware of the following common concepts:

• target: Exposed if the given Criterion supports targeting a specific sub field, example: FieldDefinition or Meta Data identifier
• value: The value(s) to filter on, this is typically a  scalar or array of scalars.
• operator: Exposed on some Criteria
  • All operators can be seen on eZ\Publish\API\Repository\Values\Content\Query\Criterion\Operator, at time of writing: IN, EQ, GT, GTE, LT, LTE, LIKE, BETWEEN, CONTAINS
  • Most Criteria do not expose this and select EQ or IN depending on if value is scalar or array
  • IN & BETWEEN always acts on an array of values, while the other operators act on single scalar value
• valueData : Additional value data, required by some Criteria, MapLocationDistance for instance

List of Criteria

The list below reflects Criteria available in the eZ\Publish\API\Repository\Values\Content\Query\Criterion namespace (it is also possible to make a custom Criterion):

Only for LocationSearch

Common

Sort Clauses Reference

Sort Clauses are the sorting options for Content and Location Search in eZ Platform. For generic use of API Search see Search Criteria and Sort Clauses.

A Sort Clause consists of two parts just like Criterion and FacetBuilder:

• The API Value: SortClause
• Specific handler per search engine: SortClausesHandler

The SortClause represents the value you use in the API, while SortClauseHandler deals with the business logic in the background, translating the value to something the Search engine can understand.

Common concepts for all Sort Clauses 

For how to use each and every Sort Clause, see list below as it depends on the Sort Clause Value constructor, but in general you should be aware of the following common concept:

• sortDirection: The direction to perform the sort, either Query::SORT_ASC (default) or Query:: SORT_DESC

List of Sort Clauses 

The list below reflects Sort Clauses available in the eZ\Publish\API\Repository\Values\Content\Query\SortClause namespace (it is also possible to make a custom Sort Clause):

Only for LocationSearch

Common