What Is the Changes API



Accessing Changes API

The changes subscription is accessible by a document store through its IDatabaseChanges interface.

store.changes([database]);
Parameters
database string Name of database to open changes API for. If null, the database configured in DocumentStore will be used.
Return value
IDatabaseChanges object Instance implementing IDatabaseChanges interface.

Connection interface

Changes object interface extends IConnectableChanges interface that represents the connection. It exposes the following properties, methods and events.

Properties and methods
connected boolean Indicates whether it's connected or not
on("connectionStatus") method Adds a listener for 'connectionStatus' event
on("error") method Adds a listener for 'error' event
ensureConnectedNow() method Returns a Promise resolved once connection to the server is established.

Subscribing

To receive notifications regarding server-side events, subscribe using one of the following methods.

Unsubscribing

To end a subscription (stop listening for particular notifications) use dispose.

const changes = store.changes();

await changes.ensureConnectedNow();

const allDocsChanges = changes.forAllDocuments()
    .on("data", change => {
        console.log(change.type + " on document " + change.id);
    })
    .on("error", err => {
        // handle error
    });

// ...

try {
    // application code here
} finally {
    // dispose changes after use
    if (changes != null) {
        changes.dispose();
    }
}

FAQ

Changes API and Database Timeout

One or more open Changes API connections will prevent a database from becoming idle and unloaded, regardless of the configuration value for database idle timeout.


Changes API and Method Overloads

To get more method overloads, especially ones supporting delegates, please add the System.Reactive.Core package to your project.

Changes API -vs- Data Subscriptions

Changes API and Data Subscription are services that a RavenDB Server provides subscribing clients.
Both services respond to events that take place on the server, by sending updates to their subscribers.

  • Changes API is a Push Notifications Service.

    • Changes API subscribers receive notifications regarding events that took place on the server, without receiving the actual data entities affected by these events.
      For the modification of a document, for example, the client will receive a DocumentChange object with details like the document's ID and collection name.

    • The server does not keep track of sent notifications or checks clients' usage of them. It is a client's responsibility to manage its reactions to such notifications.

  • Data Subscription is a Data Consumption Service.

    • A Data Subscription task keeps track of document modifications in the database and delivers the documents in an orderly fashion when subscribers indicate they are ready to receive them.
    • The process is fully managed by the server, leaving very little for the subscribers to do besides consuming the delivered documents.

Data Subscriptions Changes API
What can the server Track Documents
Revisions
Documents
Indexes
Operations
Counters
Time Series
What can the server Deliver Documents
Revisions
Notifications
Management Managed by the Server Managed by the Client