Merge pull request #4 from ensi-platform/dev-facets

Facets

Author: zix2

README.md

@@ -37,6 +37,10 @@ class ProductSpecification extends CompositeSpecification
             AllowedAggregate::minmax('rating')
         ]);
 
+        $this->allowedFacets([
+            'package'
+        ]);
+        
         $this->whereNotNull('package');
 
         $this->nested('offers', function (Specification $spec) {
@@ -50,6 +54,10 @@ class ProductSpecification extends CompositeSpecification
             $spec->allowedSorts([
                 AllowedSort::field('price')->byMin()
             ]);
+            
+            $spec->allowedFacets([
+                AllowedFacet::terms('seller_id')
+            ]);
         });
     }
 }
@@ -74,6 +82,15 @@ Here are examples of queries for this specification.
  }
 }
 ```
+```json
+{
+  "facet": ["seller_id", "package"],
+  "filter": {
+    "package": "bottle",
+    "seller_id": [10, 20, 50, 90]
+  }
+}
+```
 
 The `nested` method adds specifications for nested documents. The names of filters, aggregates, and sorts are exported
 from them to the global scope without adding any prefixes. It is acceptable to have the same names for filters, but not
@@ -158,6 +175,25 @@ AllowedAggregate::minmax('name', 'field');  // Get min and max attribute values
 
 Aggregates from nested specifications are added to the Elasticsearch query with all constraints and active filters.
 
+You can use the `allowedFacets` method to define facets. Each facet requires an aggregate and one or
+more filters. You can use both the existing aggregate
+
+```php
+AllowedFacet::fromAggregate('name', 'filter');
+```
+
+and the aggregate created by the facet itself
+
+```php
+AllowedFacet::terms('name', 'filter');
+AllowedFacet::minmax('name', ['filter1', 'filter2']);
+```
+
+Filters are registered in the specification separately. Only their names are passed to facet creation methods.
+
+During the calculation of the available values for each facet, all set filters are applied except those associated with
+this facet.
+
 ## Search for documents
 
 ```php
@@ -210,6 +246,32 @@ class ProductsController
 }
 ```
 
+## Determining the available facet values
+
+```php
+use Ensi\LaravelElasticQuerySpecification\FacetQueryBuilder;
+use Ensi\LaravelElasticQuerySpecification\QueryBuilderRequest;
+
+class ProductsFacetsQuery extends FacetQueryBuilder
+{
+    public function __construct(QueryBuilderRequest $request)
+    {
+        parent::__construct(ProductsIndex::aggregate(), new ProductSpecification(), $request);
+    }
+}
+```
+
+```php
+class ProductsController
+{
+    // ...
+    public function facets(ProductsFacetsQuery $query)
+    {
+        return new ProductFacetsResource($query->get());
+    }
+}
+```
+
 ## Contributing
 
 Please see [CONTRIBUTING](.github/CONTRIBUTING.md) for details.

config/elastic-query-specification.php

@@ -8,5 +8,6 @@
         'filter' => 'filter',
         'sort' => 'sort',
         'aggregate' => 'aggregate',
+        'facet' => 'facet',
     ],
 ];