updated the documentation

ongr-io · Jul 12, 2016 · d6ceeb2 · d6ceeb2
1 parent 028934c
commit d6ceeb2
Showing 1 changed file with 154 additions and 8 deletions.
diff --git a/docs/Suggest/index.md b/docs/Suggest/index.md
@@ -1,12 +1,27 @@
 # Suggest
 
-Objective suggest builder represents [Elasticsearch Term suggest][1].
+Objective suggest builder in ONGR ElasticsearchDSL represents [Elasticsearch suggesters][1].
+The `Suggest` class is universal for all the suggesters that are currently implemented in
+Elasticsearch.
 
-To form a suggest you have to create `Search` object. See below an example of suggest usage.
+The `Suggest` object takes up to 5 parameters during the initiation:
+
+|   Parameter  |                              Description                                   |
+|:------------:|:--------------------------------------------------------------------------:|
+|    `name`    | The name of the Suggest                                                    |
+|    `field`   | The ES field to execute the suggest                                        |
+|    `type`    | The type of the suggest (eg. phrase)                                       |
+|    `text`    | The text that will be passed to suggest                                    |
+| `parameters` | Array of additional parameters that may be unique to every type of suggest |
+
+To form a suggest you have to create `Search` object. See examples below for more information
+on suggest usage:
+
+### Simple example
 
 ```php
 $search = new Search();
-$suggest = new Suggest('my_suggest', 'searchText', ['field' => 'title', 'size' => 5]);
+$suggest = new Suggest('my_suggest', 'term', 'searchText', 'title', ['size' => 5]);
 $search->addSuggest($suggest);
 $queryArray = $search->toArray();
 ```
@@ -25,13 +40,15 @@ That will generate following JSON:
 }
 ```
 
+### Example of multiple suggests
+
 You're able to create more than one suggest:
 
 ```php
 $search = new Search();
-$suggest1 = new Suggest('my_suggest1', 'the amsterdma meetpu', ['field' => 'body', 'size' => 5]);
+$suggest1 = new Suggest('my_suggest1', 'term', 'the amsterdma meetpu', 'body', ['size' => 5]);
 $search->addSuggest($suggest1);
-$suggest2 = new Suggest('my_suggest2', 'the rottredam meetpu', ['field' => 'title', 'size' => 5]);
+$suggest2 = new Suggest('my_suggest2', 'term', 'the rottredam meetpu', 'title', ['size' => 5]);
 $search->addSuggest($suggest2);
 $queryArray = $search->toArray();
 ```
@@ -57,8 +74,137 @@ That will generate following JSON:
 }
 ```
 
-If parameters `field` or `size` are not provided they will have default values, `field = _all` and `size = 3`
+### Example of phrase suggest
+
+Also, provide different types of suggests, for example, this is a phrase suggest:
+
+```php
+$search = new Search();
+$suggest = new Suggest(
+    'my-suggest',
+    'phrase',
+    'Xor the Got-Jewel',
+    'bigram',
+    [
+        'analyzer' => 'body',
+        'size' => 1,
+        'real_word_error_likelihood' => 0.95,
+        'max_errors' => 0.5,
+        'gram_size' => 2,
+        'direct_generator' => [
+            [
+                'field' => 'body',
+                'suggest_mode' => 'always',
+                'min_word_length' => 1
+            ]
+        ],
+        'highlight'=> [
+            'pre_tag' => '<em>',
+            'post_tag' => '</em>'
+        ]
+    ]
+);
+
+$search->addSuggest($suggest);
+$queryArray = $search->toArray();
+
+```
+
+That will generate following JSON:
+
+```yaml
+"suggest" : {
+  "my-suggest"
+    "text" : "Xor the Got-Jewel",
+    "phrase" : {
+      "analyzer" : "body",
+      "field" : "bigram",
+      "size" : 1,
+      "real_word_error_likelihood" : 0.95,
+      "max_errors" : 0.5,
+      "gram_size" : 2,
+      "direct_generator" : [ {
+        "field" : "body",
+        "suggest_mode" : "always",
+        "min_word_length" : 1
+      } ],
+      "highlight": {
+        "pre_tag": "<em>",
+        "post_tag": "</em>"
+      }
+    }
+  }
+}
+
+```
+
+### Example of completion suggest:
+
+```php
+
+$search = new Search();
+$suggest = new Suggest('song-suggest', 'completion', 'n', 'suggest');
+
+$search->addSuggest($suggest);
+$queryArray = $search->toArray();
+
+```
+
+That will generate following JSON:
+
+```yaml
+
+"suggest" : {
+  "song-suggest" : {
+    "text" : "n",
+    "completion" : {
+      "field" : "suggest"
+    }
+  }
+}
+
+```
+
+### Example of context suggest:
+
+```php
+
+$search = new Search();
+$suggest = new Suggest(
+    'context-suggestion',
+    'completion',
+    'm',
+    'suggest_field',
+    [
+        'context' => ['color' => 'red'],
+        'size' => 10
+    ]
+);
+
+$search->addSuggest($suggest);
+$queryArray = $search->toArray();
+
+```
+
+That will generate following JSON:
+
+```yaml
+
+"suggest" : {
+  "context-suggestion" : {
+    "text" : "m",
+    "completion" : {
+      "field" : "suggest_field",
+      "size": 10,
+      "context": {
+        "color": "red"
+      }
+    }
+  }
+}
+
+```
 
-Find available parameters in [Elasticsearch Term suggest documentation][1]
+Find out more about suggesters in the official [Elasticsearch suggest documentation][1]
 
-[1]: https://www.elastic.co/guide/en/elasticsearch/reference/current/search-suggesters-term.html
+[1]: https://www.elastic.co/guide/en/elasticsearch/reference/current/search-suggesters.html