Merge remote-tracking branch 'remotes/upstream/5.x'

CHANGELOG.md

@@ -1,10 +1,14 @@
 # CHANGELOG
 v5.0.0 (2017-x)
 ---
-- **[BC break]** Removed deprecated aggregation classes.
-- **[BC break]** Removed deprecated query classes.
-- **[BC break]** `Search::getQueryParams()` changed to `Search::getUriParams()`.
-- **[BC break]** `FilterEndpoint` was removed due deprecated filters.
+- **Namespace for some queries were changed**. Queries were consolidated to a domain like Elasticsearch does.  All queries were grouped to `Compound`, `FullText`, `Geo`, `Joining`, `Span`, `Specialized` and `TermLevel`.
+- PHP version support changed to >=5.6
+- Added `elasticsearch\elasticsearch` to required dependency list in the composer.json.
+- Deprecated aggregations removed. Check if the namespace is correct. All aggregations grouped to `Bucketing`, `Metric` and `Pipeline` namespaces.
+- `Search::getQueryParams()` changed to `Search::getUriParams()`. All setter's for request URI parameters removed in favor of `uriParams` container. You can add URI parameters by `addUriParam`, and this function also has validation.
+- `Search::setFields()` and `Search::getFields()` were changed to `Search::setStoredFields()` and `Search::getStoredFields()`.
+- `FilterEndpoint` was removed due to deprecated filters in elasticsearch.
+- Added missing scroll param to URL params (#202)
 
 v2.2.1 (2017-01-26)
 ---

README.md

@@ -15,14 +15,15 @@ is the preffered and recommended way to ask ONGR support questions.
 
 | Elasticsearch version | ElasticsearchDSL version    |
 | --------------------- | --------------------------- |
-| >= 5.0                | >= 5.0                       |
-| >= 2.0, < 5.0         | >= 2.0                       |
+| >= 5.0                | >= 5.0                      |
+| >= 2.0, < 5.0         | >= 2.0, < 5.0               |
 | >= 1.0, < 2.0         | 1.x                         |
-| <= 0.90.x             | not supported               |
+| <= 0.90.x             | 0.x                         |
 
 ## Documentation
 
-[The online documentation of the bundle is here](docs/index.md)
+The latest library online documentation of the bundle [is here](http://docs.ongr.io/ElasticsearchDSL). If you need 2.x 
+docs you can find it in [the github branch here](https://github.com/ongr-io/ElasticsearchDSL/tree/2.x/docs).
 
 ## Try it!
 
@@ -34,24 +35,27 @@ Install library with [composer](https://getcomposer.org):
 $ composer require ongr/elasticsearch-dsl
 ```
 
+> [elasticsearch-php](https://github.com/elastic/elasticsearch-php) client is defined in the composer requirements, no need to install it.
+
 ### Search
 
 Elasticsearch DSL was extracted from [Elasticsearch Bundle](https://github.com/ongr-io/ElasticsearchBundle) to provide standalone query dsl for [elasticsearch-php](https://github.com/elastic/elasticsearch-php). Examples how to use it together with [Elasticsearch Bundle](https://github.com/ongr-io/ElasticsearchBundle) can be found in the [Elasticsearch Bundle docs](https://github.com/ongr-io/ElasticsearchBundle/blob/master/Resources/doc/search.md).
 
 If you dont want to use Symfony or Elasticsearch bundle, no worries, you can use it in any project together with [elasticsearch-php](https://github.com/elastic/elasticsearch-php). Here's the example:
 
-Install `elasticsearch-php`:
+If you are using Symfony there is also the [ElasticsearchBundle](https://github.com/ongr-io/ElasticsearchBundle)
+which provides full integration with Elasticsearch DSL. 
 
-```bash
-$ composer require elasticsearch/elasticsearch
-```
+The library is standalone and is not coupled with any framework. You can use it in any PHP project, the only
+requirement is composer.  Here's the example:
 
 Create search:
 
 ```php
  <?php
-  require 'vendor/autoload.php';
-  $client = ClientBuilder::create()->build();
+  require 'vendor/autoload.php'; //Composer autoload
+
+  $client = ClientBuilder::create()->build(); //elasticsearch-php client
 
   $matchAll = new ONGR\ElasticsearchDSL\Query\MatchAllQuery();
 

docs/HowTo/HowToSearch.md

@@ -10,7 +10,7 @@ $search = new Search();
 
 > We won't include namespaces in any examples. Don't worry all class's names are unique, so any IDE editor should autocomplete and include it for you ;).
 
-So, when we have a `Search` object we can start add something to it. Usually you will add `Query`, `Filter` and `Aggregation`.
+So, when we have a `Search` object we can start adding something to it. Usually you will add `Query` and `Aggregation`.
 
 > More info how create [queries](../Query/index.md) and [aggregations](../Aggregation/index.md) objects.
 
@@ -43,32 +43,40 @@ At the end it will form this query:
 
 ### Form a Filter
 
-Since Elasticsearch 2.0 all filters were replaced by queries. Queries acts like
-filters when you use them in filter context.
-
-To add a filter is the same way like a query. First, lets create some `Filter` object.
-
+Since Elasticsearch 5.0 the support for top level filters was dropped. The same functionality
+is now supported via `BoolQuery`. Adding a filter to the bool query is done like so:
+
 ```php
-$matchAllQuery = new MatchAllQuery();
-```
-
-And simply add to the `Search`:
+$search = new Search();
+$boolQuery = new BoolQuery();
+$boolQuery->add(new MatchAllQuery());
+$geoQuery = new TermQuery('field', 'value');
+$boolQuery->add($geoQuery, BoolQuery::FILTER);
+$search->addQuery($boolQuery);
 
-```php
-$search->addFilter($matchAllQuery);
+$search->toArray();
 ```
 
-Unlike `Query`, when we add a `Filter` with our DSL library it will add a query and all necessary stuff for you. So when we add one filter we will get this query:
+This will result in
 
-```JSON
+```
 {
-  "query": {
-      "bool": {
-          "filter": {
-              "match_all": {}
-          }
-      }
-  }
+    "query": {
+        "bool": {
+            "must": [
+                {
+                    "match_all": {}
+                }
+            ],
+            "filter": [
+                {
+                    "term": {
+                        "field": "value"
+                    }
+                }
+            ]
+        }
+    }
 }
 ```
 
@@ -113,63 +121,17 @@ The query will look like:
 ```
 > More info how to form bool queries find in [Bool Query](../Query/Bool.md) chapter.
 
-The same way it works with a `Filter`. Take a look at this example:
-
-```php
-$search = new Search();
-$termFilter = new TermQuery('name', 'ongr');
-$missingFilter = new MissingQuery('disabled');
-$existsFilter = new ExistsQuery('tag');
-$search->addFilter($termFilter);
-$search->addFilter($missingFilter);
-$search->addFilter($existsFilter, BoolQuery::MUST_NOT);
-```
-
-Elasticsearch DSL will form this query:
-
-```JSON
-{
-  "query": {
-    "bool": {
-        "filter": {
-            "bool": {
-                "must": [
-                    {
-                        "term": {
-                            "name": "ongr"
-                        }
-                    },
-                    {
-                        "missing": {
-                            "field": "disabled"
-                        }
-                    }
-                ],
-                "must_not": [
-                    {
-                        "exists": {
-                            "field": "tag"
-                        }
-                    }
-                ]
-            }
-        }
-    }
-  }
-}
-```
-
 ### Modify queries
 
 
 
 
 ### Sent request to the elasticsearch
-And finaly we can pass it to `elasticsearch-php` client. To generate an array for the client we call `toArray()` function.
+And finally we can pass it to `elasticsearch-php` client. To generate an array for the client we call `toArray()` function.
 
 ```php
 //from elasticsearch/elasticsearch package
-$client = new Elasticsearch\Client();
+$client = ClientBuilder::create()->build();
 
 $searchParams = [
   'index' => 'people',
@@ -180,4 +142,4 @@ $searchParams = [
 $docs = $client->search($searchParams);
 ```
 
-> This example is for elasticsearch/elasticsearch ~1.0 version.
+> This example is for elasticsearch/elasticsearch ~5.0 version.

docs/Query/FullText/MatchPhrase.md

@@ -0,0 +1,34 @@
+# MatchPhrase Query
+
+> More info about match phrase query is in the [official elasticsearch docs][1]
+
+The match_phrase query analyzes the text and creates a phrase query out of the analyzed text. For example:
+
+## Simple example
+
+```JSON
+{
+    "query": {
+        "match_phrase" : {
+            "message" : {
+                "query" : "this is a test",
+                "analyzer" : "my_analyzer"
+            }
+        }
+    }
+}
+```
+
+In DSL:
+
+```php
+$query = new MatchPhraseQuery('message', 'this is a test');
+$query->addParameter('analyzer', 'my_analyzer');
+
+$search = new Search();
+$search->addQuery($query);
+
+$queryArray = $search->toArray();
+```
+
+[1]: https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-match-query-phrase.html

docs/Query/FullText/MatchPhrasePrefix.md

@@ -0,0 +1,34 @@
+# Match Phrase Prefix Query
+
+> More info about match phrase prefix query is in the [official elasticsearch docs][1]
+
+The `match_phrase_prefix` is the same as `match_phrase`, except that it allows for prefix matches on the last term in the text. For example
+
+## Simple example
+
+```JSON
+{
+    "query": {
+        "match_phrase_prefix" : {
+            "message" : {
+                "query" : "quick brown f",
+                "max_expansions" : 10
+            }
+        }
+    }
+}
+```
+
+In DSL:
+
+```php
+$query = new MatchPhrasePrefixQuery('message', 'quick brown f');
+$query->addParameter('max_expansions', 10);
+
+$search = new Search();
+$search->addQuery($query);
+
+$queryArray = $search->toArray();
+```
+
+[1]: https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-match-query-phrase-prefix.html

docs/Query/Geo/GeoBoundingBox.md

@@ -0,0 +1,97 @@
+# Geo Bounding Box Query
+
+> More info about geo bounding box query is in the [official elasticsearch docs][1]
+
+A query allowing to filter hits based on a point location using a bounding box. Assuming the following indexed document:
+
+## Simple example
+
+```JSON
+{
+    "query": {
+        "bool" : {
+            "must" : {
+                "match_all" : {}
+            },
+            "filter" : {
+                "geo_bounding_box" : {
+                    "pin.location" : {
+                        "top_left" : {
+                            "lat" : 40.73,
+                            "lon" : -74.1
+                        },
+                        "bottom_right" : {
+                            "lat" : 40.01,
+                            "lon" : -71.12
+                        }
+                    }
+                }
+            }
+        }
+    }
+}
+```
+
+In DSL:
+
+```php
+$search = new Search();
+$location = [
+    ['lat' => 40.73, 'lon' => -74.1],
+    [ 'lat' => 40.01, 'lon' => -71.12],
+];
+$boolQuery = new BoolQuery();
+$boolQuery->add(new MatchAllQuery());
+$geoQuery = new GeoBoundingBoxQuery('pin.location', $location);
+$boolQuery->add($geoQuery, BoolQuery::FILTER);
+$search->addQuery($boolQuery);
+
+$queryArray = $search->toArray();
+```
+
+> This query accepts an array with either 2 or 4 elements as its second parameter,
+failing to meet this criteria will result in an error!
+
+Alternatively the vertices of the bounding box can be set separately:
+
+```json
+
+{
+    "query": {
+        "bool" : {
+            "must" : {
+                "match_all" : {}
+            },
+            "filter" : {
+                "geo_bounding_box" : {
+                    "pin.location" : {
+                        "top" : 40.73,
+                        "left" : -74.1,
+                        "bottom" : 40.01,
+                        "right" : -71.12
+                    }
+                }
+            }
+        }
+    }
+}
+
+```
+
+Now via DSL:
+
+```php
+
+$search = new Search();
+$location = [40.73, -74.1, 40.01, -71.12];
+$boolQuery = new BoolQuery();
+$boolQuery->add(new MatchAllQuery());
+$geoQuery = new GeoBoundingBoxQuery('pin.location', $location);
+$boolQuery->add($geoQuery, BoolQuery::FILTER);
+$search->addQuery($boolQuery);
+
+$queryArray = $search->toArray();
+
+```
+
+[1]: https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-geo-bounding-box-query.html