MongoCollection
public class 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 let encoder: BSONEncoder
-
Decoder used by this collection for BSON conversions (e.g. converting documents to
CollectionType
s).Declaration
Swift
public let decoder: BSONDecoder
-
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 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 collectionDeclaration
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 }
-
Cleans up internal state.
Declaration
Swift
deinit
-
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() throws
-
Execute multiple write operations.
Throws
Throws:
UserError.invalidArgumentError
ifrequests
is empty.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 theCollectionType
or the options to BSON.
Declaration
Swift
@discardableResult public func bulkWrite(_ requests: [WriteModel], options: BulkWriteOptions? = 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
, ornil
if the write concern is unacknowledged. -
A model for a
See moredeleteOne
operation within a bulk write.Declaration
Swift
public struct DeleteOneModel : WriteModel
-
A model for a
See moredeleteMany
operation within a bulk write.Declaration
Swift
public struct DeleteManyModel : WriteModel
-
A model for an
See moreinsertOne
operation within a bulk write.Declaration
Swift
public struct InsertOneModel : WriteModel
-
A model for a
See morereplaceOne
operation within a bulk write.Declaration
Swift
public struct ReplaceOneModel : WriteModel
-
A model for an
See moreupdateOne
operation within a bulk write.Declaration
Swift
public struct UpdateOneModel : WriteModel
-
A model for an
See moreupdateMany
operation within a bulk write.Declaration
Swift
public struct UpdateManyModel : WriteModel
-
Finds a single document and deletes it, returning the original.
Throws
Throws:
UserError.invalidArgumentError
if any of the provided options are invalid.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 aCollectionType
value.
Declaration
Swift
@discardableResult public func findOneAndDelete(_ filter: Document, options: FindOneAndDeleteOptions? = nil) throws -> CollectionType?
Parameters
filter
Document
representing the match criteriaoptions
Optional
FindOneAndDeleteOptions
to use when executing the 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:
UserError.invalidArgumentError
if any of the provided options are invalid.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 aCollectionType
value.EncodingError
ifreplacement
cannot be encoded to aDocument
.
Declaration
Swift
@discardableResult public func findOneAndReplace(filter: Document, replacement: CollectionType, options: FindOneAndReplaceOptions? = nil) throws -> CollectionType?
Parameters
filter
Document
representing the match criteriareplacement
a
CollectionType
to replace the found documentoptions
Optional
FindOneAndReplaceOptions
to use when executing the 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:
UserError.invalidArgumentError
if any of the provided options are invalid.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 aCollectionType
value.
Declaration
Swift
@discardableResult public func findOneAndUpdate(filter: Document, update: Document, options: FindOneAndUpdateOptions? = nil) throws -> CollectionType?
Parameters
filter
Document
representing the match criteriaupdate
a
Document
containing updates to applyoptions
Optional
FindOneAndUpdateOptions
to use when executing the 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:
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.EncodingError
if an error occurs while encoding the index specification or options.
Declaration
Swift
@discardableResult public func createIndex(_ forModel: IndexModel, options: CreateIndexOptions? = nil) throws -> String
Parameters
model
An
IndexModel
representing the keys and options for the indexwriteConcern
Optional WriteConcern 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.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) throws -> String
Parameters
keys
a
Document
specifing the keys for the indexoptions
Optional
IndexOptions
to use for the indexwriteConcern
Optional
WriteConcern
to use for the commandReturn 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.EncodingError
if an error occurs while encoding the index specifications or options.
Declaration
Swift
@discardableResult public func createIndexes(_ forModels: [IndexModel], options: CreateIndexOptions? = nil) throws -> [String]
Parameters
models
An
[IndexModel]
specifying the indexes to createwriteConcern
Optional
WriteConcern
to use for the 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:
ServerError.commandError
if an error occurs that prevents the command from executing.UserError.invalidArgumentError
if the options passed in form an invalid combination.
Declaration
Swift
public func dropIndex(_ name: String, options: DropIndexOptions? = nil) throws
Parameters
name
The name of the index to drop
writeConcern
An optional WriteConcern to use for the command
-
Attempts to drop a single index from the collection given the keys and options 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.EncodingError
if an error occurs while encoding the options.
Declaration
Swift
@discardableResult public func dropIndex(_ keys: Document, options: IndexOptions? = nil, commandOptions: DropIndexOptions? = nil) throws -> Document
Parameters
keys
a
Document
containing the keys for the index to dropoptions
Optional
IndexOptions
the dropped index should matchwriteConcern
An optional
WriteConcern
to use for the commandReturn 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.EncodingError
if an error occurs while encoding the options.
Declaration
Swift
@discardableResult public func dropIndex(_ model: IndexModel, options: DropIndexOptions? = nil) throws -> Document
Parameters
model
An
IndexModel
describing the index to dropwriteConcern
An optional
WriteConcern
to use for the commandReturn 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.EncodingError
if an error occurs while encoding the options.
Declaration
Swift
@discardableResult public func dropIndexes(options: DropIndexOptions? = nil) throws -> Document
Parameters
writeConcern
An optional
WriteConcern
to use for the commandReturn Value
a
Document
containing the server’s response to the command. -
Retrieves a list of the indexes currently on this collection.
Throws
A
userError.invalidArgumentError
if the options passed are an invalid combination.Declaration
Swift
public func listIndexes() 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.EncodingError
if an error occurs while encoding the options to BSON.
Declaration
Swift
public func find(_ filter: Document = [:], options: FindOptions? = nil) throws -> MongoCursor<CollectionType>
Parameters
filter
A
Document
that should match the queryoptions
Optional
FindOptions
to use when executing the commandReturn Value
A
MongoCursor
over the resultingDocument
s -
Runs an aggregation framework pipeline against this collection.
Throws
Throws:
UserError.invalidArgumentError
if the options passed are an invalid combination.EncodingError
if an error occurs while encoding the options to BSON.
Declaration
Swift
public func aggregate(_ pipeline: [Document], options: AggregateOptions? = nil) throws -> MongoCursor<Document>
Parameters
pipeline
an
[Document]
containing the pipeline of aggregation operations to performoptions
Optional
AggregateOptions
to use when executing the commandReturn Value
A
MongoCursor
over the resultingDocument
s -
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) throws -> Int
Parameters
filter
a
Document
, the filter that documents must match in order to be countedoptions
Optional
CountOptions
to use when executing the commandReturn 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.EncodingError
if an error occurs while encoding the options to BSON.
Declaration
Swift
public func distinct(fieldName: String, filter: Document = [:], options: DistinctOptions? = 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 operationoptions
Optional
DistinctOptions
to use when executing the 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:
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 theCollectionType
to BSON.
Declaration
Swift
@discardableResult public func insertOne(_ value: CollectionType, options: InsertOneOptions? = nil) throws -> InsertOneResult?
Parameters
value
A
CollectionType
value to encode and insertoptions
Optional
InsertOneOptions
to use when executing the 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:
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.EncodingError
if an error occurs while encoding theCollectionType
or options to BSON.
Declaration
Swift
@discardableResult public func insertMany(_ values: [CollectionType], options: InsertManyOptions? = nil) throws -> InsertManyResult?
Parameters
values
The
CollectionType
values to insertoptions
optional
InsertManyOptions
to use while executing the operationReturn Value
an
InsertManyResult
, ornil
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.EncodingError
if an error occurs while encoding theCollectionType
or options to BSON.
Declaration
Swift
@discardableResult public func replaceOne(filter: Document, replacement: CollectionType, options: ReplaceOptions? = 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 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:
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 to BSON.
Declaration
Swift
@discardableResult public func updateOne(filter: Document, update: Document, options: UpdateOptions? = 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 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:
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 to BSON.
Declaration
Swift
@discardableResult public func updateMany(filter: Document, update: Document, options: UpdateOptions? = 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 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:
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 to BSON.
Declaration
Swift
@discardableResult public func deleteOne(_ filter: Document, options: DeleteOptions? = nil) throws -> DeleteResult?
Parameters
filter
A
Document
representing the match criteriaoptions
Optional
DeleteOptions
to use when executing the commandReturn 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.EncodingError
if an error occurs while encoding the options to BSON.
Declaration
Swift
@discardableResult public func deleteMany(_ filter: Document, options: DeleteOptions? = nil) throws -> DeleteResult?
Parameters
filter
Document representing the match criteria
options
Optional
DeleteOptions
to use when executing the commandReturn Value
The optional result of performing the deletion. If the
WriteConcern
is unacknowledged,nil
is returned.