see on GitHub

Side-by-Side indexes

This feature enables you to create an index that will be replaced by another one after one of the following conditions are met:

  • new index becomes non-stale (non-optional)
  • new index reaches last indexed etag (in the moment of creation of a new side-by-side index) of a index that will be replaced (optional)
  • particular date is reached (optional)

Applications

As you probably know, making any changes in index definition will reset its indexing state and indexing process will start from scratch. This situation can be troublesome when you need to update index (assuming that changes are backward compatibile) on production server without having your application display partial results (due to index reset). This is why side-by-side indexes were introduced.

Deployment

using AbstractIndexCreationTask

void SideBySideExecute(
	IDatabaseCommands databaseCommands,
	DocumentConvention documentConvention,
	Etag minimumEtagBeforeReplace = null,
	DateTime? replaceTimeUtc = null);

Task SideBySideExecuteAsync(
	IAsyncDatabaseCommands asyncDatabaseCommands,
	DocumentConvention documentConvention,
	Etag minimumEtagBeforeReplace = null,
	DateTime? replaceTimeUtc = null,
	CancellationToken token = default(CancellationToken));

void SideBySideExecute(
	IDocumentStore store,
	Etag minimumEtagBeforeReplace = null,
	DateTime? replaceTimeUtc = null);

Task SideBySideExecuteAsync(
	IDocumentStore store,
	Etag minimumEtagBeforeReplace = null,
	DateTime? replaceTimeUtc = null);

Example

// This method will create 'ReplacementOf/Orders/ByCompany' index, which will replace 'Orders/ByCompany' when
// - new index will become non-stale
// - new index will reach at least '01000000-0000-000E-0000-000000000293' etag
// - in 6 hours from the deployment date
new Orders_ByCompany().SideBySideExecute(store.DatabaseCommands, store.Conventions, Etag.Parse("01000000-0000-000E-0000-000000000293"), DateTime.UtcNow.AddHours(6));

using DocumentStore

void SideBySideExecuteIndex(
	AbstractIndexCreationTask indexCreationTask,
	Etag minimumEtagBeforeReplace = null,
	DateTime? replaceTimeUtc = null);

Task SideBySideExecuteIndexAsync(
	AbstractIndexCreationTask indexCreationTask,
	Etag minimumEtagBeforeReplace = null,
	DateTime? replaceTimeUtc = null);

void SideBySideExecuteIndexes(
	List<AbstractIndexCreationTask> indexCreationTasks, 
	Etag minimumEtagBeforeReplace = null, 
	DateTime? replaceTimeUtc = null);

Task SideBySideExecuteIndexesAsync(
	List<AbstractIndexCreationTask> indexCreationTasks, 
	Etag minimumEtagBeforeReplace = null, 
	DateTime? replaceTimeUtc = null);

Execution of multiple side by side indexes

Side by side indexes are created as a single request when overloads for multiple indexes are used.

Example

using (var store = new DocumentStore
	                   {
		                   Url = "http://localhost:8080/",
						   DefaultDatabase = "Northwind"
	                   })
{
	store.Initialize();

	// This method will create 'ReplacementOf/Orders/ByCompany' index, which will replace 'Orders/ByCompany' when
	// - new index will become non-stale
	// - new index will reach at least '01000000-0000-000E-0000-000000000293' etag
	// - in 6 hours from the deployment date
	store.SideBySideExecuteIndex(new Orders_ByCompany(), Etag.Parse("01000000-0000-000E-0000-000000000293"), DateTime.UtcNow.AddHours(6));
}

Studio

  • first you need to edit index. In our example we are picking Orders/Totals and we are adding ShipVia field.
Figure 1. Side-by-Side. Index Edit.
  • finally, when index definiton is ready, you need to save index as Side-by-Side using action bar. The popup will appear with the name of an index that will be replaced and a list of replacement conditions.
Figure 2. Side-by-Side. Index Edit. Definition. Change
Figure 3. Side-by-Side. Index. Popup.