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



259
260
261
262
263
264
265
266
267
 
# File 'lib/parse/atlas_search/index_manager.rb', line 259

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



134
135
136
137
138
139
140
141
 
# File 'lib/parse/atlas_search/index_manager.rb', line 134

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`



152
153
154
155
156
157
158
159
 
# File 'lib/parse/atlas_search/index_manager.rb', line 152

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

.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

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



171
172
173
174
175
176
177
178
 
# File 'lib/parse/atlas_search/index_manager.rb', line 171

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:

  • (IndexNotFound) —

    if the index doesn’t exist or isn’t ready



108
109
110
111
112
113
114
115
 
# File 'lib/parse/atlas_search/index_manager.rb', line 108

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.



206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
 
# File 'lib/parse/atlas_search/index_manager.rb', line 206

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