Language
Java Node.JS
Article For
3.0 3.5 4.0 4.1 4.2 5.0 5.1 5.2

What Is the Changes API



Accessing Changes API

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

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

Connection interface

IDatabaseChanges inherits from IConnectableChanges<TChanges> interface that represent the connection.

public interface IConnectableChanges<TChanges> : IDisposable
    where TChanges : IDatabaseChanges
{
    // returns state of the connection
    bool Connected { get; }

    // A task that ensures that the connection to the server was established.
    Task<TChanges> EnsureConnectedNow();

    //An event handler to detect changed to the connection status
    event EventHandler ConnectionStatusChanged;

    //An action to take if an error occured in the connection to the server
    event Action<Exception> OnError;
}

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) you must Dispose of the subscription.

IDatabaseChanges subscription = store.Changes();
await subscription.EnsureConnectedNow();
subscription.ForAllDocuments().Subscribe(change => Console.WriteLine("{0} on document {1}", change.Type, change.Id));

try
{
    // application code here
}
finally
{
    if (subscription != null)
        subscription.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
Counters
Time Series
Documents
Indexes
Operations
Counters
Time Series
What can the server Deliver Documents
Revisions
Counters
Time Series
Notifications
Management Managed by the Server Managed by the Client