RemoteMongoCollection

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

The RemoteMongoCollection represents a MongoDB collection.

You can get an instance from a RemoteMongoDatabase.

Create, read, update, and delete methods are available.

Operations against the Stitch server are performed asynchronously.

Note

Before you can read or write data, a user must log in. See StitchAuth.

See also

RemoteMongoClient, RemoteMongoDatabase

  • Undocumented

    Declaration

    Swift

    public let sync: Sync<T>

Properties

  • The name of this collection.

    Declaration

    Swift

    public var name: String { get }

  • The name of the database containing this collection.

    Declaration

    Swift

    public var databaseName: String { get }

Custom Document Types

  • 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.

    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.

    Declaration

    Swift

    public typealias CollectionType = T

  • Creates a collection using the same datatabase name and collection name, but with a new Codable type with which to encode and decode documents retrieved from and inserted into the collection.

    Declaration

    Swift

    public func withCollectionType<U>(_ type: U.Type) -> RemoteMongoCollection<U> where U : Decodable, U : Encodable

CRUD Operations

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

    Important

    Invoking this method by itself does not perform any network requests. You must call one of the methods on the resulting RemoteMongoReadOperation instance to trigger the operation against the database.

    Declaration

    Swift

    public func find(_ filter: Document = [:],
                 options: RemoteFindOptions? = nil) -> RemoteMongoReadOperation<CollectionType>

    Parameters

    filter

    A Document that should match the query.
    options

    Optional RemoteFindOptions to use when executing the command.

    Return Value

    A RemoteMongoReadOperation that allows retrieval of the resulting documents.

  • Runs an aggregation framework pipeline against this collection.

    You can use any aggregation stage except for the following:

  • $collStats
  • $currentOp
  • $lookup
  • $out
  • $indexStats
  • $facet
  • $graphLookup
  • $text

  • $geoNear

    Important

    Invoking this method by itself does not perform any network requests. You must call one of the methods on the resulting RemoteMongoReadOperation instance to trigger the operation against the database.

  • pipeline: An array of Documents containing the pipeline of aggregation operations to perform.

    • Declaration

    Swift

    public func aggregate(_ pipeline: [Document]) -> RemoteMongoReadOperation<CollectionType>

    Parameters

    pipeline

    An array of Documents containing the pipeline of aggregation operations to perform.

    Return Value

    A RemoteMongoReadOperation that allows retrieval of the resulting documents.

  • Finds a document in this collection that matches the provided filter.

    Declaration

    Swift

    public func findOne(_ filter: Document = [:],
                    options: RemoteFindOptions? = nil,
                    _ completionHandler: @escaping (StitchResult<CollectionType?>) -> Void)

    Parameters

    filter

    A Document that should match the query.
    options

    Optional RemoteFindOptions to use when executing the command.

    Return Value

    A the resulting Document or nil if no such document exists

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

    Declaration

    Swift

    public func count(_ filter: Document = [:],
                  options: RemoteCountOptions? = nil,
                  _ completionHandler: @escaping (StitchResult<Int>) -> Void)

    Parameters

    filter

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

    Optional RemoteCountOptions to use when executing the command.
    completionHandler

    The completion handler to call when the count is completed or if the operation fails. This handler is executed on a non-main global DispatchQueue. If the operation is successful, the result will contain the count of the documents that matched the filter.

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

    Important

    If the insert failed due to a request timeout, it does not necessarily indicate that the insert failed on the database. Application code should handle timeout errors with the assumption that the document may or may not have been inserted.

    Declaration

    Swift

    public func insertOne(_ value: CollectionType,
                      _ completionHandler: @escaping (StitchResult<RemoteInsertOneResult>) -> Void)

    Parameters

    value

    A CollectionType value to encode and insert.
    completionHandler

    The completion handler to call when the insert is completed or if the operation fails. This handler is executed on a non-main global DispatchQueue. If the operation is successful, the result will contain the result of attempting to perform the insert, as a RemoteInsertOneResult.

  • Encodes the provided values as BSON and inserts them. If any values are missing identifiers, they will be generated.

    Important

    If the insert failed due to a request timeout, it does not necessarily indicate that the insert failed on the database. Application code should handle timeout errors with the assumption that documents may or may not have been inserted.

    Declaration

    Swift

    public func insertMany(_ documents: [CollectionType],
                       _ completionHandler: @escaping (StitchResult<RemoteInsertManyResult>) -> Void)

    Parameters

    documents

    The CollectionType values to insert.
    completionHandler

    The completion handler to call when the insert is completed or if the operation fails. This handler is executed on a non-main global DispatchQueue.
    result

    The result of attempting to perform the insert, or nil if the insert failed. If the operation is successful, the result will contain the result of attempting to perform the insert, as a RemoteInsertManyResult.

  • Deletes a single matching document from the collection.

    Important

    If the delete failed due to a request timeout, it does not necessarily indicate that the delete failed on the database. Application code should handle timeout errors with the assumption that a document may or may not have been deleted.

    Declaration

    Swift

    public func deleteOne(_ filter: Document,
                      _ completionHandler: @escaping (StitchResult<RemoteDeleteResult>) -> Void)

    Parameters

    filter

    A Document representing the match criteria.
    completionHandler

    The completion handler to call when the delete is completed or if the operation fails. This handler is executed on a non-main global DispatchQueue. If the operation is successful, the result will contain the result of performing the deletion, as a RemoteDeleteResult.

  • Deletes multiple documents from the collection.

    Important

    If the delete failed due to a request timeout, it does not necessarily indicate that the delete failed on the database. Application code should handle timeout errors with the assumption that documents may or may not have been deleted.

    Declaration

    Swift

    public func deleteMany(_ filter: Document,
                       _ completionHandler: @escaping (StitchResult<RemoteDeleteResult>) -> Void)

    Parameters

    filter

    A Document representing the match criteria.
    completionHandler

    The completion handler to call when the delete is completed or if the operation fails. This handler is executed on a non-main global DispatchQueue. If the operation is successful, the result will contain the result of performing the deletion, as a RemoteDeleteResult.

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

    Important

    If the update failed due to a request timeout, it does not necessarily indicate that the update failed on the database. Application code should handle timeout errors with the assumption that a document may or may not have been updated.

    Declaration

    Swift

    public func updateOne(filter: Document,
                      update: Document,
                      options: RemoteUpdateOptions? = nil,
                      _ completionHandler: @escaping (StitchResult<RemoteUpdateResult>) -> Void)

    Parameters

    filter

    A Document representing the match criteria.
    update

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

    Optional RemoteUpdateOptions to use when executing the command.
    completionHandler

    The completion handler to call when the update is completed or if the operation fails. This handler is executed on a non-main global DispatchQueue. If the operation is successful, the result will contain the result of attempting to update a document, as a RemoteUpdateResult.

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

    Important

    If the update failed due to a request timeout, it does not necessarily indicate that the update failed on the database. Application code should handle timeout errors with the assumption that documents may or may not have been updated.

    Declaration

    Swift

    public func updateMany(filter: Document,
                       update: Document,
                       options: RemoteUpdateOptions? = nil,
                       _ completionHandler: @escaping (StitchResult<RemoteUpdateResult>) -> Void)

    Parameters

    filter

    A Document representing the match criteria.
    update

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

    Optional RemoteUpdateOptions to use when executing the command.
    completionHandler

    The completion handler to call when the update is completed or if the operation fails. This handler is executed on a non-main global DispatchQueue. If the operation is successful, the result will contain the result of attempting to update multiple documents, as a RemoteUpdateResult.

  • Finds a document in this collection which matches the provided filter and performs the given update on that document.

    Important

    If the update failed due to a request timeout, it does not necessarily indicate that the update failed on the database. Application code should handle timeout errors with the assumption that documents may or may not have been updated.

    Declaration

    Swift

    public func findOneAndUpdate(filter: Document,
                             update: Document,
                             options: RemoteFindOneAndModifyOptions? = nil,
                             _ completionHandler: @escaping (StitchResult<CollectionType?>) -> Void)

    Parameters

    filter

    A Document that should match the query.
    update

    A Document describing the update.
    options

    Optional RemoteFindOneAndModifyOptions to use when executing the command.
    completionHandler

    The completion handler to call when the update is completed or if the operation fails. This handler is executed on a non-main global DispatchQueue. If the operation is successful, the result will contain the resulting document or nil if the query matched no documents.

  • Finds a document in this collection which matches the provided filter and replaces that document with the given document.

    Important

    If the update failed due to a request timeout, it does not necessarily indicate that the update failed on the database. Application code should handle timeout errors with the assumption that documents may or may not have been updated.

    Declaration

    Swift

    public func findOneAndReplace(filter: Document,
                              replacement: Document,
                              options: RemoteFindOneAndModifyOptions? = nil,
                              _ completionHandler: @escaping (StitchResult<CollectionType?>) -> Void)

    Parameters

    filter

    A Document that should match the query.
    replacement

    A Document to replace the matched document with.
    options

    Optional RemoteFindOneAndModifyOptions to use when executing the command.
    completionHandler

    The completion handler to call when the update is completed or if the operation fails. This handler is executed on a non-main global DispatchQueue. If the operation is successful, the result will contain the resulting document or nil if the query matched no documents.

  • Finds a document in this collection which matches the provided filter and delete the document.

    Important

    If the update failed due to a request timeout, it does not necessarily indicate that the update failed on the database. Application code should handle timeout errors with the assumption that documents may or may not have been updated.

    Declaration

    Swift

    public func findOneAndDelete(filter: Document,
                             options: RemoteFindOneAndModifyOptions? = nil,
                             _ completionHandler: @escaping (StitchResult<CollectionType?>) -> Void)

    Parameters

    filter

    A Document that should match the query.
    options

    Optional RemoteFindOneAndModifyOptions to use when executing the command. Note: findOneAndDelete() only accepts the sort and projection options
    completionHandler

    The completion handler to call when the update is completed or if the operation fails. This handler is executed on a non-main global DispatchQueue. If the operation is successful, the result will contain the resulting document or nil if the query matched no documents.

  • Opens a MongoDB change stream against the collection to watch for changes. The resulting stream will be notified of all events on this collection that the active user is authorized to see based on the configured MongoDB rules.

    • This method has a generic type parameter of DelegateT, which is the type of the delegate that will react to events on the stream. This can be any type as long as it conforms to the ChangeStreamDelegate protocol, and the DocumentT type parameter on the delegate matches the T parameter of this collection.

    • When this method returns the ChangeStreamSession, the change stream may not yet be open. The stream is not open until the didOpen method is called on the provided delegate. This means that events that happen after this method returns will not necessarily be received by this stream until the didOpen method is called.

    Declaration

    Swift

    public func watch<DelegateT: ChangeStreamDelegate>(
    delegate: DelegateT
) throws -> ChangeStreamSession<T> where DelegateT.DocumentT == T

    Parameters

    delegate

    The delegate that will react to events and errors from the resulting change stream.

    Return Value

    A reference to the change stream opened by this method.

  • Opens a MongoDB change stream against the collection to watch for changes. The provided BSON document will be used as a match expression filter on the change events coming from the stream.

    See

    See https://docs.mongodb.com/manual/reference/operator/aggregation/match/ for documentation around how to define a match filter.

  • Defining the match expression to filter ChangeEvents is similar to defining the match expression for triggers: https://docs.mongodb.com/stitch/triggers/database-triggers/

  • This method has a generic type parameter of DelegateT, which is the type of the delegate that will react to events on the stream. This can be any type as long as it conforms to the ChangeStreamDelegate protocol, and the DocumentT type parameter on the delegate matches the T parameter of this collection.

  • When this method returns the ChangeStreamSession, the change stream may not yet be open. The stream is not open until the didOpen method is called on the provided delegate. This means that events that happen after this method returns will not necessarily be received by this stream until the didOpen method is called.

    • Declaration

    Swift

    public func watch<DelegateT: ChangeStreamDelegate >(
    matchFilter: Document,
    delegate: DelegateT
) throws -> ChangeStreamSession<T> where DelegateT.DocumentT == T

    Parameters

    matchFilter

    The $match filter to apply to incoming change events
    delegate

    The delegate that will react to events and errors from the resulting change stream.

    Return Value

    A reference to the change stream opened by this method.

  • Opens a MongoDB change stream against the collection to watch for changes made to specific documents. The documents to watch must be explicitly specified by their _id.

    • This method’s forStreamType can be initialized with generic type parameters of FullDelegateT or CompactDelegateT, which are the type of the delegate that will react to events on the stream. These can be any type as long as they conform to either the ChangeStreamDelegate protocol or CompactChangeStreamDelegate protocol respectively, and the DocumentT type parameter on the delegate matches the T parameter of this collection.

    • When this method returns the ChangeStreamSession, the change stream may not yet be open. The stream is not open until the didOpen method is called on the provided delegate. This means that events that happen after this method returns will not necessarily be received by this stream until the didOpen method is called.

    Declaration

    Swift

    public func watch (
    ids: [BSONValue],
    forStreamType streamType: ChangeStreamType<T>
) throws -> ChangeStreamSession<T>

    Parameters

    ids

    The list of _ids in the collection to watch.
    streamType

    Whether to use a full or compact stream. This contains the delegate that will react to events and errors from the resulting change stream.

    Return Value

    A reference to the change stream opened by this method.