Module org.elasticsearch.server
Package org.elasticsearch.index.codec.tsdb.pipeline.numeric.stages

Class GcdCodecStage

java.lang.Object
org.elasticsearch.index.codec.tsdb.pipeline.numeric.stages.GcdCodecStage
All Implemented Interfaces:
NumericCodecStage, TransformDecoder, TransformEncoder
public final class GcdCodecStage extends Object implements NumericCodecStage
GCD factoring transform stage.

Effectiveness

Applied when all values share a common divisor greater than 1. Divides all values by the GCD, reducing their magnitude and therefore the number of bits required for bit-packing. Skipped when the GCD is 0 or 1 (unsigned comparison).

Example

Values [100, 200, 300, 400] with GCD=100 produces [1, 2, 3, 4].

Metadata layout

Written to the stage metadata section (see BlockFormat): 

   +---------------------+
   | VLong(gcd - 2)      |  1-9 bytes, unsigned variable-length
   +---------------------+

The GCD is always >= 2 when the stage applies, so subtracting 2 before encoding as unsigned VLong saves one byte for small divisors (e.g., GCD=2 stores as 0, which is a single byte).

Power-of-two optimization

When the GCD is a power of two, division and multiplication are replaced by arithmetic shifts. The JIT cannot optimize division by a runtime variable (it always emits idiv, ~20-90 cycles), while shifts are single-cycle and SIMD-friendly.

  • Field Details

    • INSTANCE

      public static final GcdCodecStage INSTANCE
      Singleton instance.

  • Method Details

    • id

      public byte id()
      Description copied from interface: TransformEncoder
      Returns the unique stage identifier.
      Specified by:
      id in interface TransformDecoder
      Specified by:
      id in interface TransformEncoder
      Returns:
      the stage ID byte

    • encode

      public void encode(long[] values, int valueCount, EncodingContext context)
      Description copied from interface: TransformEncoder
      Transforms values in-place and writes any metadata to the context.

      If the stage determines that the transformation would not be effective, it may return without modifying the values or writing metadata. The pipeline checks EncodingContext.isStageApplied(int) to detect this.

      Specified by:
      encode in interface TransformEncoder
      Parameters:
      values - the values to transform in-place
      valueCount - the number of valid values in the array
      context - the encoding context for metadata and stage tracking

    • decode

      public void decode(long[] values, int valueCount, DecodingContext context) throws IOException
      Description copied from interface: TransformDecoder
      Reverses the transformation on values in-place using metadata from the context.
      Specified by:
      decode in interface TransformDecoder
      Parameters:
      values - the values to reverse-transform in-place
      valueCount - the number of valid values in the array
      context - the decoding context for reading stage metadata
      Throws:
      IOException - if an I/O error occurs while reading metadata

    • encodeStatic

      public static void encodeStatic(GcdCodecStage stage, long[] values, int valueCount, EncodingContext context) throws IOException
      Throws:
      IOException

    • decodeStatic

      public static void decodeStatic(GcdCodecStage stage, long[] values, int valueCount, DecodingContext context) throws IOException
      Throws:
      IOException