Skip to main content

Creating and deploying indexes

Indexes are used by server to satisfy queries, whenever a user issues a query RavenDB will use an existing index if it matches query or create a new one if no match is found.

Indexes created by issuing a query are called dynamic or Auto indexes and can be easily identified, due to their name that starts with Auto/ prefix.

Indexes created explicitly by user are called static.

Static indexes​

There are a couple of ways to create static index and send it to server, we can use low-level commands or create a custom class. There is also a possibility to scan an assembly and deploy all found indexes or even deploy indexes side by side.

using AbstractIndexCreationTask​

If you are interested in having a strongly-typed syntax during index creation, have an ability to deploy indexes using assembly scanner, avoid hard-coding index names in every query and do not worry about setting sorting for numerical fields, then AbstractIndexCreationTask should be your choice.

We recommend creating and using indexes in this form due to its simplicity, many benefits and few disadvantages.

When index is deployed using AbstractIndexCreationTask then all numerical fields in generated index definition will contain appropriate sorting options set.

Naming conventions​

Actually there is only one naming conventions: each _ in class name will be translated to / in index name.

e.g.

In Northwind samples there is a index called Orders/Totals. To get such a index name, we need to create class called Orders_Totals.

// Define a static-index
// Inherit from 'AbstractIndexCreationTask'
public class Orders_ByTotal : AbstractIndexCreationTask<Order>
{
  // ...
}

Sending to server​

There is not much use from an index if it is not deployed to server. In order to do so, we need to create instance of our class that inherits from AbstractIndexCreationTask and use one of the deployment methods: Execute or ExecuteAsync for asynchronous call.

public class Orders_ByTotal : AbstractIndexCreationTask<Order>
{
  public Orders_ByTotal()
  {
      // ...
      // Set an indexing configuration value for this index:
      Configuration["Indexing.MapTimeoutInSec"] = "30";
  }
}
// Call 'Execute' directly on the index instance
new Orders_ByTotal().Execute(store);

If index exists on server and stored definition is the same as the one that was send, then it will not be overwritten, which implies that indexed data will not be deleted and indexation will not start from scratch.

Using assembly scanner​

All classes that inherit from AbstractIndexCreationTask can be deployed at once using one of IndexCreation.CreateIndexes method overloads.

// Call 'ExecuteAsync' directly on the index instance
await new Orders_ByTotal().ExecuteAsync(store);

Underneath, the IndexCreation will attempt to create all indexes in a single request. If it fails, then it will repeat the execution by calling Execute method one-by-one for each of found indexes in separate requests.

IndexCreation.CreateIndexes will also deploy all classes that inherit from AbstractTransformerCreationTask (more about it here).

Example​

var indexesToDeploy = new List<AbstractIndexCreationTask>
{
  new Orders_ByTotal(),
  new Employees_ByLastName()
};

// Call 'ExecuteIndexesAsync' on your store object
await store.ExecuteIndexesAsync(indexesToDeploy);

using Commands​

Low-level PutIndex command from DatabaseCommands (which API reference can be found here) can be used also to send index to server.

The benefit of this approach is that you can choose the name as you feel fit and change various settings available in IndexDefinition, but loose the ability to deploy using assembly scanner. Also you will have to use string-based names of indexes when querying.

// Call 'ExecuteIndex' on your store object
store.ExecuteIndex(new Orders_ByTotal());

IndexDefinitionBuilder​

IndexDefinitionBuilder is a very useful class that enables you to create IndexDefinitions using strongly-typed syntax with an access to low-level settings not available when AbstractIndexCreationTask approach is used.

// Call 'ExecuteIndexAsync' on your store object
await store.ExecuteIndexAsync(new Orders_ByTotal());

Remarks​

Commands or IndexDefinitionBuilder approaches are not recommended and should be used only if you can't do that by inheriting from AbstractIndexCreationTask.

Auto indexes​

Auto-indexes are created when queries that do not specify an index name are executed and (after in-depth query analysis) no matching index is found on server-side.

Naming convention​

As mentioned earlier auto-indexes can be recognized by Auto/ prefix in name. Their name also contains name of a collection that was queried and list of fields that were required to find valid query results.

For instance, issuing query like this

var indexesToDeploy = new List<AbstractIndexCreationTask>
{
  new Orders_ByTotal(),
  new Employees_ByLastName()
};

// Call 'ExecuteIndexes' on your store object
store.ExecuteIndexes(indexesToDeploy);

will result in a creation of a index named Auto/Employees/ByFirstNameAndLastName.

Disabling creation of Auto indexes​

By default, Raven/CreateAutoIndexesForAdHocQueriesIfNeeded configuration option is set to true, which allows auto-index creation if needed. To disable it server or database-wide please refer to this article.

Auto indexes and indexing prioritization​

To reduce the server load, if auto-indexes are not queried for a certain amount of time defined in Raven/TimeToWaitBeforeMarkingAutoIndexAsIdle setting (1 hour by default), then they will be marked as Idle. You can read more about implications of marking index as Idle here.

If this is disabled, you'll have to manually ensure that all queries have covering indexes. This is not a recommended configuration.

Remarks​

By default, new indexes are created in-memory (can be disabled by changing Raven/DisableInMemoryIndexing to false) and persisted to disk when one of the following conditions are met:

  • index is not stale after write,
  • when in-memory size of an index exceeds 64MB (can be altered by changing Raven/NewIndexInMemoryMaxMB),
  • when difference between current write time and index creation time exceeds 15 minutes (can be altered by changing Raven/NewIndexInMemoryMaxTime),
  • when backup is created,
  • when database is closed,
  • on user request. More info here.