You are currently browsing legacy 4.0 version of documentation. Click here to switch to the newest 4.2 version.

We can help you with migration to the latest RavenDB

Contact Us Now
see on GitHub

Indexes: Creating and Deploying Indexes

Indexes are used by the server to satisfy queries. Whenever a user issues a query, RavenDB will use an existing index if it matches the query. If it doesn't, RavenDB will create a new one.

Remember

Indexes created by issuing a query are called dynamic or Auto indexes. They can be easily identified. Their name starts with Auto/ prefix.

Indexes created explicitly by the user are called static.

Static indexes

There are a couple of ways to create a static index and send it to the server. We can use maintenance operations or create a custom class.


Using AbstractIndexCreationTask

AbstractIndexCreationTask lets you avoid hard-coding index names in every query.

Note

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

Naming Convention

There is only one naming convention: each _ in the class name will be translated to / in the index name.

e.g.

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

class Orders_Totals extends AbstractIndexCreationTask {
    /// ...
}

Sending to Server

There is not much use from an index if it is not deployed to the server. To do so, we need to create an instance of our class that inherits from AbstractIndexCreationTask and use execute method.

// deploy index to database defined in `DocumentStore.getDatabase` method
// using default DocumentStore `conventions`
await new Orders_Totals().execute(store);

// deploy index to `Northwind` database
// using default DocumentStore `conventions`
await new Orders_Totals().execute(store, store.conventions, "Northwind");

Safe By Default

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

Example

class Orders_Totals extends AbstractIndexCreationTask {

    constructor() {
        super();
        this.map = "docs.Orders.Select(order => new { " +
            "    Employee = order.Employee, " +
            "    Company = order.Company, " +
            "    Total = Enumerable.Sum(order.Lines, l => ((decimal)((((decimal) l.Quantity) * l.PricePerUnit) * (1M - l.Discount)))) " +
            "})";
    }

}

async function main() {
    store.initialize();

    const ordersTotalsIndex = new Orders_Totals();
    await ordersTotalsIndex.execute(store);

    {
        const session = store.openSession();
        const orders = await session
            .query({ indexName: ordersTotalsIndex.getIndexName() })
            .whereGreaterThan("Total", 100)
            .ofType(Order)
            .all();
    }
}


Using Maintenance Operations

The PutIndexesOperation maintenance operation (which API references can be found here) can be used also to send index(es) to the server.

The benefit of this approach is that you can choose the name as you feel fit, and change various settings available in IndexDefinition. You will have to use string-based names of indexes when querying.

const indexDefinition = new IndexDefinition();
indexDefinition.name = "Orders/Totals";
indexDefinition.maps = new Set([
    "from order in docs.Orders " +
    " select new " +
    " { " +
    "    order.Employee, " +
    "    order.Company, " +
    "    Total = order.Lines.Sum(l => (l.Quantity * l.PricePerUnit) * (1 - l.Discount)) " +
    "}" 
]);

await store.maintenance.send(new PutIndexesOperation(indexDefinition));

Remarks

Side-by-Side

Since RavenDB 4.0, all index updates are side-by-side by default. The new index will replace the existing one once it becomes non-stale. If you want to force an index to swap immediately, you can use the Studio for that.

Index Naming Constraints

  • An index name can be composed of letters, digits, ., /, -, and _. The name must be unique in the scope of the database.
  • Uniqueness is evaluated in a case-insensitive way - you can't create indexes named both usersbyname and UsersByName.
  • The characters _ and / are treated as equivalent - you can't create indexes named both users/byname and users_byname.
  • If the index name contains the character ., it must have some other character on both sides to be valid. /./ is a valid index name, but ./, /., and /../ are all invalid.

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 AUTO index is found on the server-side.

Naming Convention

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

For instance, issuing a query like this

const employees = await session
    .query(Employee)
    .whereEquals("FirstName", "Robert")
    .andAlso()
    .whereEquals("LastName", "King")
    .all();
from Employees
where FirstName = 'Robert' and LastName = 'King'

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

Auto Indexes and Indexing State

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

Setting this configuration option to a high value may result in performance degradation due to the possibility of having a high amount of unnecessary work that is all redundant and not needed by indexes to perform. This is not a recommended configuration.