Start of docs for aggregations

Andrew Kane
1 parent 1b48f029
Showing 1 changed file with 34 additions and 21 deletions Show diff stats
README.md
@@ -547,54 +547,67 @@ products = Product.search &quot;peantu butta&quot;, suggest: true
 products.suggestions # ["peanut butter"]
 ```
  
-### Facets
+### Aggregations / Facets
  
-[Facets](http://www.elasticsearch.org/guide/reference/api/search/facets/) provide aggregated search data.
+[Aggregations](http://www.elasticsearch.org/guide/reference/api/search/facets/) provide aggregated search data.
  
-![Facets](http://ankane.github.io/searchkick/facets.png)
+![Aggregations](http://ankane.github.io/searchkick/facets.png)
  
 ```ruby
-products = Product.search "chuck taylor", facets: [:product_type, :gender, :brand]
-p products.facets
+products = Product.search "chuck taylor", aggs: [:product_type, :gender, :brand]
+p products.aggs
 ```
  
-By default, `where` conditions are not applied to facets (for backward compatibility).
+By default, `where` conditions are not applied to aggregations (for backward compatibility).
  
 ```ruby
-Product.search "wingtips", where: {color: "brandy"}, facets: [:size]
-# facets *not* filtered by color :(
+Product.search "wingtips", where: {color: "brandy"}, aggs: [:size]
+# aggs *not* filtered by color :(
 ```
  
 Change this with:
  
 ```ruby
-Product.search "wingtips", where: {color: "brandy"}, facets: [:size], smart_facets: true
+Product.search "wingtips", where: {color: "brandy"}, aggs: [:size], smart_aggs: true
 ```
  
-or set `where` conditions for each facet separately:
+or set `where` conditions for each aggregation separately:
  
 ```ruby
-Product.search "wingtips", facets: {size: {where: {color: "brandy"}}}
+Product.search "wingtips", aggs: {size: {where: {color: "brandy"}}}
 ```
  
 Limit
  
 ```ruby
-Product.search "apples", facets: {store_id: {limit: 10}}
+Product.search "apples", aggs: {store_id: {limit: 10}}
 ```
  
-Ranges
+#### Moving From Facets
  
-```ruby
-price_ranges = [{to: 20}, {from: 20, to: 50}, {from: 50}]
-Product.search "*", facets: {price: {ranges: price_ranges}}
-```
+1. Replace `facets` with `aggs` in searches. **Note:** Range and stats facets are not supported at this time.
  
-Use the `stats` option to get to max, min, mean, and total scores for each facet
+  ```ruby
+  products = Product.search "chuck taylor", aggs: [:brand]
+  ```
  
-```ruby
-Product.search "*", facets: {store_id: {stats: true}}
-```
+2. Replace the `facets` method with `aggs` to get the results.
+
+  ```ruby
+  products.aggs
+  ```
+
+  The format of results slightly differs. Instead of:
+
+  ```json
+
+  ```
+
+  You get:
+
+  ```json
+
+  ```
  
 ### Highlight
...	...	@@ -547,54 +547,67 @@ products = Product.search "peantu butta", suggest: true
547	547	products.suggestions # ["peanut butter"]
548	548	```
549	549
550		-### Facets
	550	+### Aggregations / Facets
551	551
552		-[Facets](http://www.elasticsearch.org/guide/reference/api/search/facets/) provide aggregated search data.
	552	+[Aggregations](http://www.elasticsearch.org/guide/reference/api/search/facets/) provide aggregated search data.
553	553
554		-![Facets](http://ankane.github.io/searchkick/facets.png)
	554	+![Aggregations](http://ankane.github.io/searchkick/facets.png)
555	555
556	556	```ruby
557		-products = Product.search "chuck taylor", facets: [:product_type, :gender, :brand]
558		-p products.facets
	557	+products = Product.search "chuck taylor", aggs: [:product_type, :gender, :brand]
	558	+p products.aggs
559	559	```
560	560
561		-By default, `where` conditions are not applied to facets (for backward compatibility).
	561	+By default, `where` conditions are not applied to aggregations (for backward compatibility).
562	562
563	563	```ruby
564		-Product.search "wingtips", where: {color: "brandy"}, facets: [:size]
565		-# facets not filtered by color :(
	564	+Product.search "wingtips", where: {color: "brandy"}, aggs: [:size]
	565	+# aggs not filtered by color :(
566	566	```
567	567
568	568	Change this with:
569	569
570	570	```ruby
571		-Product.search "wingtips", where: {color: "brandy"}, facets: [:size], smart_facets: true
	571	+Product.search "wingtips", where: {color: "brandy"}, aggs: [:size], smart_aggs: true
572	572	```
573	573
574		-or set `where` conditions for each facet separately:
	574	+or set `where` conditions for each aggregation separately:
575	575
576	576	```ruby
577		-Product.search "wingtips", facets: {size: {where: {color: "brandy"}}}
	577	+Product.search "wingtips", aggs: {size: {where: {color: "brandy"}}}
578	578	```
579	579
580	580	Limit
581	581
582	582	```ruby
583		-Product.search "apples", facets: {store_id: {limit: 10}}
	583	+Product.search "apples", aggs: {store_id: {limit: 10}}
584	584	```
585	585
586		-Ranges
	586	+#### Moving From Facets
587	587
588		-```ruby
589		-price_ranges = [{to: 20}, {from: 20, to: 50}, {from: 50}]
590		-Product.search "*", facets: {price: {ranges: price_ranges}}
591		-```
	588	+1. Replace `facets` with `aggs` in searches. Note: Range and stats facets are not supported at this time.
592	589
593		-Use the `stats` option to get to max, min, mean, and total scores for each facet
	590	+ ```ruby
	591	+ products = Product.search "chuck taylor", aggs: [:brand]
	592	+ ```
594	593
595		-```ruby
596		-Product.search "*", facets: {store_id: {stats: true}}
597		-```
	594	+2. Replace the `facets` method with `aggs` to get the results.
	595	+
	596	+ ```ruby
	597	+ products.aggs
	598	+ ```
	599	+
	600	+ The format of results slightly differs. Instead of:
	601	+
	602	+ ```json
	603	+
	604	+ ```
	605	+
	606	+ You get:
	607	+
	608	+ ```json
	609	+
	610	+ ```
598	611
599	612	### Highlight
600	613
...	...