DittoCollection

public class DittoCollection

A reference to a collection in a DittoStore.

  • The name of the collection.

    Declaration

    Swift

    public var name: String { get }

  • Inserts a new document into the collection and returns its ID. If the document already exists, the behavior is determined by the given writeStrategy.

    Throws

    DittoSwiftError.

    Declaration

    Swift

    @discardableResult
public func upsert(
    _ content: [String: Any?],
    writeStrategy: DittoWriteStrategy = .merge
) throws -> DittoDocumentID

    Parameters

    content

    The new document to insert.
    writeStrategy

    Specifies the desired strategy for inserting a document. Defaults to .merge.

    Return Value

    The ID of the inserted document.

  • Inserts a new document into the collection and returns its ID. If the document already exists, the behavior is determined by the given writeStrategy.

    Throws

    DittoSwiftError.

    Precondition

    The document content to insert must conform to Encodable.

    Declaration

    Swift

    @discardableResult
public func upsert<T: Encodable>(
    _ content: T,
    writeStrategy: DittoWriteStrategy = .merge
) throws -> DittoDocumentID

    Parameters

    content

    The new document to insert.
    writeStrategy

    Specifies the desired strategy for inserting a document. Defaults to .merge.

    Return Value

    The ID of the inserted document.

  • Inserts a new document into the collection and returns its assigned ID.

    Throws

    DittoSwiftError.

    Deprecated: use upsert() instead.

    Declaration

    Swift

    @available(*, deprecated, message: "use `upsert(﹚` instead")
@discardableResult
public func insert(
    _ content: [String: Any?],
    id: Any? = nil,
    isDefault: Bool = false
) throws -> DittoDocumentID

    Parameters

    content

    The new document to insert.
    id

    The value for the ID to use for the document. If nil then Ditto will automatically assign an ID.
    isDefault

    Represents whether or not the data being inserted should be treated as default data or not. Set this to true if you want to set a default value that you expect to be overwritten by other devices in the network. The default value is false.

    Return Value

    The ID of the inserted document.

  • Inserts a new document into the collection and returns its assigned ID.

    Throws

    DittoSwiftError.

    Deprecated: use upsert() instead.

    Declaration

    Swift

    @available(*, deprecated, message: "use `upsert(﹚` instead")
@discardableResult
public func insertWithStrategy(
    _ content: [String: Any?],
    id: DittoDocumentID? = nil,
    writeStrategy: DittoWriteStrategy = .overwrite
) throws -> DittoDocumentID

    Parameters

    content

    The new document to insert.
    id

    The ID to use for the document. If nil then Ditto will automatically assign an ID.
    writeStrategy

    Specifies the desired strategy for inserting a document. The default value is .overwrite.

    Return Value

    The ID of the inserted document.

  • Inserts a new document into the collection and returns its assigned ID.

    Throws

    DittoSwiftError.

    Deprecated: use upsert() instead.

    Declaration

    Swift

    @available(*, deprecated, message: "use `upsert(﹚` instead")
@discardableResult
public func insert<T: Codable>(
    _ content: T,
    id: DittoDocumentID? = nil,
    isDefault: Bool = false
) throws -> DittoDocumentID

    Parameters

    content

    The new document to insert.
    id

    The ID to use for the document. If nil then Ditto will automatically assign an ID.
    isDefault

    Represents whether or not the data being inserted should be treated as default data or not. Set this to true if you want to set a default value that you expect to be overwritten by other devices in the network. The default value is false.

    Return Value

    The ID of the inserted document.

  • Inserts a new document into the collection and returns its assigned ID.

    Throws

    DittoSwiftError.

    Precondition

    The document content to insert must conform to Codable.

    Deprecated: use upsert() instead.

    Declaration

    Swift

    @available(*, deprecated, message: "use `upsert(﹚` instead")
@discardableResult
public func insertWithStrategy<T: Codable>(
    _ content: T,
    id: DittoDocumentID? = nil,
    writeStrategy: DittoWriteStrategy = .overwrite
) throws -> DittoDocumentID

    Parameters

    content

    The new document to insert.
    id

    The ID to use for the document. If nil then Ditto will automatically assign an ID.
    writeStrategy

    Specifies the desired strategy for inserting a document. The default value is .overwrite.

    Return Value

    The ID of the inserted document.

  • Generates a DittoPendingIDSpecificOperation with the provided document ID that can be used to find the document at a point in time or you can chain a call to observe, observeLocal, or subscribe if you want to get updates about the document over time. It can also be used to update, remove or evict the document.

    Declaration

    Swift

    public func findByID(_ id: DittoDocumentID) -> DittoPendingIDSpecificOperation

    Parameters

    id

    The ID of the document.

    Return Value

    A DittoPendingIDSpecificOperation that you can chain function calls to either get the document immediately or get updates about it over time.

  • Generates a DittoPendingIDSpecificOperation with the provided document ID that can be used to find the document at a point in time or you can chain a call to observe, observeLocal, or subscribe if you want to get updates about the document over time. It can also be used to update, remove or evict the document.

    Declaration

    Swift

    public func findByID(_ id: Any) -> DittoPendingIDSpecificOperation

    Parameters

    id

    The ID of the document.

    Return Value

    A DittoPendingIDSpecificOperation that you can chain function calls to either get the document immediately or get updates about it over time.

  • Generates a DittoPendingCursorOperation with the provided query that can be used to find the documents matching the query at a point in time or you can chain a call to observe, observeLocal, or subscribe if you want to get updates about documents matching the query as they occur. It can also be used to update, remove, or evict documents.

    Declaration

    Swift

    public func find(_ query: String) -> DittoPendingCursorOperation

    Parameters

    query

    The query to run against the collection.

    Return Value

    A DittoPendingCursorOperation that you can use to chain further query-related function calls.

  • Generates a DittoPendingCursorOperation with the provided query and query arguments that can be used to find the documents matching the query at a point in time or you can chain a call to observe, observeLocal, or subscribe if you want to get updates about documents matching the query as they occur. It can also be used to update, remove, or evict documents.

    This is the recommended function to use when performing queries on a collection if you have any dynamic data included in the query string. It allows you to provide a query string with placeholders, in the form of $args.my_arg_name, along with an accompanying dictionary of arguments, in the form of { "my_arg_name": "some value" }, and the placeholders will be appropriately replaced by the matching provided arguments from the dictionary. This includes handling things like wrapping strings in quotation marks and arrays in square brackets, for example.

    Declaration

    Swift

    public func find(_ query: String, args queryArgs: Dictionary<String, Any?>) -> DittoPendingCursorOperation

    Parameters

    query

    The query to run against the collection.
    queryArgs

    The arguments to use to replace placeholders in the provided query.

    Return Value

    A DittoPendingCursorOperation that you can use to chain further query-related function calls.

  • Generates a DittoPendingCursorOperation that can be used to find all documents in the collection at a point in time or you can chain a call to observe, observeLocal, or subscribe if you want to get updates about documents in the collection over time. It can also be used to update, remove or evict documents.

    Declaration

    Swift

    public func findAll() -> DittoPendingCursorOperation

    Return Value

    A DittoPendingCursorOperation that you can use to chain further query-related function calls.

  • Creates a new attachment, which can then be inserted into a document.

    The file residing at the provided path will be copied into the Ditto’s store. The DITAttachment object that is returned is what you can then use to insert an attachment into a document.

    You can provide metadata about the attachment, which will be replicated to other peers alongside the file attachment.

    Below is a snippet to show how you can use the newAttachment functionality to insert an attachment into a document.

    if let attachment = collection.newAttachment("/path/to/my/file.pdf") {
    let docID = try! collection.insert(["attachment": attachment, "other": "string"])
}

    Declaration

    Swift

    public func newAttachment(path: String, metadata: [String : String] = [:]) -> DittoAttachment?

    Parameters

    path

    Path to the file on disk that will be used as the attachment.
    metadata

    Optional metadata relating to the attachment.

    Return Value

    A DittoAttachment object, which can be used to insert the attachment into a document.

  • Fetch the attachment corresponding to the provided attachment token.

    Declaration

    Swift

    public func fetchAttachment(
    token: DittoAttachmentToken,
    deliverOn queue: DispatchQueue = .main,
    onFetchEvent: @escaping (DittoAttachmentFetchEvent) -> Void
) -> DittoAttachmentFetcher?

    Parameters

    token

    The token for the attachment that you want to fetch.
    dispatchQueue

    The dispatch queue that will be used to deliver live query updates. Defaults to the main queue.
    onFetchEvent

    A closure that will be called when there is an update relating to the attachment fetch attempt. If the attachment is already available then this will be called almost immediately with a completed fetch event value.

    Return Value

    A DittoAttachmentFetcher object, which must be kept alive for the fetch request to proceed and for you to be notified about the attachment fetch attempt’s events. If the attachment fetcher could not be created then nil will be returned. This can happen if, for example, an invalid attachment token was provided.

  • A Combine publisher that fetches an attachement. Can also be used to monitor progress as a large attachment is downloaded across the network.

    See more

    Declaration

    Swift

    struct FetchAttachmentPublisher : Publisher

  • A Combine publisher that fetches an attachement.

    Declaration

    Swift

    func fetchAttachmentPublisher(attachmentToken: DittoAttachmentToken) -> FetchAttachmentPublisher

    Parameters

    attachmentToken

    The DittoAttachmentToken for the attachment to fetch.

    Return Value

    A FetchAttachmentPublisher which has an output of DittoAttachmentFetchEvent