Merge branch 'master' of github.com:ongr-io/ElasticsearchDSL

docs/Aggregation/Avg.md

+# Avg Aggregation
+
+> More info about avg aggregation is in the [official elasticsearch docs][1]
+
+A single-value metrics aggregation that computes the average of numeric values that are extracted from the aggregated documents.
+
+
+## Simple example
+
+```JSON
+{
+    "aggregations": {
+        "agg_avg_grade": {
+            "avg": {
+                "field": "grade"
+            }
+        }
+    }
+}
+```
+
+And now the query via DSL:
+
+```php
+$avgAggregation = new AvgAggregation('avg_grade');
+$avgAggregation->setField('grade');
+
+$search = new Search();
+$search->addAggregation($avgAggregation);
+
+$queryArray = $search->toArray();
+```
+
+[1]: https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-metrics-avg-aggregation.html
\ No newline at end of file

docs/Aggregation/Cardinality.md

+# Cardinality Aggregation
+
+> More info about cardinality aggregation is in the [official elasticsearch docs][1]
+
+A single-value metrics aggregation that calculates an approximate count of distinct values.
+
+## Simple example
+
+```JSON
+{
+     "aggregations" : {
+         "agg_author_count" : {
+             "cardinality" : {
+                 "field" : "author"
+             }
+         }
+     }
+ }
+```
+
+And now the query via DSL:
+
+```php
+$cardinalityAggregation = new CardinalityAggregation('author_count', 'author');
+
+$search = new Search();
+$search->addAggregation($cardinalityAggregation);
+
+$queryArray = $search->toArray();
+```
+
+[1]: https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-metrics-cardinality-aggregation.html

docs/Aggregation/Children.md

+# Children Aggregation
+
+> More info about children aggregation is in the [official elasticsearch docs][1]
+
+A special single bucket aggregation that enables aggregating from buckets on parent
+document types to buckets on child documents.
+
+## Simple example
+
+```JSON
+{
+    "aggregations": {
+        "agg_author_count": {
+            "children": {
+                "type": "answer"
+            },
+            "aggregations": {
+                "agg_top_names": {
+                    "terms": {
+                        "field": "owner.display_name"
+                    }
+                }
+            }
+        }
+    }
+}
+```
+
+And now the query via DSL:
+
+```php
+$termsAggregation = new TermsAggregation('top_names', 'owner.display_name');
+
+$childrenAggregation = new ChildrenAggregation('author_count', 'answer');
+$childrenAggregation->addAggregation($termsAggregation);
+
+$search = new Search();
+$search->addAggregation($childrenAggregation);
+
+$queryArray = $search->toArray();
+```
+
+[1]: https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-children-aggregation.html

docs/Aggregation/DateRange.md

+# Date Range Aggregation
+
+> More info about date range aggregation is in the [official elasticsearch docs][1]
+
+A range aggregation that is dedicated for date values.
+
+## Simple example
+
+```JSON
+{
+    "aggregations": {
+        "agg_range": {
+            "date_range": {
+                "field": "date",
+                "format": "MM-yyy",
+                "ranges": [
+                    { "to": "now-10M/M" }, 
+                    { "from": "now-10M/M" } 
+                ]
+            }
+        }
+    }
+}
+```
+
+And now the query via DSL:
+
+```php
+$dateRangeAggregation = new DateRangeAggregation('range');
+$dateRangeAggregation->setField('date');
+$dateRangeAggregation->setFormat('MM-yyy');
+$dateRangeAggregation->addRange(null, 'now-10M/M');
+$dateRangeAggregation->addRange('now-10M/M', null);
+```
+
+Or : 
+
+```php
+$dateRangeAggregation = new DateRangeAggregation(
+    'range',
+    'date',
+    'MM-yyy',
+    [
+        ['to' => 'now-10M/M'],
+        ['from' => 'now-10M/M'],
+    ]
+);
+
+$search = new Search();
+$search->addAggregation($dateRangeAggregation);
+```
+
+[1]: https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-daterange-aggregation.html

docs/Aggregation/ExtendedStats.md

+# Extended Stats Aggregation
+
+> More info about extended stats aggregation is in the [official elasticsearch docs][1]
+
+A multi-value metrics aggregation that computes stats over numeric values extracted from the aggregated documents.
+
+## Simple example
+
+```JSON
+{
+    "aggregations" : {
+        "agg_grades_stats" : {
+            "extended_stats" : { "field" : "grade" }
+        }
+    }
+}
+```
+
+And now the query via DSL:
+
+```php
+$extendedStatsAggregation = new ExtendedStatsAggregation('grades_stats', 'grade');
+
+$search = new Search();
+$search->addAggregation($extendedStatsAggregation);
+
+$queryArray = $search->toArray();
+```
+
+[1]: https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-metrics-extendedstats-aggregation.html

docs/Aggregation/Filter.md

+# Filter Aggregation
+
+> More info about filter aggregation is in the [official elasticsearch docs][1]
+
+Defines a single bucket of all the documents in the current document set context that
+match a specified filter. Often this will be used to narrow down the current aggregation
+context to a specific set of documents.
+
+## Simple example
+
+```JSON
+{
+    "aggregations" : {
+        "agg_red_products" : {
+            "filter" : { "term": { "color": "red" } },
+            "aggs" : {
+                "agg_avg_price" : { "avg" : { "field" : "price" } }
+            }
+        }
+    }
+}
+```
+
+And now the query via DSL:
+
+```php
+$termFilter = new TermFilter('color', 'red');
+$avgAggregation = new AvgAggregation('avg_price', 'price');
+
+$filterAggregation = new FilterAggregation('grades_stats', $termFilter);
+$filterAggregation->addAggregation($avgAggregation);
+
+$search = new Search();
+$search->addAggregation($filterAggregation);
+
+$queryArray = $search->toArray();
+```
+
+[1]: https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-filter-aggregation.html

docs/Aggregation/Filters.md

+# Filters Aggregation
+
+> More info about filters aggregation is in the [official elasticsearch docs][1]
+
+Defines a multi bucket aggregations where each bucket is associated with a filter.
+Each bucket will collect all documents that match its associated filter.
+
+Filters can have names or be anonymous, this is controlled by setAnonymous method.
+By default filters are not anonymous and trying to add filter without name will result
+in exception.
+
+## Named example
+
+```JSON
+{
+  "aggregations" : {
+    "agg_messages" : {
+      "filters" : {
+        "filters" : {
+          "errors" :   { "term" : { "body" : "error"   }},
+          "warnings" : { "term" : { "body" : "warning" }}
+        }
+      },
+      "aggregations" : {
+        "agg_monthly" : {
+          "histogram" : {
+            "field" : "timestamp",
+            "interval" : "1M"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+And now the query via DSL:
+
+```php
+$errorTermFilter = new TermFilter('body', 'error');
+$warningTermFilter = new TermFilter('body', 'warning');
+
+$histogramAggregation = new HistogramAggregation('monthly', 'timestamp');
+$histogramAggregation->setInterval('1M');
+
+$filterAggregation = new FiltersAggregation(
+    'grades_stats',
+    [
+        'error' => $errorTermFilter,
+        'warning' => $warningTermFilter,
+    ]
+);
+$filterAggregation->addAggregation($histogramAggregation);
+
+$search = new Search();
+$search->addAggregation($filterAggregation);
+
+$queryArray = $search->toArray();
+```
+
+## Anonymous example
+
+```php
+$errorTermFilter = new TermFilter('body', 'error');
+$warningTermFilter = new TermFilter('body', 'warning');
+
+$histogramAggregation = new HistogramAggregation('monthly', 'timestamp');
+$histogramAggregation->setInterval('1M');
+
+$filterAggregation = new FiltersAggregation(
+    'grades_stats',
+    [
+        $errorTermFilter,
+        $warningTermFilter,
+    ],
+    true
+);
+$filterAggregation->addAggregation($histogramAggregation);
+
+$search = new Search();
+$search->addAggregation($filterAggregation);
+
+$queryArray = $search->toArray();
+```
+
+[1]: https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-filters-aggregation.html
\ No newline at end of file

docs/Aggregation/GeoBounds.md

+# Geo Bounds Aggregation
+
+> More info about geo bounds aggregation is in the [official elasticsearch docs][1]
+
+A metric aggregation that computes the bounding box containing all geo_point values for a field.
+
+## Simple example
+
+```JSON
+{
+    "aggregations" : {
+        "agg_viewport" : {
+            "geo_bounds" : {
+                "field" : "location",
+                "wrap_longitude" : true
+            }
+        }
+    }
+}
+```
+
+And now the query via DSL:
+
+```php
+$geoBoundsAggregation = new GeoBoundsAggregation('viewport', 'location');
+
+$search = new Search();
+$search->addAggregation($geoBoundsAggregation);
+
+$queryArray = $search->toArray();
+```
+
+[1]: https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-metrics-geobounds-aggregation.html

docs/Aggregation/GeoDistance.md

+# Geo Distance Aggregation
+
+> More info about geo distance aggregation is in the [official elasticsearch docs][1]
+
+A multi-bucket aggregation that works on geo_point fields
+and conceptually works very similar to the range aggregation.
+
+## Simple example
+
+```JSON
+{
+    "aggregations" : {
+        "rings_around_amsterdam" : {
+            "geo_distance" : {
+                "field" : "location",
+                "origin" : "52.3760, 4.894",
+                "ranges" : [
+                    { "to" : 100 },
+                    { "from" : 100, "to" : 300 },
+                    { "from" : 300 }
+                ]
+            }
+        }
+    }
+}
+```
+
+And now the query via DSL:
+
+```php
+$geoDistanceAggregation = new GeoDistanceAggregation(
+    'rings_around_amsterdam',
+    'location',
+    '52.3760, 4.894',
+    [
+        ['to' => 100],
+        ['from' => 100, 'to' => 300],
+        ['from' => 300],
+    ]
+);
+
+$search = new Search();
+$search->addAggregation($geoDistanceAggregation);
+
+$queryArray = $search->toArray();
+```
+
+[1]: https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-geodistance-aggregation.html

docs/Aggregation/GeoHashGrid.md

+# Geo Hash Grid Aggregation
+
+> More info about geo hash grid aggregation is in the [official elasticsearch docs][1]
+
+A multi-bucket aggregation that works on geo_point fields and groups points into buckets
+that represent cells in a grid.
+
+## Simple example
+
+```JSON
+{
+    "aggregations" : {
+        "agg_GrainGeoHashGrid" : {
+            "geohash_grid" : {
+                "field" : "location",
+                "precision" : 3
+            }
+        }
+    }
+}
+```
+
+And now the query via DSL:
+
+```php
+$geoHashGridAggregation = new GeoHashGridAggregation(
+    'GrainGeoHashGrid',
+    'location',
+    3
+);
+
+$search = new Search();
+$search->addAggregation($geoHashGridAggregation);
+
+$queryArray = $search->toArray();
+```
+
+[1]: https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-geohashgrid-aggregation.html

docs/Aggregation/Global.md

+# Global Aggregation
+
+> More info about cardinality aggregation is in the [official elasticsearch docs][1]
+
+Defines a single bucket of all the documents within the search execution
+context. This context is defined by the indices and the document types
+you’re searching on, but is **not influenced** by the search query itself.
+
+## Simple example
+
+```JSON
+{
+    "aggregations": {
+        "agg_all_products": {
+            "global": {},
+            "aggregations": {
+                "agg_avg_price": {
+                    "avg": {
+                        "field": "price"
+                    }
+                }
+            }
+        }
+    }
+}
+```
+
+And now the query via DSL:
+
+```php
+$avgAggregation = new AvgAggregation('avg_price', 'price');
+$globalAggregation = new GlobalAggregation('all_products');
+$globalAggregation->addAggregation($avgAggregation);
+
+$search = new Search();
+$search->addAggregation($globalAggregation);
+
+$queryArray = $search->toArray();
+```
+
+[1]: https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-global-aggregation.html

docs/Aggregation/Histogram.md

+# Histogram Aggregation
+
+> More info about histogram aggregation is in the [official elasticsearch docs][1]
+
+A multi-bucket values source based aggregation that can be applied on numeric values extracted from
+the documents. It dynamically builds fixed size (a.k.a. interval) buckets over the values.
+
+## Simple example
+
+```JSON
+{
+    "aggregations": {
+        "agg_prices": {
+            "histogram": {
+                "field": "price",
+                "interval": 50
+            }
+        }
+    }
+}
+```
+
+And now the query via DSL:
+
+```php
+$histogramAggregation = new HistogramAggregation('prices', 'price', 50);
+
+$search = new Search();
+$search->addAggregation($histogramAggregation);
+
+$queryArray = $search->toArray();
+```
+
+[1]: https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-histogram-aggregation.html

docs/Aggregation/Ipv4Range.md

+# Ipv4 Range Aggregation
+
+> More info about ipv4 range aggregation is in the [official elasticsearch docs][1]
+
+Just like the dedicated date range aggregation, there is also a dedicated
+range aggregation for IPv4 typed fields.
+
+## Simple example
+
+```JSON
+{
+    "aggregations" : {
+        "agg_ip_range" : {
+            "ip_range" : {
+                "field" : "ip",
+                "ranges" : [
+                    { "to" : "10.0.0.5" },
+                    { "from" : "10.0.0.5" }
+                ]
+            }
+        }
+    }
+}
+```
+
+And now the query via DSL:
+
+```php
+$ipv4RangeAggregation = new Ipv4RangeAggregation(
+    'ip_range',
+    'ip',
+    [
+        ['to' => '10.0.0.5'],
+        ['from' => '10.0.0.5'],
+    ]
+);
+
+$search = new Search();
+$search->addAggregation($ipv4RangeAggregation);
+
+$queryArray = $search->toArray();
+```
+
+## Example using masks
+
+```php
+$ipv4RangeAggregation = new Ipv4RangeAggregation(
+    'ip_range',
+    'ip',
+    ['10.0.0.0/25']
+);
+
+$search = new Search();
+$search->addAggregation($ipv4RangeAggregation);
+
+$queryArray = $search->toArray();
+```
+
+## Example using adders
+
+```php
+$ipv4RangeAggregation = new Ipv4RangeAggregation('ip_range', 'ip');
+$ipv4RangeAggregation->addMask('10.0.0.0/25');
+$ipv4RangeAggregation->addRange(null, '10.0.0.5');
+$ipv4RangeAggregation->addRange('10.0.0.5');
+$ipv4RangeAggregation->addRange('10.0.0.0', '10.0.0.127');
+
+$search = new Search();
+$search->addAggregation($ipv4RangeAggregation);
+
+$queryArray = $search->toArray();
+```
+
+[1]: https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-iprange-aggregation.html

docs/Aggregation/Max.md

+# Max Aggregation
+
+> More info about max aggregation is in the [official elasticsearch docs][1]
+
+A single-value metrics aggregation that keeps track and returns the
+maximum value among the numeric values extracted from the aggregated documents.
+
+## Simple example
+
+```JSON
+{
+    "aggregations" : {
+        "max_price" : { "max" : { "field" : "price" } }
+    }
+}
+```
+
+And now the query via DSL:
+
+```php
+$maxAggregation = new MaxAggregation('max_price', 'price');
+
+$search = new Search();
+$search->addAggregation($maxAggregation);
+
+$queryArray = $search->toArray();
+```
+
+[1]: https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-metrics-max-aggregation.html

docs/Aggregation/Min.md

+# Min Aggregation
+
+> More info about min aggregation is in the [official elasticsearch docs][1]
+
+A single-value metrics aggregation that keeps track and returns the minimum value among
+numeric values extracted from the aggregated documents.
+
+## Simple example
+
+```JSON
+{
+    "aggregations" : {
+        "min_price" : { "min" : { "field" : "price" } }
+    }
+}
+```
+
+And now the query via DSL:
+
+```php
+$minAggregation = new MinAggregation('min_price', 'price');
+
+$search = new Search();
+$search->addAggregation($minAggregation);
+
+$queryArray = $search->toArray();
+```
+
+[1]: https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-metrics-min-aggregation.html

docs/Aggregation/Missing.md

+# Missing Aggregation
+
+> More info about missing aggregation is in the [official elasticsearch docs][1]
+
+A field data based single bucket aggregation, that creates a bucket of all documents
+in the current document set context that are missing a field value.
+
+## Simple example
+
+```JSON
+{
+     "aggregations" : {
+         "agg_products_without_a_price" : {
+             "missing" : { "field" : "price" }
+         }
+     }
+ }
+```
+
+And now the query via DSL:
+
+```php
+$missingAggregation = new MissingAggregation('products_without_a_price', 'price');
+
+$search = new Search();
+$search->addAggregation($missingAggregation);
+
+$queryArray = $search->toArray();
+```
+
+[1]: https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-missing-aggregation.html

docs/Aggregation/Nested.md

+# Nested Aggregation
+
+> More info about nested aggregation is in the [official elasticsearch docs][1]
+
+A special single bucket aggregation that enables aggregating nested documents.
+
+## Simple example
+
+```JSON
+{
+    "aggregations" : {
+        "agg_resellers" : {
+            "nested" : {
+                "path" : "resellers"
+            },
+            "aggregations" : {
+                "agg_min_price" : { "min" : { "field" : "resellers.price" } }
+            }
+        }
+    }
+}
+```
+
+And now the query via DSL:
+
+```php
+$minAggregation = new MinAggregation('min_price', 'resellers.price');
+$nestedAggregation = new NestedAggregation('resellers', 'resellers');
+$nestedAggregation->addAggregation($minAggregation);
+
+$search = new Search();
+$search->addAggregation($nestedAggregation);
+
+$queryArray = $search->toArray();
+```
+
+[1]: https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-nested-aggregation.html

docs/Aggregation/PercentileRanks.md

+# Percentile Ranks Aggregation
+
+> More info about percentile ranks aggregation is in the [official elasticsearch docs][1]
+
+A multi-value metrics aggregation that calculates one or more percentile
+ranks over numeric values extracted from the aggregated documents.
+
+## Simple example
+
+```JSON
+{
+    "aggregations" : {
+        "agg_load_time_outlier" : {
+            "percentile_ranks" : {
+                "field" : "load_time",
+                "values" : [15, 30]
+            }
+        }
+    }
+}
+```
+
+And now the query via DSL:
+
+```php
+$percentileRanksAggregation = new PercentileRanksAggregation('load_time_outlier', 'load_time', [15, 30]);
+
+$search = new Search();
+$search->addAggregation($percentileRanksAggregation);
+
+$queryArray = $search->toArray();
+```
+
+[1]: https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-metrics-percentile-rank-aggregation.html

docs/Aggregation/Percentiles.md

+# Percentiles Aggregation
+
+> More info about percentiles aggregation is in the [official elasticsearch docs][1]
+
+A multi-value metrics aggregation that calculates one or more percentiles over
+numeric values extracted from the aggregated documents.
+
+## Simple example
+
+```JSON
+{
+    "aggregations" : {
+        "agg_load_time_outlier" : {
+            "percentiles" : {
+                "field" : "load_time"
+            }
+        }
+    }
+}
+```
+
+And now the query via DSL:
+
+```php
+$percentilesAggregation = new PercentilesAggregation('load_time_outlier', 'load_time');
+
+$search = new Search();
+$search->addAggregation($percentilesAggregation);
+
+$queryArray = $search->toArray();
+```
+
+[1]: https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-metrics-cardinality-aggregation.html

docs/Aggregation/Range.md

+# Range Aggregation
+
+> More info about range aggregation is in the [official elasticsearch docs][1]
+
+A multi-bucket value source based aggregation that enables the user to define a set of
+ranges - each representing a bucket.
+
+## Simple example
+
+```JSON
+{
+    "aggs" : {
+        "agg_price_ranges" : {
+            "range" : {
+                "field" : "price",
+                "ranges" : [
+                    { "to" : 50 },
+                    { "from" : 50, "to" : 100 },
+                    { "from" : 100 }
+                ]
+            }
+        }
+    }
+}
+```
+
+And now the query via DSL:
+
+```php
+$rangeAggregation = new RangeAggregation(
+    'price_ranges',
+    'price',
+    [
+        ['to' => 50],
+        ['from' => 50, 'to' => 100],
+        ['from' => 100],
+    ]
+);
+
+$search = new Search();
+$search->addAggregation($rangeAggregation);
+
+$queryArray = $search->toArray();
+```
+
+## Keyed example
+
+```php
+$rangeAggregation = new RangeAggregation(
+    'price_ranges',
+    'price',
+    [
+        ['key' => 'cheap', 'to' => 50],
+        ['from' => 50, 'to' => 100],
+        ['key' => 'expensive', 'from' => 100],
+    ],
+    true
+);
+
+$search = new Search();
+$search->addAggregation($rangeAggregation);
+
+$queryArray = $search->toArray();
+```
+
+## Adder example
+
+```php
+$rangeAggregation = new RangeAggregation('price_ranges', 'price');
+$rangeAggregation->setKeyed(true);
+$rangeAggregation->addRange(null, 50, 'cheap');
+$rangeAggregation->addRange(50, 100);
+$rangeAggregation->addRange(100, null, 'expensive');
+
+$search = new Search();
+$search->addAggregation($rangeAggregation);
+
+$queryArray = $search->toArray();
+```
+
+
+[1]: https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-range-aggregation.html