Class: Mongo::Index::View

Inherits:
Object
  • Object
show all
Extended by:
Forwardable
Includes:
Enumerable, Cursor::NonTailable, CursorHost, Retryable
Defined in:
lib/mongo/index/view.rb

Overview

A class representing a view of indexes.

Since:

  • 2.0.0

Constant Summary collapse

KEY =

The index key field.

Since:

  • 2.0.0

'key'.freeze
NAME =

The index name field.

Since:

  • 2.0.0

'name'.freeze
OPTIONS =

The mappings of Ruby index options to server options.

Since:

  • 2.0.0

{
  :background => :background,
  :bits => :bits,
  :bucket_size => :bucketSize,
  :default_language => :default_language,
  :expire_after => :expireAfterSeconds,
  :expire_after_seconds => :expireAfterSeconds,
  :key => :key,
  :language_override => :language_override,
  :max => :max,
  :min => :min,
  :name => :name,
  :partial_filter_expression => :partialFilterExpression,
  :sparse => :sparse,
  :sphere_version => :'2dsphereIndexVersion',
  :storage_engine => :storageEngine,
  :text_version => :textIndexVersion,
  :unique => :unique,
  :version => :v,
  :weights => :weights,
  :collation => :collation,
  :comment => :comment,
  :wildcard_projection => :wildcardProjection,
}.freeze

Instance Attribute Summary collapse

Attributes included from CursorHost

#cursor, #timeout_mode

Instance Method Summary collapse

Methods included from Cursor::NonTailable

#cursor_type, #timeout_mode

Methods included from CursorHost

#validate_timeout_mode!

Methods included from Retryable

#read_worker, #select_server, #write_worker

Constructor Details

#initialize(collection, options = {}) ⇒ View

Create the new index view.

Examples:

Create the new index view.

View::Index.new(collection)

Parameters:

  • collection (Collection) —

    The collection.

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

    Options for getting a list of indexes.

Options Hash (options):

  • :batch_size (Integer) —

    The batch size for results returned from the listIndexes command.

  • :timeout_mode (:cursor_lifetime | :iteration) —

    How to interpret :timeout_ms (whether it applies to the lifetime of the cursor, or per iteration).

  • :timeout_ms (Integer) —

    The operation timeout in milliseconds. Must be a non-negative integer. An explicit value of 0 means infinite. The default value is unset which means the value is inherited from the collection or the database or the client.

Since:

  • 2.0.0



318
319
320
321
322
323
324
325
326
 
# File 'lib/mongo/index/view.rb', line 318

def initialize(collection, options = {})
  @collection = collection
  @operation_timeout_ms = options.delete(:timeout_ms)

  validate_timeout_mode!(options)

  @batch_size = options[:batch_size]
  @options = options
end

Instance Attribute Details

#batch_size ⇒ Integer (readonly)

Returns batch_size The size of the batch of results when sending the listIndexes command.

Returns:

  • (Integer) —

    batch_size The size of the batch of results when sending the listIndexes command.

Since:

  • 2.0.0



38
39
40
 
# File 'lib/mongo/index/view.rb', line 38

def batch_size
  @batch_size
end

#collection ⇒ Collection (readonly)

Returns collection The indexes collection.

Returns:

  • (Collection) —

    collection The indexes collection.

Since:

  • 2.0.0



34
35
36
 
# File 'lib/mongo/index/view.rb', line 34

def collection
  @collection
end

#operation_timeout_ms ⇒ Integer | nil | The timeout_ms value that was passed as an option to the view. (readonly)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns Integer | nil | The timeout_ms value that was passed as an option to the view.

Returns:

  • (Integer | nil | The timeout_ms value that was passed as an option to the view.) —

    Integer | nil | The timeout_ms value that was passed as an option to the view.

Since:

  • 2.0.0



44
45
46
 
# File 'lib/mongo/index/view.rb', line 44

def operation_timeout_ms
  @operation_timeout_ms
end

Instance Method Details

#create_many(*models) ⇒ Result

Note:

On MongoDB 3.0.0 and higher, the indexes will be created in parallel on the server.

Creates multiple indexes on the collection.

Examples:

Create multiple indexes.

view.create_many([
  { key: { name: 1 }, unique: true },
  { key: { age: -1 }, background: true }
])

Create multiple indexes with options.

view.create_many(
  { key: { name: 1 }, unique: true },
  { key: { age: -1 }, background: true },
  { commit_quorum: 'majority' }
)

Parameters:

  • models (Array<Hash>) —

    The index specifications. Each model MUST include a :key option, except for the last item in the Array, which may be a Hash specifying options relevant to the createIndexes operation. The following options are accepted:

    • commit_quorum: Specify how many data-bearing members of a replica set, including the primary, must complete the index builds successfully before the primary marks the indexes as ready. Potential values are:

      • an integer from 0 to the number of members of the replica set

      • “majority” indicating that a majority of data bearing nodes must vote

      • “votingMembers” which means that all voting data bearing nodes must vote

    • session: The session to use.

    • comment: A user-provided comment to attach to this command.

Returns:

  • (Result) —

    The result of the command.

Since:

  • 2.0.0



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
 
# File 'lib/mongo/index/view.rb', line 216

def create_many(*models)
  models = models.flatten
  options = {}
  if models && !models.last.key?(:key)
    options = models.pop
  end

  client.with_session(@options.merge(options)) do |session|
    server = next_primary(nil, session)

    indexes = normalize_models(models, server)
    indexes.each do |index|
      if index[:bucketSize] || index['bucketSize']
        client.log_warn("Haystack indexes (bucketSize index option) are deprecated as of MongoDB 4.4")
      end
    end

    spec = {
      indexes: indexes,
      db_name: database.name,
      coll_name: collection.name,
      session: session,
      commit_quorum: options[:commit_quorum],
      write_concern: write_concern,
      comment: options[:comment],
    }
    context = Operation::Context.new(
      client: client,
      session: session,
      operation_timeouts: operation_timeouts(options)
    )
    Operation::CreateIndex.new(spec).execute(server, context: context)
  end
end

#create_one(keys, options = {}) ⇒ Result

Note:

Note that the options listed may be subset of those available.

Creates an index on the collection.

See the MongoDB documentation for a full list of supported options by server version.

Examples:

Create a unique index on the collection.

view.create_one({ name: 1 }, { unique: true })

Parameters:

  • keys (Hash) —

    A hash of field name/direction pairs.

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

    Options for this index.

Options Hash (options):

  • :unique (true, false) — default: false —

    If true, this index will enforce a uniqueness constraint on that field.

  • :background (true, false) — default: false —

    If true, the index will be built in the background (only available for server versions >= 1.3.2 )

  • :drop_dups (true, false) — default: false —

    If creating a unique index on this collection, this option will keep the first document the database indexes and drop all subsequent documents with duplicate values on this field.

  • :bucket_size (Integer) — default: nil —

    For use with geoHaystack indexes. Number of documents to group together within a certain proximity to a given longitude and latitude.

  • :max (Integer) — default: nil —

    Specify the max latitude and longitude for a geo index.

  • :min (Integer) — default: nil —

    Specify the min latitude and longitude for a geo index.

  • :partial_filter_expression (Hash) —

    Specify a filter for a partial index.

  • :hidden (Boolean) —

    When :hidden is true, this index will exist on the collection but not be used by the query planner when executing operations.

  • :commit_quorum (String | Integer) —

    Specify how many data-bearing members of a replica set, including the primary, must complete the index builds successfully before the primary marks the indexes as ready. Potential values are:

    • an integer from 0 to the number of members of the replica set

    • “majority” indicating that a majority of data bearing nodes must vote

    • “votingMembers” which means that all voting data bearing nodes must vote

  • :session (Session) —

    The session to use for the operation.

  • :comment (Object) —

    A user-provided comment to attach to this command.

Returns:

  • (Result) —

    The response.

Since:

  • 2.0.0



167
168
169
170
171
172
173
174
175
176
177
178
179
180
 
# File 'lib/mongo/index/view.rb', line 167

def create_one(keys, options = {})
  options = options.dup

  create_options = {}
  if session = @options[:session]
    create_options[:session] = session
  end
  %i(commit_quorum session comment timeout_ms max_time_ms).each do |key|
    if value = options.delete(key)
      create_options[key] = value
    end
  end
  create_many({ key: keys }.merge(options), create_options)
end

#drop_all(options = {}) ⇒ Result

Drop all indexes on the collection.

Examples:

Drop all indexes on the collection.

view.drop_all

Parameters:

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

    Options for this operation.

Options Hash (options):

  • :comment (Object) —

    A user-provided comment to attach to this command.

Returns:

  • (Result) —

    The response.

Since:

  • 2.0.0



119
120
121
 
# File 'lib/mongo/index/view.rb', line 119

def drop_all(options = {})
  drop_by_name(Index::ALL, options)
end

#drop_one(name, options = {}) ⇒ Result

Drop an index by its name.

Examples:

Drop an index by its name.

view.drop_one('name_1')

Parameters:

  • name (String) —

    The name of the index.

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

    Options for this operation.

Options Hash (options):

  • :comment (Object) —

    A user-provided comment to attach to this command.

Returns:

  • (Result) —

    The response.

Raises:

Since:

  • 2.0.0



101
102
103
104
 
# File 'lib/mongo/index/view.rb', line 101

def drop_one(name, options = {})
  raise Error::MultiIndexDrop.new if name == Index::ALL
  drop_by_name(name, options)
end

#each(&block) ⇒ Object

Iterate over all indexes for the collection.

Examples:

Get all the indexes.

view.each do |index|
  ...
end

Since:

  • 2.0.0



279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
 
# File 'lib/mongo/index/view.rb', line 279

def each(&block)
  session = client.get_session(@options)
  context = Operation::Context.new(
    client: client,
    session: session,
    operation_timeouts: operation_timeouts(@options)
  )

  cursor = read_with_retry_cursor(session, ServerSelector.primary, self, context: context) do |server|
    send_initial_query(server, session, context)
  end
  if block_given?
    cursor.each do |doc|
      yield doc
    end
  else
    cursor.to_enum
  end
end

#get(keys_or_name) ⇒ Hash

Convenience method for getting index information by a specific name or spec.

Examples:

Get index information by name.

view.get('name_1')

Get index information by the keys.

view.get(name: 1)

Parameters:

  • keys_or_name (Hash, String) —

    The index name or spec.

Returns:

  • (Hash) —

    The index information.

Since:

  • 2.0.0



265
266
267
268
269
 
# File 'lib/mongo/index/view.rb', line 265

def get(keys_or_name)
  find do |index|
    (index[NAME] == keys_or_name) || (index[KEY] == normalize_keys(keys_or_name))
  end
end

#operation_timeouts(opts = {}) ⇒ Hash

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns timeout_ms value set on the operation level (if any), and/or timeout_ms that is set on collection/database/client level (if any).

Returns:

  • (Hash) —

    timeout_ms value set on the operation level (if any), and/or timeout_ms that is set on collection/database/client level (if any).

Since:

  • 2.0.0



340
341
342
343
344
345
346
347
348
 
# File 'lib/mongo/index/view.rb', line 340

def operation_timeouts(opts = {})
  {}.tap do |result|
    if opts[:timeout_ms] || operation_timeout_ms
      result[:operation_timeout_ms] = opts.delete(:timeout_ms) || operation_timeout_ms
    else
      result[:inherited_timeout_ms] = collection.timeout_ms
    end
  end
end

#timeout_ms ⇒ Integer | nil

The timeout_ms value to use for this operation; either specified as an option to the view, or inherited from the collection.

Returns:

  • (Integer | nil) —

    the timeout_ms for this operation

Since:

  • 2.0.0



332
333
334
 
# File 'lib/mongo/index/view.rb', line 332

def timeout_ms
  operation_timeout_ms || collection.timeout_ms
end