Module: Mongoid::SearchIndexable::ClassMethods

Defined in:
lib/mongoid/search_indexable.rb

Overview

Implementations for the feature's class-level methods.

Instance Method Summary collapse

Instance Method Details

#auto_embed_search(text, index: nil, path: nil, limit: 10, num_candidates: nil, filter: nil, exact: false, model: nil, pipeline: []) ⇒ Array<Mongoid::Document>

Performs an Atlas Vector Search query using auto-embedding. Atlas generates the query vector from the supplied text at query time; no pre-computed embedding is required.

Each returned document has a vector_search_score attribute populated with its relevance score. Unlike vector_search, the indexed text field is retained in returned documents.

Examples:

Search by text.

Article.auto_embed_search('machine learning', limit: 5)

Exact nearest-neighbor search (no numCandidates).

Article.auto_embed_search('deep learning', exact: true, limit: 5)

Parameters:

  • text (String) —

    The query text.

  • index (String | Symbol | nil) (defaults to: nil) —

    The name of the auto-embed index to use (optional when only one is declared on the model).

  • path (String | Symbol | nil) (defaults to: nil) —

    The indexed text field path (optional if unambiguous from the index definition).

  • limit (Integer) (defaults to: 10) —

    Maximum number of results (default: 10).

  • num_candidates (Integer | nil) (defaults to: nil) —

    Candidates for ANN search; defaults to limit * 10. Ignored when exact: true.

  • filter (Hash | nil) (defaults to: nil) —

    Optional MongoDB filter for pre-filtering.

  • exact (true | false) (defaults to: false) —

    Use exact nearest-neighbor (ENN) search instead of ANN (default: false). When true, numCandidates is omitted.

  • model (String | nil) (defaults to: nil) —

    Query-time embedding model override.

  • pipeline (Array) (defaults to: []) —

    Additional aggregation stages appended after the vector search and score projection.

Returns:

  • (Array<Mongoid::Document>) —

    matching documents, each with a populated vector_search_score attribute.



352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
 
# File 'lib/mongoid/search_indexable.rb', line 352

def auto_embed_search(text, index: nil, path: nil, limit: 10, num_candidates: nil, filter: nil, exact: false, model: nil, pipeline: []) # rubocop:disable Metrics/ParameterLists
  resolved_index, resolved_path = resolve_auto_embed_index(index, path)

  vs_options = {
    'index' => resolved_index,
    'path' => resolved_path,
    'query' => { 'text' => text },
    'limit' => limit
  }
  vs_options['numCandidates'] = num_candidates || (limit * 10) unless exact
  vs_options['exact'] = true if exact
  vs_options['filter'] = filter if filter
  vs_options['model'] = model if model

  agg_pipeline = [
    { '$vectorSearch' => vs_options },
    { '$addFields'    => { 'vector_search_score' => { '$meta' => 'vectorSearchScore' } } }
  ]
  agg_pipeline.concat(Array(pipeline))

  collection.aggregate(agg_pipeline).map { |doc| instantiate(doc) }
end

#create_search_indexes ⇒ Array<String>

Request the creation of all registered search indices. Note that the search indexes are created asynchronously, and may take several minutes to be fully available.

Returns:

  • (Array<String>) —

    The names of the search indexes.



155
156
157
158
159
 
# File 'lib/mongoid/search_indexable.rb', line 155

def create_search_indexes
  return if search_index_specs.empty?

  collection.search_indexes.create_many(search_index_specs)
end

#remove_search_index(name: nil, id: nil) ⇒ Object

Removes the search index specified by the given name or id. Either name OR id must be given, but not both.

Parameters:

  • name (String | nil) (defaults to: nil) —

    the name of the index to remove

  • id (String | nil) (defaults to: nil) —

    the id of the index to remove



197
198
199
200
201
202
203
204
 
# File 'lib/mongoid/search_indexable.rb', line 197

def remove_search_index(name: nil, id: nil)
  logger.info(
    "MONGOID: Removing search index '#{name || id}' " \
    "on collection '#{collection.name}'."
  )

  collection.search_indexes.drop_one(name: name, id: id)
end

#remove_search_indexes ⇒ Object

Note:

It would be nice if this could remove ONLY the search indexes

Request the removal of all registered search indexes. Note that the search indexes are removed asynchronously, and may take several minutes to be fully deleted.

that have been declared on the model, but because the model may not name the index, we can't guarantee that we'll know the name or id of the corresponding indexes. It is not unreasonable to assume, though, that the intention is for the model to declare, one-to-one, all desired search indexes, so removing all search indexes ought to suffice. If a specific index or set of indexes needs to be removed instead, consider using search_indexes.each with remove_search_index.



218
219
220
221
222
 
# File 'lib/mongoid/search_indexable.rb', line 218

def remove_search_indexes
  search_indexes.each do |spec|
    remove_search_index id: spec['id']
  end
end

#search_index(name_or_defn, defn = nil) ⇒ Object

Adds an index definition for the provided single or compound keys.

Examples:

Create a basic index.

class Person
  include Mongoid::Document
  field :name, type: String
  search_index({ ... })
  search_index :name_of_index, { ... }
end

Parameters:

  • name_or_defn (Symbol | String | Hash) —

    Either the name of the index to define, or the index definition.

  • defn (Hash) (defaults to: nil) —

    The search index definition.



237
238
239
240
241
242
243
 
# File 'lib/mongoid/search_indexable.rb', line 237

def search_index(name_or_defn, defn = nil)
  name = name_or_defn
  name, defn = nil, name if name.is_a?(Hash)

  spec = { definition: defn }.tap { |s| s[:name] = name.to_s if name }
  search_index_specs.push(spec)
end

#search_indexes(options = {}) ⇒ Object

A convenience method for querying the search indexes available on the current model's collection.

Parameters:

  • options (Hash) (defaults to: {}) —

    the options to pass through to the search index query.

Options Hash (options):

  • :id (String) —

    The id of the specific index to query (optional)

  • :name (String) —

    The name of the specific index to query (optional)

  • :aggregate (Hash) —

    The options hash to pass to the aggregate command (optional)



188
189
190
 
# File 'lib/mongoid/search_indexable.rb', line 188

def search_indexes(options = {})
  collection.search_indexes(options)
end

#vector_search(vector, index: nil, path: nil, limit: 10, num_candidates: nil, filter: nil, pipeline: []) ⇒ Array<Mongoid::Document>

Performs an Atlas Vector Search query and returns matching documents. Each returned document has a vector_search_score attribute populated with its relevance score.

The vector field (given by path:) is excluded from the returned documents by default, as vectors are large and rarely useful after retrieval.

Examples:

Search by an explicit query vector.

Article.vector_search(embedding, limit: 5, filter: { status: 'published' })

Parameters:

  • vector (Array<Numeric>) —

    The query vector.

  • index (String | Symbol | nil) (defaults to: nil) —

    The name of the vector search index to use (optional if only one is declared on the model).

  • path (String | Symbol | nil) (defaults to: nil) —

    The field containing the stored vector (optional if unambiguous from the index definition).

  • limit (Integer) (defaults to: 10) —

    The maximum number of results (default: 10).

  • num_candidates (Integer | nil) (defaults to: nil) —

    The number of candidates to consider during the ANN search; defaults to limit * 10.

  • filter (Hash | nil) (defaults to: nil) —

    An optional MongoDB filter to pre-filter candidates before scoring.

  • pipeline (Array) (defaults to: []) —

    Additional aggregation stages to append after the vector search and score projection.

Returns:

  • (Array<Mongoid::Document>) —

    matching documents, each with a populated vector_search_score attribute.



298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
 
# File 'lib/mongoid/search_indexable.rb', line 298

def vector_search(vector, index: nil, path: nil, limit: 10, num_candidates: nil, filter: nil, pipeline: []) # rubocop:disable Metrics/ParameterLists
  resolved_index, resolved_path = resolve_vector_index(index, path)
  num_candidates ||= limit * 10

  vs_options = {
    'index' => resolved_index,
    'path' => resolved_path,
    'queryVector' => vector,
    'numCandidates' => num_candidates,
    'limit' => limit
  }
  vs_options['filter'] = filter if filter

  agg_pipeline = [
    { '$vectorSearch' => vs_options },
    { '$addFields'    => { 'vector_search_score' => { '$meta' => 'vectorSearchScore' } } },
    { '$project'      => { resolved_path => 0 } }
  ]
  agg_pipeline.concat(Array(pipeline))

  collection.aggregate(agg_pipeline).map { |doc| instantiate(doc) }
end

#vector_search_index(name_or_defn, defn = nil) ⇒ Object

Adds a vector search index definition. Also defines a read-only vector_search_score field on the model the first time it is called, which is populated on documents returned by vector_search.

Examples:

Create a vector search index.

class Person
  include Mongoid::Document
  vector_search_index({ fields: [...] })
  vector_search_index :my_vector_index, { fields: [...] }
end

Parameters:

  • name_or_defn (Symbol | String | Hash) —

    Either the name of the index to define, or the index definition.

  • defn (Hash) (defaults to: nil) —

    The vector search index definition.



259
260
261
262
263
264
265
266
267
268
269
270
 
# File 'lib/mongoid/search_indexable.rb', line 259

def vector_search_index(name_or_defn, defn = nil)
  name = name_or_defn
  name, defn = nil, name if name.is_a?(Hash)

  spec = { type: 'vectorSearch', definition: defn }.tap { |s| s[:name] = name.to_s if name }
  search_index_specs.push(spec)

  return if fields.key?('vector_search_score')

  field :vector_search_score, type: Float
  attr_readonly :vector_search_score
end

#wait_for_search_indexes(names, interval: 5) {|SearchIndexable::Status| ... } ⇒ Object

Waits for the named search indexes to be created.

Parameters:

  • names (Array<String>) —

    the list of index names to wait for

  • interval (Integer) (defaults to: 5) —

    the number of seconds to wait before polling again (only used when a progress callback is given).

Yields:



168
169
170
171
172
173
174
175
176
 
# File 'lib/mongoid/search_indexable.rb', line 168

def wait_for_search_indexes(names, interval: 5)
  loop do
    status = Status.new(get_indexes(names))
    yield status if block_given?
    break if status.ready?

    sleep interval
  end
end