org.apache.lucene.facet.search

## Class FacetRequest

- java.lang.Object
- - org.apache.lucene.facet.search.FacetRequest

- Direct Known Subclasses:
    AssociationFloatSumFacetRequest, AssociationIntSumFacetRequest, CountFacetRequest, SumScoreFacetRequest

      public abstract class FacetRequest
      extends Object

  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 and Description
    --- | ---
    `static class` | `FacetRequest.FacetArraysSource` Specifies which array of `FacetArrays` should be used to resolve values.
    `static class` | `FacetRequest.ResultMode` Result structure manner of applying request's limits such as `getNumLabel()` and `numResults`.
    `static class` | `FacetRequest.SortOrder` Requested sort order for the results.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `CategoryPath` | `categoryPath`
    `static int` | `DEFAULT_DEPTH` Default depth for facets accumulation.
    `static FacetRequest.ResultMode` | `DEFAULT_RESULT_MODE` Default result mode
    `int` | `numResults`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `FacetRequest(CategoryPath path, int numResults)` Initialize the request with a given path, and a requested number of facets results.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `Aggregator` | `createAggregator(boolean useComplements, FacetArrays arrays, TaxonomyReader taxonomy)` Create an aggregator for this facet request.
    `boolean` | `equals(Object o)`
    `int` | `getDepth()` How deeply to look under the given category.
    `abstract FacetRequest.FacetArraysSource` | `getFacetArraysSource()` Returns the `FacetRequest.FacetArraysSource` this `FacetRequest` uses in `getValueOf(FacetArrays, int)`.
    `int` | `getNumLabel()` If getNumLabel() < getNumResults(), only the first getNumLabel() results will have their category paths calculated, and the rest will only be available as ordinals (category numbers) and will have null paths.
    `FacetRequest.ResultMode` | `getResultMode()` Return the requested result mode.
    `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()`
    `void` | `setDepth(int depth)`
    `void` | `setNumLabel(int numLabel)`
    `void` | `setResultMode(FacetRequest.ResultMode resultMode)`
    `void` | `setSortOrder(FacetRequest.SortOrder sortOrder)`
    `String` | `toString()`

    - ### Methods inherited from class java.lang.Object

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### DEFAULT_DEPTH

          public static final int DEFAULT_DEPTH

      Default depth for facets accumulation.
      See Also:
        `getDepth()`, Constant Field Values

    - #### DEFAULT_RESULT_MODE

          public static final FacetRequest.ResultMode DEFAULT_RESULT_MODE

      Default result mode
      See Also:
        `getResultMode()`

    - #### categoryPath

          public final CategoryPath categoryPath

    - #### numResults

          public final int numResults

  - ### 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 see `setNumLabel(int)`.

      NOTE: if `numResults` is given as `Integer.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

    - #### createAggregator

          public Aggregator createAggregator(boolean useComplements,
                                    FacetArrays arrays,
                                    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.
        `taxonomy` - reader of taxonomy in effect.
      Throws:
        `IOException` - If there is a low-level I/O error.

    - #### equals

          public boolean equals(Object o)

      Overrides:
        `equals` in class `Object`

    - #### 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.

    - #### getFacetArraysSource

          public abstract FacetRequest.FacetArraysSource getFacetArraysSource()

      Returns the `FacetRequest.FacetArraysSource` this `FacetRequest` uses in `getValueOf(FacetArrays, int)`.

    - #### getNumLabel

          public final int getNumLabel()

      If getNumLabel() < getNumResults(), only the first getNumLabel() results will have their category paths calculated, and the rest will only be available as ordinals (category numbers) and will have null paths.

      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 of `the target category` would be labeled, as well as 3 top children of each of them, and so forth, until the depth defined by `getDepth()`.

      See Also:
        `getResultMode()`

    - #### getResultMode

          public final FacetRequest.ResultMode getResultMode()

      Return the requested result mode.

    - #### getSortOrder

          public final FacetRequest.SortOrder getSortOrder()

      Return the requested order of results.

    - #### 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 in `arrays`. E.g., for ordinal number n, with partition, of size partitionSize, now covering n, `getValueOf` would be invoked with `idx` being n % partitionSize.

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `Object`

    - #### setDepth

          public void setDepth(int depth)

    - #### setNumLabel

          public void setNumLabel(int numLabel)

    - #### setResultMode

          public void setResultMode(FacetRequest.ResultMode resultMode)

      Parameters:
        `resultMode` - the resultMode to set
      See Also:
        `getResultMode()`

    - #### setSortOrder

          public void setSortOrder(FacetRequest.SortOrder sortOrder)

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`

Copyright © 2000-2013 Apache Software Foundation. All Rights Reserved.