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 index:
There are a few ways to deploy a static-index from the Client API:
- Call
Execute()
on a specific index instance - Call
IndexCreation.CreateIndexes()
to deploy multiple indexes - Execute
PutIndexesOperation
maintenance operation on the Document Store - see below - Learn more in static indexes
Auto index:
- An auto-index is created by the server when making a filtering query that doesn't specify which index to use
- Learn more in auto indexes
Put indexes operation with IndexDefinition
Using PutIndexesOperation
with IndexDefinition allows the following:
- Choosing any name for the index.
- Setting low-level properties available in IndexDefinition.
// 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.
// 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)
Parameters | Type | Description |
---|---|---|
indexesToAdd | params IndexDefinition[] |
Definitions of indexes to deploy |
IndexDefinition |
||
---|---|---|
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 |
Return value of store.Maintenance.Send(putIndexesOp) |
|
---|---|
PutIndexResult[] |
List of PutIndexResult per index |
PutIndexResult |
||
---|---|---|
Index | string | Name of the index that was added |
RaftCommandIndex | long | Index of raft command that was executed |