diff --git a/docs/Aggregation/SignificantTerms.md b/docs/Aggregation/SignificantTerms.md new file mode 100644 index 0000000000000000000000000000000000000000..3d126059e139497f6b1249d3d7b3336bda85136c --- /dev/null +++ b/docs/Aggregation/SignificantTerms.md @@ -0,0 +1,109 @@ +# Significant Terms Aggregation + +> More info about histogram aggregation is in the [official elasticsearch docs][1] + +An aggregation that returns interesting or unusual occurrences of terms in a set. + +## Simple example + +```JSON +{ + "query" : { + "terms" : {"force" : [ "British Transport Police" ]} + }, + "aggregations" : { + "significantCrimeTypes" : { + "significant_terms" : { "field" : "crime_type" } + } + } +} +``` + +And now the query via DSL: + +```php +$significantTermsAggregation = new SignificantTermsAggregation('significantCrimeTypes', 'crime_type'); +$query = new TermsQuery('force', ['British Transport Police']); + +$search = new Search(); +$search->addQuery($query); +$search->addAggregation($histogramAggregation); + +$queryArray = $search->toArray(); +``` + +## Multi-set Analysis + +A simpler way to perform analysis across multiple categories is to use a parent-level aggregation to segment the data ready for analysis. + +```JSON + +{ + "aggregations": { + "forces": { + "terms": {"field": "force"}, + "aggregations": { + "significantCrimeTypes": { + "significant_terms": {"field": "crime_type"} + } + } + } + } +} + +``` + +And now the query via DSL: + +```php + +$significantTermsAggregation = new SignificantTermsAggregation('significantCrimeTypes', 'crime_type'); +$termsAggregation = new TermsAggregation('forces', 'force'); +$termsAggregation->addAggregation($significantTermsAggregation); + +$search = new Search(); +$search->addAggregation($termsAggregation); + +$queryArray = $search->toArray(); + +``` + +Other top level aggregations can be used to segment the data, for example, it can be segmented by +geographic area to identify unusual hot-spots of a particular crime: + +```JSON + +{ + "aggs": { + "hotspots": { + "geohash_grid" : { + "field":"location", + "precision":5, + }, + "aggs": { + "significantCrimeTypes": { + "significant_terms": {"field": "crime_type"} + } + } + } + } +} + +``` + +And now via DSL: + +```php + +$significantTermsAggregation = new SignificantTermsAggregation('significantCrimeTypes', 'crime_type'); +$geoHashAggregation = new GeoHashGridAggregation('hotspots', 'location', 5); +$geoHashAggregation->addAggregation($significantTermsAggregation); + +$search = new Search(); +$search->addAggregation($geoHashAggregation); + +$queryArray = $search->toArray(); + +``` + +[1]: https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-significantterms-aggregation.html diff --git a/src/Aggregation/SignificantTermsAggregation.php b/src/Aggregation/SignificantTermsAggregation.php new file mode 100644 index 0000000000000000000000000000000000000000..be70ed683daaf69d942a49daf64c9c3c020e996a --- /dev/null +++ b/src/Aggregation/SignificantTermsAggregation.php @@ -0,0 +1,28 @@ +<?php + +/* + * This file is part of the ONGR package. + * + * (c) NFQ Technologies UAB <info@nfq.com> + * + * For the full copyright and license information, please view the LICENSE + * file that was distributed with this source code. + */ + +namespace ONGR\ElasticsearchDSL\Aggregation; + +/** + * Class representing TermsAggregation. + * + * @link https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-significantterms-aggregation.html + */ +class SignificantTermsAggregation extends TermsAggregation +{ + /** + * {@inheritdoc} + */ + public function getType() + { + return 'significant_terms'; + } +} diff --git a/tests/Aggregation/SignificantTermsAggregationTest.php b/tests/Aggregation/SignificantTermsAggregationTest.php new file mode 100644 index 0000000000000000000000000000000000000000..1406d4188d7bdf24c2cdbf34ace3203326683dd9 --- /dev/null +++ b/tests/Aggregation/SignificantTermsAggregationTest.php @@ -0,0 +1,45 @@ +<?php + +/* + * This file is part of the ONGR package. + * + * (c) NFQ Technologies UAB <info@nfq.com> + * + * For the full copyright and license information, please view the LICENSE + * file that was distributed with this source code. + */ + +namespace ONGR\ElasticsearchDSL\Tests\Aggregation; + +use ONGR\ElasticsearchDSL\Aggregation\SignificantTermsAggregation; + +/** + * Unit test for children aggregation. + */ +class SignificantTermsAggregationTest extends \PHPUnit_Framework_TestCase +{ + /** + * Tests getType method. + */ + public function testSignificantTermsAggregationGetType() + { + $aggregation = new SignificantTermsAggregation('foo'); + $result = $aggregation->getType(); + $this->assertEquals('significant_terms', $result); + } + + /** + * Tests getArray method. + */ + public function testSignificantTermsAggregationGetArray() + { + $mock = $this->getMockBuilder('ONGR\ElasticsearchDSL\Aggregation\AbstractAggregation') + ->disableOriginalConstructor() + ->getMockForAbstractClass(); + $aggregation = new SignificantTermsAggregation('foo', 'title'); + $aggregation->addAggregation($mock); + $result = $aggregation->getArray(); + $expected = ['field' => 'title']; + $this->assertEquals($expected, $result); + } +}