Package org.hibernate.search.engine.search.aggregation.dsl

Interface SearchAggregationFactory

All Known Subinterfaces:
ExtendedSearchAggregationFactory<SR,S,PDF>, TypedSearchAggregationFactory<SR>
All Known Implementing Classes:
AbstractSearchAggregationFactory
public interface SearchAggregationFactory
A factory for search aggregations.

Field paths

By default, field paths passed to this DSL are interpreted as absolute, i.e. relative to the index root.

However, a new, "relative" factory can be created with withRoot(String): the new factory interprets paths as relative to the object field passed as argument to the method.

This can be useful when calling reusable methods that can apply the same aggregation on different object fields that have same structure (same sub-fields).

Such a factory can also transform relative paths into absolute paths using toAbsolutePath(String); this can be useful for native aggregations in particular.

Field references

A field reference is always represented by the absolute field path and, if applicable, i.e. when a field reference is typed, a combination of the ValueModel and the type.

Field references are usually accessed from the generated Hibernate Search's static metamodel classes that describe the index structure. Such reference provides the information on which search capabilities the particular index field possesses, and allows switching between different value model representations.

Author:
Emmanuel Bernard emmanuel@hibernate.org

  • Method Details

    • range

      RangeAggregationFieldStep<?,?> range()
      Perform aggregation in range buckets.

      Given a field and one or more ranges of values, this aggregation creates one bucket per range, and puts in each bucket every document for which the given field has a value that falls into the corresponding range.

      For each bucket, the document count is computed, or more complex metrics or sub-aggregations for backends that support it.

      Returns:
      The next step.

    • terms

      TermsAggregationFieldStep<?,?> terms()
      Perform aggregation in term buckets.

      Given a field, this aggregation creates one bucket per term of that field in the index, and puts in each bucket every document for which the given field matches the corresponding term.

      For each bucket, the document count is computed, or more complex metrics or sub-aggregations for backends that support it.

      Returns:
      The next step.

    • sum

      @Incubating SumAggregationFieldStep<?,?> sum()
      Perform the sum metric aggregation.

      Sums up the field values.

      Returns:
      The next step.

    • min

      @Incubating MinAggregationFieldStep<?,?> min()
      Perform the min metric aggregation.

      Provides the minimum value among the field values.

      Returns:
      The next step.

    • max

      @Incubating MaxAggregationFieldStep<?,?> max()
      Perform the max metric aggregation.

      Provides the maximum value among the field values.

      Returns:
      The next step.

    • count

      @Incubating CountAggregationKindStep<?,?> count()
      Perform the count metric aggregation.

      The following steps allow defining the kind of the count aggregation: count documents or count values.

      Returns:
      The next step.

    • countDistinct

      @Deprecated(since="8.1", forRemoval=true) @Incubating CountDistinctValuesAggregationFieldStep<?,?> countDistinct()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use count() with CountValuesAggregationOptionsStep.distinct() instead.
      Perform the count distinct values metric aggregation.

      Counts the number of unique field values.

      Returns:
      The next step.

    • avg

      @Incubating AvgAggregationFieldStep<?,?> avg()
      Perform the count distinct values metric aggregation.

      Counts the number of unique field values.

      Returns:
      the next step.

    • composite

      @Incubating CompositeAggregationInnerStep composite()
      Starts the definition of a composite aggregation, which will combine multiple given aggregations.
      Returns:
      A DSL step where the "composite" aggregation can be defined in more details.

    • composite

      @Incubating AggregationFinalStep<List<?>> composite(SearchAggregation<?>... aggregations)
      Create an aggregation that will compose a List based on the given aggregations.
      Parameters:
      aggregations - The aggregations used to populate the list, in order.
      Returns:
      The "composite" aggregation.

    • composite

      @Incubating default AggregationFinalStep<List<?>> composite(AggregationFinalStep<?>... dslFinalSteps)
      Create an aggregation that will compose a List based on the given almost-built aggregations.
      Parameters:
      dslFinalSteps - The final steps in the aggregation DSL allowing the retrieval of SearchAggregations.
      Returns:
      The "composite" aggregation.

    • withParameters

      @Incubating <T> AggregationFinalStep<T> withParameters(Function<? super NamedValues,? extends AggregationFinalStep<T>> aggregationCreator)
      Delegating aggregation that creates the actual aggregation at query create time and provides access to query parameters.

      Which aggregation exactly to create is defined by a function passed to the arguments of this aggregation.

      Parameters:
      aggregationCreator - The function creating an actual aggregation.
      Returns:
      A final DSL step in a parameterized aggregation definition.

    • extension

      <T> T extension(SearchAggregationFactoryExtension<T> extension)
      Extend the current factory with the given extension, resulting in an extended factory offering different types of aggregations.
      Type Parameters:
      T - The type of factory provided by the extension.
      Parameters:
      extension - The extension to the aggregation DSL.
      Returns:
      The extended factory.
      Throws:
      org.hibernate.search.util.common.SearchException - If the extension cannot be applied (wrong underlying backend, ...).

    • withRoot

      @Incubating SearchAggregationFactory withRoot(String objectFieldPath)
      Create a new aggregation factory whose root for all paths passed to the DSL will be the given object field.

      See here for more information.

      Parameters:
      objectFieldPath - The path from the current root to an object field that will become the new root.
      Returns:
      A new aggregation factory using the given object field as root.

    • toAbsolutePath

      @Incubating String toAbsolutePath(String relativeFieldPath)
      Parameters:
      relativeFieldPath - The path to a field, relative to the root of this factory.
      Returns:
      The absolute path of the field, for use in native aggregations for example. Note the path is returned even if the field doesn't exist.