---
title: "Data Subscriptions: Revisions Support"
url: "https://docs.ravendb.net/6.2/client-api/data-subscriptions/advanced-topics/subscription-with-revisioning"
version: "6.2"
language: "java"
---

# Data Subscriptions: Revisions Support

> Client language: Java. Also available for [C#](https://docs.ravendb.net/6.2/client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.md), [Node.js](https://docs.ravendb.net/6.2/client-api/data-subscriptions/advanced-topics/subscription-with-revisioning.nodejs.md).
>
> RavenDB publishes an official agent skill for coding assistants at https://docs.ravendb.net/skills/ravendb/SKILL.md (also installable with `npx skills add ravendb/skills`). The skill describes itself as: "Read this before writing any RavenDB query, client call or /databases/ request. Covers server setup, document modelling, the Node.js, .NET and Python clients, RQL, indexes, vector search and AI agents. Code written from recall tends to run and return the wrong rows, because RQL resembles SQL and the clients take field names as plain strings."

> **Note**
>
> - The **Data Subscription** feature supports subscribing not only to documents, but also to [document revisions](https://docs.ravendb.net/6.2/document-extensions/revisions/overview.md).
>
> - The revisions support is defined within the subscription.  
>   A [Revisions Configuration](https://docs.ravendb.net/6.2/document-extensions/revisions/client-api/operations/configure-revisions.java.md) must be defined for the subscribed collection.
>
> - While a regular subscription processes a single document, a Revisions subscription processes **pairs of subsequent document revisions**.
>
>   Using this functionality allows you to keep track of each change made in a document, as well as compare pairs of subsequent versions of the document.
>
>   Both revisions are accessible for filtering and projection.
>
> - In this page:
>   - [Revisions processing order](#revisions-processing-order)
>   - [Simple declaration and usage](#simple-declaration-and-usage)
>   - [Revisions processing and projection](#revisions-processing-and-projection)

## Revisions processing order

The Revisions feature allows the tracking of changes made in a document, by storing the audit trail of its changes over time.
An audit trail entry is called a **Document Revision**, and is comprised of a document snapshot.  
Read more about revisions [here](https://docs.ravendb.net/6.2/document-extensions/revisions/overview.md).

In a data subscription, revisions will be processed in pairs of subsequent entries.  
For example, consider the following User document:

`{
    Name:'James',
    Age:'21'
}`

We update the User document twice, in separate operations:

- We update the 'Age' field to the value of 22
- We update the 'Age' field to the value of 23

The data subscriptions revisions processing mechanism will receive pairs of revisions in the following order:

| # | Previous | Current |
| - | - | - |
| 1 | `null` | `{ Name:'James', Age:'21' }` |
| 2 | `{ Name:'James', Age:'21' }` | `{ Name:'James', Age:'22' }` |
| 3 | `{ Name:'James', Age:'22' }` | `{ Name:'James', Age:'23' }` |

> **Warning**
>
> The revisions subscription will be able to function properly only if the revisions it needs to process are available.
> Please make sure that your revisions configuration doesn't purge revisions before the subscription had the chance to process them.

## Simple declaration and usage

Here we declare a simple revisions subscription that will send pairs of subsequent document revisions to the client:

Creation:

### Generic-syntax

```java
name = store.subscriptions().createForRevisions(Order.class);
```

### RQL-syntax

```java
SubscriptionCreationOptions options = new SubscriptionCreationOptions();
options.setQuery("from orders (Revisions = true)");
name = store.subscriptions().createForRevisions(Order.class, options);
```

Consumption:

```java
SubscriptionWorker<Revision<Order>> revisionWorker = store
  .subscriptions().getSubscriptionWorkerForRevisions(Order.class, name);
revisionWorker.run(x -> {
  for (SubscriptionBatch.Item<Revision<Order>> documentsPair : x.getItems()) {

      Order prev = documentsPair.getResult().getPrevious();
      Order current = documentsPair.getResult().getCurrent();

      processOrderChanges(prev, current);
  }
});
```

## Revisions processing and projection

Here we declare a revisions subscription that will filter and project data from revisions pairs:

Creation:

```java
SubscriptionCreationOptions options = new SubscriptionCreationOptions();
options.setQuery("declare function getOrderLinesSum(doc) {" +
  "    var sum = 0;" +
  "    for (var i in doc.Lines) { sum += doc.Lines[i]; } " +
  "    return sum;" +
  "}" +
  "" +
  "  from orders (Revisions = true) " +
  " where getOrderLinesSum(this.Current) > getOrderLinesSum(this.Previous) " +
  " select {" +
  "  previousRevenue: getOrderLinesSum(this.Previous)," +
  "  currentRevenue: getOrderLinesSum(this.Current)" +
  "}");

name = store.subscriptions().create(options);
```

Consumption:

```java
SubscriptionWorker<Revision<Order>> revisionWorker = store
  .subscriptions().getSubscriptionWorkerForRevisions(Order.class, name);
revisionWorker.run(x -> {
  for (SubscriptionBatch.Item<Revision<Order>> documentsPair : x.getItems()) {

      Order prev = documentsPair.getResult().getPrevious();
      Order current = documentsPair.getResult().getCurrent();

      processOrderChanges(prev, current);
  }
});
```

## See also

- [What are Data Subscriptions](https://docs.ravendb.net/6.2/client-api/data-subscriptions/what-are-data-subscriptions.java.md)
- [How to Create a Data Subscription](https://docs.ravendb.net/6.2/client-api/data-subscriptions/creation/how-to-create-data-subscription.java.md)
- [How to Consume a Data Subscription](https://docs.ravendb.net/6.2/client-api/data-subscriptions/consumption/how-to-consume-data-subscription.java.md)
- [Revisions API Overview](https://docs.ravendb.net/6.2/document-extensions/revisions/client-api/overview.java.md)
- [Revisions Overview](https://docs.ravendb.net/6.2/document-extensions/revisions/overview.md)
- [JavaScript Engine](https://docs.ravendb.net/6.2/server/kb/javascript-engine.md)
