Search Criteria and Sort Clauses

=20

Introduction=
Search Engine Handling of Criteria and Sort Clauses=20
= Custom Criteria and Sort Clauses
Difference between Content and Location Search
How to configure your own Criterion and Sort Clause = Handlers=20
- Example of registeri= ng ContentId Criterion handler, common for both Content and Location Search=
- Example of registering Depth Sort Clause han= dler for Location Search=20
  - Related topics= :

=20

Introduction

Search Criteria and = Sort Clauses are value object classes used for building Search Query, to define f= ilter criteria and ordering of the result set. eZ Platform (and eZ Publish = Platform 5.x) 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.

Example of standard ContentId criterion

=20

<?php

namespace eZ\Publish\API\Repository\Values\Content\Query\Criterion;

use eZ\Publish\API\Repository\Values\Content\Query\Criterion;
use eZ\Publish\API\Repository\Values\Content\Query\Criterion\Operator\Speci=
fications;
use eZ\Publish\API\Repository\Values\Content\Query\CriterionInterface;

/**
 * A criterion that matches content based on its id
 *
 * Supported operators:
 * - IN: will match from a list of ContentId
 * - EQ: will match against one ContentId
 */
class ContentId extends Criterion implements CriterionInterface
{
    /**
     * Creates a new ContentId criterion
     *
     * @param int|int[] $value One or more content Id that must be matched.
     *
     * @throws \InvalidArgumentException if a non numeric id is given
     * @throws \InvalidArgumentException if the value type doesn't match th=
e operator
     */
    public function __construct( $value )
    {
        parent::__construct( null, null, $value );
    }

    public function getSpecifications()
    {
        $types =3D Specifications::TYPE_INTEGER | Specifications::TYPE_STRI=
NG;
        return array(
            new Specifications( Operator::IN, Specifications::FORMAT_ARRAY,=
 $types ),
            new Specifications( Operator::EQ, Specifications::FORMAT_SINGLE=
, $types ),
        );
    }

    public static function createFromQueryBuilder( $target, $operator, $val=
ue )
    {
        return new self( $value );
    }
}

=20

Search Engine Handling of Criteria and Sort Clauses

As Criterions and Sort Clauses are value objects which are used to define the Query from API perspect= ive, 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.

Example of ContentId criterion handler in Legacy Storage Engine

=20

<?php

namespace eZ\Publish\Core\Search\Legacy\Content\Common\Gateway\CriterionHan=
dler;

use eZ\Publish\Core\Search\Legacy\Content\Common\Gateway\CriterionHandler;
use eZ\Publish\Core\Search\Legacy\Content\Common\Gateway\CriteriaConverter;
use eZ\Publish\API\Repository\Values\Content\Query\Criterion;
use eZ\Publish\Core\Persistence\Database\SelectQuery;

/**
 * Content ID criterion handler
 */
class ContentId extends CriterionHandler
{
    /**
     * Check if this criterion handler accepts to handle the given criterio=
n.
     *
     * @param \eZ\Publish\API\Repository\Values\Content\Query\Criterion $cr=
iterion
     *
     * @return boolean
     */
    public function accept( Criterion $criterion )
    {
        return $criterion instanceof Criterion\ContentId;
    }


    /**
     * Generate query expression for a Criterion this handler accepts
     *
     * accept() must be called before calling this method.
     *
     * @param \eZ\Publish\Core\Search\Legacy\Content\Common\Gateway\Criteri=
aConverter $converter
     * @param \eZ\Publish\Core\Persistence\Database\SelectQuery $query
     * @param \eZ\Publish\API\Repository\Values\Content\Query\Criterion $cr=
iterion
     *
     * @return \eZ\Publish\Core\Persistence\Database\Expression
     */
    public function handle( CriteriaConverter $converter, SelectQuery $quer=
y, Criterion $criterion )
    {
        return $query->expr->in(
            $this->dbHandler->quoteColumn( "id", "ezcontentobject" ),
            $criterion->value
        );
    }
}

=20

Example of ContentId criterion handler in Solr Storage engine

=20

<?php

namespace EzSystems\EzPlatformSolrSearchEngine\Query\Content\CriterionVisit=
or;

use EzSystems\EzPlatformSolrSearchEngine\Query\CriterionVisitor;
use eZ\Publish\API\Repository\Values\Content\Query\Criterion;
use eZ\Publish\API\Repository\Values\Content\Query\Criterion\Operator;

/**
 * Visits the ContentId criterion
 */
class ContentIdIn extends CriterionVisitor
{
    /**
     * CHeck if visitor is applicable to current criterion
     *
     * @param Criterion $criterion
     *
     * @return boolean
     */
    public function canVisit( Criterion $criterion )
    {
        return
            $criterion instanceof Criterion\ContentId &&
            ( ( $criterion->operator ?: Operator::IN ) =3D=3D=3D Operato=
r::IN ||
              $criterion->operator =3D=3D=3D Operator::EQ );
    }


    /**
     * Map field value to a proper Solr representation
     *
     * @param Criterion $criterion
     * @param CriterionVisitor $subVisitor
     *
     * @return string
     */
    public function visit( Criterion $criterion, CriterionVisitor $subVisit=
or =3D null )
    {
        return '(' .
            implode(
                ' OR ',
                array_map(
                    function ( $value )
                    {
                        return 'id:"' . $value . '"';
                    },
                    $criterion->value
                )
            ) .
            ')';
    }
}

=20

Custom= Criteria and Sort Clauses

Sometimes you will find that standard Criteria and Sort Clauses provided with eZ Publish are not sufficient for yo= u needs. Most often this will be the case if you have developed a custom FieldType using exte= rnal storage, which therefore can not be searched using standard Field Crit= erion.

On use of Field Criterion/SortClause with large database= s

Field Criterion/SortClause does not perform well by design when using SQ= L database, so if you have a large database and want to use them you either= need to use Solr search engine, or develop your own Custom Criterion / Sor= t Clause to avoid use of attributes (Fields) database table, and instead us= es a custom simplified table which can handle the amount of data you have.<= /p>

In this case you can implement a custom Criterion or Sort Clause, togeth= er 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 Locatio= ns or for Content. Each has dedicated methods in Search Service:

Type of search	Method in Search Service
Content	`findContent()`
Content	`findSingle()`
Location	`findLocations()`

All Criterions and Sort Clauses will be accepted with Location Search, b= ut 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 c= an have multiple Locations. In this context some Criterions and Sort Clause= s would produce ambiguous queries and such will therefore not be accepted b= y Content Search.

Content Search will explicitly refuse to accept Criterions and Sort Clau= ses implementing these abstract classes:

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

eZ\Publish\API\Repository\Values\Content\SortClause\Criterio=
n\Location

How to configure your own Criterion and Sort Clause Handle= rs

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

Available tags for Criterion handlers in Legacy Storage Engine are:

ezpublish.search.legacy.gateway.criterion_handler.co= ntent
ezpublish.search.legacy.gateway.criterion_handler.lo= cation

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

You will find all the native handlers and the tags for the Legacy Storag= e Engine available in the eZ/Publish/Core/settings/storage_engines/legacy/search_query_h= andlers.yml file.

Example of registering Con= tentId Criterion handler, common for both Content and Location Search

Registering Criterion handler

=20

services:
    ezpublish.search.legacy.gateway.criterion_handler.common.content_i=
d:
        class: eZ\Publish\Core\Search\Legacy\Content\Common\Gateway\Criteri=
onHandler\ContentId
        arguments: [@ezpublish.api.storage_engine.legacy.dbhandler]
        tags:
          - {name: ezpublish.search.legacy.gateway.criterion_handler.conten=
t}
          - {name: ezpublish.search.legacy.gateway.criterion_handler.locati=
on}

=20

Example of registering Depth Sort Clause handler f= or Location Search

Registering Sort Clause handler

=20

ezpublish.search.legacy.gateway.sort_clause_handler.location.depth=
:
    class: eZ\Publish\Core\Search\Legacy\Content\Location\Gateway\SortClaus=
eHandler\Location\Depth
    arguments: [@ezpublish.api.storage_engine.legacy.dbhandler]
    tags:
        - {name: ezpublish.search.legacy.gateway.sort_clause_handler.locati=
on}

=20