Module: Parse::Core::VectorSearchable

Included in:
Object
Defined in:
lib/parse/model/core/vector_searchable.rb

Overview

Class-level find_similar wrapper around VectorSearch.search for any Parse::Object subclass that has declared at least one :vector property.

The wrapper handles three things the low-level entry point doesn't:

  1. Field resolution. Defaults to the subclass's single :vector property; raises if the class has none, requires explicit field: if it has more than one.
  2. Declared-dimension validation. Compares the query vector's length against the dimensions: declared on the property, so callers get "expected 1536, got 768" instead of an Atlas- side error after a round-trip.
  3. Index auto-discovery. Looks up the Atlas vectorSearch index covering the field via AtlasSearch::IndexManager.find_vector_index when no explicit index: kwarg is given.

ACL/CLP enforcement is inherited from VectorSearch.search (which routes through MongoDB — REST /aggregate is master-key-only and bypasses ACL/CLP, see CLAUDE.md). The full scope-kwarg surface (session_token:, master:, acl_user:, acl_role:) is forwarded as-is.

Examples:

default field, default index

WikiArticle.find_similar(vector: query_embedding, k: 5)

explicit field + post-filter, scoped to a session

Document.find_similar(
  vector: embed.call("ruby parse"),
  field: :body_embedding,
  k: 10,
  filter: { tag: "ruby" },
  session_token: user.session_token,
)

Defined Under Namespace

Classes: AmbiguousVectorField, EmbedderNotConfigured, IndexNotResolved, NoVectorProperty

Instance Method Summary collapse

Instance Method Details

#find_similar(vector: nil, text: nil, k: 10, field: nil, filter: nil, vector_filter: nil, index: nil, num_candidates: nil, max_time_ms: nil, raw: false, **scope_opts) ⇒ Array<Parse::Object>, Array<Hash>

Note:

When text: is given, the text is sent over the wire to the embedding provider (e.g. OpenAI). Operators that enable global Faraday request logging on the embedding connection will capture the full query text in the JSON request body. Treat text: as user-visible content for log-handling purposes.

Note:

The provider is responsible for bounding its own request timeout. Embeddings::OpenAI self-bounds at 30 s read / 5 s connect with capped retries. Custom providers MUST self-bound — find_similar does not impose a wall-clock deadline on the embed step.

Find documents whose declared :vector property is closest to vector: under the Atlas vectorSearch index's similarity function.

Parameters:

  • vector (Array<Float>, Parse::Vector, nil) (defaults to: nil) —

    the query embedding. Mutually exclusive with text: — exactly one of the two must be given.

  • text (String, nil) (defaults to: nil) —

    natural-language query. When given, the resolved field's declared provider: is looked up via Embeddings.provider, used to embed [text] with input_type: :search_query, and the resulting vector is used in place of vector:. Requires the property to have been declared with provider: metadata.

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

    number of hits to return. Default 10.

  • field (Symbol, String, nil) (defaults to: nil) —

    the :vector property to search. Auto-resolves when the class has exactly one :vector property.

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

    post-$vectorSearch $match filter.

  • vector_filter (Hash, nil) (defaults to: nil) —

    Atlas-native pre-search filter (fields must be declared type: "filter" in the index).

  • index (String, nil) (defaults to: nil) —

    explicit vectorSearch index name. Skips auto-discovery when given.

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

    HNSW search width.

  • max_time_ms (Integer, nil) (defaults to: nil) —

    server-side timeout.

  • raw (Boolean) (defaults to: false) —

    when true return the raw Mongo documents (each enriched with _vscore); when false (default) build instances of the calling class and attach vector_score.

  • scope_opts (Hash) —

    ACL/CLP scope kwargs forwarded to VectorSearch.search: session_token:, master:, acl_user:, acl_role:.

Returns:

  • (Array<Parse::Object>, Array<Hash>) —

    hits in descending-similarity order. Each instance responds to vector_score (the Atlas vectorSearchScore).

Raises:



129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
 
# File 'lib/parse/model/core/vector_searchable.rb', line 129

def find_similar(vector: nil, text: nil, k: 10, field: nil, filter: nil,
                 vector_filter: nil, index: nil,
                 num_candidates: nil, max_time_ms: nil, raw: false,
                 **scope_opts)
  if vector.nil? && text.nil?
    raise ArgumentError,
          "#{self}.find_similar: must pass either `vector:` or `text:`."
  end
  if !vector.nil? && !text.nil?
    raise ArgumentError,
          "#{self}.find_similar: pass either `vector:` or `text:`, not both."
  end

  resolved_field = resolve_vector_field!(field)
  declared_dims = vector_properties.dig(resolved_field, :dimensions)

  query_vector =
    if text.nil?
      coerce_query_vector(vector)
    else
      embed_query_text!(text, resolved_field)
    end
  Parse::VectorSearch.validate_query_vector!(query_vector, dimensions: declared_dims)

  index_name = resolve_vector_index!(resolved_field, index)

  raw_hits = Parse::VectorSearch.search(
    parse_class,
    field: resolved_field,
    query_vector: query_vector,
    k: k,
    num_candidates: num_candidates,
    filter: filter,
    vector_filter: vector_filter,
    index: index_name,
    max_time_ms: max_time_ms,
    **scope_opts,
  )

  return raw_hits if raw
  build_vector_hits(raw_hits)
end