MongoCollection

public class MongoCollection<T> where T : Decodable, T : Encodable

A MongoDB collection.

  • Encoder used by this collection for BSON conversions. (e.g. converting CollectionTypes, indexes, and options to documents).

    Declaration

    Swift

    public let encoder: BSONEncoder
  • Decoder used by this collection for BSON conversions (e.g. converting documents to CollectionTypes).

    Declaration

    Swift

    public let decoder: BSONDecoder
  • A Codable type associated with this MongoCollection instance. This allows CollectionType values to be directly inserted into and retrieved from the collection, by encoding/decoding them using the BSONEncoder and BSONDecoder. The strategies to be used by the encoder and decoder for certain types can be configured by setting the coding strategies on the options used to create this collection instance. The default strategies are inherited from those set on the database this collection derived from.

    This type association only exists in the context of this particular MongoCollection instance. It is the responsibility of the user to ensure that any data already stored in the collection was encoded from this same type and according to the coding strategies set on this instance.

    Declaration

    Swift

    public typealias CollectionType = T
  • The name of this collection.

    Declaration

    Swift

    public var name: String { get }
  • The ReadConcern set on this collection, or nil if one is not set.

    Declaration

    Swift

    public var readConcern: ReadConcern? { get }
  • The ReadPreference set on this collection.

    Declaration

    Swift

    public var readPreference: ReadPreference { get }
  • The WriteConcern set on this collection, or nil if one is not set.

    Declaration

    Swift

    public var writeConcern: WriteConcern? { get }
  • Drops this collection from its parent database.

    Throws

    • ServerError.commandError if an error occurs that prevents the command from executing.

    Declaration

    Swift

    public func drop(session: ClientSession? = nil) throws
  • Execute multiple write operations.

    Throws

    Throws:

    • UserError.invalidArgumentError if requests is empty.
    • UserError.logicError if the provided session is inactive.
    • ServerError.bulkWriteError if any error occurs while performing the writes.
    • ServerError.commandError if an error occurs that prevents the operation from being performed.
    • EncodingError if an error occurs while encoding the CollectionType or the options to BSON.

    Declaration

    Swift

    @discardableResult
    public func bulkWrite(_ requests: [WriteModel],
                          options: BulkWriteOptions? = nil,
                          session: ClientSession? = nil) throws -> BulkWriteResult?

    Parameters

    requests

    a [WriteModel] containing the writes to perform.

    options

    optional BulkWriteOptions to use while executing the operation.

    Return Value

    a BulkWriteResult, or nil if the write concern is unacknowledged.

  • A model for a deleteOne operation within a bulk write.

    See more

    Declaration

    Swift

    public struct DeleteOneModel : WriteModel, Decodable
  • A model for a deleteMany operation within a bulk write.

    See more

    Declaration

    Swift

    public struct DeleteManyModel : WriteModel, Decodable
  • A model for an insertOne operation within a bulk write.

    See more

    Declaration

    Swift

    public struct InsertOneModel : WriteModel, Decodable
  • A model for a replaceOne operation within a bulk write.

    See more

    Declaration

    Swift

    public struct ReplaceOneModel : WriteModel, Decodable
  • A model for an updateOne operation within a bulk write.

    See more

    Declaration

    Swift

    public struct UpdateOneModel : WriteModel, Decodable
  • A model for an updateMany operation within a bulk write.

    See more

    Declaration

    Swift

    public struct UpdateManyModel : WriteModel, Decodable
  • Finds a single document and deletes it, returning the original.

    Throws

    Throws:

    • UserError.invalidArgumentError if any of the provided options are invalid.
    • UserError.logicError if the provided session is inactive.
    • ServerError.commandError if an error occurs that prevents the command from executing.
    • ServerError.writeError if an error occurs while executing the command.
    • DecodingError if the deleted document cannot be decoded to a CollectionType value.

    Declaration

    Swift

    @discardableResult
    public func findOneAndDelete(_ filter: Document,
                                 options: FindOneAndDeleteOptions? = nil,
                                 session: ClientSession? = nil) throws -> CollectionType?

    Parameters

    filter

    Document representing the match criteria

    options

    Optional FindOneAndDeleteOptions to use when executing the command

    Return Value

    The deleted document, represented as a CollectionType, or nil if no document was deleted.

  • Finds a single document and replaces it, returning either the original or the replaced document.

    Throws

    Throws:

    • UserError.invalidArgumentError if any of the provided options are invalid.
    • UserError.logicError if the provided session is inactive.
    • ServerError.commandError if an error occurs that prevents the command from executing.
    • ServerError.writeError if an error occurs while executing the command.
    • DecodingError if the replaced document cannot be decoded to a CollectionType value.
    • EncodingError if replacement cannot be encoded to a Document.

    Declaration

    Swift

    @discardableResult
    public func findOneAndReplace(filter: Document,
                                  replacement: CollectionType,
                                  options: FindOneAndReplaceOptions? = nil,
                                  session: ClientSession? = nil) throws -> CollectionType?

    Parameters

    filter

    Document representing the match criteria

    replacement

    a CollectionType to replace the found document

    options

    Optional FindOneAndReplaceOptions to use when executing the command

    Return Value

    A CollectionType, representing either the original document or its replacement, depending on selected options, or nil if there was no match.

  • Finds a single document and updates it, returning either the original or the updated document.

    Throws

    Throws:

    • UserError.invalidArgumentError if any of the provided options are invalid.
    • UserError.logicError if the provided session is inactive.
    • ServerError.commandError if an error occurs that prevents the command from executing.
    • ServerError.writeError if an error occurs while executing the command.
    • DecodingError if the updated document cannot be decoded to a CollectionType value.

    Declaration

    Swift

    @discardableResult
    public func findOneAndUpdate(filter: Document,
                                 update: Document,
                                 options: FindOneAndUpdateOptions? = nil,
                                 session: ClientSession? = nil) throws -> CollectionType?

    Parameters

    filter

    Document representing the match criteria

    update

    a Document containing updates to apply

    options

    Optional FindOneAndUpdateOptions to use when executing the command

    Return Value

    A CollectionType representing either the original or updated document, depending on selected options, or nil if there was no match.

  • Creates an index over the collection for the provided keys with the provided options.

    Throws

    Throws:

    • ServerError.writeError if an error occurs while performing the write.
    • ServerError.commandError if an error occurs that prevents the command from executing.
    • UserError.invalidArgumentError if the options passed in form an invalid combination.
    • UserError.logicError if the provided session is inactive.
    • EncodingError if an error occurs while encoding the index specification or options.

    Declaration

    Swift

    @discardableResult
    public func createIndex(_ keys: Document,
                            options: IndexOptions? = nil,
                            commandOptions: CreateIndexOptions? = nil,
                            session: ClientSession? = nil) throws -> String

    Parameters

    keys

    a Document specifing the keys for the index

    options

    Optional IndexOptions to use for the index

    commandOptions

    Optional CreateIndexOptions to use for the command

    Return Value

    The name of the created index.

  • Creates an index over the collection for the provided keys with the provided options.

    Throws

    Throws:

    • ServerError.writeError if an error occurs while performing the write.
    • ServerError.commandError if an error occurs that prevents the command from executing.
    • UserError.invalidArgumentError if the options passed in form an invalid combination.
    • UserError.logicError if the provided session is inactive.
    • EncodingError if an error occurs while encoding the index specification or options.

    Declaration

    Swift

    @discardableResult
    public func createIndex(_ model: IndexModel,
                            options: CreateIndexOptions? = nil,
                            session: ClientSession? = nil) throws -> String

    Parameters

    model

    An IndexModel representing the keys and options for the index

    options

    Optional CreateIndexOptions to use for the command

    Return Value

    The name of the created index.

  • Creates multiple indexes in the collection.

    Throws

    Throws:

    • ServerError.writeError if an error occurs while performing the write.
    • ServerError.commandError if an error occurs that prevents the command from executing.
    • UserError.invalidArgumentError if the options passed in form an invalid combination.
    • UserError.logicError if the provided session is inactive.
    • EncodingError if an error occurs while encoding the index specifications or options.

    Declaration

    Swift

    @discardableResult
    public func createIndexes(_ models: [IndexModel],
                              options: CreateIndexOptions? = nil,
                              session: ClientSession? = nil) throws -> [String]

    Parameters

    models

    An [IndexModel] specifying the indexes to create

    options

    Optional CreateIndexOptions to use for the command

    Return Value

    An [String] containing the names of all the indexes that were created.

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

    Throws

    Throws:

    • ServerError.writeError if an error occurs while performing the command.
    • ServerError.commandError if an error occurs that prevents the command from executing.
    • UserError.invalidArgumentError if the options passed in form an invalid combination.
    • EncodingError if an error occurs while encoding the options.

    Declaration

    Swift

    @discardableResult
    public func dropIndex(_ name: String,
                          options: DropIndexOptions? = nil,
                          session: ClientSession? = nil) throws -> Document

    Parameters

    name

    The name of the index to drop

    options

    Optional DropIndexOptions to use for the command

  • Attempts to drop a single index from the collection given the keys describing it.

    Throws

    Throws:

    • ServerError.writeError if an error occurs while performing the command.
    • ServerError.commandError if an error occurs that prevents the command from executing.
    • UserError.invalidArgumentError if the options passed in form an invalid combination.
    • UserError.logicError if the provided session is inactive.
    • EncodingError if an error occurs while encoding the options.

    Declaration

    Swift

    @discardableResult
    public func dropIndex(_ keys: Document,
                          commandOptions: DropIndexOptions? = nil,
                          session: ClientSession? = nil) throws -> Document

    Parameters

    keys

    a Document containing the keys for the index to drop

    options

    Optional DropIndexOptions to use for the command

    Return Value

    a Document containing the server’s response to the command.

  • Attempts to drop a single index from the collection given an IndexModel describing it.

    Throws

    Throws:

    • ServerError.writeError if an error occurs while performing the command.
    • ServerError.commandError if an error occurs that prevents the command from executing.
    • UserError.invalidArgumentError if the options passed in form an invalid combination.
    • UserError.logicError if the provided session is inactive.
    • EncodingError if an error occurs while encoding the options.

    Declaration

    Swift

    @discardableResult
    public func dropIndex(_ model: IndexModel,
                          options: DropIndexOptions? = nil,
                          session: ClientSession? = nil) throws -> Document

    Parameters

    model

    An IndexModel describing the index to drop

    options

    Optional DropIndexOptions to use for the command

    Return Value

    a Document containing the server’s response to the command.

  • Drops all indexes in the collection.

    Throws

    Throws:

    • ServerError.writeError if an error occurs while performing the command.
    • ServerError.commandError if an error occurs that prevents the command from executing.
    • UserError.invalidArgumentError if the options passed in form an invalid combination.
    • UserError.logicError if the provided session is inactive.
    • EncodingError if an error occurs while encoding the options.

    Declaration

    Swift

    @discardableResult
    public func dropIndexes(options: DropIndexOptions? = nil, session: ClientSession? = nil) throws -> Document

    Parameters

    options

    Optional DropIndexOptions to use for the command

    Return Value

    a Document containing the server’s response to the command.

  • Retrieves a list of the indexes currently on this collection.

    Throws

    UserError.logicError if the provided session is inactive.

    Declaration

    Swift

    public func listIndexes(session: ClientSession? = nil) throws -> MongoCursor<Document>

    Return Value

    A MongoCursor over the index names.

  • Finds the documents in this collection which match the provided filter.

    Throws

    Throws:

    • UserError.invalidArgumentError if the options passed are an invalid combination.
    • UserError.logicError if the provided session is inactive.
    • EncodingError if an error occurs while encoding the options to BSON.

    Declaration

    Swift

    public func find(_ filter: Document = [:],
                     options: FindOptions? = nil,
                     session: ClientSession? = nil) throws -> MongoCursor<CollectionType>

    Parameters

    filter

    A Document that should match the query

    options

    Optional FindOptions to use when executing the command

    Return Value

    A MongoCursor over the resulting Documents

  • Runs an aggregation framework pipeline against this collection.

    Throws

    Throws:

    • UserError.invalidArgumentError if the options passed are an invalid combination.
    • UserError.logicError if the provided session is inactive.
    • EncodingError if an error occurs while encoding the options to BSON.

    Declaration

    Swift

    public func aggregate(_ pipeline: [Document],
                          options: AggregateOptions? = nil,
                          session: ClientSession? = nil) throws -> MongoCursor<Document>

    Parameters

    pipeline

    an [Document] containing the pipeline of aggregation operations to perform

    options

    Optional AggregateOptions to use when executing the command

    Return Value

    A MongoCursor over the resulting Documents

  • Counts the number of documents in this collection matching the provided filter.

    Throws

    Throws:

    • ServerError.commandError if an error occurs that prevents the command from performing the write.
    • UserError.invalidArgumentError if the options passed in form an invalid combination.
    • EncodingError if an error occurs while encoding the options to BSON.

    Declaration

    Swift

    public func count(_ filter: Document = [:],
                      options: CountOptions? = nil,
                      session: ClientSession? = nil) throws -> Int

    Parameters

    filter

    a Document, the filter that documents must match in order to be counted

    options

    Optional CountOptions to use when executing the command

    Return Value

    The count of the documents that matched the filter

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

    Throws

    Throws:

    • ServerError.commandError if an error occurs that prevents the command from executing.
    • UserError.invalidArgumentError if the options passed in form an invalid combination.
    • UserError.logicError if the provided session is inactive.
    • EncodingError if an error occurs while encoding the options to BSON.

    Declaration

    Swift

    public func distinct(fieldName: String,
                         filter: Document = [:],
                         options: DistinctOptions? = nil,
                         session: ClientSession? = nil) throws -> [BSONValue]

    Parameters

    fieldName

    The field for which the distinct values will be found

    filter

    a Document representing the filter documents must match in order to be considered for the operation

    options

    Optional DistinctOptions to use when executing the command

    Return Value

    A [BSONValue] containing the distinct values for the specified criteria

  • Encodes the provided value to BSON and inserts it. If the value is missing an identifier, one will be generated for it.

    Throws

    Throws:

    • ServerError.writeError if an error occurs while performing the command.
    • ServerError.commandError if an error occurs that prevents the command from executing.
    • UserError.invalidArgumentError if the options passed in form an invalid combination.
    • UserError.logicError if the provided session is inactive.
    • EncodingError if an error occurs while encoding the CollectionType to BSON.

    Declaration

    Swift

    @discardableResult
    public func insertOne(_ value: CollectionType,
                          options: InsertOneOptions? = nil,
                          session: ClientSession? = nil) throws -> InsertOneResult?

    Parameters

    value

    A CollectionType value to encode and insert

    options

    Optional InsertOneOptions to use when executing the command

    Return Value

    The optional result of attempting to perform the insert. If the WriteConcern is unacknowledged, nil is returned.

  • Encodes the provided values to BSON and inserts them. If any values are missing identifiers, the driver will generate them.

    Throws

    Throws:

    • ServerError.bulkWriteError if an error occurs while performing any of the writes.
    • ServerError.commandError if an error occurs that prevents the command from executing.
    • UserError.invalidArgumentError if the options passed in form an invalid combination.
    • UserError.logicError if the provided session is inactive.
    • EncodingError if an error occurs while encoding the CollectionType or options to BSON.

    Declaration

    Swift

    @discardableResult
    public func insertMany(_ values: [CollectionType],
                           options: InsertManyOptions? = nil,
                           session: ClientSession? = nil) throws -> InsertManyResult?

    Parameters

    values

    The CollectionType values to insert

    options

    optional InsertManyOptions to use while executing the operation

    Return Value

    an InsertManyResult, or nil if the write concern is unacknowledged.

  • Replaces a single document matching the provided filter in this collection.

    Throws

    Throws:

    • ServerError.writeError if an error occurs while performing the command.
    • ServerError.commandError if an error occurs that prevents the command from executing.
    • UserError.invalidArgumentError if the options passed in form an invalid combination.
    • UserError.logicError if the provided session is inactive.
    • EncodingError if an error occurs while encoding the CollectionType or options to BSON.

    Declaration

    Swift

    @discardableResult
    public func replaceOne(filter: Document,
                           replacement: CollectionType,
                           options: ReplaceOptions? = nil,
                           session: ClientSession? = nil) throws -> UpdateResult?

    Parameters

    filter

    A Document representing the match criteria

    replacement

    The replacement value, a CollectionType value to be encoded and inserted

    options

    Optional ReplaceOptions to use when executing the command

    Return Value

    The optional result of attempting to replace a document. If the WriteConcern is unacknowledged, nil is returned.

  • Updates a single document matching the provided filter in this collection.

    Throws

    Throws:

    • ServerError.writeError if an error occurs while performing the command.
    • ServerError.commandError if an error occurs that prevents the command from executing.
    • UserError.invalidArgumentError if the options passed in form an invalid combination.
    • UserError.logicError if the provided session is inactive.
    • EncodingError if an error occurs while encoding the options to BSON.

    Declaration

    Swift

    @discardableResult
    public func updateOne(filter: Document,
                          update: Document,
                          options: UpdateOptions? = nil,
                          session: ClientSession? = nil) throws -> UpdateResult?

    Parameters

    filter

    A Document representing the match criteria

    update

    A Document representing the update to be applied to a matching document

    options

    Optional UpdateOptions to use when executing the command

    Return Value

    The optional result of attempting to update a document. If the WriteConcern is unacknowledged, nil is returned.

  • Updates multiple documents matching the provided filter in this collection.

    Throws

    Throws:

    • ServerError.writeError if an error occurs while performing the command.
    • ServerError.commandError if an error occurs that prevents the command from executing.
    • UserError.invalidArgumentError if the options passed in form an invalid combination.
    • UserError.logicError if the provided session is inactive.
    • EncodingError if an error occurs while encoding the options to BSON.

    Declaration

    Swift

    @discardableResult
    public func updateMany(filter: Document,
                           update: Document,
                           options: UpdateOptions? = nil,
                           session: ClientSession? = nil) throws -> UpdateResult?

    Parameters

    filter

    A Document representing the match criteria

    update

    A Document representing the update to be applied to matching documents

    options

    Optional UpdateOptions to use when executing the command

    Return Value

    The optional result of attempting to update multiple documents. If the write concern is unacknowledged, nil is returned

  • Deletes a single matching document from the collection.

    Throws

    Throws:

    • ServerError.writeError if an error occurs while performing the command.
    • ServerError.commandError if an error occurs that prevents the command from executing.
    • UserError.invalidArgumentError if the options passed in form an invalid combination.
    • UserError.logicError if the provided session is inactive.
    • EncodingError if an error occurs while encoding the options to BSON.

    Declaration

    Swift

    @discardableResult
    public func deleteOne(_ filter: Document,
                          options: DeleteOptions? = nil,
                          session: ClientSession? = nil) throws -> DeleteResult?

    Parameters

    filter

    A Document representing the match criteria

    options

    Optional DeleteOptions to use when executing the command

    Return Value

    The optional result of performing the deletion. If the WriteConcern is unacknowledged, nil is returned.

  • Deletes multiple documents

    Throws

    Throws:

    • ServerError.writeError if an error occurs while performing the command.
    • ServerError.commandError if an error occurs that prevents the command from executing.
    • UserError.invalidArgumentError if the options passed in form an invalid combination.
    • UserError.logicError if the provided session is inactive.
    • EncodingError if an error occurs while encoding the options to BSON.

    Declaration

    Swift

    @discardableResult
    public func deleteMany(_ filter: Document,
                           options: DeleteOptions? = nil,
                           session: ClientSession? = nil) throws -> DeleteResult?

    Parameters

    filter

    Document representing the match criteria

    options

    Optional DeleteOptions to use when executing the command

    Return Value

    The optional result of performing the deletion. If the WriteConcern is unacknowledged, nil is returned.