What Is the Changes API

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

IDatabaseChanges Changes(string database = null);

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;
}

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

• For Document Changes:

  • ForAllDocuments
    Track changes for all document
  • ForDocument
    Track changes for a given document (by Doc ID)
  • ForDocumentsInCollection
    Track changes for all documents in a given collection
  • ForDocumentsStartingWith
    Track changes for documents whose ID contains a given prefix

• For Index Changes:

  • ForAllIndexes
    Track changes for all indexes
  • ForIndex
    Track changes for a given index (by Index Name)

• For Operation Changes:

  • ForAllOperations
    Track changes for all operation
  • ForOperationId
    Track changes for a given operation (by Operation ID)

• For Counter Changes:

  • ForAllCounters
    Track changes for all counters
  • ForCounter
    Track changes for a given counter (by Counter Name)
  • ForCounterOfDocument
    Track changes for a specific counter of a chosen document (by Doc ID and Counter Name)
  • ForCountersOfDocument
    Track changes for all counters of a chosen document (by Doc ID)

• For Time Series Changes:

  • ForAllTimeSeries
    Track changes for all time series
  • ForTimeSeries
    Track changes for all time series with a given name
  • ForTimeSeriesOfDocument
    Track changes for -
    • a specific time series of a given document (by Doc ID and Time Series Name)
    • any time series of a given document (by Doc ID)

To end a subscription (stop listening for particular notifications) you must Dispose of the subscription.

IDatabaseChanges changes = store.Changes();
await changes.EnsureConnectedNow();
var subscription = changes
        .ForAllDocuments()
        .Subscribe(change => Console.WriteLine("{0} on document {1}", change.Type, change.Id));
try
{
    // application code here
}
finally
{
    if (subscription != null)
        subscription.Dispose();
}

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

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.