You are currently browsing legacy 3.0 version of documentation. Click here to switch to the newest 4.2 version.

We can help you with migration to the latest RavenDB

Contact Us Now
see on GitHub

Commands: Querying: How to work with Facet query?

There are two methods that allow you to send a Facet query to a database:
- GetFacets
- GetMultiFacets

GetFacets

There are two overloads for the GetFacets method and the only difference between them is a source of the facets. In one facets are passed as a parameter, in the other user must provide a key to a facet setup document.

Syntax

FacetResults GetFacets(
	string index,
	IndexQuery query,
	List<Facet> facets,
	int start = 0,
	int? pageSize = null);

FacetResults GetFacets(
	string index,
	IndexQuery query,
	string facetSetupDoc,
	int start = 0,
	int? pageSize = null);

Parameters
index string A name of an index to query
query IndexQuery A query definition containing all information required to query a specified index.
facets List<Facet> List of facets required to perform a facet query (mutually exclusive with facetSetupDoc).
facetSetupDoc string Document key that contains predefined FacetSetup (mutually exclusive with facets).
start int number of results that should be skipped. Default: 0.
pageSize int maximum number of results that will be retrieved. Default: null.
Return Value
FacetResults Facet query results containing query Duration and a list of Results - one entry for each term/range as specified in [FacetSetup] document or passed in parameters.

Example I

// 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
FacetResults facetResults = store
	.DatabaseCommands
	.GetFacets(
		"Camera/Costs",
		new IndexQuery(),
		new List<Facet>
			{
				new Facet
				{
					Name = "Manufacturer"
				},
				new Facet
				{
					Name = "Cost_Range",
					Mode = FacetMode.Ranges,
					Ranges =
					{
						"[NULL TO Dx200.0]",
						"[Dx300.0 TO Dx400.0]",
						"[Dx500.0 TO Dx600.0]",
						"[Dx700.0 TO Dx800.0]",
						"[Dx900.0 TO NULL]"
					}
				},
				new Facet
				{
					Name = "Megapixels_Range",
					Mode = FacetMode.Ranges,
					Ranges =
					{
						"[NULL TO Dx3.0]",
						"[Dx4.0 TO Dx7.0]",
						"[Dx8.0 TO Dx10.0]",
						"[Dx11.0 TO NULL]"
					}
				}
			});

FacetResult manufacturerResults = facetResults.Results["Manufacturer"];
FacetResult costResults = facetResults.Results["Cost_Range"];
FacetResult megapixelResults = facetResults.Results["Megapixels_Range"];

Example II

// 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
store.DatabaseCommands.Put(
	"facets/CameraFacets",
	null,
	RavenJObject.FromObject(
		new FacetSetup
		{
			Id = "facets/CameraFacets",
			Facets =
				new List<Facet>
					{
						new Facet
						{
							Name = "Manufacturer"
						},
						new Facet
						{
							Name = "Cost_Range",
							Mode = FacetMode.Ranges,
							Ranges =
							{
								"[NULL TO Dx200.0]",
								"[Dx300.0 TO Dx400.0]",
								"[Dx500.0 TO Dx600.0]",
								"[Dx700.0 TO Dx800.0]",
								"[Dx900.0 TO NULL]"
							}
						},
						new Facet
						{
							Name = "Megapixels_Range",
							Mode = FacetMode.Ranges,
							Ranges =
							{
								"[NULL TO Dx3.0]", 
								"[Dx4.0 TO Dx7.0]", 
								"[Dx8.0 TO Dx10.0]", 
								"[Dx11.0 TO NULL]"
							}
						}
					}
		}),
	new RavenJObject());

FacetResults facetResults = store
	.DatabaseCommands
	.GetFacets("Camera/Costs", new IndexQuery(), "facets/CameraFacets");

FacetResult manufacturerResults = facetResults.Results["Manufacturer"];
FacetResult costResults = facetResults.Results["Cost_Range"];
FacetResult megapixelResults = facetResults.Results["Megapixels_Range"];

GetMultiFacets

Sending multiple facet queries is achievable by using GetMultiFacets method.

Syntax

FacetResults[] GetMultiFacets(FacetQuery[] facetedQueries);

Parameters
facetedQueries FacetQuery[] List of the faceted queries that will be executed on the server-side.
Return Value
FacetResult[] List of the results, each matching position of a FacetQuery in the facetedQueries parameter.

Example

FacetResults[] facetResults = store
	.DatabaseCommands
	.GetMultiFacets(
		new[]
		{
			new FacetQuery
			{
				IndexName = "Camera/Costs",
				FacetSetupDoc = "facets/CameraFacets1", 
				Query = new IndexQuery()
			},
			new FacetQuery
			{
				IndexName = "Camera/Costs",
				FacetSetupDoc = "facets/CameraFacets2", 
				Query = new IndexQuery()
			},
			new FacetQuery
			{
				IndexName = "Camera/Costs",
				FacetSetupDoc = "facets/CameraFacets3", 
				Query = new IndexQuery()
			}
		});

Dictionary<string, FacetResult> facetResults1 = facetResults[0].Results;
Dictionary<string, FacetResult> facetResults2 = facetResults[1].Results;
Dictionary<string, FacetResult> facetResults3 = facetResults[2].Results;