EZP-27458: Provided Aggregation API

[adamwojs]

Question	Answer
JIRA issue	EZP-27458
Type	feature
Target eZ Platform version	v3.2
BC breaks	no
Tests pass	?
Doc needed	yes

Introduction

Aggregation API is successor of Facet API, however aggregation is wider concept then facet.

Description

Aggregation MUST implement \eZ\Publish\API\Repository\Values\Content\Query\AggregationInterface interface

<?php

/**
 * @copyright Copyright (C) eZ Systems AS. All rights reserved.
 * @license For full copyright and license information view LICENSE file distributed with this source code.
 */
declare(strict_types=1);

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

interface AggregationInterface
{
    public function getName(): string;
} 

Method getName() SHOULD return identifier specified by API user and unique across query e.g. price_stats, availability, content_type_facet.

One or more aggregations could be added using \eZ\Publish\API\Repository\Values\Content\Query::$aggregations property in exact same way as in case of sort clauses:

<?php 

use eZ\Publish\API\Repository\Values\Content\Query;
use eZ\Publish\API\Repository\Values\Content\Query\Aggregation\ContentTypeTermAggregation;
use eZ\Publish\API\Repository\Values\Content\Query\Aggregation\SectionTermAggregation;

$query = new Query();
$query->aggregations[] = new ContentTypeTermAggregation('content_type_facet');
$query->aggregations[] = new SectionTermAggregation('section_facet');

$results = $this->searchService->findContent($query);

// ... 

Aggregation Result MUST extends \eZ\Publish\API\Repository\Values\Content\Search\AggregationResult class

abstract class AggregationResult extends ValueObject
{
    /**
     * The name of the related aggregation.
     *
     * @var string
     */
    private $name;

    public function __construct(string $name)
    {
        parent::__construct();

        $this->name = $name;
    }

    public function getName(): string
    {
        return $this->name;
    }
}

Collection of aggregation results is accessible via \eZ\Publish\API\Repository\Values\Content\Search\SearchResult::$aggregations property.

// ...

foreach ($results->aggregations as $aggregation) {
    // Iterate over aggregations results
}

\eZ\Publish\API\Repository\Values\Content\Search\SearchResult::$aggregations property is \eZ\Publish\API\Repository\Values\Content\Search\AggregationResultCollection which offers the following API

Aggregations which are not supported by search engine MUST be ignored.

Aggregation results are limited to objects which match criteria specified in \eZ\Publish\API\Repository\Values\Content\Query::$filter and \eZ\Publish\API\Repository\Values\Content\Query::$query.

Supported aggregations

Aggregations could be classified by type of result:

• Term aggregation: group by value and count object in each group
• Range aggregation: count values in specified ranges
• Stats aggregation: computes stats over numeric fields: minimum, average and maximum value, count and sum of values

or by aggregation subject:

• Content aggregation
• Location aggregation

with subset of Field Type specific aggregations.

Content aggregations

Name	Comment
ContentTypeTermAggregation	Term aggregation based on content type
ContentTypeGroupTermAggregation	Term aggregation based on content type group
DateMetadataRangeAggregation	Range aggregation based on content creation/modification/publication date
LanguageTermAggregation	Term aggregation based on content language
ObjectStateTermAggregation	Term aggregation based on object state
SectionTermAggregation	Term aggregation based on section
UserMetadataTermAggregation	Term aggregation based on content owner/owner group or modifier
VisibilityTermAggregation	Term aggregation based on content/location visibility

Location aggregations

Location specific aggregations should implement \eZ\Publish\API\Repository\Values\Content\Query\Aggregation\LocationAggregationInterface marker interface.

Field type specific aggregations

Field type specific aggregations should implement \eZ\Publish\API\Repository\Values\Content\Query\Aggregation\FieldAggregationInterface interface

<?php

/**
 * @copyright Copyright (C) eZ Systems AS. All rights reserved.
 * @license For full copyright and license information view LICENSE file distributed with this source code.
 */
declare(strict_types=1);

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

interface FieldAggregationInterface
{
    public function getContentTypeIdentifier(): string;

    public function getFieldDefinitionIdentifier(): string;
}

Class naming convention:

• Field type identifier without vendor prefix (`ez` in our case)
• Type of aggregation
• Aggregation suffix

The following aggregations are field type specific

Name	Comment
CheckboxTermAggregation	-
CountryTermAggregation	-
DateRangeAggregation	-
DateTimeRangeAggregation	-
FloatRangeAggregation	-
FloatStatsAggregation	-
IntegerRangeAggregation	-
IntegerStatsAggregation	-
KeywordTermAggregation	-
SelectionTermAggregation	-
TimeRangeAggregation	-

Usage example:

<?php

$query = new Query();
$query->aggregations[] = new CheckboxTermAggregation('availability', 'product', 'is_available');
$query->aggregations[] = new KeywordTermAggregation('tags', 'product', 'tags');
$query->aggregations[] = new SelectionTermAggregation('categories', 'product', 'category');

Raw aggregations

Raw aggregations allows to compute aggregation for specified search index field name.

• \eZ\Publish\API\Repository\Values\Content\Query\Aggregation\RawRangeAggregation
• \eZ\Publish\API\Repository\Values\Content\Query\Aggregation\RawStatsAggregation
• \eZ\Publish\API\Repository\Values\Content\Query\Aggregation\RawTermAggregation

$query = new LocationQuery();
$query->filter = new MatchAll();
$query->aggregations[] = new RawRangeAggregation('priority', 'priority_id', [
    new Range(1, 10),  // low priority locations
    new Range(10, 100) // high priority
]);
$query->aggregations[] = new RawStatsAggregation('location_depth_stats', 'depth_i');
$query->aggregations[] = new RawTermAggregation('content_per_content_type', 'content_type_id_id');

TODO

• Initial implementaion
• Deprecate Facet API
• Introduce \eZ\Publish\Core\Search\Common\FieldNameResolver::getAggregationFieldName
• Consider to intoroduce AggregationCollection and AggregationResultCollection (similar to \eZ\Publish\API\Repository\Values\ContentType\FieldDefinitionCollection)
• Impl. \eZ\Publish\Core\FieldType\Float\Type::isSearchable (EZP-31817: Enabled ezfloat values indexing #103)
• Impl. ElasticSearch (ezsystems/ezplatform-elastic-search-engine#13)
• Impl. Solr support (EZP-27458: Aggregation API ezplatform-solr-search-engine#192)
• Rename UserTermAggregation to UserMetadataTermAggregation
• Rename DateRangeAggregation to DateMetadataRangeAggregation
• Remove $limit and $minCount from `\eZ\Publish\API\Repository\Values\Content\Query\Aggregation\AbstractTermAggregation::__construct`
• Fix https://jira.ez.no/browse/EZP-31741

Checklist:

• PR description is updated.
• Tests are implemented.
• Added code follows Coding Standards (use $ composer fix-cs).
• PR is ready for a review.

[kaff]

the class is quite long, can be split into smaller ones? ex. by TermAggregation, test case etc.
Smaller classes will be more friendly to maintain in future

[adamwojs]

I agree. I will split this class into smaller once (by Aggregation) in follow up PR.

[adamwojs]

Merging. Any further comments and suggestions will be taken into account as follow up PRs.

[sonarcloud]

Kudos, SonarCloud Quality Gate passed!

0 Bugs
0 Vulnerabilities (and 0 Security Hotspots to review)
11 Code Smells

No Coverage information
2.0% Duplication