Package com.apple.foundationdb.async.guardiann

Record Class SearchConfig

java.lang.Object
java.lang.Record
com.apple.foundationdb.async.guardiann.SearchConfig
Record Components:
candidatePoolFactor - how large the in-flight candidate pool should be relative to the requested k, expressed as a multiple (e.g. 1.15 keeps a pool 15% larger than k); the absolute pool size for a given search is candidatePoolSize(int). Being k-relative rather than absolute, it can be tuned once and reused across searches asking for different k. In the pruned Search.kNearestNeighborsSearch(com.apple.foundationdb.ReadTransaction, int, com.apple.foundationdb.async.guardiann.SearchConfig, boolean, com.apple.foundationdb.linear.RealVector) the pool is the size of the DistinctTopK candidate pool; in the streaming Search.searchOrderedByDistance(com.apple.foundationdb.ReadTransaction, int, com.apple.foundationdb.async.guardiann.SearchConfig, com.apple.foundationdb.linear.RealVector, double, double, com.apple.foundationdb.tuple.Tuple) it is the reorder-window size of the almost-sorted iterator. Larger values improve recall/ordering at the cost of latency. Must be >= 1.0 so the pool is never smaller than k. (This replaces the old, absolute candidatePoolSize — itself the rename of the misleadingly named efSearch, unrelated to HNSW's efSearch.)
searchMaxClusters - the maximum number of cluster centroids to probe around the query
searchMinClustersBeforePruning - the number of nearest clusters always retained before distance-ratio pruning is allowed to drop any (pruned search only; ignored by the streaming search)
searchDistanceRatioCutoff - clusters whose centroid distance exceeds this multiple of the nearest centroid's distance are pruned, once searchMinClustersBeforePruning clusters are retained (pruned search only; ignored by the streaming search)
centroidEfRingSearch - the ring-search exploration factor for the centroid HNSW walk that selects candidate clusters (passed through to HNSW.orderByDistance(com.apple.foundationdb.ReadTransaction, int, int, boolean, com.apple.foundationdb.linear.RealVector, double, com.apple.foundationdb.tuple.Tuple, boolean))
centroidEfOutwardSearch - the outward-search exploration factor (candidate-queue size) for that same centroid HNSW walk
searchConcurrency - the executor parallelism for the fan-out metadata/reference reads a search issues
public record SearchConfig(double candidatePoolFactor, int searchMaxClusters, int searchMinClustersBeforePruning, double searchDistanceRatioCutoff, int centroidEfRingSearch, int centroidEfOutwardSearch, int searchConcurrency) extends Record
The performance/recall tuning knobs for a single Guardiann search. These are the parameters that change how hard the search works — how many candidates it buffers, how many clusters it probes, how aggressively it prunes — without changing what a correct answer is. The semantic inputs (k, the query vector, includeVectors, and the streaming pagination cursor) stay direct arguments of the search methods; everything that only trades latency against recall lives here so it can travel as one value and grow without widening every signature.

There is deliberately no built-in "default" instance: good values depend on the dataset, its size, the index topology, and the recall target, so picking them is the caller's (or the test harness's) responsibility. The DEFAULT_* constants exist only as the SearchConfig.SearchConfigBuilder's per-field fallbacks, so a caller can set just the knobs it cares about and leave the rest at a reasonable starting point.

  • Field Details

    • DEFAULT_CANDIDATE_POOL_FACTOR

      public static final double DEFAULT_CANDIDATE_POOL_FACTOR
      See Also:

    • DEFAULT_SEARCH_MAX_CLUSTERS

      public static final int DEFAULT_SEARCH_MAX_CLUSTERS
      See Also:

    • DEFAULT_SEARCH_MIN_CLUSTERS_BEFORE_PRUNING

      public static final int DEFAULT_SEARCH_MIN_CLUSTERS_BEFORE_PRUNING
      See Also:

    • DEFAULT_SEARCH_DISTANCE_RATIO_CUTOFF

      public static final double DEFAULT_SEARCH_DISTANCE_RATIO_CUTOFF
      See Also:

    • DEFAULT_SEARCH_CONCURRENCY

      public static final int DEFAULT_SEARCH_CONCURRENCY
      See Also:

  • Constructor Details

    • SearchConfig

      public SearchConfig(double candidatePoolFactor, int searchMaxClusters, int searchMinClustersBeforePruning, double searchDistanceRatioCutoff, int centroidEfRingSearch, int centroidEfOutwardSearch, int searchConcurrency)
      Creates an instance of a SearchConfig record class.
      Parameters:
      candidatePoolFactor - the value for the candidatePoolFactor record component
      searchMaxClusters - the value for the searchMaxClusters record component
      searchMinClustersBeforePruning - the value for the searchMinClustersBeforePruning record component
      searchDistanceRatioCutoff - the value for the searchDistanceRatioCutoff record component
      centroidEfRingSearch - the value for the centroidEfRingSearch record component
      centroidEfOutwardSearch - the value for the centroidEfOutwardSearch record component
      searchConcurrency - the value for the searchConcurrency record component

  • Method Details

    • candidatePoolSize

      public int candidatePoolSize(int k)
      Resolves the absolute candidate-pool size for a search asking for k results by applying candidatePoolFactor(). The result is rounded up and clamped to at least k, so the pool is never smaller than the requested top-k even for a factor of exactly 1.0 or tiny k.
      Parameters:
      k - the number of results the search will ultimately return
      Returns:
      the number of candidates to keep in flight before trimming to k

    • toBuilder

      @Nonnull public SearchConfig.SearchConfigBuilder toBuilder()

    • toString

      @Nonnull public String toString()
      Returns a string representation of this record class. The representation contains the name of the class, followed by the name and value of each of the record components.
      Specified by:
      toString in class Record
      Returns:
      a string representation of this object

    • hashCode

      public final int hashCode()
      Returns a hash code value for this object. The value is derived from the hash code of each of the record components.
      Specified by:
      hashCode in class Record
      Returns:
      a hash code value for this object

    • equals

      public final boolean equals(Object o)
      Indicates whether some other object is "equal to" this one. The objects are equal if the other object is of the same class and if all the record components are equal. All components in this record class are compared with '=='.
      Specified by:
      equals in class Record
      Parameters:
      o - the object with which to compare
      Returns:
      true if this object is the same as the o argument; false otherwise.

    • candidatePoolFactor

      public double candidatePoolFactor()
      Returns the value of the candidatePoolFactor record component.
      Returns:
      the value of the candidatePoolFactor record component

    • searchMaxClusters

      public int searchMaxClusters()
      Returns the value of the searchMaxClusters record component.
      Returns:
      the value of the searchMaxClusters record component

    • searchMinClustersBeforePruning

      public int searchMinClustersBeforePruning()
      Returns the value of the searchMinClustersBeforePruning record component.
      Returns:
      the value of the searchMinClustersBeforePruning record component

    • searchDistanceRatioCutoff

      public double searchDistanceRatioCutoff()
      Returns the value of the searchDistanceRatioCutoff record component.
      Returns:
      the value of the searchDistanceRatioCutoff record component

    • centroidEfRingSearch

      public int centroidEfRingSearch()
      Returns the value of the centroidEfRingSearch record component.
      Returns:
      the value of the centroidEfRingSearch record component

    • centroidEfOutwardSearch

      public int centroidEfOutwardSearch()
      Returns the value of the centroidEfOutwardSearch record component.
      Returns:
      the value of the centroidEfOutwardSearch record component

    • searchConcurrency

      public int searchConcurrency()
      Returns the value of the searchConcurrency record component.
      Returns:
      the value of the searchConcurrency record component