MongoCollection
public struct MongoCollection<T> where T : Decodable, T : Encodable
A MongoDB collection.
-
Encoder used by this collection for BSON conversions. (e.g. converting
CollectionType
s, indexes, and options to documents).Declaration
Swift
public var encoder: BSONEncoder { get }
-
Decoder used by this collection for BSON conversions (e.g. converting documents to
CollectionType
s).Declaration
Swift
public var decoder: BSONDecoder { get }
-
A
Codable
type associated with thisMongoCollection
instance. This allowsCollectionType
values to be directly inserted into and retrieved from the collection, by encoding/decoding them using theBSONEncoder
andBSONDecoder
. 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 namespace for this collection.
Declaration
Swift
public var namespace: MongoNamespace { get }
-
The name of this collection.
Declaration
Swift
public var name: String { get }
-
The
ReadConcern
set on this collection, ornil
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.
Declaration
Swift
public func drop(options: DropCollectionOptions? = nil, session: ClientSession? = nil) throws
-
Starts a
ChangeStream
on a collection. TheCollectionType
will be associated with thefullDocument
field inChangeStreamEvent
s emitted by the returnedChangeStream
. The server will return an error if this method is called on a system collection.Throws
Throws:
MongoError.CommandError
if an error occurs on the server while creating the change stream.MongoError.InvalidArgumentError
if the options passed formed an invalid combination.MongoError.InvalidArgumentError
if the_id
field is projected out of the change stream documents by the pipeline.
Declaration
Swift
public func watch( _ pipeline: [BSONDocument] = [], options: ChangeStreamOptions? = nil, session: ClientSession? = nil ) throws -> ChangeStream<ChangeStreamEvent<CollectionType>>
Parameters
pipeline
An array of aggregation pipeline stages to apply to the events returned by the change stream.
options
An optional
ChangeStreamOptions
to use when constructing the change stream.session
An optional
ClientSession
to use with this change stream.Return Value
A
ChangeStream
on a specific collection. -
Starts a
ChangeStream
on a collection. Associates the specifiedCodable
typeT
with thefullDocument
field in theChangeStreamEvent
s emitted by the returnedChangeStream
. The server will return an error if this method is called on a system collection.Throws
Throws:
MongoError.CommandError
if an error occurs on the server while creating the change stream.MongoError.InvalidArgumentError
if the options passed formed an invalid combination.MongoError.InvalidArgumentError
if the_id
field is projected out of the change stream documents by the pipeline.
Declaration
Swift
public func watch<FullDocType: Codable>( _ pipeline: [BSONDocument] = [], options: ChangeStreamOptions? = nil, session: ClientSession? = nil, withFullDocumentType _: FullDocType.Type ) throws -> ChangeStream<ChangeStreamEvent<FullDocType>>
Parameters
pipeline
An array of aggregation pipeline stages to apply to the events returned by the change stream.
options
An optional
ChangeStreamOptions
to use when constructing the change stream.session
An optional
ClientSession
to use with this change stream.withFullDocumentType
The type that the
fullDocument
field of the emittedChangeStreamEvent
s will be decoded to.Return Value
A
ChangeStream
on a specific collection. -
Starts a
ChangeStream
on a collection. Associates the specifiedCodable
typeT
with the returnedChangeStream
. The server will return an error if this method is called on a system collection.Throws
Throws:
MongoError.CommandError
if an error occurs on the server while creating the change stream.MongoError.InvalidArgumentError
if the options passed formed an invalid combination.MongoError.InvalidArgumentError
if the_id
field is projected out of the change stream documents by the pipeline.
Declaration
Swift
public func watch<EventType: Codable>( _ pipeline: [BSONDocument] = [], options: ChangeStreamOptions? = nil, session: ClientSession? = nil, withEventType _: EventType.Type ) throws -> ChangeStream<EventType>
Parameters
pipeline
An array of aggregation pipeline stages to apply to the events returned by the change stream.
options
An optional
ChangeStreamOptions
to use when constructing the change stream.session
An optional
ClientSession
to use with this change stream.withEventType
The type that the entire change stream response will be decoded to and that will be returned when iterating through the change stream.
Return Value
A
ChangeStream
on a specific collection. -
Finds a single document and deletes it, returning the original.
Throws
Throws:
MongoError.InvalidArgumentError
if any of the provided options are invalid.MongoError.LogicError
if the provided session is inactive.MongoError.CommandError
if an error occurs that prevents the command from executing.MongoError.WriteError
if an error occurs while executing the command.DecodingError
if the deleted document cannot be decoded to aCollectionType
value.
Declaration
Swift
@discardableResult public func findOneAndDelete( _ filter: BSONDocument, options: FindOneAndDeleteOptions? = nil, session: ClientSession? = nil ) throws -> CollectionType?
Parameters
filter
Document
representing the match criteriaoptions
Optional
FindOneAndDeleteOptions
to use when executing the commandsession
Optional
ClientSession
to use when executing this commandReturn Value
The deleted document, represented as a
CollectionType
, ornil
if no document was deleted. -
Finds a single document and replaces it, returning either the original or the replaced document.
Throws
Throws:
MongoError.InvalidArgumentError
if any of the provided options are invalid.MongoError.LogicError
if the provided session is inactive.MongoError.CommandError
if an error occurs that prevents the command from executing.MongoError.WriteError
if an error occurs while executing the command.DecodingError
if the replaced document cannot be decoded to aCollectionType
value.EncodingError
ifreplacement
cannot be encoded to aDocument
.
Declaration
Swift
@discardableResult public func findOneAndReplace( filter: BSONDocument, replacement: CollectionType, options: FindOneAndReplaceOptions? = nil, session: ClientSession? = nil ) throws -> CollectionType?
Parameters
filter
Document
representing the match criteriareplacement
a
CollectionType
to replace the found documentoptions
Optional
FindOneAndReplaceOptions
to use when executing the commandsession
Optional
ClientSession
to use when executing this commandReturn Value
A
CollectionType
, representing either the original document or its replacement, depending on selected options, ornil
if there was no match. -
Finds a single document and updates it, returning either the original or the updated document.
Throws
Throws:
MongoError.InvalidArgumentError
if any of the provided options are invalid.MongoError.LogicError
if the provided session is inactive.MongoError.CommandError
if an error occurs that prevents the command from executing.MongoError.WriteError
if an error occurs while executing the command.DecodingError
if the updated document cannot be decoded to aCollectionType
value.
Declaration
Swift
@discardableResult public func findOneAndUpdate( filter: BSONDocument, update: BSONDocument, options: FindOneAndUpdateOptions? = nil, session: ClientSession? = nil ) throws -> CollectionType?
Parameters
filter
Document
representing the match criteriaupdate
a
Document
containing updates to applyoptions
Optional
FindOneAndUpdateOptions
to use when executing the commandsession
Optional
ClientSession
to use when executing this commandReturn Value
A
CollectionType
representing either the original or updated document, depending on selected options, ornil
if there was no match. -
Creates an index over the collection for the provided keys with the provided options.
Throws
Throws:
MongoError.WriteError
if an error occurs while performing the write.MongoError.CommandError
if an error occurs that prevents the command from executing.MongoError.InvalidArgumentError
if the options passed in form an invalid combination.MongoError.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: BSONDocument, indexOptions: IndexOptions? = nil, options: CreateIndexOptions? = nil, session: ClientSession? = nil ) throws -> String
Parameters
keys
a
Document
specifing the keys for the indexindexOptions
Optional
IndexOptions
to use for the indexoptions
Optional
CreateIndexOptions
to use for the commandsession
Optional
ClientSession
to use when executing this commandReturn Value
The name of the created index.
-
Creates an index over the collection for the provided keys with the provided options.
Throws
Throws:
MongoError.WriteError
if an error occurs while performing the write.MongoError.CommandError
if an error occurs that prevents the command from executing.MongoError.InvalidArgumentError
if the options passed in form an invalid combination.MongoError.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 indexoptions
Optional
CreateIndexOptions
to use for the commandsession
Optional
ClientSession
to use when executing this commandReturn Value
The name of the created index.
-
Creates multiple indexes in the collection.
Throws
Throws:
MongoError.WriteError
if an error occurs while performing the write.MongoError.CommandError
if an error occurs that prevents the command from executing.MongoError.InvalidArgumentError
if the options passed in form an invalid combination.MongoError.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 createoptions
Optional
CreateIndexOptions
to use for the commandsession
Optional
ClientSession
to use when executing this commandReturn 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:
MongoError.WriteError
if an error occurs while performing the command.MongoError.CommandError
if an error occurs that prevents the command from executing.MongoError.InvalidArgumentError
if the options passed in form an invalid combination.EncodingError
if an error occurs while encoding the options.
Declaration
Swift
public func dropIndex( _ name: String, options: DropIndexOptions? = nil, session: ClientSession? = nil ) throws
Parameters
name
The name of the index to drop
options
Optional
DropIndexOptions
to use for the commandsession
Optional
ClientSession
to use when executing this command -
Attempts to drop a single index from the collection given the keys describing it.
Throws
Throws:
MongoError.WriteError
if an error occurs while performing the command.MongoError.CommandError
if an error occurs that prevents the command from executing.MongoError.InvalidArgumentError
if the options passed in form an invalid combination.MongoError.LogicError
if the provided session is inactive.EncodingError
if an error occurs while encoding the options.
Declaration
Swift
public func dropIndex( _ keys: BSONDocument, options: DropIndexOptions? = nil, session: ClientSession? = nil ) throws
Parameters
keys
a
Document
containing the keys for the index to dropoptions
Optional
DropIndexOptions
to use for the commandsession
Optional
ClientSession
to use when executing this command -
Attempts to drop a single index from the collection given an
IndexModel
describing it.Throws
Throws:
MongoError.WriteError
if an error occurs while performing the command.MongoError.CommandError
if an error occurs that prevents the command from executing.MongoError.InvalidArgumentError
if the options passed in form an invalid combination.MongoError.LogicError
if the provided session is inactive.EncodingError
if an error occurs while encoding the options.
Declaration
Swift
public func dropIndex( _ model: IndexModel, options: DropIndexOptions? = nil, session: ClientSession? = nil ) throws
Parameters
model
An
IndexModel
describing the index to dropoptions
Optional
DropIndexOptions
to use for the commandsession
Optional
ClientSession
to use when executing this command -
Drops all indexes in the collection.
Throws
Throws:
MongoError.WriteError
if an error occurs while performing the command.MongoError.CommandError
if an error occurs that prevents the command from executing.MongoError.InvalidArgumentError
if the options passed in form an invalid combination.MongoError.LogicError
if the provided session is inactive.EncodingError
if an error occurs while encoding the options.
Declaration
Swift
public func dropIndexes( options: DropIndexOptions? = nil, session: ClientSession? = nil ) throws
Parameters
options
Optional
DropIndexOptions
to use for the commandsession
Optional
ClientSession
to use when executing this command -
Retrieves a list of the indexes currently on this collection.
Throws
MongoError.LogicError
if the provided session is inactive.Declaration
Swift
public func listIndexes(session: ClientSession? = nil) throws -> MongoCursor<IndexModel>
Parameters
session
Optional
ClientSession
to use when executing this commandReturn Value
A
MongoCursor
over theIndexModel
s. -
Retrieves a list of names of the indexes currently on this collection.
Throws
MongoError.LogicError
if the provided session is inactive.Declaration
Swift
public func listIndexNames(session: ClientSession? = nil) throws -> [String]
Parameters
session
Optional
ClientSession
to use when executing this commandReturn Value
A
MongoCursor
over the index names. -
Finds the documents in this collection which match the provided filter.
Throws
Throws:
MongoError.InvalidArgumentError
if the options passed are an invalid combination.MongoError.LogicError
if the provided session is inactive.EncodingError
if an error occurs while encoding the options to BSON.
Declaration
Swift
public func find( _ filter: BSONDocument = [:], options: FindOptions? = nil, session: ClientSession? = nil ) throws -> MongoCursor<CollectionType>
Parameters
filter
A
Document
that should match the queryoptions
Optional
FindOptions
to use when executing the commandsession
Optional
ClientSession
to use when executing this commandReturn Value
A
MongoCursor
over the resultingDocument
s -
Finds a single document in this collection that matches the provided filter.
Throws
Throws:
MongoError.InvalidArgumentError
if the options passed are an invalid combination.MongoError.LogicError
if the provided session is inactive.EncodingError
if an error occurs while encoding the options to BSON.
Declaration
Swift
public func findOne( _ filter: BSONDocument = [:], options: FindOneOptions? = nil, session: ClientSession? = nil ) throws -> T?
Parameters
filter
A
Document
that should match the queryoptions
Optional
FindOneOptions
to use when executing the commandsession
Optional
ClientSession
to use when executing this commandReturn Value
the resulting
Document
, or nil if there is no match -
Runs an aggregation framework pipeline against this collection.
Throws
Throws:
MongoError.InvalidArgumentError
if the options passed are an invalid combination.MongoError.LogicError
if the provided session is inactive.EncodingError
if an error occurs while encoding the options to BSON.
Declaration
Swift
public func aggregate( _ pipeline: [BSONDocument], options: AggregateOptions? = nil, session: ClientSession? = nil ) throws -> MongoCursor<BSONDocument>
Parameters
pipeline
an
[Document]
containing the pipeline of aggregation operations to performoptions
Optional
AggregateOptions
to use when executing the commandsession
Optional
ClientSession
to use when executing this commandReturn Value
A
MongoCursor
over the resultingDocument
s -
Counts the number of documents in this collection matching the provided 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
estimatedDocumentCount
.Declaration
Swift
public func countDocuments( _ filter: BSONDocument = [:], options: CountDocumentsOptions? = nil, session: ClientSession? = nil ) throws -> Int
Parameters
filter
a
Document
, the filter that documents must match in order to be countedoptions
Optional
CountDocumentsOptions
to use when executing the commandsession
Optional
ClientSession
to use when executing this commandReturn Value
The count of the documents that matched the filter
-
Gets an estimate of the count of documents in this collection using collection metadata. This operation cannot be used in a transaction.
Declaration
Swift
public func estimatedDocumentCount(options: EstimatedDocumentCountOptions? = nil) throws -> Int
Parameters
options
Optional
EstimatedDocumentCountOptions
to use when executing the commandReturn Value
an estimate of the count of documents in this collection
-
Finds the distinct values for a specified field across the collection.
Throws
Throws:
MongoError.CommandError
if an error occurs that prevents the command from executing.MongoError.InvalidArgumentError
if the options passed in form an invalid combination.MongoError.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: BSONDocument = [:], options: DistinctOptions? = nil, session: ClientSession? = nil ) throws -> [BSON]
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 operationoptions
Optional
DistinctOptions
to use when executing the commandsession
Optional
ClientSession
to use when executing this commandReturn 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:
MongoError.WriteError
if an error occurs while performing the command.MongoError.CommandError
if an error occurs that prevents the command from executing.MongoError.InvalidArgumentError
if the options passed in form an invalid combination.MongoError.LogicError
if the provided session is inactive.EncodingError
if an error occurs while encoding theCollectionType
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 insertoptions
Optional
InsertOneOptions
to use when executing the commandsession
Optional
ClientSession
to use when executing this commandReturn 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:
MongoError.BulkWriteError
if an error occurs while performing any of the writes.MongoError.CommandError
if an error occurs that prevents the command from executing.MongoError.InvalidArgumentError
if the options passed in form an invalid combination.MongoError.LogicError
if the provided session is inactive.EncodingError
if an error occurs while encoding theCollectionType
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 insertoptions
optional
InsertManyOptions
to use while executing the operationsession
Optional
ClientSession
to use when executing this commandReturn Value
an
InsertManyResult
, ornil
if the write concern is unacknowledged. -
Replaces a single document matching the provided filter in this collection.
Throws
Throws:
MongoError.WriteError
if an error occurs while performing the command.MongoError.CommandError
if an error occurs that prevents the command from executing.MongoError.InvalidArgumentError
if the options passed in form an invalid combination.MongoError.LogicError
if the provided session is inactive.EncodingError
if an error occurs while encoding theCollectionType
or options to BSON.
Declaration
Swift
@discardableResult public func replaceOne( filter: BSONDocument, replacement: CollectionType, options: ReplaceOptions? = nil, session: ClientSession? = nil ) throws -> UpdateResult?
Parameters
filter
A
Document
representing the match criteriareplacement
The replacement value, a
CollectionType
value to be encoded and insertedoptions
Optional
ReplaceOptions
to use when executing the commandsession
Optional
ClientSession
to use when executing this commandReturn 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:
MongoError.WriteError
if an error occurs while performing the command.MongoError.CommandError
if an error occurs that prevents the command from executing.MongoError.InvalidArgumentError
if the options passed in form an invalid combination.MongoError.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: BSONDocument, update: BSONDocument, options: UpdateOptions? = nil, session: ClientSession? = nil ) throws -> UpdateResult?
Parameters
filter
A
Document
representing the match criteriaupdate
A
Document
representing the update to be applied to a matching documentoptions
Optional
UpdateOptions
to use when executing the commandsession
Optional
ClientSession
to use when executing this commandReturn 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:
MongoError.WriteError
if an error occurs while performing the command.MongoError.CommandError
if an error occurs that prevents the command from executing.MongoError.InvalidArgumentError
if the options passed in form an invalid combination.MongoError.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: BSONDocument, update: BSONDocument, options: UpdateOptions? = nil, session: ClientSession? = nil ) throws -> UpdateResult?
Parameters
filter
A
Document
representing the match criteriaupdate
A
Document
representing the update to be applied to matching documentsoptions
Optional
UpdateOptions
to use when executing the commandsession
Optional
ClientSession
to use when executing this commandReturn 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:
MongoError.WriteError
if an error occurs while performing the command.MongoError.CommandError
if an error occurs that prevents the command from executing.MongoError.InvalidArgumentError
if the options passed in form an invalid combination.MongoError.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: BSONDocument, options: DeleteOptions? = nil, session: ClientSession? = nil ) throws -> DeleteResult?
Parameters
filter
A
Document
representing the match criteriaoptions
Optional
DeleteOptions
to use when executing the commandsession
Optional
ClientSession
to use when executing this commandReturn Value
The optional result of performing the deletion. If the
WriteConcern
is unacknowledged,nil
is returned. -
Deletes multiple documents
Throws
Throws:
MongoError.WriteError
if an error occurs while performing the command.MongoError.CommandError
if an error occurs that prevents the command from executing.MongoError.InvalidArgumentError
if the options passed in form an invalid combination.MongoError.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: BSONDocument, options: DeleteOptions? = nil, session: ClientSession? = nil ) throws -> DeleteResult?
Parameters
filter
Document representing the match criteria
options
Optional
DeleteOptions
to use when executing the commandsession
Optional
ClientSession
to use when executing this commandReturn Value
The optional result of performing the deletion. If the
WriteConcern
is unacknowledged,nil
is returned. -
Execute multiple write operations.
Throws
Throws:
MongoError.InvalidArgumentError
ifrequests
is empty.MongoError.LogicError
if the provided session is inactive.MongoError.BulkWriteError
if any error occurs while performing the writes. This includes errors that would typically be thrown asRuntimeError
s orMongoError.CommandError
s elsewhere.EncodingError
if an error occurs while encoding theCollectionType
or the options to BSON.
Declaration
Swift
@discardableResult public func bulkWrite( _ requests: [WriteModel<T>], 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.session
Optional
ClientSession
to use when executing this commandReturn Value
a
BulkWriteResult
, ornil
if the write concern is unacknowledged.