Class FacetRequest
- java.lang.Object
-
- org.apache.lucene.facet.search.params.FacetRequest
-
- All Implemented Interfaces:
Cloneable
- Direct Known Subclasses:
AssociationFloatSumFacetRequest
,AssociationIntSumFacetRequest
,CountFacetRequest
,ScoreFacetRequest
public abstract class FacetRequest extends Object implements Cloneable
Request to accumulate facet information for a specified facet and possibly also some of its descendants, upto a specified depth.The facet request additionally defines what information should be computed within the facet results, if and how should results be ordered, etc.
An example facet request is to look at all sub-categories of "Author", and return the 10 with the highest counts (sorted by decreasing count).
- WARNING: This API is experimental and might change in incompatible ways in the next release.
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
FacetRequest.ResultMode
Result structure manner of applying request's limits such asgetNumLabel()
andgetNumResults()
.static class
FacetRequest.SortBy
Sort options for facet results.static class
FacetRequest.SortOrder
Requested sort order for the results.
-
Field Summary
Fields Modifier and Type Field Description static int
DEFAULT_DEPTH
Default depth for facets accumulation.static FacetRequest.ResultMode
DEFAULT_RESULT_MODE
Default result modestatic FacetRequest.SortBy
DEFAULT_SORT_BY
Default sort mode.
-
Constructor Summary
Constructors Constructor Description FacetRequest(CategoryPath path, int numResults)
Initialize the request with a given path, and a requested number of facets results.
-
Method Summary
All Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method Description Object
clone()
abstract Aggregator
createAggregator(boolean useComplements, FacetArrays arrays, org.apache.lucene.index.IndexReader indexReader, TaxonomyReader taxonomy)
Create an aggregator for this facet request.CategoryListIterator
createCategoryListIterator(org.apache.lucene.index.IndexReader reader, TaxonomyReader taxo, FacetSearchParams sParams, int partition)
Create the category list iterator for the specified partition.FacetResultsHandler
createFacetResultsHandler(TaxonomyReader taxonomyReader)
Creates a newFacetResultsHandler
that matches the request logic and current settings, such asdepth
,limits-mode
, etc, as well as the passed inTaxonomyReader
.boolean
equals(Object o)
CategoryPath
getCategoryPath()
The root category of this facet request.int
getDepth()
How deeply to look under the given category.int
getNumLabel()
If getNumLabel()int
getNumResults()
The number of sub-categories to return (at most).FacetRequest.ResultMode
getResultMode()
Return the requested result mode.FacetRequest.SortBy
getSortBy()
Specify how should results be sorted.FacetRequest.SortOrder
getSortOrder()
Return the requested order of results.abstract double
getValueOf(FacetArrays arrays, int idx)
Return the value of a category used for facets computations for this request.int
hashCode()
abstract boolean
requireDocumentScore()
Indicates whether the results of this request depends on each result document's scorevoid
setDepth(int depth)
void
setNumLabel(int numLabel)
void
setResultMode(FacetRequest.ResultMode resultMode)
void
setSortBy(FacetRequest.SortBy sortBy)
void
setSortOrder(FacetRequest.SortOrder sortOrder)
boolean
supportsComplements()
Indicates whether this facet request is eligible for applying the complements optimization.String
toString()
-
-
-
Field Detail
-
DEFAULT_DEPTH
public static final int DEFAULT_DEPTH
Default depth for facets accumulation.- See Also:
getDepth()
, Constant Field Values
-
DEFAULT_SORT_BY
public static final FacetRequest.SortBy DEFAULT_SORT_BY
Default sort mode.- See Also:
getSortBy()
-
DEFAULT_RESULT_MODE
public static final FacetRequest.ResultMode DEFAULT_RESULT_MODE
Default result mode- See Also:
getResultMode()
-
-
Constructor Detail
-
FacetRequest
public FacetRequest(CategoryPath path, int numResults)
Initialize the request with a given path, and a requested number of facets results. By default, all returned results would be labeled - to alter this default seesetNumLabel(int)
.NOTE: if
numResults
is given asInteger.MAX_VALUE
than all the facet results would be returned, without any limit.NOTE: it is assumed that the given
CategoryPath
is not modified after construction of this object. Otherwise, some things may not function properly, e.g.hashCode()
.- Throws:
IllegalArgumentException
- if numResults is ≤ 0
-
-
Method Detail
-
clone
public Object clone() throws CloneNotSupportedException
- Overrides:
clone
in classObject
- Throws:
CloneNotSupportedException
-
setNumLabel
public void setNumLabel(int numLabel)
-
setDepth
public void setDepth(int depth)
-
setSortOrder
public void setSortOrder(FacetRequest.SortOrder sortOrder)
-
setSortBy
public void setSortBy(FacetRequest.SortBy sortBy)
-
getCategoryPath
public final CategoryPath getCategoryPath()
The root category of this facet request. The categories that are returned as a result of this request will all be descendants of this root.NOTE: you should not modify the returned
CategoryPath
, or otherwise some methonds may not work properly, e.g.hashCode()
.
-
getDepth
public final int getDepth()
How deeply to look under the given category. If the depth is 0, only the category itself is counted. If the depth is 1, its immediate children are also counted, and so on. If the depth is Integer.MAX_VALUE, all the category's descendants are counted.
TODO (Facet): add AUTO_EXPAND option
-
getNumLabel
public final int getNumLabel()
If getNumLabel()If Integer.MAX_VALUE is specified, all results are labled. The purpose of this parameter is to avoid having to run the whole faceted search again when the user asks for more values for the facet; The application can ask (getNumResults()) for more values than it needs to show, but keep getNumLabel() only the number it wants to immediately show. The slow-down caused by finding more values is negligible, because the slowest part - finding the categories' paths, is avoided.
Depending on the
LimitsMode
, this limit is applied globally or per results node. In the global mode, if this limit is 3, only 3 top results would be labeled. In the per-node mode, if this limit is 3, 3 top children ofthe target category
would be labeled, as well as 3 top children of each of them, and so forth, until the depth defined bygetDepth()
.- See Also:
getResultMode()
-
getNumResults
public final int getNumResults()
The number of sub-categories to return (at most). If the sub-categories are returned.If Integer.MAX_VALUE is specified, all sub-categories are returned.
Depending on the
LimitsMode
, this limit is applied globally or per results node. In the global mode, if this limit is 3, only 3 top results would be computed. In the per-node mode, if this limit is 3, 3 top children ofthe target category
would be returned, as well as 3 top children of each of them, and so forth, until the depth defined bygetDepth()
.- See Also:
getResultMode()
-
getSortBy
public final FacetRequest.SortBy getSortBy()
Specify how should results be sorted.
-
getSortOrder
public final FacetRequest.SortOrder getSortOrder()
Return the requested order of results.
-
createFacetResultsHandler
public FacetResultsHandler createFacetResultsHandler(TaxonomyReader taxonomyReader)
Creates a newFacetResultsHandler
that matches the request logic and current settings, such asdepth
,limits-mode
, etc, as well as the passed inTaxonomyReader
.- Parameters:
taxonomyReader
- taxonomy reader is needed e.g. for knowing the taxonomy size.
-
getResultMode
public final FacetRequest.ResultMode getResultMode()
Return the requested result mode.
-
setResultMode
public void setResultMode(FacetRequest.ResultMode resultMode)
- Parameters:
resultMode
- the resultMode to set- See Also:
getResultMode()
-
createAggregator
public abstract Aggregator createAggregator(boolean useComplements, FacetArrays arrays, org.apache.lucene.index.IndexReader indexReader, TaxonomyReader taxonomy) throws IOException
Create an aggregator for this facet request. Aggregator action depends on request definition. For a count request, it will usually increment the count for that facet.- Parameters:
useComplements
- whether the complements optimization is being used for current computation.arrays
- provider for facet arrays in use for current computation.indexReader
- index reader in effect.taxonomy
- reader of taxonomy in effect.- Throws:
IOException
-
createCategoryListIterator
public CategoryListIterator createCategoryListIterator(org.apache.lucene.index.IndexReader reader, TaxonomyReader taxo, FacetSearchParams sParams, int partition) throws IOException
Create the category list iterator for the specified partition. If a non null cache is provided which contains the required data, use it for the iteration.- Throws:
IOException
-
getValueOf
public abstract double getValueOf(FacetArrays arrays, int idx)
Return the value of a category used for facets computations for this request. For a count request this would be the count for that facet, i.e. an integer number. but for other requests this can be the result of a more complex operation, and the result can be any double precision number. Having this method with a general name value which is double precision allows to have more compact API and code for handling counts and perhaps other requests (such as for associations) very similarly, and by the same code and API, avoiding code duplication.- Parameters:
arrays
- provider for facet arrays in use for current computation.idx
- an index into the count arrays now in effect inarrays
. E.g., for ordinal number n, with partition, of size partitionSize, now covering n,getValueOf
would be invoked withidx
being n % partitionSize.
-
supportsComplements
public boolean supportsComplements()
Indicates whether this facet request is eligible for applying the complements optimization.
-
requireDocumentScore
public abstract boolean requireDocumentScore()
Indicates whether the results of this request depends on each result document's score
-
-