MongoClient
public class MongoClient
extension MongoClient: Equatable
A MongoDB Client providing a synchronous API.
-
Encoder whose options are inherited by databases derived from this client.
Declaration
Swift
public var encoder: BSONEncoder { get }
-
Decoder whose options are inherited by databases derived from this client.
Declaration
Swift
public var decoder: BSONDecoder { get }
-
The read concern set on this client, or nil if one is not set.
Declaration
Swift
public var readConcern: ReadConcern? { get }
-
The
ReadPreference
set on this client.Declaration
Swift
public var readPreference: ReadPreference { get }
-
The write concern set on this client, or nil if one is not set.
Declaration
Swift
public var writeConcern: WriteConcern? { get }
-
Create a new client connection to a MongoDB server. For options that included in both the connection string URI and the MongoClientOptions struct, the final value is set in descending order of priority: the value specified in MongoClientOptions (if non-nil), the value specified in the URI, or the default value if both are unset.
Throws
Throws:
- A
MongoError.InvalidArgumentError
if the connection string passed in is improperly formatted. - A
MongoError.InvalidArgumentError
if the connection string specifies the use of TLS but libmongoc was not built with TLS support.
Declaration
Swift
public init(_ connectionString: String = "mongodb://localhost:27017", options: MongoClientOptions? = nil) throws
Parameters
connectionString
the connection string to connect to.
options
optional
MongoClientOptions
to use for this client - A
-
Starts a new
ClientSession
with the provided options.Declaration
Swift
public func startSession(options: ClientSessionOptions? = nil) -> ClientSession
-
Starts a new
ClientSession
with the provided options and passes it to the provided closure. The session is only valid within the body of the closure and will be ended after the body completes.Throws
RuntimeError.compatibilityError
if the deployment does not support sessions.
Declaration
Swift
public func withSession<T>( options: ClientSessionOptions? = nil, _ sessionBody: (ClientSession) throws -> T ) rethrows -> T
-
Run the
listDatabases
command.Throws
Throws:
MongoError.LogicError
if the provided session is inactive.EncodingError
if an error is encountered while encoding the options to BSON.MongoError.CommandError
if options.authorizedDatabases is false and the user does not have listDatabases permissions.
Declaration
Swift
public func listDatabases( _ filter: BSONDocument? = nil, options: ListDatabasesOptions? = nil, session: ClientSession? = nil ) throws -> [DatabaseSpecification]
Parameters
filter
Optional
Document
specifying a filter that the listed databases must pass. This filter can be based on the “name”, “sizeOnDisk”, “empty”, or “shards” fields of the output.options
Optional
ListDatabasesOptions
specifying options for listing databases.session
Optional
ClientSession
to use when executing this command.Return Value
A
[DatabaseSpecification]
containing the databases matching provided criteria. -
Get a list of
MongoDatabase
s.Throws
Throws:
MongoError.LogicError
if the provided session is inactive.MongoError.CommandError
if options.authorizedDatabases is false and the user does not have listDatabases permissions.
Declaration
Swift
public func listMongoDatabases( _ filter: BSONDocument? = nil, options: ListDatabasesOptions? = nil, session: ClientSession? = nil ) throws -> [MongoDatabase]
Parameters
filter
Optional
Document
specifying a filter on the names of the returned databases.options
Optional
ListDatabasesOptions
specifying options for listing databases.session
Optional
ClientSession
to use when executing this commandReturn Value
An Array of
MongoDatabase
s that match the provided filter. -
Get a list of names of databases.
Throws
Throws:
MongoError.LogicError
if the provided session is inactive.MongoError.CommandError
if options.authorizedDatabases is false and the user does not have listDatabases permissions.
Declaration
Swift
public func listDatabaseNames( _ filter: BSONDocument? = nil, options: ListDatabasesOptions? = nil, session: ClientSession? = nil ) throws -> [String]
Parameters
filter
Optional
Document
specifying a filter on the names of the returned databases.options
Optional
ListDatabasesOptions
specifying options for listing databases.session
Optional
ClientSession
to use when executing this commandReturn Value
A
[String]
containing names of databases that match the provided filter. -
Gets a
MongoDatabase
instance for the given database name. If an option is not specified in the optionalMongoDatabaseOptions
param, the database will inherit the value from the parent client or the default if the client’s option is not set. To override an option inherited from the client (e.g. a read concern) with the default value, it must be explicitly specified in the options param (e.g. ReadConcern.serverDefault, not nil).Declaration
Swift
public func db(_ name: String, options: MongoDatabaseOptions? = nil) -> MongoDatabase
Parameters
name
the name of the database to retrieve
options
Optional
MongoDatabaseOptions
to use for the retrieved databaseReturn Value
a
MongoDatabase
corresponding to the provided database name -
Starts a
ChangeStream
on aMongoClient
. Allows the client to observe all changes in a cluster - excluding system collections and the “config”, “local”, and “admin” databases.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.
See also
SeeAlso:
Note
Supported in MongoDB version 4.0+ only.
Declaration
Swift
public func watch( _ pipeline: [BSONDocument] = [], options: ChangeStreamOptions? = nil, session: ClientSession? = nil ) throws -> ChangeStream<ChangeStreamEvent<BSONDocument>>
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 all collections in all databases in a cluster. -
Starts a
ChangeStream
on aMongoClient
. Allows the client to observe all changes in a cluster - excluding system collections and the “config”, “local”, and “admin” databases. Associates the specifiedCodable
typeT
with thefullDocument
field in theChangeStreamEvent
s emitted by the returnedChangeStream
.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.
See also
SeeAlso:
Note
Supported in MongoDB version 4.0+ only.
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 all collections in all databases in a cluster. -
Starts a
ChangeStream
on aMongoClient
. Allows the client to observe all changes in a cluster - excluding system collections and the “config”, “local”, and “admin” databases. Associates the specifiedCodable
typeT
with the returnedChangeStream
.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.
See also
SeeAlso:
Note
Supported in MongoDB version 4.0+ only.
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 all collections in all databases in a cluster. -
Attach a
CommandEventHandler
that will receiveCommandEvent
s emitted by this client.Note: the client stores a weak reference to this handler, so it must be kept alive separately in order for it to continue to receive events.
Declaration
Swift
public func addCommandEventHandler<T>(_ handler: T) where T : CommandEventHandler
-
Attach a callback that will receive
CommandEvent
s emitted by this client.Note: if the provided callback captures this client, it must do so weakly. Otherwise, it will constitute a strong reference cycle and potentially result in memory leaks.
Declaration
Swift
public func addCommandEventHandler(_ handlerFunc: @escaping (CommandEvent) -> Void)
-
Attach an
SDAMEventHandler
that will receiveSDAMEvent
s emitted by this client.Note: the client stores a weak reference to this handler, so it must be kept alive separately in order for it to continue to receive events.
Declaration
Swift
public func addSDAMEventHandler<T>(_ handler: T) where T : SDAMEventHandler
-
Attach a callback that will receive
SDAMEvent
s emitted by this client.Note: if the provided callback captures this client, it must do so weakly. Otherwise, it will constitute a strong reference cycle and potentially result in memory leaks.
Declaration
Swift
public func addSDAMEventHandler(_ handlerFunc: @escaping (SDAMEvent) -> Void)
-
Declaration
Swift
public static func == (lhs: MongoClient, rhs: MongoClient) -> Bool