Class BinaryQuantIndexConfig

java.lang.Object
com.tangosol.io.AbstractEvolvable
com.oracle.coherence.rag.config.AbstractConfig<com.oracle.coherence.ai.index.BinaryQuantIndex<?,?,?>>
com.oracle.coherence.rag.config.index.IndexConfig<com.oracle.coherence.ai.index.BinaryQuantIndex<?,?,?>>
com.oracle.coherence.rag.config.index.BinaryQuantIndexConfig
All Implemented Interfaces:
Evolvable, PortableObject
public class BinaryQuantIndexConfig extends IndexConfig<com.oracle.coherence.ai.index.BinaryQuantIndex<?,?,?>>
Configuration class for BinaryQuantIndex vector indexing.

Binary quantization is a memory-efficient vector indexing technique that reduces vector storage requirements by compressing high-dimensional vectors into binary representations. This approach significantly reduces memory footprint and can improve search performance, especially for large-scale vector datasets.

Binary Quantization Benefits:

  • Memory Efficiency - Reduces memory usage by up to 32x compared to full-precision vectors
  • Fast Similarity Search - Binary operations (XOR, popcount) are extremely fast on modern CPUs
  • Cache Friendliness - Compressed vectors fit better in CPU cache, improving performance
  • Scalability - Enables indexing of larger datasets that wouldn't fit in memory otherwise

Trade-offs:

  • Accuracy - Some precision is lost due to quantization, though this is often acceptable
  • Oversampling - Higher oversampling factors can recover accuracy at the cost of performance

Configuration Example: 


 BinaryQuantIndexConfig config = new BinaryQuantIndexConfig()
     .setOversamplingFactor(5); // Higher accuracy, more computation

This configuration class supports POF serialization for persistence and distribution across Coherence cluster nodes, and provides fluent API for method chaining.

Since:
25.09
Author:
Aleks Seovic 2025.06.28
See Also:

  • Field Details

    • TYPE

      public static final String TYPE
      The type of the index this configuration is for.
      See Also:

    • IMPLEMENTATION_VERSION

      public static final int IMPLEMENTATION_VERSION
      The implementation version for this class.

      This version is used by Coherence POF for class evolution support. Increment this value when making incompatible changes to the class structure.

      See Also:

    • DEFAULT_OVERSAMPLING_FACTOR

      public static final int DEFAULT_OVERSAMPLING_FACTOR
      The default oversampling factor value.

      This default value of 3 provides a good balance between search accuracy and computational performance for most binary quantization use cases.

      See Also:

  • Constructor Details

    • BinaryQuantIndexConfig

      public BinaryQuantIndexConfig()
      Constructs a new BinaryQuantIndexConfig with default settings.

      Initializes the configuration with:

      • Index type: "BINARY"
      • Oversampling factor: 3 (balanced accuracy/performance)

      The default oversampling factor of 3 provides a good balance between search accuracy and computational performance for most use cases.

  • Method Details

    • type

      public String type()
      Returns the type of the index this configuration is for.
      Overrides:
      type in class IndexConfig<com.oracle.coherence.ai.index.BinaryQuantIndex<?,?,?>>
      Returns:
      the type of the index this configuration is for

    • getOversamplingFactor

      public int getOversamplingFactor()
      Returns the oversampling factor used during binary quantization search.

      The oversampling factor determines how many additional candidates are considered during the binary quantization process to improve search accuracy. This parameter directly affects the accuracy vs. performance trade-off.

      Returns:
      the oversampling factor, defaults to 3
      See Also:

    • setOversamplingFactor

      public BinaryQuantIndexConfig setOversamplingFactor(int nOversamplingFactor)
      Sets the oversampling factor used during binary quantization search.

      The oversampling factor determines how many additional candidates are considered during the binary quantization process to improve search accuracy. This parameter directly affects the accuracy vs. performance trade-off.

      Recommended Values:

      • Low Latency Applications: 1-2 (prioritize speed over accuracy)
      • General Purpose: 3-5 (balanced approach, recommended default)
      • High Accuracy Requirements: 6-10 (prioritize accuracy over speed)

      Performance Impact: Higher oversampling factors increase computational cost approximately linearly, as more candidates must be evaluated using full-precision similarity calculations.

      Parameters:
      nOversamplingFactor - the oversampling factor to set, must be positive
      Returns:
      this BinaryQuantIndexConfig instance for method chaining
      Throws:
      IllegalArgumentException - if nOversamplingFactor is less than 1
      See Also:

    • apply

      public com.oracle.coherence.ai.index.BinaryQuantIndex<?,?,?> apply(com.oracle.coherence.ai.index.BinaryQuantIndex<?,?,?> target)
      Description copied from class: AbstractConfig
      Applies all readable properties from this config instance to the given target object.

      This supports both JavaBean-style and fluent-style setter methods on the target.

      Overrides:
      apply in class AbstractConfig<com.oracle.coherence.ai.index.BinaryQuantIndex<?,?,?>>
      Parameters:
      target - the object to apply configuration values to (e.g., a POJO or Builder)

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class IndexConfig<com.oracle.coherence.ai.index.BinaryQuantIndex<?,?,?>>

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class IndexConfig<com.oracle.coherence.ai.index.BinaryQuantIndex<?,?,?>>

    • toString

      public String toString()
      Overrides:
      toString in class IndexConfig<com.oracle.coherence.ai.index.BinaryQuantIndex<?,?,?>>

    • getImplVersion

      public int getImplVersion()
      Description copied from class: AbstractEvolvable
      Determine the serialization version supported by the implementing class.
      Specified by:
      getImplVersion in interface Evolvable
      Overrides:
      getImplVersion in class IndexConfig<com.oracle.coherence.ai.index.BinaryQuantIndex<?,?,?>>
      Returns:
      the serialization version supported by this object

    • readExternal

      public void readExternal(PofReader in) throws IOException
      Description copied from interface: PortableObject
      Restore the contents of a user type instance by reading its state using the specified PofReader object.
      Specified by:
      readExternal in interface PortableObject
      Overrides:
      readExternal in class IndexConfig<com.oracle.coherence.ai.index.BinaryQuantIndex<?,?,?>>
      Parameters:
      in - the PofReader from which to read the object's state
      Throws:
      IOException - if an I/O error occurs

    • writeExternal

      public void writeExternal(PofWriter out) throws IOException
      Description copied from interface: PortableObject
      Save the contents of a POF user type instance by writing its state using the specified PofWriter object.
      Specified by:
      writeExternal in interface PortableObject
      Overrides:
      writeExternal in class IndexConfig<com.oracle.coherence.ai.index.BinaryQuantIndex<?,?,?>>
      Parameters:
      out - the PofWriter to which to write the object's state
      Throws:
      IOException - if an I/O error occurs