Put Indexes Operation



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.create_indexes() 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
index_definition = 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={
        """
          // 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.:
    deployment_mode=IndexDeploymentMode.ROLLING,
    priority=IndexPriority.HIGH,
    configuration={"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
put_indexes_op = PutIndexesOperation(index_definition)

# Execute the operation by passing it to maintenance.send
store.maintenance.send(put_indexes_op)
# Create an index definition
index_definition = 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 multimap index
    maps={
        """
        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.:
    deployment_mode=IndexDeploymentMode.ROLLING,
    priority=IndexPriority.HIGH,
    configuration={"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
put_indexes_op = PutIndexesOperation(index_definition)

# Execute the operation by passing it to Maintenance.Send
store.maintenance.send(put_indexes_op)

Put indexes operation with IndexDefinitionBuilder

  • Using PutIndexesOperation with an IndexDefinition created from an IndexDefinitionBuilder allows setting low-level properties available in IndexDefinitionBuilder.

  • Note that 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
builder = IndexDefinitionBuilder()
builder.map = """
          // 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))
            }               
        """
# Can provide other properties available on the IndexDefinitionBuilder class, e.g.:
builder.deployment_mode = IndexDeploymentMode.ROLLING
builder.priority = IndexPriority.HIGH
# builder.reduce = ..., etc.

# Generate index definition from builder
# Pass the conventions, needed for building the maps property
builder.to_index_definition(store.conventions)

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

# Define the put indexes operation, pass the index definition
# Note: multiple index definitions can be passed, see syntax below
put_indexes_op = PutIndexesOperation(index_definition)

# Execute the operation by passing it to Maintenance.Send
store.maintenance.send(put_indexes_op)

Syntax

class PutIndexesOperation(MaintenanceOperation):
    def __init__(self, *indexes_to_add: IndexDefinition): ...
Parameters Type Description
*indexes_to_add IndexDefinition Definitions of indexes to deploy

IndexDefinition parameter Type Description
name str Name of the index, a unique identifier
maps Set[str] All the map functions for the index
reduce str The index reduce function
deployment_mode IndexDeploymentMode Deployment mode
(PARALLEL, ROLLING)
state IndexState State of index
(NORMAL, DISABLED, IDLE, ERROR)
priority IndexPriority Priority of index
(LOW, NORMAL, HIGH)
lock_mode IndexLockMode Lock mode of index
(UNLOCK, LOCKED_IGNORE, LOCKED_ERROR)
fields Dict[str, IndexFieldOptions] IndexFieldOptions per index field
additional_sources Dict[str, str] Additional code files to be compiled with this index
additional_assemblies Set[AdditionalAssembly] Additional assemblies that are referenced
configuration IndexConfiguration Can override indexing configuration by setting this dictionary
output_reduce_to_collection str A collection name for saving the reduce results as documents
reduce_output_index int This number will be part of the reduce results documents IDs
pattern_for_output_reduce_to_collection_references str Pattern for documents IDs which reference IDs of reduce results documents
pattern_references_collection_name str A collection name for the reference documents created based on provided pattern
store.maintenance.send(put_indexes_op) return value Description
List[PutIndexResult] List of PutIndexResult per index
PutIndexResult parameter Type Description
index str Name of the index that was added
raft_command_index int Index of raft command that was executed