Package org.elasticsearch.search.aggregations.support

Interface ValuesSourceType

All Known Implementing Classes:
CoreValuesSourceType
public interface ValuesSourceType
ValuesSourceType represents a collection of fields that share a common set of operations, for example all numeric fields. Aggregations declare their support for a given ValuesSourceType (via ValuesSourceRegistry.Builder.register(org.elasticsearch.search.aggregations.support.ValuesSourceRegistry.RegistryKey<T>, org.elasticsearch.search.aggregations.support.ValuesSourceType, T, boolean)), and should then not need to care about the fields which use that ValuesSourceType. ValuesSourceTypes provide a set of methods to instantiate concrete ValuesSource instances, based on the actual source of the data for the aggregations. In general, aggregations should not call these methods, but rather rely on ValuesSourceConfig to have selected the correct implementation. ValuesSourceTypes should be stateless. We recommend that plugins define an enum for their ValuesSourceTypes, even if the plugin only intends to define one ValuesSourceType. ValuesSourceTypes are not serialized as part of the aggregations framework. Prefer reusing an existing ValuesSourceType (ideally from CoreValuesSourceType) over creating a new type. There are some cases where creating a new type is necessary however. In particular, consider a new ValuesSourceType if the field has custom encoding/decoding requirements; if the field needs to expose additional information to the aggregation (e.g. ValuesSource.Range.rangeType()); or if logically the type needs a more restricted use (e.g. even though dates are stored as numbers, it doesn't make sense to pass them to a sum aggregation). When adding a new ValuesSourceType, new aggregators should be added and registered at the same time, to add support for the new type to existing aggregations, as appropriate.

  • Method Details

    • getEmpty

      ValuesSource getEmpty()
      Called when an aggregation is operating over a known empty set (usually because the field isn't specified), this method allows for returning a no-op implementation. All ValuesSources should implement this method.
      Returns:
      - Empty specialization of the base ValuesSource

    • getScript

      ValuesSource getScript(AggregationScript.LeafFactory script, ValueType scriptValueType)
      Returns the type-specific sub class for a script data source. ValuesSources that do not support scripts should throw AggregationExecutionException. Note that this method is called when a script is operating without an underlying field. Scripts operating over fields are handled by the script argument to getField below.
      Parameters:
      script - - The script being wrapped
      scriptValueType - - The expected output type of the script
      Returns:
      - Script specialization of the base ValuesSource

    • getField

      ValuesSource getField(FieldContext fieldContext, AggregationScript.LeafFactory script, AggregationContext context)
      Return a ValuesSource wrapping a field for the given type. All ValuesSources must implement this method.
      Parameters:
      fieldContext - - The field being wrapped
      script - - Optional script that might be applied over the field
      context - context for the aggregation fetching the field
      Returns:
      - Field specialization of the base ValuesSource

    • replaceMissing

      ValuesSource replaceMissing(ValuesSource valuesSource, Object rawMissing, DocValueFormat docValueFormat, AggregationContext context)
      Apply the given missing value to an already-constructed ValuesSource. Types which do not support missing values should throw AggregationExecutionException
      Parameters:
      valuesSource - - The original ValuesSource
      rawMissing - - The missing value we got from the parser, typically a string or number
      docValueFormat - - The format to use for further parsing the user supplied value, e.g. a date format
      context - - Context for this aggregation used to handle "now"
      Returns:
      - Wrapper over the provided ValuesSource to apply the given missing value

    • getFormatter

      default DocValueFormat getFormatter(String format, ZoneId tz)
      This method provides a hook for specifying a type-specific formatter. When ValuesSourceConfig can resolve a MappedFieldType, it prefers to get the formatter from there. Only when a field can't be resolved (which is to say script cases and unmapped field cases), it will fall back to calling this method on whatever ValuesSourceType it was able to resolve to.
      Parameters:
      format - - User supplied format string (Optional)
      tz - - User supplied time zone (Optional)
      Returns:
      - A formatter object, configured with the passed in settings if appropriate.

    • typeName

      String typeName()
      Returns the name of the Values Source Type for stats purposes
      Returns:
      the name of the Values Source Type