Package org.apache.druid.query.extraction

Interface ExtractionFn

All Superinterfaces:
Cacheable
All Known Implementing Classes:
BucketExtractionFn, CascadeExtractionFn, DimExtractionFn, FunctionalExtraction, IdentityExtractionFn, JavaScriptExtractionFn, LookupExtractionFn, LowerExtractionFn, MatchingDimExtractionFn, RegexDimExtractionFn, RegisteredLookupExtractionFn, SearchQuerySpecDimExtractionFn, StringFormatExtractionFn, StrlenExtractionFn, SubstringDimExtractionFn, TimeDimExtractionFn, TimeFormatExtractionFn, UpperExtractionFn
@SubclassesMustOverrideEqualsAndHashCode public interface ExtractionFn extends Cacheable
An ExtractionFn is a function that can be used to transform the values of a column (typically a dimension). Note that ExtractionFn implementations are expected to be Threadsafe. A simple example of the type of operation this enables is the RegexDimExtractionFn which applies a regular expression with a capture group. When the regular expression matches the value of a dimension, the value captured by the group is used for grouping operations instead of the dimension value.

  • Method Details

    • apply

      @Nullable String apply(@Nullable Object value)
      The "extraction" function. This should map an Object into some String value.

      In order to maintain the "null and empty string are equivalent" semantics that Druid provides, the empty string is considered invalid output for this method and should instead return null. This is a contract on the method rather than enforced at a lower level in order to eliminate a global check for extraction functions that do not already need one.

      Parameters:
      value - the original value of the dimension
      Returns:
      a value that should be used instead of the original

    • apply

      @Nullable String apply(@Nullable String value)
      The "extraction" function. This should map a String value into some other String value.

      Like apply(Object), the empty string is considered invalid output for this method and it should instead return null.

      Parameters:
      value - the original value of the dimension
      Returns:
      a value that should be used instead of the original

    • apply

      String apply(long value)
      The "extraction" function. This should map a long value into some String value.

      Like apply(Object), the empty string is considered invalid output for this method and it should instead return null.

      Parameters:
      value - the original value of the dimension
      Returns:
      a value that should be used instead of the original

    • preservesOrdering

      boolean preservesOrdering()
      Offers information on whether the extraction will preserve the original ordering of the values.

      Some optimizations of queries is possible if ordering is preserved. Null values *do* count towards ordering.

      Returns:
      true if ordering is preserved, false otherwise

    • getExtractionType

      ExtractionFn.ExtractionType getExtractionType()
      A dim extraction can be of one of two types, renaming or rebucketing. In the `ONE_TO_ONE` case, a unique values is modified into another unique value. In the `MANY_TO_ONE` case, there is no longer a 1:1 relation between old dimension value and new dimension value
      Returns:
      ExtractionFn.ExtractionType declaring what kind of manipulation this function does