What Is the Changes API

• The Changes API is a Push Notifications service, that allows a RavenDB Client to receive messages from a RavenDB Server regarding events that occurred on the server.

• A client can subscribe to events related to documents, indexes, operations, counters, or time series.

• The Changes API enables you to notify users of various changes, without requiring any expensive polling.

• In this page:

  • Accessing Changes API
  • Connection interface
  • Subscribing
  • Unsubscribing
  • FAQ
    • Changes API and Database Timeout
    • Changes API and Method Overloads
  • Changes API -vs- Data Subscriptions

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.

• 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)

Unsubscribing

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

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