ankane/searchkick · error · Searchkick::Error

Not sure how to load records

Error message

Not sure how to load records

What it means

method_parameters.ef_search on OpenSearch kNN queries exists only from OpenSearch 2.16 onwards. Before building the query Searchkick checks the live server version (Searchkick.server_below?('2.16.0')) and raises Error 'ef_search requires OpenSearch 2.16+' when the option is used against an older cluster. The check is skipped on Elasticsearch, which takes a different branch.

Source

Thrown at lib/searchkick.rb:296

  end

  def self.warn(message)
    super("[searchkick] WARNING: #{message}")
  end

  # private
  def self.load_records(relation, ids)
    relation =
      if relation.respond_to?(:primary_key)
        primary_key = relation.primary_key
        raise Error, "Need primary key to load records" if !primary_key

        relation.where(primary_key => ids)
      elsif relation.respond_to?(:queryable)
        relation.queryable.for_ids(ids)
      end

    raise Error, "Not sure how to load records" if !relation

    relation
  end

  # public (for reindexing conversions)
  def self.load_model(class_name, allow_child: false)
    model = class_name.safe_constantize
    raise Error, "Could not find class: #{class_name}" unless model
    if allow_child
      unless model.respond_to?(:searchkick_klass)
        raise Error, "#{class_name} is not a searchkick model"
      end
    else
      unless Searchkick.models.include?(model)
        raise Error, "#{class_name} is not a searchkick model"
      end
    end
    model

View on GitHub (pinned to 93e901a75b)

Solutions

1. Remove ef_search from the query so the server default applies
2. Upgrade the OpenSearch cluster/engine to 2.16+ and keep the tuning
3. Set it conditionally: opts[:ef_search] = 500 unless Searchkick.server_below?('2.16.0')

Example fix

# before
Product.search('*', knn: {field: :v, vector: vec, distance: 'cosine', ef_search: 500})
# => Searchkick::Error: ef_search requires OpenSearch 2.16+

# after
knn = {field: :v, vector: vec, distance: 'cosine'}
knn[:ef_search] = 500 unless Searchkick.server_below?('2.16.0')
Product.search('*', knn: knn)

knn = {field: :v, vector: vec, distance: 'cosine'}
knn[:ef_search] = 500 unless Searchkick.server_below?('2.16.0')
Product.search('*', knn: knn)

When it happens

Trigger: Product.search('*', knn: {field: :embedding, vector: vec, distance: 'cosine', ef_search: 200}) while Searchkick.client points at OpenSearch < 2.16 (e.g. 2.11, 1.x, or an AWS OpenSearch engine older than 2.16).

Common situations: Tuning recall on a local dev instance with a recent OpenSearch image, then deploying to an older managed cluster (AWS OpenSearch <= 2.13 engines); docker-compose pinning an old opensearch image; upgrading Searchkick versions that added the ef_search option.

Related errors

• Need primary key to load records
• Must specify a distance for OpenSearch
• Unknown distance: #{distance}
• Quantization not supported yet for OpenSearch
• The `elasticsearch` gem must be 8+

AI-assisted analysis of ankane/searchkick@93e901a75b (2026-08-21). Data as JSON: /api/errors/f418396e1b6988c5. Report an issue: GitHub.