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, and time series.
-
Using the Changes API allows you to notify users of various changes without requiring any expensive polling.
-
In this page:
Accessing Changes API
The changes subscription is accessible by a document store through its IDatabaseChanges
or ISingleNodeDatabaseChanges
interfaces.
IDatabaseChanges Changes(string database = null);
ISingleNodeDatabaseChanges Changes(string database, string nodeTag);
Parameters | ||
---|---|---|
database | string |
Name of database to open changes API for. If null , the Database configured in DocumentStore will be used. |
nodeTag | string |
Tag of the cluster node to open changes API for. |
Return value | |
---|---|
IDatabaseChanges |
Instance implementing IDatabaseChanges interface. |
ISingleNodeDatabaseChanges |
Instance implementing ISingleNodeDatabaseChanges interface. |
- Use
IDatabaseChanges
to subscribe to database changes. - Use
ISingleNodeDatabaseChanges
to limit tracking to a specific node.
Note that from RavenDB 6.2 on, some changes can be tracked not cross-cluster but only on a specific node. In these cases, it is required that you open the Changes API using the second overload, passing both a database name and a node tag:
store.Changes(dbName, nodeTag)
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
- ForAllDocuments
-
For Index Changes:
- ForAllIndexes
Track changes for all indexes - ForIndex
Track changes for a given index (by Index Name)
- ForAllIndexes
-
For Operation Changes:
Operation changes can be tracked only on a specific node.- ForAllOperations
Track changes for all operation - ForOperationId
Track changes for a given operation (by Operation ID)
- ForAllOperations
-
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)
- ForAllCounters
-
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)
- ForAllTimeSeries
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 |