Put Indexes Operation

There are a few ways to create and deploy indexes in a database.
This page describes deploying a static-index using the PutIndexesOperation Operation.
For a general description of Operations see what are operations.
In this page:

Ways to deploy indexes - short summary

Static-indexes:

There are a few ways to deploy a static-index from the Client API:

The following methods are explained in section Deploy a static-index:
- Call Execute() on a specific index instance.
- Call ExecuteIndex() or ExecuteIndexes() on your DocumentStore object.
- Call IndexCreation.CreateIndexes().
Alternatively, you can execute the PutIndexesOperation maintenance operation on the DocumentStore, as explained below.

Auto-indexes:

An auto-index is created by the server when making a filtering query that doesn't specify which index to use. Learn more in Creating auto indexes.

Put indexes operation with IndexDefinition

Using PutIndexesOperation with IndexDefinition allows you to:

Choose any name for the index.
This string-based name is specified when querying the index.
Set low-level properties available in IndexDefinition.

LINQ-index-Sync
LINQ-index-Async
JavaScript-index

// Create an index definition
var indexDefinition = new IndexDefinition 
{
  // Name is mandatory, can use any string
  Name = "OrdersByTotal",

  // Define the index Map functions, string format
  // A single string for a map-index, multiple strings for a multi-map-index
  Maps = new HashSet<string>
  {
      @"
        // Define the collection that will be indexed:
        from order in docs.Orders

          // Define the index-entry:
          select new 
          {
              // Define the index-fields within each index-entry:
              Employee = order.Employee,
              Company = order.Company,
              Total = order.Lines.Sum(l => (l.Quantity * l.PricePerUnit) * (1 - l.Discount))
          }"
  },
  
  // Reduce = ...,
  
  // Can provide other index definitions available on the IndexDefinition class
  // Override the default values, e.g.:
  DeploymentMode = IndexDeploymentMode.Rolling,
  Priority = IndexPriority.High,
  Configuration = new IndexConfiguration
  {
      { "Indexing.IndexMissingFieldsAsNull", "true" }
  }
  // See all available properties in syntax below
};

// Define the put indexes operation, pass the index definition
// Note: multiple index definitions can be passed, see syntax below
IMaintenanceOperation<PutIndexResult[]> putIndexesOp = new PutIndexesOperation(indexDefinition);

// Execute the operation by passing it to Maintenance.Send
store.Maintenance.Send(putIndexesOp);

// Create an index definition
var indexDefinition = new IndexDefinition
{
  // Name is mandatory, can use any string
  Name = "OrdersByTotal",
  
  // Define the index Map functions, string format
  // A single string for a map-index, multiple strings for a multi-map-index
  Maps = new HashSet<string>
  {
      @"
        // Define the collection that will be indexed:
        from order in docs.Orders

          // Define the index-entry:
          select new 
          {
              // Define the index-fields within each index-entry:
              Employee = order.Employee,
              Company = order.Company,
              Total = order.Lines.Sum(l => (l.Quantity * l.PricePerUnit) * (1 - l.Discount))
          }"
  },

  // Reduce = ...,
 
  // Can provide other index definitions available on the IndexDefinition class
  // Override the default values, e.g.:
  DeploymentMode = IndexDeploymentMode.Rolling,
  Priority = IndexPriority.High,
  Configuration = new IndexConfiguration
  {
      { "Indexing.IndexMissingFieldsAsNull", "true" }
  }
  // See all available properties in syntax below
};

// Define the put indexes operation, pass the index definition
// Note: multiple index definitions can be passed, see syntax below
IMaintenanceOperation<PutIndexResult[]> putIndexesOp = new PutIndexesOperation(indexDefinition);

// Execute the operation by passing it to Maintenance.SendAsync
await store.Maintenance.SendAsync(putIndexesOp);

// Create an index definition
var indexDefinition = new IndexDefinition
{
  // Name is mandatory, can use any string
  Name = "OrdersByTotal",
  
  // Define the index Map functions, string format
  // A single string for a map-index, multiple strings for a multi-map-index
  Maps = new HashSet<string>
  {
      @"map('Orders', function(order) {
            return {
                Employee: order.Employee,
                Company: order.Company,
                Total: order.Lines.reduce(function(sum, l) {
                    return sum + (l.Quantity * l.PricePerUnit) * (1 - l.Discount);
                }, 0)
            };
      });"
  },
  
  // Reduce = ...,
 
  // Can provide other index definitions available on the IndexDefinition class
  // Override the default values, e.g.:
  DeploymentMode = IndexDeploymentMode.Rolling,
  Priority = IndexPriority.High,
  Configuration = new IndexConfiguration
  {
      { "Indexing.IndexMissingFieldsAsNull", "true" }
  }
  // See all available properties in syntax below
};

// Define the put indexes operation, pass the index definition
// Note: multiple index definitions can be passed, see syntax below
IMaintenanceOperation<PutIndexResult[]> putIndexesOp = new PutIndexesOperation(indexDefinition);

// Execute the operation by passing it to Maintenance.Send
store.Maintenance.Send(putIndexesOp);

Put indexes operation with IndexDefinitionBuilder

Using PutIndexesOperation with an IndexDefinition created from an IndexDefinitionBuilder allows:

Creating an index definition using a strongly typed LINQ syntax.
Setting low-level properties available in IndexDefinitionBuilder.
Note:
Only map or map-reduce indexes can be generated by the IndexDefinitionBuilder.
To generate multi-map indexes use the above IndexDefinition option.

Sync
Async

// Create an index definition builder
var builder = new IndexDefinitionBuilder<Order>
{
  // Define the map function, strongly typed LINQ format
  Map =
      // Define the collection that will be indexed:
      orders => from order in orders
          // Define the index-entry:
          select new
          {
              // Define the index-fields within each index-entry:
              Employee = order.Employee,
              Company = order.Company,
              Total = order.Lines.Sum(l => (l.Quantity * l.PricePerUnit) * (1 - l.Discount))
          },
  
  // Can provide other properties available on the IndexDefinitionBuilder class, e.g.:
  DeploymentMode = IndexDeploymentMode.Rolling,
  Priority = IndexPriority.High,
  // Reduce = ..., etc.
};

// Generate index definition from builder
// Pass the conventions, needed for building the Maps property
var indexDefinition = builder.ToIndexDefinition(store.Conventions);

// Optionally, set the index name, can use any string
// If not provided then default name from builder is used, e.g.: "IndexDefinitionBuildersOfOrders"
indexDefinition.Name = "OrdersByTotal";

// Define the put indexes operation, pass the index definition
// Note: multiple index definitions can be passed, see syntax below
IMaintenanceOperation<PutIndexResult[]> putIndexesOp = new PutIndexesOperation(indexDefinition);

// Execute the operation by passing it to Maintenance.Send
store.Maintenance.Send(putIndexesOp);

// Create an index definition builder
var builder = new IndexDefinitionBuilder<Order>
{
  // Define the map function, strongly typed LINQ format
  Map = 
      // Define the collection that will be indexed:
      orders => from order in orders
          // Define the index-entry:
          select new
          {
              // Define the index-fields within each index-entry:
              Employee = order.Employee,
              Company = order.Company,
              Total = order.Lines.Sum(l => (l.Quantity * l.PricePerUnit) * (1 - l.Discount))
          },
  
  // Can provide other properties available on the IndexDefinitionBuilder class, e.g.:
  DeploymentMode = IndexDeploymentMode.Rolling,
  Priority = IndexPriority.High,
  // Reduce = ..., etc.
};

// Generate index definition from builder
// Pass the conventions, needed for building the Maps property
var indexDefinition = builder.ToIndexDefinition(store.Conventions);

// Optionally, set the index name, can use any string
// If not provided then default name from builder is used, e.g.: "IndexDefinitionBuildersOfOrders"
indexDefinition.Name = "OrdersByTotal";

// Define the put indexes operation, pass the index definition
// Note: multiple index definitions can be passed, see syntax below
IMaintenanceOperation<PutIndexResult[]> putIndexesOp = new PutIndexesOperation(indexDefinition);

// Execute the operation by passing it to Maintenance.SendAsync
await store.Maintenance.SendAsync(putIndexesOp);

Syntax

public PutIndexesOperation(params IndexDefinition[] indexesToAdd)

Parameter	Type	Description
indexesToAdd	`params IndexDefinition[]`	Definitions of indexes to deploy

`IndexDefinition` parameter	Type	Description
Name	`string`	Name of the index, a unique identifier
Maps	`HashSet<string>`	All the map functions for the index
Reduce	`string`	The index reduce function
DeploymentMode	`IndexDeploymentMode?`	Deployment mode (Parallel, Rolling)
State	`IndexState?`	State of index (Normal, Disabled, Idle, Error)
Priority	`IndexPriority?`	Priority of index (Low, Normal, High)
LockMode	`IndexLockMode?`	Lock mode of index (Unlock, LockedIgnore, LockedError)
Fields	`Dictionary<string, IndexFieldOptions>`	IndexFieldOptions per index field
AdditionalSources	`Dictionary<string, string>`	Additional code files to be compiled with this index
AdditionalAssemblies	`HashSet<AdditionalAssembly>`	Additional assemblies that are referenced
Configuration	`IndexConfiguration`	Can override indexing configuration by setting this dictionary
OutputReduceToCollection	`string`	A collection name for saving the reduce results as documents
ReduceOutputIndex	`long?`	This number will be part of the reduce results documents IDs
PatternForOutputReduceToCollectionReferences	`string`	Pattern for documents IDs which reference IDs of reduce results documents
PatternReferencesCollectionName	`string`	A collection name for the reference documents created based on provided pattern

`store.Maintenance.Send(putIndexesOp)` return value	Description
`PutIndexResult[]`	List of PutIndexResult per index

`PutIndexResult` parameter	Type	Description
Index	`string`	Name of the index that was added
RaftCommandIndex	`long`	Index of raft command that was executed

Ways to deploy indexes - short summary​

Static-indexes:​

Auto-indexes:​

Put indexes operation with IndexDefinition​

Put indexes operation with IndexDefinitionBuilder​

Syntax​