Message-ID: <1092031240.4014.1485856352544.JavaMail.confluence@ip-10-127-227-164> Subject: Exported From Confluence MIME-Version: 1.0 Content-Type: multipart/related; boundary="----=_Part_4013_256275180.1485856352544" ------=_Part_4013_256275180.1485856352544 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable Content-Location: file:///C:/exported.html Search Criteria and Sort Clauses

Search Criteria and Sort Clauses

Version compatibility

This recipe is compatible with eZ Publish 5.3 and highe= r

=20 =20

Introduction

Search Criteria and Sort Clauses are valu= e object classes used for building Search Query, to define filter cr= iteria and ordering of the result set. eZ Platform (and eZ Publish Platform= 5.x)  provides a number of standard Criteria and Sort Clauses that yo= u 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<= /code> objects which are used to define the Query from API perspective, the= y are are common for all storage engines. Each storage engine needs to impl= ement its own handler for corresponding Criterion and Sort Cla= use value object, which will be used to translate the value ob= ject into storage specific search query.

Example of ContentId criterion handler in Legacy Storage Engine
=20 
<?php

namespace eZ\Publish\Core\Persistence\Legacy\Content\Search\Common\Gateway\=
CriterionHandler;

use eZ\Publish\Core\Persistence\Legacy\Content\Search\Common\Gateway\Criter=
ionHandler;
use eZ\Publish\Core\Persistence\Legacy\Content\Search\Common\Gateway\Criter=
iaConverter;
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\Persistence\Legacy\Content\Search\Common\Gat=
eway\CriteriaConverter $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 eZ\Publish\Core\Persistence\Solr\Content\Search\CriterionVisitor;

use eZ\Publish\Core\Persistence\Solr\Content\Search\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 you needs.= Most often this will be the case if you have developed a custom FieldType using external sto= rage, which therefore can not be searched using standard Field Criterion.

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 wait and use Solr/ElasticSearch support when official later in 201= 5, or develop your own Custom Criterion / Sort Clause to avoid use of attri= butes (Fields) database table, and instead uses a custom simplified table w= hich can handle the amount of data you have.

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:

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.

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.

Tags

>=3D5.4.= 2

Available tags for Criterion handlers in Legacy Storage Engine are:

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

<= =3D5.3

Available tags for Criterion handlers in Legacy Storage Engine are:

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

Example of register= ing ContentId Criterion handler in 5.4.x, common for both Content and Locat= ion 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 ha= ndler in 5.3.x for Location Search

Registering Sort Clause handler
=20 
ezpublish.persistence.legacy.search.gateway.sort_clause_handler.lo=
cation.depth:
    class: eZ\Publish\Core\Persistence\Legacy\Content\Search\Location\Gatew=
ay\SortClauseHandler\Location\Depth
    arguments: [@ezpublish.api.storage_engine.legacy.dbhandler]
    tags:
        - {name: ezpublish.persistence.legacy.search.gateway.sort_clause_ha=
ndler.location}
=20

See also

See also Symfony= documentation about Service Container for passing parameters

------=_Part_4013_256275180.1485856352544--