Merge pull request #105 from daniellienert/feature-elasticsearch-suggestions

[FEATURE] implements the suggest feature of elasticsearch

Author: daniellienert

Classes/Flowpack/ElasticSearch/ContentRepositoryAdaptor/Eel/ElasticSearchQueryBuilder.php

@@ -451,7 +451,7 @@ public function fieldBasedAggregation($name, $field, $type = "terms", $parentPat
      * nodes = ${Search....aggregation("color", this.aggregationDefinition).execute()}
      *
      * Access all aggregation data with {nodes.aggregations} in your fluid template
-     * 
+     *
      * @param string $name
      * @param array $aggregationDefinition
      * @param null $parentPath
@@ -501,6 +501,64 @@ protected function addSubAggregation($parentPath, $name, $aggregationConfigurati
         return $this;
     }
 
+    /**
+     * This method is used to create a simple term suggestion.
+     *
+     * Example Usage of a term suggestion
+     *
+     * nodes = ${Search....termSuggestions("aTerm")}
+     *
+     * Access all suggestions data with {nodes.suggestions} in your fluid template
+     *
+     * @param string $text
+     * @param string $field
+     * @param string $name
+     * @return $this
+     */
+    public function termSuggestions($text, $field = '_all', $name = 'suggestions')
+    {
+        $suggestionDefinition = [
+            'text' => $text,
+            'term' => [
+                'field' => $field
+            ]
+        ];
+
+        $this->suggestions($name, $suggestionDefinition);
+        return $this;
+    }
+
+    /**
+     * This method is used to create any kind of suggestion.
+     *
+     * Example Usage of a term suggestion for the fulltext search
+     *
+     * suggestionDefinition = TYPO3.TypoScript:RawArray {
+     *     text = "some text"
+     *     terms = TYPO3.TypoScript:RawArray {
+     *         field = "body"
+     *     }
+     * }
+     *
+     * nodes = ${Search....suggestion("my-suggestions", this.suggestionDefinition).execute()}
+     *
+     * Access all suggestions data with {nodes.suggestions} in your fluid template
+     *
+     * @param string $name
+     * @param array $suggestionDefinition
+     * @return $this
+     */
+    public function suggestions($name, array $suggestionDefinition)
+    {
+        if (!array_key_exists('suggest', $this->request)) {
+            $this->request['suggest'] = [];
+        }
+
+        $this->request['suggest'][$name] = $suggestionDefinition;
+
+        return $this;
+    }
+    
     /**
      * Get the ElasticSearch request as we need it
      *

Classes/Flowpack/ElasticSearch/ContentRepositoryAdaptor/Eel/ElasticSearchQueryResult.php

@@ -198,6 +198,22 @@ public function getAggregations()
         return array();
     }
 
+    /**
+     * @return array
+     */
+    public function getSuggestions()
+    {
+        $this->initialize();
+        if (count($this->result['suggest']) === 1) {
+            $suggestArray = current($this->result['suggest']);
+
+            if (count($suggestArray) === 1) {
+                return current($suggestArray);
+            }
+        }
+        return $this->result['suggest'];
+    }
+
     /**
      * Returns the ElasticSearch "hit" (e.g. the raw content being transferred back from ElasticSearch)
      * for the given node.
@@ -222,3 +238,4 @@ public function allowsCallOfMethod($methodName)
         return true;
     }
 }
+

README.md

@@ -393,6 +393,50 @@ of `__typeAndSupertypes` containing `TYPO3.Neos:Document`.
 
 **For a search user interface, checkout the Flowpack.SearchPlugin package**
 
+## Suggestions
+
+Elasticsearch offers an easy way to get query suggestions based on your query. Check
+`https://www.elastic.co/guide/en/elasticsearch/reference/current/search-suggesters.html` for more information about how
+you can build and use suggestion in your search.
+
+**Suggestion methods implemented**
+There are two methods implemented. `suggestions` is a generic one that allows to build the suggestion query of your 
+dreams. The other method is `termSuggestions` and is meant for basic term suggestions. They can be added to your totaly 
+awesome TS search query.
+   
+* `suggestions($name, array $suggestionDefinition)` -- generic method to be filled with your own suggestionQuery
+* `termSuggestions($term, $field = '_all', $name = 'suggestions'` -- simple term suggestion query on all fields
+
+### Examples
+#### Add a simple suggestion to a query
+Simple suggestion that returns a suggestion based on the sent term
+
+```
+suggestions = $(Search.query(site)...termSuggestions('someTerm')}
+```
+You can access your suggestions inside your fluid template with 
+```
+{nodes.suggestions}
+```
+
+### Add a custom suggestion
+Phrase query that returns query suggestions
+
+```
+suggestionsQueryDefinition = TYPO3.TypoScript:RawArray {
+    text = 'some Text'
+    simple_phrase = TYPO3.TypoScript:RawArray {
+        phrase = TYPO3.TypoScript:RawArray {
+            analyzer = 'body'
+            field = 'bigram'
+            size = 1
+            real_world_error_likelihood = 0.95
+            ...
+        }
+    }
+}
+suggestions = ${Search.query(site)...suggestions('my_suggestions', this.suggestionsQueryDefinition)}
+```
 
 ## Advanced: Configuration of Indexing
 

Tests/Functional/Eel/ElasticSearchQueryTest.php

@@ -143,6 +143,28 @@ public function fieldBasedAggregations()
         $this->assertEquals($expectedChickenBucket, $result[$aggregationTitle]['buckets'][0]);
     }
 
+    /**
+     * @test
+     */
+    public function termSuggestion()
+    {
+        $titleSuggestionKey = "chickn";
+
+        $result = $this->queryBuilder->query($this->context->getRootNode())->termSuggestions($titleSuggestionKey, "title")->execute()->getSuggestions();
+
+        $this->assertArrayHasKey("options", $result);
+
+        $this->assertCount(1, $result['options']);
+
+        $expectedChickenBucket = array(
+            'text' => 'chicken',
+            'freq' => 2,
+            'score' => 0.8333333
+        );
+
+        $this->assertEquals($expectedChickenBucket, $result['options'][0]);
+    }
+
     /**
      * @test
      */