Document Refresh

• The Refresh feature increments a document's change vector, triggering its re-indexation as well as other features that react to document updates.

• Refresh is scheduled using the @refresh flag in a document's metadata.

• In this page:

  • Overview
  • Syntax
  • Examples

Overview

To refresh a document, add a @refresh flag to a document's metadata with a value of type DateTime (this must be in UTC format, i.e. DateTime.UtcNow). This specifies when the document should be refreshed.

This will cause the document to refresh only once! The refresh operation removes the @refresh flag.

The exact time that the document refreshes is not determined by the value of @refresh

• rather, the server refreshes documents at regular intervals determined by the Refresh Configuration. The default interval is 60 seconds.

Refreshing a document causes its change vector to increment the same way it would after any other kind of update to the document. This triggers any features that react to documents updating, including but not limited to:

• The document is re-indexed by any indexes that cover it.
• Replication, Subscriptions, and ETL are triggered.
• A revision of the document is created.

Syntax

To activate and/or configure document refreshing, the server needs to be sent a RefreshConfiguration object using a ConfigureRefreshOperation operation.

RefreshConfiguration Object

public class RefreshConfiguration
{
  // Set 'Disabled' to false to enable the refresh feature
  public bool Disabled { get; set; }

  // How frequently to process documents with a @refresh flag
  public long? RefreshFrequencyInSec { get; set; }

  // How many items to refresh (each time the refresh task is invoked)
  public long? MaxItemsToProcess { get; set; }
}

Parameter	Type	Description
Disabled	bool	If set to true, document refreshing is disabled for the entire database. Default: true
RefreshFrequencyInSec	long	Determines how often the server checks for documents that need to be refreshed. Default: 60

Studio

Alternatively, document refreshing can also be configured in the studio, under Settings > Document Refresh.

Examples

Example I

How to set refresh configuration for a database:

var refreshConfig = new RefreshConfiguration {
  Disabled = false, 
  RefreshFrequencyInSec = 300,
  MaxItemsToProcess = 1000 
};

var result = documentStore.Maintenance.Send(new ConfigureRefreshOperation(refreshConfig));

This activates document refreshing and sets the interval at 5 minutes.

Example II

How to set a document to refresh 1 hour from now:

using (var session = documentStore.OpenSession())
{
  var document = session.Load<object>("users/1-A");

  session.Advanced.GetMetadataFor(document)["@refresh"] = DateTime.UtcNow.AddHours(1);

  session.SaveChanges();
}