Represents a collection of a Ditto store.

This is the entrypoint for inserting documents into a collection, as well as querying a collection. You can get a collection by calling collection() on a Store of a Ditto object.


  • Collection


name: string

The name of the collection.

store: Store

The store this collection belongs to.


  • Trigger an attachment to be downloaded locally to the device and observe its progress as it does so.

    When you encounter a document that contains an attachment the attachment will not automatically be downloaded along with the document. You trigger an attachment to be downloaded locally to a device by calling this method. It will report events relating to the attachment fetch attempt as it tries to download it. The eventHandler block may be called multiple times with progress events. It will then be called with either a Completed event or a Deleted event. If downloading the attachment succeeds then the Completed event that the eventHandler will be called with will hold a reference to the downloaded attachment.


    An AttachmentFetcher object, which must be kept alive for the fetch request to proceed and for you to be notified about the attachment's fetch status changes.


    • token: AttachmentToken

      The AttachmentToken relevant to the attachment that you wish to download and observe. Throws if token is invalid.

    • Optional eventHandler: ((AttachmentFetchEvent: any) => void)

      An optional callback that will be called when there is an update to the status of the attachment fetch attempt.

        • (AttachmentFetchEvent: any): void
        • Parameters

          • AttachmentFetchEvent: any

          Returns void

    Returns AttachmentFetcher

  • Generates a PendingCursorOperation using the provided query.

    The returned object can be used to find and return the documents or you can chain a call to observeLocal() or subscribe() if you want to get updates about the list of matching documents over time. It can also be used to update, remove or evict the matching documents.

    You can incorporate dynamic data into the query string with placeholders in the form of $args.my_arg_name, along with providing an accompanying dictionary in the form of { "my_arg_name": "some value" }. The placeholders will be appropriately replaced by the corresponding argument contained in queryArgs. This includes handling things like wrapping strings in quotation marks and arrays in square brackets, for example.


    • query: string

      The query to run against the collection.

    • Optional queryArgs: QueryArguments

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

    Returns PendingCursorOperation

  • Creates a new Attachment object, which can then be inserted into a document. Node only, throws when running in the web browser.

    The file residing at the provided path will be copied into Ditto's store. The Attachment 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.

    const attachment = await collection.newAttachment('/path/to/my/file.pdf')
    await collection.upsert({ _id: '123', attachment, other: 'some-string' })


    • pathOrData: string | Uint8Array

      The path to the file that you want to create an attachment with or the raw data.

    • Optional metadata: {
          [key: string]: string;

      Metadata relating to the attachment.

      • [key: string]: string

    Returns Promise<Attachment>

  • Inserts a new document into the collection and returns its ID. If the document already exists, the contents of both are merged by default. You can change this by providing a different writeStrategy via options.


    Returns Promise<DocumentID>