Module: Mongoid::SearchIndexable

Extended by:
ActiveSupport::Concern
Included in:
Composable
Defined in:
lib/mongoid/search_indexable.rb

Overview

Encapsulates behavior around managing search indexes. This feature is only supported when connected to an Atlas cluster.

Defined Under Namespace

Modules: ClassMethods Classes: Status

Instance Method Summary collapse

Instance Method Details

#auto_embed_search(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 for documents with text similar to this document's stored text field, using auto-embedding. The current document is excluded from the results.

Examples:

Find articles with similar descriptions.

article.auto_embed_search(limit: 5, filter: { status: 'published' })

Parameters:

  • 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 search (default: false).

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

    Query-time embedding model override.

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

    Additional aggregation stages to append.

Returns:

  • (Array<Mongoid::Document>) —

    matching documents, each with a populated vector_search_score attribute.



123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
 
# File 'lib/mongoid/search_indexable.rb', line 123

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

  if text.nil?
    raise ArgumentError,
          "#{resolved_path} is nil on this document; cannot perform auto-embed search"
  end

  self_filter = { '_id' => { '$ne' => _id } }
  combined_filter = filter ? { '$and' => [ self_filter, filter ] } : self_filter

  self.class.auto_embed_search(
    text,
    index: index,
    path: path,
    limit: limit,
    num_candidates: num_candidates,
    filter: combined_filter,
    exact: exact,
    model: model,
    pipeline: pipeline
  )
end

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

Performs a vector search for documents similar to this one, using this document's stored embedding as the query vector. The document itself is excluded from the results.

Examples:

Find articles similar to this one.

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

Parameters:

  • 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.



79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
 
# File 'lib/mongoid/search_indexable.rb', line 79

def vector_search(index: nil, path: nil, limit: 10, num_candidates: nil, filter: nil, pipeline: [])
  _index, resolved_path = self.class.send(:resolve_vector_index, index, path)
  query_vector = public_send(resolved_path)

  if query_vector.nil?
    raise ArgumentError,
          "#{resolved_path} is nil on this document; cannot perform vector search"
  end

  self_filter = { '_id' => { '$ne' => _id } }
  combined_filter = filter ? { '$and' => [ self_filter, filter ] } : self_filter

  self.class.vector_search(
    query_vector,
    index: index,
    path: path,
    limit: limit,
    num_candidates: num_candidates,
    filter: combined_filter,
    pipeline: pipeline
  )
end