Package org.apache.lucene.facet

## Class FacetsConfig

- java.lang.Object
- - org.apache.lucene.facet.FacetsConfig

-     public class FacetsConfig
      extends Object

  Records per-dimension configuration. By default a dimension is flat, single valued and does not require count for the dimension; use the setters in this class to change these settings for each dim.

  NOTE: this configuration is not saved into the index, but it's vital, and up to the application to ensure, that at search time the provided `FacetsConfig` matches what was used during indexing.

  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` | `FacetsConfig.DimConfig` | Holds the configuration for one dimension
    `static class` | `FacetsConfig.DrillDownTermsIndexing` | Drill down terms indexing option to control whether dimension and sub-path terms should be indexed.

  - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static FacetsConfig.DimConfig` | `DEFAULT_DIM_CONFIG` | Default per-dimension configuration.
    `static String` | `DEFAULT_INDEX_FIELD_NAME` | Which Lucene field holds the drill-downs and ords (as doc values).
    `static char` | `DELIM_CHAR` | Character used to join the category path components together into a single drill down term for indexing.

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `FacetsConfig()` | Default constructor.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `Document` | `build​(Document doc)` | Translates any added `FacetField`s into normal fields for indexing; only use this version if you did not add any taxonomy-based fields ( `FacetField` or `AssociationFacetField`).
    `Document` | `build​(TaxonomyWriter taxoWriter, Document doc)` | Translates any added `FacetField`s into normal fields for indexing.
    `protected BytesRef` | `dedupAndEncode​(IntsRef ordinals)` | Deprecated. Starting in Lucene 9, we moved to a more straight-forward numeric doc values encoding and no longer support custom binary encodings.
    `protected FacetsConfig.DimConfig` | `getDefaultDimConfig()` | Get the default configuration for new dimensions.
    `FacetsConfig.DimConfig` | `getDimConfig​(String dimName)` | Get the current configuration for a dimension.
    `Map<String,​FacetsConfig.DimConfig>` | `getDimConfigs()` | Returns map of field name to `FacetsConfig.DimConfig`.
    `boolean` | `isDimConfigured​(String dimName)` | Returns true if the dimension for provided name has ever been manually configured.
    `static String` | `pathToString​(String[] path)` | Turns a dim + path into an encoded string.
    `static String` | `pathToString​(String[] path, int length)` | Turns the first `length` elements of `path` into an encoded string.
    `static String` | `pathToString​(String dim, String... path)` | Turns a dim + path into an encoded string.
    `void` | `setDrillDownTermsIndexing​(String dimName, FacetsConfig.DrillDownTermsIndexing drillDownTermsIndexing)` | Specify drill down terms option on the field / dimension.
    `void` | `setHierarchical​(String dimName, boolean v)` | Pass `true` if this dimension is hierarchical (has depth > 1 paths).
    `void` | `setIndexFieldName​(String dimName, String indexFieldName)` | Specify which index field name should hold the ordinals for this dimension; this is only used by the taxonomy based facet methods.
    `void` | `setMultiValued​(String dimName, boolean value)` | Pass `true` if this dimension may have more than one value per document.
    `void` | `setRequireDimCount​(String dimName, boolean value)` | Pass `true` if at search time you require accurate counts of the dimension, i.e.
    `static String[]` | `stringToPath​(String s)` | Turns an encoded string (from a previous call to `pathToString(java.lang.String, java.lang.String...)`) back into the original `String[]`.

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

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### DEFAULT_INDEX_FIELD_NAME

          public static final String DEFAULT_INDEX_FIELD_NAME

      Which Lucene field holds the drill-downs and ords (as doc values).
      See Also:
        Constant Field Values

    - #### DEFAULT_DIM_CONFIG

          public static final FacetsConfig.DimConfig DEFAULT_DIM_CONFIG

      Default per-dimension configuration.

    - #### DELIM_CHAR

          public static final char DELIM_CHAR

      Character used to join the category path components together into a single drill down term for indexing. Applications and unit-tests can reference this for creating their own drill-down terms, or use existing APIs (for example, `pathToString(java.lang.String, java.lang.String...)`).
      See Also:
        Constant Field Values
      NOTE: This API is for internal purposes only and might change in incompatible ways in the next release.

  - ### Constructor Detail

    - #### FacetsConfig

          public FacetsConfig()

      Default constructor.

  - ### Method Detail

    - #### getDefaultDimConfig

          protected FacetsConfig.DimConfig getDefaultDimConfig()

      Get the default configuration for new dimensions. Useful when the dimension is not known beforehand and may need different global default settings, like `multivalue = true`.
      Returns:
        The default configuration to be used for dimensions that are not yet set in the `FacetsConfig`

    - #### getDimConfig

          public FacetsConfig.DimConfig getDimConfig​(String dimName)

      Get the current configuration for a dimension.

    - #### isDimConfigured

          public boolean isDimConfigured​(String dimName)

      Returns true if the dimension for provided name has ever been manually configured. The opposite means that dimension is still valid and `DEFAULT_DIM_CONFIG` is being used for it.

    - #### setHierarchical

          public void setHierarchical​(String dimName,
                                      boolean v)

      Pass `true` if this dimension is hierarchical (has depth > 1 paths).

    - #### setMultiValued

          public void setMultiValued​(String dimName,
                                     boolean value)

      Pass `true` if this dimension may have more than one value per document.

    - #### setRequireDimCount

          public void setRequireDimCount​(String dimName,
                                         boolean value)

      Pass `true` if at search time you require accurate counts of the dimension, i.e. how many hits have this dimension.

    - #### setIndexFieldName

          public void setIndexFieldName​(String dimName,
                                        String indexFieldName)

      Specify which index field name should hold the ordinals for this dimension; this is only used by the taxonomy based facet methods.

    - #### setDrillDownTermsIndexing

          public void setDrillDownTermsIndexing​(String dimName,
                                                FacetsConfig.DrillDownTermsIndexing drillDownTermsIndexing)

      Specify drill down terms option on the field / dimension.

    - #### getDimConfigs

          public Map<String,​FacetsConfig.DimConfig> getDimConfigs()

      Returns map of field name to `FacetsConfig.DimConfig`.

    - #### build

          public Document build​(Document doc)
                         throws IOException

      Translates any added `FacetField`s into normal fields for indexing; only use this version if you did not add any taxonomy-based fields ( `FacetField` or `AssociationFacetField`).

      NOTE: you should add the returned document to IndexWriter, not the input one!

      Throws:
        `IOException`

    - #### build

          public Document build​(TaxonomyWriter taxoWriter,
                                Document doc)
                         throws IOException

      Translates any added `FacetField`s into normal fields for indexing.

      NOTE: you should add the returned document to IndexWriter, not the input one!

      Throws:
        `IOException`

    - #### dedupAndEncode

          @Deprecated
          protected BytesRef dedupAndEncode​(IntsRef ordinals)

      Deprecated.
      Starting in Lucene 9, we moved to a more straight-forward numeric doc values encoding and no longer support custom binary encodings.
      Encodes ordinals into a BytesRef; expert: subclass can override this to change encoding.

    - #### pathToString

          public static String pathToString​(String dim,
                                            String... path)

      Turns a dim + path into an encoded string.

    - #### pathToString

          public static String pathToString​(String[] path)

      Turns a dim + path into an encoded string.

    - #### pathToString

          public static String pathToString​(String[] path,
                                            int length)

      Turns the first `length` elements of `path` into an encoded string.

    - #### stringToPath

          public static String[] stringToPath​(String s)

      Turns an encoded string (from a previous call to `pathToString(java.lang.String, java.lang.String...)`) back into the original `String[]`.