RDoc-2497 Indexes > Querying > Faceted search - Part 4

Documentation/5.2/Raven.Documentation.Pages/client-api/session/querying/how-to-perform-a-faceted-search.dotnet.markdown

@@ -8,7 +8,7 @@
 
 * To make a faceted search,  
   a static-index must be defined for the fields you want to query and apply facets on.  
-  Please refer to article __Query by Facets__ under: [Indexes > Querying > Faceted search](../../../indexes/querying/faceted-search).
+  Please refer to article __Query by Facets__ under [Indexes > Querying > Faceted search](../../../indexes/querying/faceted-search).
 
 {NOTE/}
 

Documentation/5.2/Raven.Documentation.Pages/client-api/session/querying/how-to-perform-a-faceted-search.java.markdown

@@ -0,0 +1,98 @@
+# Session: Querying: How to Perform a Faceted (Aggregated) Search
+
+To execute facet (aggregation) query using the session `query` method, use the `aggregateBy` or `aggregateUsing` methods. This will scope you to the aggregation query builder where you will be allowed to define single or multiple facets for the query using a straightforward and fluent API.
+
+## Syntax
+
+{CODE:java facet_1@ClientApi\Session\Querying\HowToPerformFacetedSearch.java /}
+
+| Parameters | | |
+| ------------- | ------------- | ----- |
+| **facet** | FacetBase | `FacetBase` implementation defining the scope of the facet and its options (either `Facet` or `RangeFacet`) |
+| **facets** | `FacetBase...` | Items containing `FacetBase` implementations |
+| **builder** | `Consumer<IFacetBuilder<T>>` | Builder with a fluent API that constructs a `FacetBase` instance |
+| **facetSetupDocumentId** | String | ID of a document containing `FacetSetup` | 
+
+### Facet & RangeFacet
+
+{INFO:Facet vs RangeFacet}
+`RangeFacet` allows you to split the results of the calculations into several ranges, in contrast to `Facet` where whole spectrum of results will be used to generate a single outcome.
+{INFO/}
+
+{CODE-TABS}
+{CODE-TAB:java:Facet facet_7_3@ClientApi\Session\Querying\HowToPerformFacetedSearch.java /}
+{CODE-TAB:java:RangeFacet facet_7_4@ClientApi\Session\Querying\HowToPerformFacetedSearch.java /}
+{CODE-TAB:java:FacetAggregation facet_7_5@ClientApi\Session\Querying\HowToPerformFacetedSearch.java /}
+{CODE-TABS/}
+
+### Builder
+
+{CODE:java facet_7_1@ClientApi\Session\Querying\HowToPerformFacetedSearch.java /}
+
+| Parameters | | |
+| ------------- | ------------- | ----- |
+| **path** | String | Points to the index field that should be used for operation (`byRanges`, `byField`) or to document field that should be used for aggregation (`sumOn`, `minOn`, `maxOn`, `averageOn`) |
+| **fieldName** | String | Points to the index field that should be used for operation (`byRanges`, `byField`) or to document field that should be used for aggregation (`sumOn`, `minOn`, `maxOn`, `averageOn`) |
+| **displayName** | String | If set, results of a facet will be returned under this name |
+| **options** | `FacetOptions` | Non-default options that should be used for operation |
+
+### Options
+
+{CODE:java facet_7_2@ClientApi\Session\Querying\HowToPerformFacetedSearch.java /}
+
+| Options | | |
+| ------------- | ------------- | ----- |
+| **termSortMode** | `FacetTermSortMode` | Indicates how terms should be sorted (`VALUE_ASC`, `VALUE_DESC`, `COUNT_ASC`, `COUNT_DESC`) |
+| **includeRemainingTerms** | booelean | Indicates if remaining terms should be included in results |
+| **start** | int | Used to skip given number of facet results in the outcome |
+| **pageSize** | int | Used to limit facet results to the given value |
+
+## Example I
+
+{CODE-TABS}
+{CODE-TAB:java:Java facet_2_1@ClientApi\Session\Querying\HowToPerformFacetedSearch.java /}
+{CODE-TAB-BLOCK:sql:RQL}
+from index 'Camera/Costs' 
+select 
+facet(manufacturer), 
+facet(cost < 200, cost >= 200 AND cost < 400, cost >= 400 AND cost < 600, cost >= 600 AND cost < 800, cost >= 800),
+facet(megapixels < 3, megapixels >= 3 AND megapixels < 7, megapixels >= 7 AND megapixels < 10, megapixels >= 10)
+{CODE-TAB-BLOCK/}
+{CODE-TABS/}
+
+## Example II
+
+{CODE-TABS}
+{CODE-TAB:java:Java facet_3_1@ClientApi\Session\Querying\HowToPerformFacetedSearch.java /}
+{CODE-TAB-BLOCK:sql:RQL}
+from index 'Camera/Costs' 
+select 
+facet(manufacturer), 
+facet(cost < 200, cost >= 200 AND cost < 400, cost >= 400 AND cost < 600, cost >= 600 AND cost < 800, cost >= 800),
+facet(megapixels < 3, megapixels >= 3 AND megapixels < 7, megapixels >= 7 AND megapixels < 10, megapixels >= 10)
+{CODE-TAB-BLOCK/}
+{CODE-TABS/}
+
+## Example III
+
+{CODE-TABS}
+{CODE-TAB:java:Java facet_4_1@ClientApi\Session\Querying\HowToPerformFacetedSearch.java /}
+{CODE-TAB-BLOCK:sql:RQL}
+from index 'Camera/Costs' 
+select facet(id('facets/CameraFacets'))
+{CODE-TAB-BLOCK/}
+{CODE-TABS/}
+
+## Remarks
+
+{WARNING `aggregateBy` only supports aggregation by a single field. If you want to aggregate by multiple fields, you need to emit a single field that contains all values. /}
+
+## Related Articles
+
+### Session
+
+- [How to Query](../../../client-api/session/querying/how-to-query)
+
+### Indexes
+
+- [Faceted Search](../../../indexes/querying/faceted-search) 

Documentation/5.2/Raven.Documentation.Pages/client-api/session/querying/how-to-perform-a-faceted-search.js.markdown

@@ -0,0 +1,25 @@
+# Perform a Faceted (Aggregated) Search
+
+---
+
+{NOTE: }
+
+* A __Faceted Search__ provides an efficient way to explore and navigate through large datasets or search results.  
+
+* To make a faceted search,  
+  a static-index must be defined for the fields you want to query and apply facets on.  
+  Please refer to article __Query by Facets__ under [Indexes > Querying > Faceted search](../../../indexes/querying/faceted-search).
+
+{NOTE/}
+
+---
+
+## Related Articles
+
+### Session
+
+- [How to Query](../../../client-api/session/querying/how-to-query)
+
+### Indexes
+
+- [Faceted Search](../../../indexes/querying/faceted-search) 

Documentation/5.2/Raven.Documentation.Pages/indexes/querying/faceted-search.java.markdown

@@ -0,0 +1,161 @@
+# Querying: Faceted (Aggregation) Search
+
+When displaying a large amount of data, paging is often used to make viewing the data manageable. It's also useful to give some context of the entire data-set and a easy way to drill-down into particular categories. The common approach to doing this is a "faceted search", as shown in the image below. __Note__ how the count of each category within the current search is across the top.
+
+![Facets](images\CNET_faceted_search.jpg)
+
+<br />
+Let's start with defining a document like this:
+
+{CODE:java camera@Indexes\Querying\Faceted.java /}
+
+## Step 1
+
+Create an index to work against. 
+
+{CODE:java step_2@Indexes\Querying\FacetedSearch.java /}
+
+## Step 2
+
+Setup your facet definitions:
+
+{CODE:java step_1@Indexes\Querying\FacetedSearch.java /}
+
+This tells RavenDB that you would like to get the following facets:
+
+* For the **manufacturer** field, look at the documents and return a count for each unique Term found.
+
+* For the **cost** field, return the count of the following ranges:
+
+ * cost < 200.0
+ * 200.0 <= cost < 400.0
+ * 400.0 <= cost < 600.0
+ * 600.0 <= cost < 800.0
+ * cost >= 800.0
+* For the **megapixels** field, return the count of the following ranges:
+ * megapixels <= 3.0
+ * 3.0 <= megapixels < 7.0
+ * 7.0 <= megapixels < 10.0
+ * megapixels >= 10.0
+
+## Step 3
+
+You can write the following code to get back the data below:
+
+{CODE-TABS}
+{CODE-TAB:java:Query step_3_0@Indexes\Querying\FacetedSearch.java /}
+{CODE-TAB:java:Facets step_1@Indexes\Querying\FacetedSearch.java /}
+{CODE-TAB-BLOCK:sql:RQL}
+from index 'Cameras/ByManufacturerModelCostDateOfListingAndMegapixels' 
+where cost between 100 and 300
+select facet(manufacturer), facet(cost <= 200, cost between 200 and 400, cost between 400 and 600, cost between 600 and 800, cost >= 800), facet(megapixels <= 3, megapixels between 3 and 7, megapixels between 7 and 10, megapixels >= 10)
+{CODE-TAB-BLOCK/}
+{CODE-TABS/}
+
+This data represents the sample faceted data that satisfies the above query:
+
+{CODE-BLOCK:json}
+[
+    {
+        "Name": "manufacturer",
+        "Values": [
+            {
+                "Count": 1,
+                "Range": "canon"
+            },
+            {
+                "Count": 2,
+                "Range": "jessops"
+            },
+            {
+                "Count": 1,
+                "Range": "nikon"
+            },
+            {
+                "Count": 1,
+                "Range": "phillips"
+            },
+            {
+                "Count": 3,
+                "Range": "sony"
+            }
+        ]
+    },
+    {
+        "Name": "cost",
+        "Values": [
+            {
+                "Count": 6,
+                "Range": "cost <= 200"
+            },
+            {
+                "Count": 2,
+                "Range": "cost between 200 and 400"
+            },
+            {
+                "Count": 0,
+                "Range": "cost between 400 and 600"
+            },
+            {
+                "Count": 0,
+                "Range": "cost between 600 and 800"
+            },
+            {
+                "Count": 0,
+                "Range": "cost >= 800"
+            }
+        ]
+    },
+    {
+        "Name": "megapixels",
+        "Values": [
+            {
+                "Count": 0,
+                "Range": "megapixels <= 3"
+            },
+            {
+                "Count": 6,
+                "Range": "megapixels between 3 and 7"
+            },
+            {
+                "Count": 1,
+                "Range": "megapixels between 7 and 10"
+            },
+            {
+                "Count": 1,
+                "Range": "megapixels >= 10"
+            }
+        ]
+    }
+]
+{CODE-BLOCK/}
+
+### Storing Facets
+
+If you do not have to change your facets dynamically, you can store your facets as a `FacetSetup` document and pass the document ID instead of the list each time:
+
+{CODE:java step_4_0@Indexes\Querying\FacetedSearch.java /}
+
+{CODE-TABS}
+{CODE-TAB:java:Query step_4_1@Indexes\Querying\FacetedSearch.java /}
+{CODE-TAB:java:Facets step_1@Indexes\Querying\FacetedSearch.java /}
+{CODE-TAB-BLOCK:sql:RQL}
+from index 'Cameras/ByManufacturerModelCostDateOfListingAndMegapixels' 
+where cost between 100 and 300
+select facet(id('facets/CameraFacets'))
+{CODE-TAB-BLOCK/}
+{CODE-TABS/}
+
+### Stale Results
+
+The faceted search does not take into account a staleness of an index. You can wait for non stale results by customizing your query with the `waitForNonStaleResults` method.
+
+### Fluent API
+
+As an alternative for creating a list of facets and passing it to the `aggregateBy` method, RavenDB also exposes a dynamic API where you can create your facets using a builder. You can read more about those methods in our dedicated Client API article [here](../../client-api/session/querying/how-to-perform-a-faceted-search).
+
+## Related Articles
+
+### Client API
+
+- [How to Perform a Faceted Search](../../client-api/session/querying/how-to-perform-a-faceted-search)