What are Indexes

Indexes are fundamental:

• Indexes are fundamental to RavenDB’s query execution, enabling efficient query performance by processing the underlying data and delivering faster results.
• ALL queries in RavenDB use an index to deliver results and ensure optimal performance.
  Learn more in Queries always provide results using an index.

Main concepts:

• When discussing indexes in RavenDB, three key components come into play:

  • The index definition
  • The indexing process
  • The indexed data

• Each of these components is described in detail in Indexes - The moving parts.

The indexing process:

• The indexing process iterates over the raw documents, creating an index-entry for each document that is processed. (Usually a single index-entry is created per raw document, unless working with a fanout index).
• Each index-entry contains index-fields, and each index-field contains content (index-terms) that was generated from the raw documents, as defined by the index definition and depending on the analyzer used.
• A map is built between the indexed-terms and the documents they originated from,
  enabling you to query for documents based on the indexed data.

Automatic data processing:

• Once defined and deployed, an index will initially process the entire dataset.
  After that, the index will only process documents that were modified, added or deleted.
  This happens automatically without requiring direct user intervention.
• For example, if changes are made to documents in the "Orders" collection,
  all indexes defined for the "Orders" collection will be triggered to update the index with the new data.
• This approach helps avoid costly table scans, allows the server to respond quickly,
  and reduces the load on queries while optimizing machine resource usage.

Background operation:

• RavenDB indexes are designed to run asynchronously in the background.
• The indexing process does not block or interrupt database operations, such as writing data or running queries, though queries may temporarily return stale results until the index is fully updated.

Separate storage:

• Indexes store their processed data separately, ensuring that the raw data remains unaffected.
  This separation helps maintain the integrity of the raw data while allowing the index to optimize query performance.

• If system resources become strained due to indexing, it may require adjustments to the index design, hardware, or other factors. Learn more in If indexes exhaust system resources.

• Indexes in RavenDB are categorized along the following axes:

  • Auto indexes -vs- Static indexes
  • Map indexes -vs- Map-Reduce indexes
  • Single-Collection (Single-Map) indexes -vs- Multi-Collection (Multi-Map) indexes

• For a detailed description of each type, refer to section Index types.

In this example we create a static-index that indexes content from documents in the Employees collection.
This allows querying for Employee documents by any of the index-fields (FullName, LastName, Country).

// Define the index:
// =================

public static class Employees_ByNameAndCountry extends AbstractIndexCreationTask {
    public Employees_ByNameAndCountry() {
        map =  "docs.Employees.Select(employee => new { " +
            "    LastName = employee.LastName, " +
            "    FullName = (employee.FirstName + \" \") + employee.LastName, " +
            "    Country = employee.Address.Country " +
            "})";
    }
}

// Deploy the index to the server:
// ===============================

new Employees_ByNameAndCountry().execute(store);

// Query the database using the index: 
// ===================================

List<Employee> employeesFromUK = session
    .query(Employee.class, Employees_ByNameAndCountry.class)
     // Here we query for all Employee documents that are from the UK
     // and have 'King' in their LastName field:                     
    .whereEquals("LastName", "King")
    .whereEquals("Country", "UK")
    .toList();

Viewing the resulting documents:

For example, the results shown in the following image are the documents that match the query predicate.

Query results - Documents

1. This is the index query.
   The query predicate filters the resulting documents based on the content of the index-fields.
2. Each row in the results represents a matching document.
3. In this example, the LastName, FirstName, Title, etc., are the raw document-fields.

Viewing the index-entries:

If you wish to view the index-entries that compose the index itself,
you can enable the option to show "raw index entries" instead of the matching documents.

Query results - Index Entries

1. Query the index (no filtering is applied in this example).
2. Click the "Settings" button and toggle on "Show raw index-entries instead of matching documents".
3. Each row in the results represents an index-entry.
4. In this example, the Country, FullName, and LastName columns are the index-fields,
   which were defined in the index definition.
5. This a term.
   In this example, usa is a term generated by the analyzer for index-field Country from document employees/4-a.

• The indexing process utilizes machine resources to keep the data up-to-date for queries.

• If indexing drains system resources, it may indicate one or more of the following:

  • Indexes may have been defined in a way that causes inefficient processing.
  • The license may need to be upgraded,
  • Your cloud instance (if used) may require optimization.
  • Hardware upgrades may be necessary to better support your workload.

• Refer to the Indexing Performance View in the Studio to monitor and analyze the indexing process.
  This view provides graphical representations and detailed statistics of all index activities at each stage.

• Additionally, refer to the Common indexing issues section for troubleshooting and resolving indexing challenges.