class Mongo::Collection

Mongo::Collection
Reference
Object

Overview

A Collection provides access to a MongoDB collection.

collection = client["database_name"]["collection_name"]

Included Modules

Mongo::WithReadConcern
Mongo::WithReadPreference
Mongo::WithWriteConcern

Defined in:

cryomongo/collection.cr

Instance Method Summary

#aggregate(pipeline : Array, *, allow_disk_use : Bool | Nil = nil, batch_size : Int32 | Nil = nil, max_time_ms : Int64 | Nil = nil, bypass_document_validation : Bool | Nil = nil, collation : Collation | Nil = nil, hint : String | H | Nil = nil, comment : String | Nil = nil, read_concern : ReadConcern | Nil = nil, write_concern : WriteConcern | Nil = nil, read_preference : ReadPreference | Nil = nil, session : Session::ClientSession | Nil = nil) : Mongo::Cursor | Nil forall H
Runs an aggregation framework pipeline.
#bulk(ordered : Bool = true, session : Session::ClientSession | Nil = nil)
Create a Mongo::Bulk instance.
#bulk_write(requests : Array(Bulk::WriteModel), *, ordered : Bool, bypass_document_validation : Bool | Nil = nil, session : Session::ClientSession | Nil = nil) : Bulk::WriteResult
Executes multiple write operations.
#command(operation, write_concern : WriteConcern | Nil = nil, read_concern : ReadConcern | Nil = nil, read_preference : ReadPreference | Nil = nil, session : Session::ClientSession | Nil = nil, **args, &)
Execute a command on the server targeting the collection.
#command(operation, write_concern : WriteConcern | Nil = nil, read_concern : ReadConcern | Nil = nil, read_preference : ReadPreference | Nil = nil, session : Session::ClientSession | Nil = nil, **args)
Execute a command on the server targeting the collection.
#count_documents(filter = BSON.new, *, skip : Int32 | Nil = nil, limit : Int32 | Nil = nil, collation : Collation | Nil = nil, hint : String | H | Nil = nil, max_time_ms : Int64 | Nil = nil, read_preference : ReadPreference | Nil = nil, session : Session::ClientSession | Nil = nil) : Int32 forall H
Count the number of documents in a collection that match the given filter.
#create_index(keys, *, options = NamedTuple.new, commit_quorum : Int32 | String | Nil = nil, max_time_ms : Int64 | Nil = nil, write_concern : WriteConcern | Nil = nil, session : Session::ClientSession | Nil = nil) : Commands::CreateIndexes::Result | Nil
This is a convenience method for creating a single index.
#create_indexes(models : Array, *, commit_quorum : Int32 | String | Nil = nil, max_time_ms : Int64 | Nil = nil, write_concern : WriteConcern | Nil = nil, session : Session::ClientSession | Nil = nil) : Commands::CreateIndexes::Result | Nil
Creates multiple indexes in the collection.
#database : Mongo::Database
The parent database.
#delete_many(filter, *, collation : Collation | Nil = nil, hint : String | H | Nil = nil, ordered : Bool | Nil = nil, write_concern : WriteConcern | Nil = nil, session : Session::ClientSession | Nil = nil) : Commands::Common::DeleteResult | Nil forall H
Deletes multiple documents.
#delete_one(filter, *, collation : Collation | Nil = nil, hint : String | H | Nil = nil, ordered : Bool | Nil = nil, write_concern : WriteConcern | Nil = nil, session : Session::ClientSession | Nil = nil) : Commands::Common::DeleteResult | Nil forall H
Deletes one document.
#distinct(key : String, *, filter = nil, read_concern : ReadConcern | Nil = nil, collation : Collation | Nil = nil, read_preference : ReadPreference | Nil = nil, session : Session::ClientSession | Nil = nil) : Array
Finds the distinct values for a specified field across a single collection.
#drop_index(name : String, *, max_time_ms : Int64 | Nil = nil, write_concern : WriteConcern | Nil = nil, session : Session::ClientSession | Nil = nil) : Commands::Common::BaseResult | Nil
Drops a single index from the collection by the index name.
#drop_indexes(*, max_time_ms : Int64 | Nil = nil, write_concern : WriteConcern | Nil = nil, session : Session::ClientSession | Nil = nil) : Commands::Common::BaseResult | Nil
Drops all indexes in the collection.
#estimated_document_count(*, max_time_ms : Int64 | Nil = nil, read_preference : ReadPreference | Nil = nil, session : Session::ClientSession | Nil = nil) : Int32
Gets an estimate of the count of documents in a collection using collection metadata.
#find(filter = BSON.new, *, sort = nil, projection = nil, hint : String | H | Nil = nil, skip : Int32 | Nil = nil, limit : Int32 | Nil = nil, batch_size : Int32 | Nil = nil, single_batch : Bool | Nil = nil, comment : String | Nil = nil, max_time_ms : Int64 | Nil = nil, read_concern : ReadConcern | Nil = nil, max = nil, min = nil, return_key : Bool | Nil = nil, show_record_id : Bool | Nil = nil, tailable : Bool | Nil = nil, oplog_replay : Bool | Nil = nil, no_cursor_timeout : Bool | Nil = nil, await_data : Bool | Nil = nil, allow_partial_results : Bool | Nil = nil, allow_disk_use : Bool | Nil = nil, collation : Collation | Nil = nil, read_preference : ReadPreference | Nil = nil, session : Session::ClientSession | Nil = nil) : Mongo::Cursor forall H
Finds the documents matching the model.
#find_one(filter = BSON.new, *, sort = nil, projection = nil, hint : String | H | Nil = nil, skip : Int32 | Nil = nil, comment : String | Nil = nil, max_time_ms : Int64 | Nil = nil, read_concern : ReadConcern | Nil = nil, max = nil, min = nil, return_key : Bool | Nil = nil, show_record_id : Bool | Nil = nil, oplog_replay : Bool | Nil = nil, no_cursor_timeout : Bool | Nil = nil, allow_partial_results : Bool | Nil = nil, collation : Collation | Nil = nil, read_preference : ReadPreference | Nil = nil, session : Session::ClientSession | Nil = nil) : BSON | Nil forall H
Finds the document matching the model.
#find_one_and_delete(filter, *, sort = nil, fields = nil, bypass_document_validation : Bool | Nil = nil, write_concern : WriteConcern | Nil = nil, collation : Collation | Nil = nil, hint : String | H | Nil = nil, max_time_ms : Int64 | Nil = nil, session : Session::ClientSession | Nil = nil) : BSON | Nil forall H
Finds a single document and deletes it, returning the original.
#find_one_and_replace(filter, replacement, *, sort = nil, new : Bool | Nil = nil, fields = nil, upsert : Bool | Nil = nil, bypass_document_validation : Bool | Nil = nil, write_concern : WriteConcern | Nil = nil, collation : Collation | Nil = nil, array_filters = nil, hint : String | H | Nil = nil, max_time_ms : Int64 | Nil = nil, session : Session::ClientSession | Nil = nil) : BSON | Nil forall H
Finds a single document and replaces it, returning either the original or the replaced document.
#find_one_and_update(filter, update, *, sort = nil, new : Bool | Nil = nil, fields = nil, upsert : Bool | Nil = nil, bypass_document_validation : Bool | Nil = nil, write_concern : WriteConcern | Nil = nil, collation : Collation | Nil = nil, array_filters = nil, hint : String | H | Nil = nil, max_time_ms : Int64 | Nil = nil, session : Session::ClientSession | Nil = nil) : BSON | Nil forall H
Finds a single document and updates it, returning either the original or the updated document.
#insert_many(documents : Array, *, ordered : Bool | Nil = nil, write_concern : WriteConcern | Nil = nil, bypass_document_validation : Bool | Nil = nil, session : Session::ClientSession | Nil = nil) : Commands::Common::InsertResult | Nil
Inserts the provided document.
#insert_one(document, *, write_concern : WriteConcern | Nil = nil, bypass_document_validation : Bool | Nil = nil, session : Session::ClientSession | Nil = nil) : Commands::Common::InsertResult | Nil
Inserts the provided document.
#list_indexes(session : Session::ClientSession | Nil = nil) : Mongo::Cursor | Nil
Gets index information for all indexes in the collection.
#name : CollectionKey
The collection name.
#read_concern : ReadConcern | Nil
Read concern accessor.
#read_concern=(read_concern : ReadConcern | Nil)
Read concern accessor.
#read_preference : ReadPreference | Nil
ReadPreference accessor.
#read_preference=(read_preference : ReadPreference | Nil)
ReadPreference accessor.
#replace_one(filter, replacement, *, upsert : Bool = false, collation : Collation | Nil = nil, hint : String | H | Nil = nil, ordered : Bool | Nil = nil, write_concern : WriteConcern | Nil = nil, bypass_document_validation : Bool | Nil = nil, session : Session::ClientSession | Nil = nil) : Commands::Common::UpdateResult | Nil forall H
Replaces a single document.
#stats(*, scale : Int32 | Nil = nil, session : Session::ClientSession | Nil = nil) : BSON | Nil
Returns a variety of storage statistics for the collection.
#update_many(filter, update, *, upsert : Bool = false, array_filters = nil, collation : Collation | Nil = nil, hint : String | H | Nil = nil, ordered : Bool | Nil = nil, write_concern : WriteConcern | Nil = nil, bypass_document_validation : Bool | Nil = nil, session : Session::ClientSession | Nil = nil) : Commands::Common::UpdateResult | Nil forall H
Updates multiple documents.
#update_one(filter, update, *, upsert : Bool = false, array_filters = nil, collation : Collation | Nil = nil, hint : String | H | Nil = nil, ordered : Bool | Nil = nil, write_concern : WriteConcern | Nil = nil, bypass_document_validation : Bool | Nil = nil, session : Session::ClientSession | Nil = nil) : Commands::Common::UpdateResult | Nil forall H
Updates one document.
#watch(pipeline : Array = [] of BSON, *, full_document : String | Nil = nil, start_at_operation_time : Time | Nil = nil, resume_after : BSON | Nil = nil, start_after : BSON | Nil = nil, max_await_time_ms : Int64 | Nil = nil, batch_size : Int32 | Nil = nil, collation : Collation | Nil = nil, read_concern : ReadConcern | Nil = nil, read_preference : ReadPreference | Nil = nil, session : Session::ClientSession | Nil = nil) : Mongo::ChangeStream::Cursor
Returns a ChangeStream::Cursor watching a specific collection.
#with_session(**args, &)
Initialize a session that has the same lifetime as the block.
#write_concern : WriteConcern | Nil
Write concern accessor.
#write_concern=(write_concern : WriteConcern | Nil)
Write concern accessor.

Instance Method Detail

Runs an aggregation framework pipeline.

NOTE for more details, please check the official MongoDB documentation.

def bulk(ordered : Bool = true, session : Session::ClientSession | Nil = nil) #

Create a Mongo::Bulk instance.

def bulk_write(requests : Array(Bulk::WriteModel), *, ordered : Bool, bypass_document_validation : Bool | Nil = nil, session : Session::ClientSession | Nil = nil) : Bulk::WriteResult #

Executes multiple write operations.

An error will be raised if the requests parameter is empty.

NOTE for more details, please check the official specifications document.

def command(operation, write_concern : WriteConcern | Nil = nil, read_concern : ReadConcern | Nil = nil, read_preference : ReadPreference | Nil = nil, session : Session::ClientSession | Nil = nil, **args, &) #

Execute a command on the server targeting the collection.

Will automatically set the collection and database arguments.

See: Mongo::Client.command

Execute a command on the server targeting the collection.

Will automatically set the collection and database arguments.

See: Mongo::Client.command

Count the number of documents in a collection that match the given filter. Note that an empty filter will force a scan of the entire collection. For a fast count of the total documents in a collection see #estimated_document_count.

See: the specification document.

This is a convenience method for creating a single index.

See: #create_indexes

Creates multiple indexes in the collection.

NOTE for more details, please check the official documentation.

def database : Mongo::Database #

The parent database.

Deletes multiple documents.

NOTE for more details, please check the official documentation.

Deletes one document.

NOTE for more details, please check the official documentation.

def distinct(key : String, *, filter = nil, read_concern : ReadConcern | Nil = nil, collation : Collation | Nil = nil, read_preference : ReadPreference | Nil = nil, session : Session::ClientSession | Nil = nil) : Array #

Finds the distinct values for a specified field across a single collection.

NOTE the results are backed by the "values" array in the distinct command's result document. This differs from aggregate and find, where results are backed by a cursor.

NOTE for more details, please check the official MongoDB documentation.

def drop_index(name : String, *, max_time_ms : Int64 | Nil = nil, write_concern : WriteConcern | Nil = nil, session : Session::ClientSession | Nil = nil) : Commands::Common::BaseResult | Nil #

Drops a single index from the collection by the index name.

See: #drop_indexes

def drop_indexes(*, max_time_ms : Int64 | Nil = nil, write_concern : WriteConcern | Nil = nil, session : Session::ClientSession | Nil = nil) : Commands::Common::BaseResult | Nil #

Drops all indexes in the collection.

NOTE for more details, please check the official documentation.

def estimated_document_count(*, max_time_ms : Int64 | Nil = nil, read_preference : ReadPreference | Nil = nil, session : Session::ClientSession | Nil = nil) : Int32 #

Gets an estimate of the count of documents in a collection using collection metadata.

See: the specification document.

Finds the documents matching the model.

NOTE for more details, please check the official MongoDB documentation.

NOTE for an overview of read operations, check the official manual.

Finds the document matching the model.

NOTE for more details, please check the official MongoDB documentation.

Finds a single document and deletes it, returning the original. The document to return may be nil.

NOTE for more details, please check the official documentation.

Finds a single document and replaces it, returning either the original or the replaced document. The document to return may be nil.

NOTE for more details, please check the official documentation.

Finds a single document and updates it, returning either the original or the updated document. The document to return may be nil.

NOTE for more details, please check the official documentation.

Inserts the provided document. If any documents are missing an identifier, they will be generated.

NOTE for more details, please check the official documentation.

def insert_one(document, *, write_concern : WriteConcern | Nil = nil, bypass_document_validation : Bool | Nil = nil, session : Session::ClientSession | Nil = nil) : Commands::Common::InsertResult | Nil #

Inserts the provided document. If the document is missing an identifier, it will be generated.

NOTE for more details, please check the official documentation.

def list_indexes(session : Session::ClientSession | Nil = nil) : Mongo::Cursor | Nil #

Gets index information for all indexes in the collection.

NOTE for more details, please check the official documentation.

def name : CollectionKey #

The collection name.

def read_concern : ReadConcern | Nil #

Read concern accessor.

See: the official documentation

def read_concern=(read_concern : ReadConcern | Nil) #

Read concern accessor.

See: the official documentation

def read_preference : ReadPreference | Nil #

ReadPreference accessor.

See: the official documentation.

def read_preference=(read_preference : ReadPreference | Nil) #

ReadPreference accessor.

See: the official documentation.

Replaces a single document.

NOTE for more details, please check the official documentation.

def stats(*, scale : Int32 | Nil = nil, session : Session::ClientSession | Nil = nil) : BSON | Nil #

Returns a variety of storage statistics for the collection.

NOTE for more details, please check the official MongoDB documentation.

Updates multiple documents.

NOTE for more details, please check the official documentation.

Updates one document.

NOTE for more details, please check the official documentation.

Returns a ChangeStream::Cursor watching a specific collection.

client = Mongo::Client.new
collection = client["db"]["coll"]

spawn {
  cursor = collection.watch(
    [
      {"$match": {"operationType": "insert"}},
    ],
    max_await_time_ms: 10000
  )
  # cursor.of(BSON) converts to the Mongo::ChangeStream::Document(BSON) type.
  cursor.of(BSON).each { |doc|
    puts doc.to_bson.to_json
  }
}

100.times do |i|
  collection.insert_one({count: i})
end

sleep

NOTE for more details, please check the official manual.

def with_session(**args, &) #

Initialize a session that has the same lifetime as the block.

First block argument is a reflection of the Collection instance with the session method argument already provided.
Second block argument is the ClientSession.

client = Mongo::Client.new
collection = client["db"]["coll"]

collection.with_session(causal_consistency: true) do |collection, session|
  5.times { |idx|
    # No need to provide: `session: session`.
    collection.insert_one({number: idx})
    collection.find_one({number: idx})
  }
end

def write_concern : WriteConcern | Nil #

Write concern accessor.

See: the official documentation

def write_concern=(write_concern : WriteConcern | Nil) #

Write concern accessor.

See: the official documentation