Module: Parse::AtlasSearch::IndexManager

Defined in:
lib/parse/atlas_search/index_manager.rb

Overview

Manages Atlas Search index discovery and caching. Uses $listSearchIndexes aggregation stage to discover available indexes.

The cache is process-local, time-bounded (default 300 seconds), and protected by a Mutex. Override the TTL via:

Parse::AtlasSearch::IndexManager.cache_ttl = 60  # seconds

Examples:

List indexes

indexes = Parse::AtlasSearch::IndexManager.list_indexes("Song")
# => [{"name" => "default", "status" => "READY", ...}]

Check if index is ready

IndexManager.index_ready?("Song", "song_search")
# => true

Constant Summary collapse

DEFAULT_CACHE_TTL =

Default cache TTL in seconds. Index definitions rarely change at runtime, but new indexes built via the Atlas UI should become visible without a process restart.

300

Class Attribute Summary collapse

Class Method Summary collapse

Class Attribute Details

.cache_ttl ⇒ Object 



32
33
34
 
# File 'lib/parse/atlas_search/index_manager.rb', line 32

def cache_ttl
  @cache_ttl || DEFAULT_CACHE_TTL
end

Class Method Details

.clear_cache(collection_name = nil) ⇒ Object

Clear the index cache

Parameters:

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

    specific collection to clear, or nil for all



327
328
329
330
331
332
333
334
335
 
# File 'lib/parse/atlas_search/index_manager.rb', line 327

def clear_cache(collection_name = nil)
  cache_mutex.synchronize do
    if collection_name
      index_cache.delete(collection_name)
    else
      @index_cache = {}
    end
  end
end

.create_index(collection_name, index_name, definition, allow_system_classes: false) ⇒ Symbol

Create an Atlas Search index on a collection and invalidate the local cache so subsequent index_exists?/index_ready? observations reflect the new index. Thin wrapper over MongoDB.create_search_index — triple-gated, idempotent on name, asynchronous on the Atlas Search node.

The build runs in the background. Poll index_ready? to confirm the index has transitioned to READY before issuing queries against it.

Parameters:

  • collection_name (String) —

    target collection / Parse class

  • index_name (String) —

    the search index name

  • definition (Hash) —

    the search index definition, e.g. { mappings: { dynamic: true } } or { mappings: { fields: { title: { type: "string" } } } }

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

    opt-in for Parse-internal

Returns:

  • (Symbol) —

    :created on submission, :exists if already present



202
203
204
205
206
207
208
209
 
# File 'lib/parse/atlas_search/index_manager.rb', line 202

def create_index(collection_name, index_name, definition, allow_system_classes: false)
  result = Parse::MongoDB.create_search_index(
    collection_name, index_name, definition,
    allow_system_classes: allow_system_classes,
  )
  clear_cache(collection_name)
  result
end

.drop_index(collection_name, index_name, confirm:, allow_system_classes: false) ⇒ Symbol

Drop an Atlas Search index by name and invalidate the local cache. Confirm token is "drop_search:#{collection}:#{name}" — distinct from MongoDB.drop_index's "drop:" prefix.

Parameters:

  • collection_name (String)
  • index_name (String)
  • confirm (String) —

    must equal "drop_search:#{collection}:#{index_name}"

  • allow_system_classes (Boolean) (defaults to: false)

Returns:

  • (Symbol) —

    :dropped or :absent



220
221
222
223
224
225
226
227
 
# File 'lib/parse/atlas_search/index_manager.rb', line 220

def drop_index(collection_name, index_name, confirm:, allow_system_classes: false)
  result = Parse::MongoDB.drop_search_index(
    collection_name, index_name, confirm: confirm,
    allow_system_classes: allow_system_classes,
  )
  clear_cache(collection_name)
  result
end

.find_vector_index(collection_name, field:) ⇒ Hash?

Find the vector-search index that covers a given field path on a collection. Walks latestDefinition.fields[] looking for an entry whose type is "vector" and whose path matches field. Returns the first matching index, or nil if none.

The shape this matches is the documented Atlas vectorSearch index definition:

{
"name" => "Movie_embedding_..._idx",
"type" => "vectorSearch",
"latestDefinition" => {
  "fields" => [
    { "type" => "vector", "path" => "embedding",
      "numDimensions" => 1536, "similarity" => "cosine" },
    { "type" => "filter", "path" => "wiki_id" }
  ]
}
}

Parameters:

Returns:

  • (Hash, nil) —

    the index definition or nil



159
160
161
162
163
164
165
166
167
168
169
170
 
# File 'lib/parse/atlas_search/index_manager.rb', line 159

def find_vector_index(collection_name, field:)
  field_str = field.to_s
  list_vector_indexes(collection_name).find do |idx|
    defn = idx["latestDefinition"] || idx[:latestDefinition] || {}
    fields = defn["fields"] || defn[:fields] || []
    fields.any? do |f|
      type = (f["type"] || f[:type]).to_s
      path = (f["path"] || f[:path]).to_s
      type == "vector" && path == field_str
    end
  end
end

.get_index(collection_name, index_name) ⇒ Hash?

Get a specific index definition

Parameters:

  • collection_name (String) —

    the Parse collection name

  • index_name (String) —

    the index name

Returns:

  • (Hash, nil) —

    the index definition or nil if not found



99
100
101
102
 
# File 'lib/parse/atlas_search/index_manager.rb', line 99

def get_index(collection_name, index_name)
  indexes = list_indexes(collection_name)
  indexes.find { |idx| idx["name"] == index_name }
end

.index_exists?(collection_name, index_name) ⇒ Boolean

Check if a search index exists for a collection

Parameters:

  • collection_name (String) —

    the Parse collection name

  • index_name (String) —

    the index name to check

Returns:

  • (Boolean) —

    true if index exists



80
81
82
83
 
# File 'lib/parse/atlas_search/index_manager.rb', line 80

def index_exists?(collection_name, index_name)
  indexes = list_indexes(collection_name)
  indexes.any? { |idx| idx["name"] == index_name }
end

.index_ready?(collection_name, index_name) ⇒ Boolean

Check if a search index exists and is ready to query

Parameters:

  • collection_name (String) —

    the Parse collection name

  • index_name (String) —

    the index name to check

Returns:

  • (Boolean) —

    true if index exists and is queryable



89
90
91
92
93
 
# File 'lib/parse/atlas_search/index_manager.rb', line 89

def index_ready?(collection_name, index_name)
  indexes = list_indexes(collection_name)
  index = indexes.find { |idx| idx["name"] == index_name }
  index.present? && index["queryable"] == true
end

.list_indexes(collection_name, force_refresh: false) ⇒ Array<Hash>

List all search indexes for a collection (cached). Uses the $listSearchIndexes aggregation stage.

Parameters:

  • collection_name (String) —

    the Parse collection name

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

    bypass cache and fetch fresh data

Returns:

  • (Array<Hash>) —

    array of index definitions with keys:

    • id: String - the index ID
    • name: String - the index name
    • status: String - "READY", "BUILDING", etc.
    • queryable: Boolean - whether the index is queryable
    • mappings: Hash - field mappings definition


47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
 
# File 'lib/parse/atlas_search/index_manager.rb', line 47

def list_indexes(collection_name, force_refresh: false)
  if !force_refresh
    cached = cache_mutex.synchronize do
      cached_indexes(collection_name) if cache_valid?(collection_name)
    end
    return cached if cached
  end

  # $listSearchIndexes must be the first and only stage in pipeline
  pipeline = [{ "$listSearchIndexes" => {} }]

  begin
    # `$listSearchIndexes` returns server-side index metadata,
    # not document rows. CLP gates row access ("find") and is
    # not the right gate for "what indexes exist on this
    # collection" — every code path that introspects index
    # state (`Model.describe`, the migrator, `wait_for_ready`)
    # would otherwise refuse under any scoped agent. Pass
    # `master: true` so the SDK's CLP layer skips this metadata
    # pipeline. The mongo-side privilege check still applies
    # (the underlying connection must hold `listSearchIndexes`).
    results = Parse::MongoDB.aggregate(collection_name, pipeline, master: true)
    cache_mutex.synchronize { cache_indexes(collection_name, results) }
    results
  rescue => e
    handle_list_error(e, collection_name)
  end
end

.list_search_indexes(collection_name) ⇒ Array<Hash>

List only type: "search" indexes (lexical / BM25). Filters the raw list_indexes output. $listSearchIndexes returns both search and vectorSearch index types on the same collection; callers building lexical pipelines should consume this view. Indexes with an absent type field default to "search" for compatibility with older Atlas Search releases that pre-date the vector-search index type.

Parameters:

  • collection_name (String) —

    the Parse collection name

Returns:



114
115
116
117
118
119
 
# File 'lib/parse/atlas_search/index_manager.rb', line 114

def list_search_indexes(collection_name)
  list_indexes(collection_name).select do |idx|
    type = (idx["type"] || idx[:type] || "search").to_s
    type == "search"
  end
end

.list_vector_indexes(collection_name) ⇒ Array<Hash>

List only type: "vectorSearch" indexes. Filters the raw list_indexes output. Vector-search indexes are the only ones eligible for the $vectorSearch aggregation stage; routing a lexical-index name into vector search (or vice versa) fails at the Atlas Search node with a non-obvious error, so the SDK filters at lookup time.

Parameters:

  • collection_name (String) —

    the Parse collection name

Returns:

  • (Array<Hash>) —

    vector-search indexes only



130
131
132
133
134
 
# File 'lib/parse/atlas_search/index_manager.rb', line 130

def list_vector_indexes(collection_name)
  list_indexes(collection_name).select do |idx|
    (idx["type"] || idx[:type]).to_s == "vectorSearch"
  end
end

.update_index(collection_name, index_name, definition, allow_system_classes: false) ⇒ Symbol

Replace the definition of an existing Atlas Search index and invalidate the local cache. The rebuild runs asynchronously; the new mapping is not live until index_ready? returns true again.

Parameters:

  • collection_name (String)
  • index_name (String)
  • definition (Hash) —

    replacement definition

  • allow_system_classes (Boolean) (defaults to: false)

Returns:



239
240
241
242
243
244
245
246
 
# File 'lib/parse/atlas_search/index_manager.rb', line 239

def update_index(collection_name, index_name, definition, allow_system_classes: false)
  result = Parse::MongoDB.update_search_index(
    collection_name, index_name, definition,
    allow_system_classes: allow_system_classes,
  )
  clear_cache(collection_name)
  result
end

.validate_index!(collection_name, index_name) ⇒ Object

Validate that an index exists and is ready

Parameters:

  • collection_name (String) —

    the Parse collection name

  • index_name (String) —

    the index name to validate

Raises:



176
177
178
179
180
181
182
183
 
# File 'lib/parse/atlas_search/index_manager.rb', line 176

def validate_index!(collection_name, index_name)
  unless index_ready?(collection_name, index_name)
    available = list_indexes(collection_name).map { |i| i["name"] }.join(", ")
    raise IndexNotFound,
      "Atlas Search index '#{index_name}' not found or not ready on collection '#{collection_name}'. " \
      "Available indexes: #{available.presence || "none"}"
  end
end

.wait_for_ready(collection_name, index_name, timeout: 600, interval: 5) ⇒ Symbol

Block until a search index reaches READY (queryable) status, the build fails, or the timeout elapses. Bypasses the IndexManager's 300-second cache via force_refresh: true on every poll — naive callers using until index_ready?; sleep cache the BUILDING state for the full TTL and never see the transition to READY. This helper is the correct path.

Resilience to transient connectivity loss. Atlas Local's internal supervisor periodically restarts mongod (5-10s outage windows during replica-set sync events). If a poll lands in a restart window, the underlying $listSearchIndexes call raises Mongo::Error::NoServerAvailable (or surfaces it via Parse::AtlasSearch::NotAvailable). The poll treats those as transient and continues until the deadline — only the final deadline-elapsed condition produces :timeout. A non- transient error (e.g. an Atlas-side FAILED status surfaced through some other exception class) still raises out.

Parameters:

  • collection_name (String)
  • index_name (String)
  • timeout (Numeric) (defaults to: 600) —

    seconds to wait before returning :timeout. Default 600 (10 minutes).

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

    seconds between polls. Default 5.

Returns:

  • (Symbol) —

    :ready once the index is queryable, :failed when the index reports a FAILED status, :timeout when the deadline elapses without either.



274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
 
# File 'lib/parse/atlas_search/index_manager.rb', line 274

def wait_for_ready(collection_name, index_name, timeout: 600, interval: 5)
  deadline = Time.now + timeout
  # Cap consecutive transient failures. The intent of the
  # resilience is to bridge a single mongod-restart window
  # (5-10s); a sustained failure of 25+ seconds is a real outage,
  # not a restart, and should raise rather than loop until the
  # caller's full timeout elapses (which can be 10+ minutes for
  # large-build callers).
  #
  # `interval <= 0` is a unit-test affordance (tests stub `sleep`
  # to a no-op and pass `interval: 0` so the suite isn't paced by
  # real wall-clock waits). Dividing 25.0 by zero produces
  # Infinity, and `Float#ceil` on Infinity raises
  # `FloatDomainError`, so guard the divisor with a small
  # positive epsilon. The clamp upper bound (12) is what the
  # formula resolves to in that case, which is the right answer
  # — with no inter-poll delay, the consecutive-failure counter
  # is the only thing bounding the loop, and the upper bound is
  # the most permissive setting.
  divisor = interval > 0 ? interval.to_f : 0.001
  max_consecutive_transient = (25.0 / divisor).ceil.clamp(3, 12)
  consecutive_transient = 0
  last_transient = nil
  loop do
    indexes = begin
        last_transient = nil
        list_indexes(collection_name, force_refresh: true)
      rescue Parse::AtlasSearch::NotAvailable, StandardError => e
        raise unless transient_poll_error?(e)
        last_transient = e
        nil
      end
    if indexes
      consecutive_transient = 0
      idx = indexes.find { |i| (i["name"] || i[:name]).to_s == index_name.to_s }
      if idx
        return :ready if idx["queryable"] == true
        status = (idx["status"] || idx[:status]).to_s.upcase
        return :failed if status == "FAILED"
      end
    else
      consecutive_transient += 1
      if consecutive_transient >= max_consecutive_transient
        raise last_transient
      end
    end
    return :timeout if Time.now >= deadline
    sleep interval
  end
end